From d11350d0a7d3d4ddd2f2c530f0eb58c28a222ac0 Mon Sep 17 00:00:00 2001 From: Alexandra Ellwood Date: Thu, 18 Sep 2008 14:56:49 +0000 Subject: [PATCH] Removed kim_identity_get_gss_name and updated documentation ticket: 6055 git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@20729 dc483132-0cff-0310-8789-dd5450dbe970 --- doc/kim/Doxyfile | 13 +- ...oup__kim__ccache__iterator__reference.html | 32 +- .../html/group__kim__ccache__reference.html | 348 +++++---- ..._kim__credential__iterator__reference.html | 38 +- .../group__kim__credential__reference.html | 246 +++---- .../html/group__kim__error__reference.html | 111 +-- .../html/group__kim__identity__reference.html | 233 +++--- .../html/group__kim__options__reference.html | 416 +++++------ .../group__kim__preferences__reference.html | 446 +++++++----- ...oup__kim__selection__hints__reference.html | 675 ++++-------------- .../html/group__kim__string__reference.html | 78 +- .../html/group__kim__types__reference.html | 271 +++---- doc/kim/html/index.html | 4 +- doc/kim/html/kim_ccache_overview.html | 44 +- doc/kim/html/kim_credential_overview.html | 40 +- doc/kim/html/kim_error_overview.html | 10 +- doc/kim/html/kim_identity_overview.html | 29 +- doc/kim/html/kim_options_overview.html | 25 +- doc/kim/html/kim_preferences_overview.html | 22 +- .../html/kim_selection_hints_overview.html | 26 +- doc/kim/html/kim_string_overview.html | 2 +- doc/kim/html/modules.html | 3 +- src/include/kim/kim_identity.h | 12 - src/kim/lib/kim_identity.c | 13 +- 24 files changed, 1345 insertions(+), 1792 deletions(-) diff --git a/doc/kim/Doxyfile b/doc/kim/Doxyfile index fbaf3726b..0f3151645 100644 --- a/doc/kim/Doxyfile +++ b/doc/kim/Doxyfile @@ -4,16 +4,16 @@ # Project related configuration options #--------------------------------------------------------------------------- DOXYFILE_ENCODING = UTF-8 -PROJECT_NAME = "Kerberos Identity Management " +PROJECT_NAME = "Kerberos Identity Management " PROJECT_NUMBER = OUTPUT_DIRECTORY = . CREATE_SUBDIRS = NO OUTPUT_LANGUAGE = English BRIEF_MEMBER_DESC = YES REPEAT_BRIEF = YES -ABBREVIATE_BRIEF = "The $name class " \ - "The $name widget " \ - "The $name file " \ +ABBREVIATE_BRIEF = "The $name class " \ + "The $name widget " \ + "The $name file " \ is \ provides \ specifies \ @@ -80,12 +80,13 @@ WARNINGS = YES WARN_IF_UNDOCUMENTED = YES WARN_IF_DOC_ERROR = YES WARN_NO_PARAMDOC = YES -WARN_FORMAT = "$file:$line: $text " +WARN_FORMAT = "$file:$line: $text " WARN_LOGFILE = #--------------------------------------------------------------------------- # configuration options related to the input files #--------------------------------------------------------------------------- -INPUT = ../../src/include/kim +INPUT = ../../src/include/kim \ + ../../Sources/include/kim INPUT_ENCODING = UTF-8 FILE_PATTERNS = *.c \ *.cc \ diff --git a/doc/kim/html/group__kim__ccache__iterator__reference.html b/doc/kim/html/group__kim__ccache__iterator__reference.html index 7f7144f76..9a4692dfb 100644 --- a/doc/kim/html/group__kim__ccache__iterator__reference.html +++ b/doc/kim/html/group__kim__ccache__iterator__reference.html @@ -9,19 +9,19 @@

Functions

+
  • kim_error kim_ccache_iterator_create (kim_ccache_iterator *out_ccache_iterator) +
    Get a ccache iterator to enumerate ccaches in the cache collection.
  • kim_error kim_ccache_iterator_next (kim_ccache_iterator in_ccache_iterator, kim_ccache *out_ccache) +
    Get the next ccache in the cache collection.
  • void kim_ccache_iterator_free (kim_ccache_iterator *io_ccache_iterator) +
    Free memory associated with a ccache iterator.

    Function Documentation

    - +
    - + - + @@ -38,24 +38,24 @@ Get a ccache iterator to enumerate ccaches in the cache collection.
    kim_error_t kim_ccache_iterator_create kim_error kim_ccache_iterator_create (kim_ccache_iterator_t * kim_ccache_iterator *  out_ccache_iterator  ) 
    out_ccache_iterator on exit, a ccache iterator object for the cache collection.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -76,18 +76,18 @@ Get the next ccache in the cache collection.
    kim_error_t kim_ccache_iterator_next kim_error kim_ccache_iterator_next (kim_ccache_iterator_t kim_ccache_iterator  in_ccache_iterator,
    kim_ccache_t * kim_ccache *  out_ccache 
    out_ccache on exit, the next ccache in the cache collection. If there are no more ccaches in the cache collection this argument will be set to NULL.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + @@ -107,7 +107,7 @@ Free memory associated with a ccache iterator.

    -

    Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  +
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/group__kim__ccache__reference.html b/doc/kim/html/group__kim__ccache__reference.html index 85dfa9c4c..884739c55 100644 --- a/doc/kim/html/group__kim__ccache__reference.html +++ b/doc/kim/html/group__kim__ccache__reference.html @@ -9,51 +9,52 @@

    Functions

    +
  • kim_error kim_ccache_create_new (kim_ccache *out_ccache, kim_identity in_client_identity, kim_options in_options) +
    Acquire a new initial credential and store it in a ccache.
  • kim_error kim_ccache_create_new_if_needed (kim_ccache *out_ccache, kim_identity in_client_identity, kim_options in_options) +
    Find a ccache containing a valid initial credential in the cache collection, or if unavailable, acquire and store a new initial credential.
  • kim_error kim_ccache_create_from_client_identity (kim_ccache *out_ccache, kim_identity in_client_identity) +
    Find a ccache for a client identity in the cache collection.
  • kim_error kim_ccache_create_from_keytab (kim_ccache *out_ccache, kim_identity in_identity, kim_options in_options, kim_string in_keytab) +
    Acquire a new initial credential from a keytab and store it in a ccache.
  • kim_error kim_ccache_create_from_default (kim_ccache *out_ccache) +
    Get the default ccache.
  • kim_error kim_ccache_create_from_type_and_name (kim_ccache *out_ccache, kim_string in_type, kim_string in_name) +
    Get a ccache for a ccache type and name.
  • kim_error kim_ccache_create_from_krb5_ccache (kim_ccache *out_ccache, krb5_context in_krb5_context, krb5_ccache in_krb5_ccache) +
    Get a ccache for a krb5 ccache.
  • kim_error kim_ccache_copy (kim_ccache *out_ccache, kim_ccache in_ccache) +
    Copy a ccache.
  • kim_error kim_ccache_get_krb5_ccache (kim_ccache in_ccache, krb5_context in_krb5_context, krb5_ccache *out_krb5_ccache) +
    Get a krb5 ccache for a ccache.
  • kim_error kim_ccache_get_name (kim_ccache in_ccache, kim_string *out_name) +
    Get the name of a ccache.
  • kim_error kim_ccache_get_type (kim_ccache in_ccache, kim_string *out_type) +
    Get the type of a ccache.
  • kim_error kim_ccache_get_display_name (kim_ccache in_ccache, kim_string *out_display_name) +
    Get the type and name for a ccache in display format.
  • kim_error kim_ccache_get_client_identity (kim_ccache in_ccache, kim_identity *out_client_identity) +
    Get the client identity for a ccache.
  • kim_error kim_ccache_get_valid_credential (kim_ccache in_ccache, kim_credential *out_credential) +
    Get the first valid credential in a ccache.
  • kim_error kim_ccache_get_state (kim_ccache in_ccache, kim_credential_state *out_state) +
    Check the state of the credentials in a ccache (valid, expired, postdated, etc).
  • kim_error kim_ccache_get_start_time (kim_ccache in_ccache, kim_time *out_start_time) +
    Get the time when the credentials in the ccache become valid.
  • kim_error kim_ccache_get_expiration_time (kim_ccache in_ccache, kim_time *out_expiration_time) +
    Get the time when the credentials in the ccache will expire.
  • kim_error kim_ccache_get_renewal_expiration_time (kim_ccache in_ccache, kim_time *out_renewal_expiration_time) +
    Get the time when the credentials in the ccache will no longer be renewable.
  • kim_error kim_ccache_set_default (kim_ccache io_ccache) +
    Set a ccache to the default ccache.
  • kim_error kim_ccache_verify (kim_ccache in_ccache, kim_identity in_service_identity, kim_string in_keytab, kim_boolean in_fail_if_no_service_key) +
    Verify the TGT in a ccache.
  • kim_error kim_ccache_renew (kim_ccache in_ccache, kim_options in_options) +
    Renew the TGT in a ccache.
  • kim_error kim_ccache_validate (kim_ccache in_ccache, kim_options in_options) +
    Validate the TGT in a ccache.
  • kim_error kim_ccache_destroy (kim_ccache *io_ccache) +
    Remove a ccache from the cache collection.
  • void kim_ccache_free (kim_ccache *io_ccache) +
    Free memory associated with a ccache.

    Function Documentation

    - +
    • void kim_ccache_iterator_free (kim_ccache_iterator_t * kim_ccache_iterator *  io_ccache_iterator  ) 
    - + - + - + - + @@ -70,36 +71,36 @@ Acquire a new initial credential and store it in a ccache.

    Parameters:
    kim_error_t kim_ccache_create_new kim_error kim_ccache_create_new (kim_ccache_t * kim_ccache *  out_ccache,
    kim_identity_t kim_identity  in_client_identity,
    kim_options_t kim_options  in_options 
    - +
    out_ccache on exit, a new cache object for a ccache containing a newly acquired initial credential. Must be freed with kim_ccache_free().
    out_ccache on exit, a new cache object for a ccache containing a newly acquired initial credential. Must be freed with kim_ccache_free().
    in_client_identity a client identity to obtain a credential for. Specify KIM_IDENTITY_ANY to allow the user to choose.
    in_options options to control credential acquisition.
    -
    Note:
    Depending on the kim_options specified, kim_ccache_create_new() may present a GUI or command line prompt to obtain information from the user.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Note:
    Depending on the kim_options specified, kim_ccache_create_new() may present a GUI or command line prompt to obtain information from the user.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + - + @@ -116,30 +117,30 @@ Find a ccache containing a valid initial credential in the cache collection, or

    Parameters:
    kim_error_t kim_ccache_create_new_if_needed kim_error kim_ccache_create_new_if_needed (kim_ccache_t * kim_ccache *  out_ccache,
    kim_identity_t kim_identity  in_client_identity,
    kim_options_t kim_options  in_options 
    - +
    out_ccache on exit, a ccache object for a ccache containing a newly acquired initial credential. Must be freed with kim_ccache_free().
    out_ccache on exit, a ccache object for a ccache containing a newly acquired initial credential. Must be freed with kim_ccache_free().
    in_client_identity a client identity to obtain a credential for.
    in_options options to control credential acquisition (if a credential is acquired).
    -
    Note:
    Depending on the kim_options specified, kim_ccache_create_new_if_needed() may present a GUI or command line prompt to obtain information from the user.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Note:
    Depending on the kim_options specified, kim_ccache_create_new_if_needed() may present a GUI or command line prompt to obtain information from the user.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -156,40 +157,40 @@ Find a ccache for a client identity in the cache collection.

    Parameters:
    kim_error_t kim_ccache_create_from_client_identity kim_error kim_ccache_create_from_client_identity (kim_ccache_t * kim_ccache *  out_ccache,
    kim_identity_t kim_identity  in_client_identity 
    - +
    out_ccache on exit, a ccache object for a ccache containing a TGT credential. Must be freed with kim_ccache_free().
    out_ccache on exit, a ccache object for a ccache containing a TGT credential. Must be freed with kim_ccache_free().
    in_client_identity a client identity to obtain a credential for.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + - + - + @@ -206,24 +207,24 @@ Acquire a new initial credential from a keytab and store it in a ccache.

    Parameters:
    kim_error_t kim_ccache_create_from_keytab kim_error kim_ccache_create_from_keytab (kim_ccache_t * kim_ccache *  out_ccache,
    kim_identity_t kim_identity  in_identity,
    kim_options_t kim_options  in_options,
    kim_string_t kim_string  in_keytab 
    - +
    out_ccache on exit, a new ccache object containing an initial credential for the client identity in_identity obtained using in_keytab. Must be freed with kim_ccache_free().
    out_ccache on exit, a new ccache object containing an initial credential for the client identity in_identity obtained using in_keytab. Must be freed with kim_ccache_free().
    in_identity a client identity to obtain a credential for. Specify NULL for the first client identity in the keytab.
    in_options options to control credential acquisition.
    in_keytab a path to a keytab. Specify NULL for the default keytab location.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + @@ -237,33 +238,33 @@ Get the default ccache.

    Parameters:
    kim_error_t kim_ccache_create_from_default kim_error kim_ccache_create_from_default (kim_ccache_t * kim_ccache *  out_ccache  ) 
    - +
    out_ccache on exit, a ccache object for the default ccache. Must be freed with kim_ccache_free().
    out_ccache on exit, a ccache object for the default ccache. Must be freed with kim_ccache_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + - + @@ -280,24 +281,24 @@ Get a ccache for a ccache type and name.

    Parameters:
    kim_error_t kim_ccache_create_from_type_and_name kim_error kim_ccache_create_from_type_and_name (kim_ccache_t * kim_ccache *  out_ccache,
    kim_string_t kim_string  in_type,
    kim_string_t kim_string  in_name 
    - +
    out_ccache on exit, a ccache object for the ccache identified by in_type and in_name. Must be freed with kim_ccache_free().
    out_ccache on exit, a ccache object for the ccache identified by in_type and in_name. Must be freed with kim_ccache_free().
    in_type a ccache type string.
    in_name a ccache name string.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    This API is provided for backwards compatibilty with applications which are not KIM-aware and should be avoided whenever possible.

    - +

    - + - + @@ -326,29 +327,29 @@ Get a ccache for a krb5 ccache.

    Parameters:
    kim_error_t kim_ccache_create_from_krb5_ccache kim_error kim_ccache_create_from_krb5_ccache (kim_ccache_t * kim_ccache *  out_ccache,
    - +
    out_ccache on exit, a new ccache object which is a copy of in_krb5_ccache. Must be freed with kim_ccache_free().
    out_ccache on exit, a new ccache object which is a copy of in_krb5_ccache. Must be freed with kim_ccache_free().
    in_krb5_context the krb5 context used to create in_krb5_ccache.
    in_krb5_ccache a krb5 ccache object.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -365,22 +366,22 @@ Copy a ccache.

    Parameters:
    kim_error_t kim_ccache_copy kim_error kim_ccache_copy (kim_ccache_t * kim_ccache *  out_ccache,
    kim_ccache_t kim_ccache  in_ccache 
    - +
    out_ccache on exit, the new ccache object which is a copy of in_ccache. Must be freed with kim_ccache_free().
    out_ccache on exit, the new ccache object which is a copy of in_ccache. Must be freed with kim_ccache_free().
    in_ccache a ccache object.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + @@ -414,24 +415,24 @@ Get a krb5 ccache for a ccache.
    kim_error_t kim_ccache_get_krb5_ccache kim_error kim_ccache_get_krb5_ccache (kim_ccache_t kim_ccache  in_ccache,
    out_krb5_ccache on exit, a new krb5 ccache object which is a copy of in_ccache. Must be freed with krb5_cc_close() or krb5_cc_destroy().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -452,24 +453,24 @@ Get the name of a ccache.
    kim_error_t kim_ccache_get_name kim_error kim_ccache_get_name (kim_ccache_t kim_ccache  in_ccache,
    kim_string_t * kim_string *  out_name 
    out_name on exit, the name string of in_ccache.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -490,24 +491,24 @@ Get the type of a ccache.
    kim_error_t kim_ccache_get_type kim_error kim_ccache_get_type (kim_ccache_t kim_ccache  in_ccache,
    kim_string_t * kim_string *  out_type 
    out_type on exit, the type string of in_ccache.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -525,27 +526,27 @@ Get the type and name for a ccache in display format.
    Parameters:
    kim_error_t kim_ccache_get_display_name kim_error kim_ccache_get_display_name (kim_ccache_t kim_ccache  in_ccache,
    kim_string_t * kim_string *  out_display_name 
    - +
    in_ccache a ccache object.
    out_display_name on exit, the type and name of in_ccache in a format appropriate for display to the user in command line programs. (ie: "<type>:<name>") Must be freed with kim_string_free(). Note: this string can also be passed to krb5_cc_resolve().
    out_display_name on exit, the type and name of in_ccache in a format appropriate for display to the user in command line programs. (ie: "<type>:<name>") Must be freed with kim_string_free(). Note: this string can also be passed to krb5_cc_resolve().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -563,27 +564,27 @@ Get the client identity for a ccache.
    Parameters:
    kim_error_t kim_ccache_get_client_identity kim_error kim_ccache_get_client_identity (kim_ccache_t kim_ccache  in_ccache,
    kim_identity_t * kim_identity *  out_client_identity 
    - +
    in_ccache a ccache object.
    out_client_identity on exit, an identity object containing the client identity of in_ccache. Must be freed with kim_identity_free().
    out_client_identity on exit, an identity object containing the client identity of in_ccache. Must be freed with kim_identity_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -601,28 +602,67 @@ Get the first valid credential in a ccache.
    Parameters:
    kim_error_t kim_ccache_get_valid_credential kim_error kim_ccache_get_valid_credential (kim_ccache_t kim_ccache  in_ccache,
    kim_credential_t * kim_credential *  out_credential 
    - +
    in_ccache a ccache object.
    out_credential on exit, the first valid credential in in_ccache. Must be freed with kim_credential_free(). Set to NULL if you only want return value, not the actual credential.
    out_credential on exit, the first valid credential in in_ccache. Must be freed with kim_credential_free(). Set to NULL if you only want return value, not the actual credential.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    Note:
    This function prefers TGT credentials. If there are any non-valid TGTs in the ccache, it will always return an error. However, if there are no TGTs at all, it will return the first valid non-TGT credential. If you only want TGTs, use kim_credential_is_tgt() to verify that out_credential is a tgt.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    Note:
    This function prefers valid TGT credentials. If there are only non-valid TGTs in the ccache, it will always return an error. However, if there are no TGTs at all, it will return the first valid non-TGT credential. If you only want TGTs, use kim_credential_is_tgt() to verify that out_credential is a tgt.

    - +

    - + - + - + + + + + + + + +
    kim_error_t kim_ccache_get_start_time kim_error kim_ccache_get_state (kim_ccache_t kim_ccache  in_ccache,
    kim_time_t * kim_credential_state *  out_state 
    )
    +
    +
    + +

    +Check the state of the credentials in a ccache (valid, expired, postdated, etc). +

    +

    Parameters:
    + + + +
    in_ccache a ccache object.
    out_state on exit, the state of the credentials in in_ccache. See kim_credential_state_enum for the possible values of out_state.
    +
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    Note:
    This function prefers TGT credentials. If there are any TGTs in the ccache, it will always return their state. However, if there are no TGTs at all, it will return the state of the first non-TGT credential.
    + +
    +

    + +

    +
    + + + + + + + + + + + @@ -643,24 +683,24 @@ Get the time when the credentials in the ccache become valid.
    kim_error kim_ccache_get_start_time (kim_ccache  in_ccache,
    kim_time *  out_start_time 
    out_start_time on exit, the time when the credentials in in_ccache become valid. May be in the past or future.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -681,24 +721,24 @@ Get the time when the credentials in the ccache will expire.
    kim_error_t kim_ccache_get_expiration_time kim_error kim_ccache_get_expiration_time (kim_ccache_t kim_ccache  in_ccache,
    kim_time_t * kim_time *  out_expiration_time 
    out_expiration_time on exit, the time when the credentials in in_ccache will expire. May be in the past or future.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -719,18 +759,18 @@ Get the time when the credentials in the ccache will no longer be renewable.
    kim_error_t kim_ccache_get_renewal_expiration_time kim_error kim_ccache_get_renewal_expiration_time (kim_ccache_t kim_ccache  in_ccache,
    kim_time_t * kim_time *  out_renewal_expiration_time 
    out_renewal_expiration_time on exit, the time when the credentials in in_ccache will no longer be renewable. May be in the past or future.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + @@ -747,37 +787,37 @@ Set a ccache to the default ccache.
    kim_error_t kim_ccache_set_default kim_error kim_ccache_set_default (kim_ccache_t kim_ccache  io_ccache  ) 
    io_ccache a ccache object which will be set to the default ccache.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    This API is provided for backwards compatibilty with applications which are not KIM-aware and should be avoided whenever possible.

    - +

    - + - + - + - + - + @@ -801,24 +841,24 @@ Verify the TGT in a ccache.
    kim_error_t kim_ccache_verify kim_error kim_ccache_verify (kim_ccache_t kim_ccache  in_ccache,
    kim_identity_t kim_identity  in_service_identity,
    kim_string_t kim_string  in_keytab,
    kim_boolean_t kim_boolean  in_fail_if_no_service_key 
    Note:
    specifying FALSE for in_fail_if_no_service_key may expose the calling program to the Zanarotti attack if the host has no keytab installed.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -839,24 +879,24 @@ Renew the TGT in a ccache.
    kim_error_t kim_ccache_renew kim_error kim_ccache_renew (kim_ccache_t kim_ccache  in_ccache,
    kim_options_t kim_options  in_options 
    in_options initial credential options to be used if a new credential is obtained.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -877,18 +917,18 @@ Validate the TGT in a ccache.
    kim_error_t kim_ccache_validate kim_error kim_ccache_validate (kim_ccache_t kim_ccache  in_ccache,
    kim_options_t kim_options  in_options 
    in_options initial credential options.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + @@ -905,19 +945,19 @@ Remove a ccache from the cache collection.
    kim_error_t kim_ccache_destroy kim_error kim_ccache_destroy (kim_ccache_t * kim_ccache *  io_ccache  ) 
    io_ccache a ccache object to be destroyed. Set to NULL on exit.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    Note:
    Frees memory associated with the ccache. Do not call kim_ccache_free() after calling this function.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    Note:
    Frees memory associated with the ccache. Do not call kim_ccache_free() after calling this function.

    - +

    - + @@ -937,7 +977,7 @@ Free memory associated with a ccache.

    -

    Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  +
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/group__kim__credential__iterator__reference.html b/doc/kim/html/group__kim__credential__iterator__reference.html index f1ffa68bd..81c8ab157 100644 --- a/doc/kim/html/group__kim__credential__iterator__reference.html +++ b/doc/kim/html/group__kim__credential__iterator__reference.html @@ -9,25 +9,25 @@

    Functions

    +
  • kim_error kim_credential_iterator_create (kim_credential_iterator *out_credential_iterator, kim_ccache in_ccache) +
    Get a credential iterator to enumerate credentials in a ccache.
  • kim_error kim_credential_iterator_next (kim_credential_iterator in_credential_iterator, kim_credential *out_credential) +
    Get the next credential in a ccache.
  • void kim_credential_iterator_free (kim_credential_iterator *io_credential_iterator) +
    Free memory associated with a credential iterator.

    Function Documentation

    - +
    • void kim_ccache_free (kim_ccache_t * kim_ccache *  io_ccache  ) 
    - + - + - + @@ -44,28 +44,28 @@ Get a credential iterator to enumerate credentials in a ccache.

    Parameters:
    kim_error_t kim_credential_iterator_create kim_error kim_credential_iterator_create (kim_credential_iterator_t * kim_credential_iterator *  out_credential_iterator,
    kim_ccache_t kim_ccache  in_ccache 
    - +
    out_credential_iterator on exit, a credential iterator object for in_ccache. Must be freed with kim_credential_iterator_free().
    out_credential_iterator on exit, a credential iterator object for in_ccache. Must be freed with kim_credential_iterator_free().
    in_ccache a ccache object.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -83,21 +83,21 @@ Get the next credential in a ccache.
    Parameters:
    kim_error_t kim_credential_iterator_next kim_error kim_credential_iterator_next (kim_credential_iterator_t kim_credential_iterator  in_credential_iterator,
    kim_credential_t * kim_credential *  out_credential 
    - +
    in_credential_iterator a credential iterator object.
    out_credential on exit, the next credential in the ccache iterated by in_credential_iterator. Must be freed with kim_credential_free(). If there are no more credentials this argument will be set to NULL.
    out_credential on exit, the next credential in the ccache iterated by in_credential_iterator. Must be freed with kim_credential_free(). If there are no more credentials this argument will be set to NULL.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + @@ -117,7 +117,7 @@ Free memory associated with a credential iterator.

    -

    Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  +
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/group__kim__credential__reference.html b/doc/kim/html/group__kim__credential__reference.html index 290e1a404..df5250239 100644 --- a/doc/kim/html/group__kim__credential__reference.html +++ b/doc/kim/html/group__kim__credential__reference.html @@ -9,45 +9,45 @@

    Functions

    +
  • kim_error kim_credential_create_new (kim_credential *out_credential, kim_identity in_client_identity, kim_options in_options) +
    Acquire a new initial credential.
  • kim_error kim_credential_create_from_keytab (kim_credential *out_credential, kim_identity in_identity, kim_options in_options, kim_string in_keytab) +
    Acquire a new initial credential from a keytab.
  • kim_error kim_credential_create_from_krb5_creds (kim_credential *out_credential, krb5_context in_krb5_context, krb5_creds *in_krb5_creds) +
    Copy a credential from a krb5 credential object.
  • kim_error kim_credential_copy (kim_credential *out_credential, kim_credential in_credential) +
    Copy a credential object.
  • kim_error kim_credential_get_krb5_creds (kim_credential in_credential, krb5_context in_krb5_context, krb5_creds **out_krb5_creds) +
    Get a krb5 credentials object for a credential object.
  • kim_error kim_credential_get_client_identity (kim_credential in_credential, kim_identity *out_client_identity) +
    Get the client identity of a credential object.
  • kim_error kim_credential_get_service_identity (kim_credential in_credential, kim_identity *out_service_identity) +
    Get the service identity of a credential object.
  • kim_error kim_credential_is_tgt (kim_credential in_credential, kim_boolean *out_is_tgt) +
    Check if a credential is a ticket granting ticket.
  • kim_error kim_credential_get_state (kim_credential in_credential, kim_credential_state *out_state) +
    Check the state of a credential (valid, expired, postdated, etc).
  • kim_error kim_credential_get_start_time (kim_credential in_credential, kim_time *out_start_time) +
    Get the time when the credentials become valid.
  • kim_error kim_credential_get_expiration_time (kim_credential in_credential, kim_time *out_expiration_time) +
    Get the time when the credentials will expire.
  • kim_error kim_credential_get_renewal_expiration_time (kim_credential in_credential, kim_time *out_renewal_expiration_time) +
    Get the time when the credentials will no longer be renewable.
  • kim_error kim_credential_store (kim_credential in_credential, kim_identity in_client_identity, kim_ccache *out_ccache) +
    Store a credential in a ccache in the cache collection.
  • kim_error kim_credential_verify (kim_credential in_credential, kim_identity in_service_identity, kim_string in_keytab, kim_boolean in_fail_if_no_service_key) +
    Verify a TGT credential.
  • kim_error kim_credential_renew (kim_credential *io_credential, kim_options in_options) +
    Renew a TGT credential.
  • kim_error kim_credential_validate (kim_credential *io_credential, kim_options in_options) +
    Validate a TGT credential.
  • void kim_credential_free (kim_credential *io_credential) +
    Free memory associated with a credential object.

    Function Documentation

    - +
    • void kim_credential_iterator_free (kim_credential_iterator_t * kim_credential_iterator *  io_credential_iterator  ) 
    - + - + - + - + @@ -64,43 +64,43 @@ Acquire a new initial credential.

    Parameters:
    kim_error_t kim_credential_create_new kim_error kim_credential_create_new (kim_credential_t * kim_credential *  out_credential,
    kim_identity_t kim_identity  in_client_identity,
    kim_options_t kim_options  in_options 
    - +
    out_credential on exit, a new credential object containing a newly acquired initial credential. Must be freed with kim_credential_free().
    out_credential on exit, a new credential object containing a newly acquired initial credential. Must be freed with kim_credential_free().
    in_client_identity a client identity to obtain a credential for. Specify NULL to allow the user to choose the identity
    in_options options to control credential acquisition.
    -
    Note:
    Depending on the kim_options specified, kim_credential_create_new() may present a GUI or command line prompt to obtain information from the user.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_ccache_create_new
    +
    Note:
    Depending on the kim_options specified, kim_credential_create_new() may present a GUI or command line prompt to obtain information from the user.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_ccache_create_new

    - +

    - + - + - + - + - + @@ -117,25 +117,25 @@ Acquire a new initial credential from a keytab.

    Parameters:
    kim_error_t kim_credential_create_from_keytab kim_error kim_credential_create_from_keytab (kim_credential_t * kim_credential *  out_credential,
    kim_identity_t kim_identity  in_identity,
    kim_options_t kim_options  in_options,
    kim_string_t kim_string  in_keytab 
    - +
    out_credential on exit, a new credential object containing an initial credential for in_identity obtained using in_keytab. Must be freed with kim_credential_free().
    out_credential on exit, a new credential object containing an initial credential for in_identity obtained using in_keytab. Must be freed with kim_credential_free().
    in_identity a client identity to obtain a credential for. Specify NULL for the first identity in the keytab.
    in_options options to control credential acquisition.
    in_keytab a path to a keytab. Specify NULL for the default keytab location.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_ccache_create_from_keytab
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_ccache_create_from_keytab

    - +

    - + - + @@ -164,29 +164,29 @@ Copy a credential from a krb5 credential object.

    Parameters:
    kim_error_t kim_credential_create_from_krb5_creds kim_error kim_credential_create_from_krb5_creds (kim_credential_t * kim_credential *  out_credential,
    - +
    out_credential on exit, a new credential object which is a copy of in_krb5_creds. Must be freed with kim_credential_free().
    out_credential on exit, a new credential object which is a copy of in_krb5_creds. Must be freed with kim_credential_free().
    in_krb5_context the krb5 context used to create in_krb5_creds.
    in_krb5_creds a krb5 credential object.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -203,22 +203,22 @@ Copy a credential object.

    Parameters:
    kim_error_t kim_credential_copy kim_error kim_credential_copy (kim_credential_t * kim_credential *  out_credential,
    kim_credential_t kim_credential  in_credential 
    - +
    out_credential on exit, a new credential object which is a copy of in_credential. Must be freed with kim_credential_free().
    out_credential on exit, a new credential object which is a copy of in_credential. Must be freed with kim_credential_free().
    in_credential a credential object.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + @@ -252,24 +252,24 @@ Get a krb5 credentials object for a credential object.
    kim_error_t kim_credential_get_krb5_creds kim_error kim_credential_get_krb5_creds (kim_credential_t kim_credential  in_credential,
    out_krb5_creds on exit, a new krb5 creds object which is a copy of in_credential. Must be freed with krb5_free_creds().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -287,27 +287,27 @@ Get the client identity of a credential object.
    Parameters:
    kim_error_t kim_credential_get_client_identity kim_error kim_credential_get_client_identity (kim_credential_t kim_credential  in_credential,
    kim_identity_t * kim_identity *  out_client_identity 
    - +
    in_credential a credential object.
    out_client_identity on exit, an identity object containing the client identity of in_credential. Must be freed with kim_identity_free().
    out_client_identity on exit, an identity object containing the client identity of in_credential. Must be freed with kim_identity_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -325,27 +325,27 @@ Get the service identity of a credential object.
    Parameters:
    kim_error_t kim_credential_get_service_identity kim_error kim_credential_get_service_identity (kim_credential_t kim_credential  in_credential,
    kim_identity_t * kim_identity *  out_service_identity 
    - +
    in_credential a credential object.
    out_service_identity on exit, an identity object containing the service identity of in_credential. Must be freed with kim_identity_free().
    out_service_identity on exit, an identity object containing the service identity of in_credential. Must be freed with kim_identity_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -366,24 +366,24 @@ Check if a credential is a ticket granting ticket.
    kim_error_t kim_credential_is_tgt kim_error kim_credential_is_tgt (kim_credential_t kim_credential  in_credential,
    kim_boolean_t * kim_boolean *  out_is_tgt 
    out_is_tgt on exit, whether or not the credential is a TGT.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -404,24 +404,24 @@ Check the state of a credential (valid, expired, postdated, etc).
    kim_error_t kim_credential_get_state kim_error kim_credential_get_state (kim_credential_t kim_credential  in_credential,
    kim_credential_state_t * kim_credential_state *  out_state 
    out_state on exit, the state of the credential. See kim_credential_state_enum for the possible values of out_state.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -442,25 +442,25 @@ Get the time when the credentials become valid.
    kim_error_t kim_credential_get_start_time kim_error kim_credential_get_start_time (kim_credential_t kim_credential  in_credential,
    kim_time_t * kim_time *  out_start_time 
    out_start_time on exit, the time when in_credential becomes valid. May be in the past or future.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_ccache_get_start_time
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_ccache_get_start_time

    - +

    - + - + - + @@ -481,25 +481,25 @@ Get the time when the credentials will expire.
    kim_error_t kim_credential_get_expiration_time kim_error kim_credential_get_expiration_time (kim_credential_t kim_credential  in_credential,
    kim_time_t * kim_time *  out_expiration_time 
    out_expiration_time on exit, the time when in_credential will expire. May be in the past or future.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_ccache_get_expiration_time
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_ccache_get_expiration_time

    - +

    - + - + - + @@ -520,31 +520,31 @@ Get the time when the credentials will no longer be renewable.
    kim_error_t kim_credential_get_renewal_expiration_time kim_error kim_credential_get_renewal_expiration_time (kim_credential_t kim_credential  in_credential,
    kim_time_t * kim_time *  out_renewal_expiration_time 
    out_renewal_expiration_time on exit, the time when in_credential will no longer be renewable. May be in the past or future.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_ccache_get_renewal_expiration_time
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_ccache_get_renewal_expiration_time

    - +

    - + - + - + - + @@ -563,39 +563,39 @@ Store a credential in a ccache in the cache collection.
    kim_error_t kim_credential_store kim_error kim_credential_store (kim_credential_t kim_credential  in_credential,
    kim_identity_t kim_identity  in_client_identity,
    kim_ccache_t * kim_ccache *  out_ccache 
    - +
    in_credential a credential object.
    in_client_identity a client identity.
    out_ccache on exit, a ccache object containing in_credential with the client identity in_client_identity. Must be freed with kim_ccache_free(). Specify NULL if you don't want this return value.
    out_ccache on exit, a ccache object containing in_credential with the client identity in_client_identity. Must be freed with kim_ccache_free(). Specify NULL if you don't want this return value.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + - + - + @@ -619,25 +619,25 @@ Verify a TGT credential.
    kim_error_t kim_credential_verify kim_error kim_credential_verify (kim_credential_t kim_credential  in_credential,
    kim_identity_t kim_identity  in_service_identity,
    kim_string_t kim_string  in_keytab,
    kim_boolean_t kim_boolean  in_fail_if_no_service_key 
    Note:
    specifying FALSE for in_fail_if_no_service_key may expose the calling program to the Zanarotti attack if the host has no keytab installed.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_ccache_verify
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_ccache_verify

    - +

    - + - + - + @@ -654,29 +654,29 @@ Renew a TGT credential.

    Parameters:
    kim_error_t kim_credential_renew kim_error kim_credential_renew (kim_credential_t * kim_credential *  io_credential,
    kim_options_t kim_options  in_options 
    - +
    io_credential a TGT credential to be renewed. On exit, the old credential object will be freed and io_credential will be replaced with a new renewed credential. The new credential must be freed with kim_credential_free().
    io_credential a TGT credential to be renewed. On exit, the old credential object will be freed and io_credential will be replaced with a new renewed credential. The new credential must be freed with kim_credential_free().
    in_options initial credential options.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_ccache_renew
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_ccache_renew

    - +

    - + - + - + @@ -693,23 +693,23 @@ Validate a TGT credential.

    Parameters:
    kim_error_t kim_credential_validate kim_error kim_credential_validate (kim_credential_t * kim_credential *  io_credential,
    kim_options_t kim_options  in_options 
    - +
    io_credential a credential object to be validated. On exit, the old credential object will be freed and io_credential will be replaced with a new validated credential. The new credential must be freed with kim_credential_free().
    io_credential a credential object to be validated. On exit, the old credential object will be freed and io_credential will be replaced with a new validated credential. The new credential must be freed with kim_credential_free().
    in_options initial credential options.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_ccache_validate
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_ccache_validate

    - +

    - + @@ -729,7 +729,7 @@ Free memory associated with a credential object.

    -

    Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  +
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/group__kim__error__reference.html b/doc/kim/html/group__kim__error__reference.html index 0eca34a03..df2723664 100644 --- a/doc/kim/html/group__kim__error__reference.html +++ b/doc/kim/html/group__kim__error__reference.html @@ -9,26 +9,23 @@

    Functions

    +
  • kim_error kim_string_get_last_error_message (kim_string *out_string, kim_error in_error) +
    Get a text description of an error suitable for display to the user.

    Function Documentation

    - +
    • void kim_credential_free (kim_credential_t * kim_credential *  io_credential  ) 
    - + - - + + - + @@ -41,102 +38,20 @@

    -Copy an error. +Get a text description of an error suitable for display to the user.

    Parameters:
    kim_error_t kim_error_copy kim_error kim_string_get_last_error_message (kim_error_t *  out_error, kim_string *  out_string,
    kim_error_t kim_error  in_error 
    - - + +
    out_error on exit, a new error object which is a copy of in_error. Must be freed with kim_error_free().
    in_error the error to copy.
    out_string On success, a human-readable UTF-8 string describing the error representedby in_error. Must be freed with kim_string_free().
    in_error an error code. Used to verify that the correct error string will be returned (see note below).
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR.
    +
    Note:
    This API is implemented using thread local storage. It should be called immediately after a KIM API returns an error code so that the correct string is returned. The returned copy may then be held by the caller until needed. If in_error does not match the last saved error KIM may return a less descriptive string.

    - -

    -
    - - - - - - - - - -
    kim_error_code_t kim_error_get_code (kim_error_t  in_error  ) 
    -
    -
    - -

    -Get a numerical error code for an error. -

    -

    Parameters:
    - - -
    in_error an error object.
    -
    -
    Returns:
    On success, a machine-readable error code describing the error represented by in_error. On failure, KIM_PARAMETER_ECODE.
    - -
    -

    - -

    -
    - - - - - - - - - -
    kim_string_t kim_error_get_display_string (kim_error_t  in_error  ) 
    -
    -
    - -

    -Get a text description of an error. -

    -

    Parameters:
    - - -
    in_error an error object.
    -
    -
    Returns:
    On success, a human-readable error string describing the error represented by in_error. On failure, NULL, indicating that the kim_error_t object was invalid.
    - -
    -

    - -

    -
    - - - - - - - - - -
    void kim_error_free (kim_error_t *  io_error  ) 
    -
    -
    - -

    -Free memory associated with an error. -

    -

    Parameters:
    - - -
    io_error the error object to be freed. Set to NULL on exit.
    -
    - -
    -

    -

    Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  +
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/group__kim__identity__reference.html b/doc/kim/html/group__kim__identity__reference.html index 86d6df71f..f20544fd3 100644 --- a/doc/kim/html/group__kim__identity__reference.html +++ b/doc/kim/html/group__kim__identity__reference.html @@ -9,37 +9,36 @@

    Functions

    +
  • kim_error kim_identity_create_from_string (kim_identity *out_identity, kim_string in_string) +
    Create a identity from a string.
  • kim_error kim_identity_create_from_components (kim_identity *out_identity, kim_string in_realm, kim_string in_1st_component,...) +
    Create a identity from a realm and component strings.
  • kim_error kim_identity_create_from_krb5_principal (kim_identity *out_identity, krb5_context in_krb5_context, krb5_principal in_krb5_principal) +
    Create an identity object from a krb5_principal.
  • kim_error kim_identity_copy (kim_identity *out_identity, kim_identity in_identity) +
    Copy an identity object.
  • kim_error kim_identity_compare (kim_identity in_identity, kim_identity in_compare_to_identity, kim_comparison *out_comparison) +
    Compare identity objects for equivalency.
  • kim_error kim_identity_get_string (kim_identity in_identity, kim_string *out_string) +
    Get the string representation of a identity.
  • kim_error kim_identity_get_display_string (kim_identity in_identity, kim_string *out_display_string) +
    Get a human-readable string representation of an identity.
  • kim_error kim_identity_get_realm (kim_identity in_identity, kim_string *out_realm_string) +
    Get the realm string of an identity.
  • kim_error kim_identity_get_number_of_components (kim_identity in_identity, kim_count *out_number_of_components) +
    Get the number of components of an identity.
  • kim_error kim_identity_get_component_at_index (kim_identity in_identity, kim_count in_index, kim_string *out_component_string) +
    Get the Nth component of an identity.
  • kim_error kim_identity_get_krb5_principal (kim_identity in_identity, krb5_context in_krb5_context, krb5_principal *out_krb5_principal) +
    Get the krb5_principal representation of an identity.
  • kim_error kim_identity_change_password (kim_identity in_identity, kim_options in_options) +
    Change the password for an identity.
  • kim_error kim_identity_change_password_to_password (kim_identity in_identity, kim_options in_options, kim_string in_new_password) +
    Change the password for an identity to a caller-provided new password.
  • void kim_identity_free (kim_identity *io_identity) +
    Free memory associated with an identity.

    Function Documentation

    - +
    - + - + - + @@ -56,34 +55,34 @@ Create a identity from a string.

    Parameters:
    kim_error_t kim_identity_create_from_string kim_error kim_identity_create_from_string (kim_identity_t * kim_identity *  out_identity,
    kim_string_t kim_string  in_string 
    - +
    out_identity on exit, a new identity object. Must be freed with kim_identity_free().
    out_identity on exit, a new identity object. Must be freed with kim_identity_free().
    in_string a string representation of a Kerberos identity. Special characters such as '/' and '@' must be escaped with '\'.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + - + @@ -106,25 +105,25 @@ Create a identity from a realm and component strings.

    Parameters:
    kim_error_t kim_identity_create_from_components kim_error kim_identity_create_from_components (kim_identity_t * kim_identity *  out_identity,
    kim_string_t kim_string  in_realm,
    kim_string_t kim_string  in_1st_component,
    - + - +
    out_identity on exit, a new identity object. Must be freed with kim_identity_free().
    out_identity on exit, a new identity object. Must be freed with kim_identity_free().
    in_realm a string representation of a Kerberos realm.
    in_1st_component a string representing the first component of the identity.
    ... zero or more strings of type kim_string_t representing additional components of the identity followed by a terminating NULL. Components will be assembled in order (ie: the 4th argument to kim_identity_create_from_components() will be the 2nd component of the identity).
    ... zero or more strings of type kim_string_t representing additional components of the identity followed by a terminating NULL. Components will be assembled in order (ie: the 4th argument to kim_identity_create_from_components() will be the 2nd component of the identity).
    -
    Note:
    The last argument must be a NULL or kim_identity_create_from_components() may crash.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Note:
    The last argument must be a NULL or kim_identity_create_from_components() may crash.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + @@ -153,29 +152,29 @@ Create an identity object from a krb5_principal.

    Parameters:
    kim_error_t kim_identity_create_from_krb5_principal kim_error kim_identity_create_from_krb5_principal (kim_identity_t * kim_identity *  out_identity,
    - +
    out_identity on exit, a new identity object which is a copy of in_krb5_principal. Must be freed with kim_identity_free().
    out_identity on exit, a new identity object which is a copy of in_krb5_principal. Must be freed with kim_identity_free().
    in_krb5_context the krb5 context used to create in_krb5_principal.
    in_krb5_principal a krb5 principal object.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -192,34 +191,34 @@ Copy an identity object.

    Parameters:
    kim_error_t kim_identity_copy kim_error kim_identity_copy (kim_identity_t * kim_identity *  out_identity,
    kim_identity_t kim_identity  in_identity 
    - +
    out_identity on exit, a new identity object which is a copy of in_identity. Must be freed with kim_identity_free().
    out_identity on exit, a new identity object which is a copy of in_identity. Must be freed with kim_identity_free().
    in_identity an identity object.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + - + @@ -241,24 +240,24 @@ Compare identity objects for equivalency.
    kim_error_t kim_identity_compare kim_error kim_identity_compare (kim_identity_t kim_identity  in_identity,
    kim_identity_t kim_identity  in_compare_to_identity,
    kim_comparison_t * kim_comparison *  out_comparison 
    out_comparison on exit, a comparison of in_identity and in_compare_to_identity which determines whether or not the two identities are equivalent and their sort order (for display to the user) if they are not.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -276,28 +275,28 @@ Get the string representation of a identity.
    Parameters:
    kim_error_t kim_identity_get_string kim_error kim_identity_get_string (kim_identity_t kim_identity  in_identity,
    kim_string_t * kim_string *  out_string 
    - +
    in_identity an identity object.
    out_string on exit, a string representation of in_identity. Must be freed with kim_string_free().
    out_string on exit, a string representation of in_identity. Must be freed with kim_string_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    Special characters such as '@' and '/' will be escaped with '\'.

    - +

    - + - + - + @@ -315,28 +314,28 @@ Get a human-readable string representation of an identity.
    Parameters:
    kim_error_t kim_identity_get_display_string kim_error kim_identity_get_display_string (kim_identity_t kim_identity  in_identity,
    kim_string_t * kim_string *  out_display_string 
    - +
    in_identity an identity object.
    out_display_string on exit, a string representation of in_identity appropriate for display to the user. Must be freed with kim_string_free().
    out_display_string on exit, a string representation of in_identity appropriate for display to the user. Must be freed with kim_string_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    Note:
    Special characters such as '/' and '@' are not escaped with '\'. As a result the string returned from this function cannot be used with kim_identity_create_from_string() because it does not uniquely specify a principal. The result of this function should only be used to display to the user.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    Note:
    Special characters such as '/' and '@' are not escaped with '\'. As a result the string returned from this function cannot be used with kim_identity_create_from_string() because it does not uniquely specify a principal. The result of this function should only be used to display to the user.

    - +

    - + - + - + @@ -354,27 +353,27 @@ Get the realm string of an identity.
    Parameters:
    kim_error_t kim_identity_get_realm kim_error kim_identity_get_realm (kim_identity_t kim_identity  in_identity,
    kim_string_t * kim_string *  out_realm_string 
    - +
    in_identity an identity object.
    out_realm_string on exit, a string representation of in_identity's realm. Must be freed with kim_string_free().
    out_realm_string on exit, a string representation of in_identity's realm. Must be freed with kim_string_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -395,30 +394,30 @@ Get the number of components of an identity.
    kim_error_t kim_identity_get_number_of_components kim_error kim_identity_get_number_of_components (kim_identity_t kim_identity  in_identity,
    kim_count_t * kim_count *  out_number_of_components 
    out_number_of_components on exit the number of components in in_identity.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + - + @@ -437,21 +436,21 @@ Get the Nth component of an identity.
    kim_error_t kim_identity_get_component_at_index kim_error kim_identity_get_component_at_index (kim_identity_t kim_identity  in_identity,
    kim_count_t kim_count  in_index,
    kim_string_t * kim_string *  out_component_string 
    - +
    in_identity an identity object.
    in_index the index of the desired component. Component indexes start at 0.
    out_component_string on exit, a string representation of the component in in_identity specified by in_index. Must be freed with kim_string_free().
    out_component_string on exit, a string representation of the component in in_identity specified by in_index. Must be freed with kim_string_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + @@ -485,62 +484,24 @@ Get the krb5_principal representation of an identity.
    kim_error_t kim_identity_get_krb5_principal kim_error kim_identity_get_krb5_principal (kim_identity_t kim_identity  in_identity,
    out_krb5_principal on exit, a krb5_principal representation of in_identity allocated with in_krb5_context. Must be freed with krb5_free_principal() using in_krb5_context.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - - - - - - - - -
    kim_error_t kim_identity_get_gss_name kim_error kim_identity_change_password (kim_identity_t kim_identity  in_identity,
    gss_name_t *  out_gss_name 
    )
    -
    -
    - -

    -Get the gss_name_t representation of an identity. -

    -

    Parameters:
    - - - -
    in_identity an identity object.
    out_gss_name on exit, a gss_name_t representation of in_identity. Must be freed with gss_release_name().
    -
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    - -
    -

    - -

    -
    - - - - - - - - - - - + @@ -561,31 +522,31 @@ Change the password for an identity.
    kim_error_t kim_identity_change_password (kim_identity_t  in_identity,
    kim_options_t kim_options  in_options 
    in_options initial credential options to be used if a new credential is obtained.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    Note:
    kim_identity_change_password() will acquire a temporary credential to change the password. It uses the in_options structure to obtain information about the desired prompter and current password.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    Note:
    kim_identity_change_password() will acquire a temporary credential to change the password. It uses the in_options structure to obtain information about the desired prompter and current password.

    - +

    - + - + - + - + @@ -607,19 +568,19 @@ Change the password for an identity to a caller-provided new password.
    kim_error_t kim_identity_change_password_to_password kim_error kim_identity_change_password_to_password (kim_identity_t kim_identity  in_identity,
    kim_options_t kim_options  in_options,
    kim_string_t kim_string  in_new_password 
    in_new_password a string representation of the identity's new password.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    kim_identity_change_password_with_passwords() will acquire a temporary credential to change the password. It uses the in_options structure to obtain information about the desired prompter and current password.

    - +

    - + @@ -639,7 +600,7 @@ Free memory associated with an identity.

    -

    Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  +
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/group__kim__options__reference.html b/doc/kim/html/group__kim__options__reference.html index 0ab05b832..0d7536473 100644 --- a/doc/kim/html/group__kim__options__reference.html +++ b/doc/kim/html/group__kim__options__reference.html @@ -9,41 +9,39 @@

    Functions

    +
  • kim_error kim_options_create (kim_options *out_options) +
    Create new options with default values.
  • kim_error kim_options_copy (kim_options *out_options, kim_options in_options) +
    Copy options.
  • kim_error kim_options_set_prompt_callback (kim_options io_options, kim_prompt_callback in_prompt_callback) +
    Set the prompt callback for obtaining information from the user.
  • kim_error kim_options_get_prompt_callback (kim_options in_options, kim_prompt_callback *out_prompt_callback) +
    Get the prompt callback for obtaining information from the user.
  • kim_error kim_options_set_data (kim_options io_options, const void *in_data) +
    Set caller-specific data for use in library callbacks.
  • kim_error kim_options_get_data (kim_options in_options, const void **out_data) +
    Get caller-specific data for use in library callbacks.
  • kim_error kim_options_set_start_time (kim_options io_options, kim_time in_start_time) +
    Set the date when a credential should become valid.
  • kim_error kim_options_get_start_time (kim_options in_options, kim_time *out_start_time) +
    Get the date when a credential should become valid.
  • kim_error kim_options_set_lifetime (kim_options io_options, kim_lifetime in_lifetime) +
    Set the duration during which a credential should be valid.
  • kim_error kim_options_get_lifetime (kim_options in_options, kim_lifetime *out_lifetime) +
    Get the duration during which an acquired credential should be valid.
  • kim_error kim_options_set_renewable (kim_options io_options, kim_boolean in_renewable) +
    Set whether or not to request a renewable credential.
  • kim_error kim_options_get_renewable (kim_options in_options, kim_boolean *out_renewable) +
    Get whether or not to request a renewable credential.
  • kim_error kim_options_set_renewal_lifetime (kim_options io_options, kim_lifetime in_renewal_lifetime) +
    Set the duration during which a valid credential should be renewable.
  • kim_error kim_options_get_renewal_lifetime (kim_options in_options, kim_lifetime *out_renewal_lifetime) +
    Get the duration during which a valid credential should be renewable.
  • kim_error kim_options_set_forwardable (kim_options io_options, kim_boolean in_forwardable) +
    Set whether or not to request a forwardable credential.
  • kim_error kim_options_get_forwardable (kim_options in_options, kim_boolean *out_forwardable) +
    Get whether or not to request a forwardable credential.
  • kim_error kim_options_set_proxiable (kim_options io_options, kim_boolean in_proxiable) +
    Set whether or not to request a proxiable credential.
  • kim_error kim_options_get_proxiable (kim_options in_options, kim_boolean *out_proxiable) +
    Get whether or not to request a proxiable credential.
  • kim_error kim_options_set_addressless (kim_options io_options, kim_boolean in_addressless) +
    Set whether or not to request an addressless credential.
  • kim_error kim_options_get_addressless (kim_options in_options, kim_boolean *out_addressless) +
    Get whether or not to request an addressless credential.
  • kim_error kim_options_set_service_name (kim_options io_options, kim_string in_service_name) +
    Set the service name to request a credential for.
  • kim_error kim_options_get_service_name (kim_options in_options, kim_string *out_service_name) +
    Get the service name to request a credential for.
  • void kim_options_free (kim_options *io_options) +
    Free memory associated with an options object.

    Function Documentation

    - +
    • void kim_identity_free (kim_identity_t * kim_identity *  io_identity  ) 
    - + - + @@ -57,27 +55,27 @@ Create new options with default values.

    Parameters:
    kim_error_t kim_options_create kim_error kim_options_create (kim_options_t * kim_options *  out_options  ) 
    - +
    out_options on exit, a new options object. Must be freed with kim_options_free().
    out_options on exit, a new options object. Must be freed with kim_options_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -94,28 +92,28 @@ Copy options.

    Parameters:
    kim_error_t kim_options_copy kim_error kim_options_copy (kim_options_t * kim_options *  out_options,
    kim_options_t kim_options  in_options 
    - +
    out_options on exit, a new options object which is a copy of in_options. Must be freed with kim_options_free().
    out_options on exit, a new options object which is a copy of in_options. Must be freed with kim_options_free().
    in_options a options object.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -136,26 +134,26 @@ Set the prompt callback for obtaining information from the user.
    kim_error_t kim_options_set_prompt_callback kim_error kim_options_set_prompt_callback (kim_options_t kim_options  io_options,
    kim_prompt_callback_t kim_prompt_callback  in_prompt_callback 
    in_prompt_callback a prompt callback function.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    Default value
    kim_prompt_callback_default
    -
    See also:
    kim_options_get_prompt_callback()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    Default value
    kim_prompt_callback_default
    +
    See also:
    kim_options_get_prompt_callback()

    - +

    - + - + - + @@ -176,20 +174,20 @@ Get the prompt callback for obtaining information from the user.
    kim_error_t kim_options_get_prompt_callback kim_error kim_options_get_prompt_callback (kim_options_t kim_options  in_options,
    kim_prompt_callback_t * kim_prompt_callback *  out_prompt_callback 
    out_prompt_callback on exit, the prompt callback specified by in_options. Does not need to be freed but may become invalid when in_options is freed.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    Default value
    kim_prompt_callback_default
    -
    See also:
    kim_options_set_prompt_callback()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    Default value
    kim_prompt_callback_default
    +
    See also:
    kim_options_set_prompt_callback()

    - +

    - + - + @@ -216,21 +214,21 @@ Set caller-specific data for use in library callbacks.
    kim_error_t kim_options_set_data kim_error kim_options_set_data (kim_options_t kim_options  io_options,
    in_data a pointer to caller-specific data.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    This option can be used by the caller to store a pointer to data needed when handling a callback. The KIM library does not use this options data in any way.
    Default value
    NULL (no data is set by default)
    -
    See also:
    kim_options_get_data()
    +
    See also:
    kim_options_get_data()

    - +

    - + - + @@ -257,123 +255,27 @@ Get caller-specific data for use in library callbacks.
    kim_error_t kim_options_get_data kim_error kim_options_get_data (kim_options_t kim_options  in_options,
    out_data on exit, the pointer to caller specific data specified by in_options. Does not need to be freed but may become invalid when in_options is freed.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    This option can be used by the caller to store a pointer to data needed when handling a callback. The KIM library does not use this options data in any way.
    Default value
    NULL (no data is set by default)
    -
    See also:
    kim_options_set_data()
    +
    See also:
    kim_options_set_data()

    - +

    - + - + - - - - - - - - - - - - - - -
    kim_error_t kim_options_set_prompt_response kim_error kim_options_set_start_time (kim_options_t kim_options  io_options,
    kim_prompt_type_t  in_prompt_type,
    void *  in_response 
    )
    -
    -
    - -

    -Set a response for a prompt for use when acquiring credentials. -

    -

    Parameters:
    - - - - -
    io_options an options object to modify.
    in_prompt_type a type of prompt.
    in_response a response to prompts of in_prompt_type.
    -
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    Note:
    Each response only overrides the first prompt of a given prompt type. If multiple prompts of the same type are required, or if a prompt of a different type is requested, the prompt callback will be called to obtain user input. If you want to turn off prompting entirely, call kim_options_set_prompt_callback() with kim_prompt_callback_none.
    -
    Default value
    NULL (no response is set by default)
    -
    See also:
    kim_options_get_prompt_response()
    - -
    -

    - -

    -
    - - - - - - - - - - - - - - - - - - - - - - - - -
    kim_error_t kim_options_get_prompt_response (kim_options_t  in_options,
    kim_prompt_type_t  in_prompt_type,
    void **  out_response 
    )
    -
    -
    - -

    -Get the response for a prompt for use when acquiring credentials. -

    -

    Parameters:
    - - - - -
    in_options an options object.
    in_prompt_type a type of prompt.
    out_response on exit, the response to prompts of type in_prompt_type specified by in_options. Does not need to be freed but may become invalid when in_options is freed.
    -
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    Note:
    Each response only overrides the first prompt of a given prompt type. If multiple prompts of the same type are required, or if a prompt of a different type is requested, the prompt callback will be called to obtain user input. If you want to turn off prompting entirely, call kim_options_set_prompt_callback() with kim_prompt_callback_none.
    -
    Default value
    NULL (no response is set by default)
    -
    See also:
    kim_options_set_prompt_response()
    - -
    -

    - -

    -
    - - - - - - - - - - - + @@ -394,27 +296,27 @@ Set the date when a credential should become valid.
    kim_error_t kim_options_set_start_time (kim_options_t  io_options,
    kim_time_t kim_time  in_start_time 
    in_start_time a start date (in seconds since January 1, 1970). Set to KIM_OPTIONS_START_IMMEDIATELY for the acquired credential to be valid immediately.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    When using a start time in the future, once the start time has been reached the credential must be validated before it can be used.
    Default value
    0, indicating "now". The credential will be valid immediately.
    -
    See also:
    kim_options_get_start_time(), kim_credential_validate(), kim_ccache_validate(), kim_identity_validate()
    +
    See also:
    kim_options_get_start_time(), kim_credential_validate(), kim_ccache_validate(), kim_identity_validate()

    - +

    - + - + - + @@ -435,27 +337,27 @@ Get the date when a credential should become valid.
    kim_error_t kim_options_get_start_time kim_error kim_options_get_start_time (kim_options_t kim_options  in_options,
    kim_time_t * kim_time *  out_start_time 
    out_start_time on exit, the start date (in seconds since January 1, 1970) specified by in_options. KIM_OPTIONS_START_IMMEDIATELY indicates the credential will be valid immediately.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    When using a start time in the future, once the start time has been reached the credential must be validated before it can be used.
    Default value
    0, indicating "now". The credential will be valid immediately.
    -
    See also:
    kim_options_set_start_time(), kim_credential_validate(), kim_ccache_validate(), kim_identity_validate()
    +
    See also:
    kim_options_set_start_time(), kim_credential_validate(), kim_ccache_validate(), kim_identity_validate()

    - +

    - + - + - + @@ -476,27 +378,27 @@ Set the duration during which a credential should be valid.
    kim_error_t kim_options_set_lifetime kim_error kim_options_set_lifetime (kim_options_t kim_options  io_options,
    kim_lifetime_t kim_lifetime  in_lifetime 
    in_lifetime a lifetime duration (in seconds).
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    KDCs have a maximum allowed lifetime per identity (usually 10 to 21 hours). As a result the credential will actually have a lifetime which is the minimum of in_lifetime and the KDC's maximum allowed lifetime.
    -
    See also:
    kim_options_get_lifetime()
    +
    See also:
    kim_options_get_lifetime()
    Default value
    Read from the user's preferences and the Kerberos configuration. 10 hours if unspecified.

    - +

    - + - + - + @@ -517,27 +419,27 @@ Get the duration during which an acquired credential should be valid.
    kim_error_t kim_options_get_lifetime kim_error kim_options_get_lifetime (kim_options_t kim_options  in_options,
    kim_lifetime_t * kim_lifetime *  out_lifetime 
    out_lifetime on exit, the lifetime duration (in seconds) specified in in_options.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    KDCs have a maximum allowed lifetime per identity (usually 10 to 21 hours). As a result the credential will actually have a lifetime which is the minimum of in_lifetime and the KDC's maximum allowed lifetime.
    Default value
    Read from the user's preferences and the Kerberos configuration. 10 hours if unspecified.
    -
    See also:
    kim_options_set_lifetime()
    +
    See also:
    kim_options_set_lifetime()

    - +

    - + - + - + @@ -558,26 +460,26 @@ Set whether or not to request a renewable credential.
    kim_error_t kim_options_set_renewable kim_error kim_options_set_renewable (kim_options_t kim_options  io_options,
    kim_boolean_t kim_boolean  in_renewable 
    in_renewable a boolean value indicating whether or not to request a renewable credential.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Default value
    Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
    -
    See also:
    kim_options_get_renewable()
    +
    See also:
    kim_options_get_renewable()

    - +

    - + - + - + @@ -598,26 +500,26 @@ Get whether or not to request a renewable credential.
    kim_error_t kim_options_get_renewable kim_error kim_options_get_renewable (kim_options_t kim_options  in_options,
    kim_boolean_t * kim_boolean *  out_renewable 
    out_renewable on exit, a boolean value indicating whether or in_options will request a renewable credential.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Default value
    Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
    -
    See also:
    kim_options_set_renewable()
    +
    See also:
    kim_options_set_renewable()

    - +

    - + - + - + @@ -638,27 +540,27 @@ Set the duration during which a valid credential should be renewable.
    kim_error_t kim_options_set_renewal_lifetime kim_error kim_options_set_renewal_lifetime (kim_options_t kim_options  io_options,
    kim_lifetime_t kim_lifetime  in_renewal_lifetime 
    in_renewal_lifetime a renewal lifetime duration (in seconds).
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    KDCs have a maximum allowed renewal lifetime per identity (usually 10 to 21 hours). As a result the credential will actually have a lifetime which is the minimum of in_lifetime and the KDC's maximum allowed lifetime.
    Default value
    Read from the user's preferences and the Kerberos configuration. 7 days if unspecified.
    -
    See also:
    kim_options_get_renewal_lifetime(), kim_identity_renew(), kim_credential_renew(), kim_ccache_renew()
    +
    See also:
    kim_options_get_renewal_lifetime(), kim_identity_renew(), kim_credential_renew(), kim_ccache_renew()

    - +

    - + - + - + @@ -679,27 +581,27 @@ Get the duration during which a valid credential should be renewable.
    kim_error_t kim_options_get_renewal_lifetime kim_error kim_options_get_renewal_lifetime (kim_options_t kim_options  in_options,
    kim_lifetime_t * kim_lifetime *  out_renewal_lifetime 
    out_renewal_lifetime on exit, the renewal lifetime duration (in seconds) specified in in_options.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    KDCs have a maximum allowed lifetime per identity (usually 10 to 21 hours). As a result the credential will actually have a lifetime which is the minimum of in_lifetime and the KDC's maximum allowed lifetime.
    Default value
    Read from the user's preferences and the Kerberos configuration. 7 days if unspecified.
    -
    See also:
    kim_options_set_renewal_lifetime(), kim_identity_renew(), kim_credential_renew(), kim_ccache_renew()
    +
    See also:
    kim_options_set_renewal_lifetime(), kim_identity_renew(), kim_credential_renew(), kim_ccache_renew()

    - +

    - + - + - + @@ -720,26 +622,26 @@ Set whether or not to request a forwardable credential.
    kim_error_t kim_options_set_forwardable kim_error kim_options_set_forwardable (kim_options_t kim_options  io_options,
    kim_boolean_t kim_boolean  in_forwardable 
    in_forwardable a boolean value indicating whether or not to request a forwardable credential.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Default value
    Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
    -
    See also:
    kim_options_get_forwardable()
    +
    See also:
    kim_options_get_forwardable()

    - +

    - + - + - + @@ -760,26 +662,26 @@ Get whether or not to request a forwardable credential.
    kim_error_t kim_options_get_forwardable kim_error kim_options_get_forwardable (kim_options_t kim_options  in_options,
    kim_boolean_t * kim_boolean *  out_forwardable 
    out_forwardable on exit, a boolean value indicating whether or in_options will request a forwardable credential.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Default value
    Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
    -
    See also:
    kim_options_set_forwardable()
    +
    See also:
    kim_options_set_forwardable()

    - +

    - + - + - + @@ -800,26 +702,26 @@ Set whether or not to request a proxiable credential.
    kim_error_t kim_options_set_proxiable kim_error kim_options_set_proxiable (kim_options_t kim_options  io_options,
    kim_boolean_t kim_boolean  in_proxiable 
    in_proxiable a boolean value indicating whether or not to request a proxiable credential.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Default value
    Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
    -
    See also:
    kim_options_get_proxiable()
    +
    See also:
    kim_options_get_proxiable()

    - +

    - + - + - + @@ -840,26 +742,26 @@ Get whether or not to request a proxiable credential.
    kim_error_t kim_options_get_proxiable kim_error kim_options_get_proxiable (kim_options_t kim_options  in_options,
    kim_boolean_t * kim_boolean *  out_proxiable 
    out_proxiable on exit, a boolean value indicating whether or in_options will request a proxiable credential.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Default value
    Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
    -
    See also:
    kim_options_set_proxiable()
    +
    See also:
    kim_options_set_proxiable()

    - +

    - + - + - + @@ -880,26 +782,26 @@ Set whether or not to request an addressless credential.
    kim_error_t kim_options_set_addressless kim_error kim_options_set_addressless (kim_options_t kim_options  io_options,
    kim_boolean_t kim_boolean  in_addressless 
    in_addressless a boolean value indicating whether or not to request an addressless credential.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Default value
    Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
    -
    See also:
    kim_options_get_addressless()
    +
    See also:
    kim_options_get_addressless()

    - +

    - + - + - + @@ -920,26 +822,26 @@ Get whether or not to request an addressless credential.
    kim_error_t kim_options_get_addressless kim_error kim_options_get_addressless (kim_options_t kim_options  in_options,
    kim_boolean_t * kim_boolean *  out_addressless 
    out_addressless on exit, a boolean value indicating whether or in_options will request an addressless credential.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Default value
    Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
    -
    See also:
    kim_options_set_addressless()
    +
    See also:
    kim_options_set_addressless()

    - +

    - + - + - + @@ -960,26 +862,26 @@ Set the service name to request a credential for.
    kim_error_t kim_options_set_service_name kim_error kim_options_set_service_name (kim_options_t kim_options  io_options,
    kim_string_t kim_string  in_service_name 
    in_service_name a service name.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Default value
    NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service.
    -
    See also:
    kim_options_get_service_name()
    +
    See also:
    kim_options_get_service_name()

    - +

    - + - + - + @@ -997,23 +899,23 @@ Get the service name to request a credential for.
    Parameters:
    kim_error_t kim_options_get_service_name kim_error kim_options_get_service_name (kim_options_t kim_options  in_options,
    kim_string_t * kim_string *  out_service_name 
    - +
    in_options an options object.
    out_service_name on exit, the service name specified in in_options. Must be freed with kim_string_free().
    out_service_name on exit, the service name specified in in_options. Must be freed with kim_string_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Default value
    NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service.
    -
    See also:
    kim_options_set_service_name()
    +
    See also:
    kim_options_set_service_name()

    - +

    - + @@ -1033,7 +935,7 @@ Free memory associated with an options object.

    -

    Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  +
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/group__kim__preferences__reference.html b/doc/kim/html/group__kim__preferences__reference.html index 27db8f41a..70ed55e94 100644 --- a/doc/kim/html/group__kim__preferences__reference.html +++ b/doc/kim/html/group__kim__preferences__reference.html @@ -9,38 +9,41 @@

    Functions

    +
  • kim_error kim_preferences_create (kim_preferences *out_preferences) +
    Create a new preferences object from the current user's preferences.
  • kim_error kim_preferences_copy (kim_preferences *out_preferences, kim_preferences in_preferences) +
    Copy a preferences object.
  • kim_error kim_preferences_set_options (kim_preferences io_preferences, kim_options in_options) +
    Set the user's preferred options.
  • kim_error kim_preferences_get_options (kim_preferences in_preferences, kim_options *out_options) +
    Get the user's preferred options.
  • kim_error kim_preferences_set_remember_options (kim_preferences io_preferences, kim_boolean in_remember_options) +
    Set whether or not to remember the last options the user used to acquire a credential.
  • kim_error kim_preferences_get_remember_options (kim_preferences in_preferences, kim_boolean *out_remember_options) +
    Get whether or not to remember the last options the user used to acquire a credential.
  • kim_error kim_preferences_set_client_identity (kim_preferences io_preferences, kim_identity in_client_identity) +
    Set the user's preferred client identity.
  • kim_error kim_preferences_get_client_identity (kim_preferences in_preferences, kim_identity *out_client_identity) +
    Get the user's preferred client identity.
  • kim_error kim_preferences_set_remember_client_identity (kim_preferences io_preferences, kim_boolean in_remember_client_identity) +
    Set whether or not to remember the last client identity the user acquired a credential for.
  • kim_error kim_preferences_get_remember_client_identity (kim_preferences in_preferences, kim_boolean *out_remember_client_identity) +
    Get whether or not to remember the last client identity the user acquired a credential for.
  • kim_error kim_preferences_set_minimum_lifetime (kim_preferences io_preferences, kim_lifetime in_minimum_lifetime) +
    Set the minimum credential lifetime for GUI credential lifetime controls.
  • kim_error kim_preferences_get_minimum_lifetime (kim_preferences in_preferences, kim_lifetime *out_minimum_lifetime) +
    Get the minimum credential lifetime for GUI credential lifetime controls.
  • kim_error kim_preferences_set_maximum_lifetime (kim_preferences io_preferences, kim_lifetime in_maximum_lifetime) +
    Set the maximum credential lifetime for GUI credential lifetime controls.
  • kim_error kim_preferences_get_maximum_lifetime (kim_preferences in_preferences, kim_lifetime *out_maximum_lifetime) +
    Get the maximum credential lifetime for GUI credential lifetime controls.
  • kim_error kim_preferences_set_minimum_renewal_lifetime (kim_preferences io_preferences, kim_lifetime in_minimum_renewal_lifetime) +
    Set the minimum credential renewal lifetime for GUI credential lifetime controls.
  • kim_error kim_preferences_get_minimum_renewal_lifetime (kim_preferences in_preferences, kim_lifetime *out_minimum_renewal_lifetime) +
    Get the minimum credential renewal lifetime for GUI credential lifetime controls.
  • kim_error kim_preferences_set_maximum_renewal_lifetime (kim_preferences io_preferences, kim_lifetime in_maximum_renewal_lifetime) +
    Set the maximum credential renewal lifetime for GUI credential lifetime controls.
  • kim_error kim_preferences_get_maximum_renewal_lifetime (kim_preferences in_preferences, kim_lifetime *out_maximum_renewal_lifetime) +
    Get the maximum credential renewal lifetime for GUI credential lifetime controls.
  • kim_error kim_preferences_get_number_of_favorite_identities (kim_preferences in_preferences, kim_count *out_number_of_identities) +
    Get the number of favorite identities in a preferences object.
  • kim_error kim_preferences_get_favorite_identity_at_index (kim_preferences in_preferences, kim_count in_index, kim_identity *out_identity, kim_options *out_options) +
    Get the Nth favorite identity in a preferences object.
  • kim_error kim_preferences_add_favorite_identity (kim_preferences io_preferences, kim_identity in_identity, kim_options in_options) +
    Add a favorite identity to a preferences object.
  • kim_error kim_preferences_remove_favorite_identity (kim_preferences io_preferences, kim_identity in_identity) +
    Remove a favorite identity from a preferences object.
  • kim_error kim_preferences_remove_all_favorite_identities (kim_preferences io_preferences) +
    Remove all favorite identities in a preferences object.
  • kim_error kim_preferences_synchronize (kim_preferences in_preferences) +
    Synchronize a preferences object with the user's preferences, writing pending changes and reading any changes applied by other processes.
  • void kim_preferences_free (kim_preferences *io_preferences) +
    Free memory associated with a preferences object.

    Function Documentation

    - +
    • void kim_options_free (kim_options_t * kim_options *  io_options  ) 
    - + - + @@ -54,27 +57,27 @@ Create a new preferences object from the current user's preferences.

    Parameters:
    kim_error_t kim_preferences_create kim_error kim_preferences_create (kim_preferences_t * kim_preferences *  out_preferences  ) 
    - +
    out_preferences on exit, a new preferences object. Must be freed with kim_preferences_free().
    out_preferences on exit, a new preferences object. Must be freed with kim_preferences_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -91,28 +94,28 @@ Copy a preferences object.

    Parameters:
    kim_error_t kim_preferences_copy kim_error kim_preferences_copy (kim_preferences_t * kim_preferences *  out_preferences,
    kim_preferences_t kim_preferences  in_preferences 
    - +
    out_preferences on exit, a new preferences object which is a copy of in_preferences. Must be freed with kim_preferences_free().
    out_preferences on exit, a new preferences object which is a copy of in_preferences. Must be freed with kim_preferences_free().
    in_preferences a preferences object.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -133,25 +136,25 @@ Set the user's preferred options.
    kim_error_t kim_preferences_set_options kim_error kim_preferences_set_options (kim_preferences_t kim_preferences  io_preferences,
    kim_options_t kim_options  in_options 
    in_options an options object.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_get_options()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_preferences_get_options()

    - +

    - + - + - + @@ -169,28 +172,28 @@ Get the user's preferred options.
    Parameters:
    kim_error_t kim_preferences_get_options kim_error kim_preferences_get_options (kim_preferences_t kim_preferences  in_preferences,
    kim_options_t * kim_options *  out_options 
    - +
    in_preferences a preferences object.
    out_options on exit, the options specified in in_preferences. Must be freed with kim_options_free().
    out_options on exit, the options specified in in_preferences. Must be freed with kim_options_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_set_options()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_preferences_set_options()

    - +

    - + - + - + @@ -211,25 +214,25 @@ Set whether or not to remember the last options the user used to acquire a crede
    kim_error_t kim_preferences_set_remember_options kim_error kim_preferences_set_remember_options (kim_preferences_t kim_preferences  io_preferences,
    kim_boolean_t kim_boolean  in_remember_options 
    in_remember_options a boolean value indicating whether or not to remember the last options used to acquire a credential.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_get_remember_options()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_preferences_get_remember_options()

    - +

    - + - + - + @@ -250,25 +253,25 @@ Get whether or not to remember the last options the user used to acquire a crede
    kim_error_t kim_preferences_get_remember_options kim_error kim_preferences_get_remember_options (kim_preferences_t kim_preferences  in_preferences,
    kim_boolean_t * kim_boolean *  out_remember_options 
    out_remember_options on exit, a boolean value indicating whether or in_preferences will remember the last options used to acquire a credential.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_set_remember_options()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_preferences_set_remember_options()

    - +

    - + - + - + @@ -289,25 +292,25 @@ Set the user's preferred client identity.
    kim_error_t kim_preferences_set_client_identity kim_error kim_preferences_set_client_identity (kim_preferences_t kim_preferences  io_preferences,
    kim_identity_t kim_identity  in_client_identity 
    in_client_identity a client identity object.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_get_client_identity()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_preferences_get_client_identity()

    - +

    - + - + - + @@ -325,28 +328,28 @@ Get the user's preferred client identity.
    Parameters:
    kim_error_t kim_preferences_get_client_identity kim_error kim_preferences_get_client_identity (kim_preferences_t kim_preferences  in_preferences,
    kim_identity_t * kim_identity *  out_client_identity 
    - +
    in_preferences a preferences object.
    out_client_identity on exit, the client identity specified in in_preferences. Must be freed with kim_identity_free().
    out_client_identity on exit, the client identity specified in in_preferences. Must be freed with kim_identity_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_set_client_identity()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_preferences_set_client_identity()

    - +

    - + - + - + @@ -367,25 +370,25 @@ Set whether or not to remember the last client identity the user acquired a cred
    kim_error_t kim_preferences_set_remember_client_identity kim_error kim_preferences_set_remember_client_identity (kim_preferences_t kim_preferences  io_preferences,
    kim_boolean_t kim_boolean  in_remember_client_identity 
    in_remember_client_identity a boolean value indicating whether or not to remember the last client identity for which a credential was acquired.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_get_remember_client_identity()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_preferences_get_remember_client_identity()

    - +

    - + - + - + @@ -406,25 +409,25 @@ Get whether or not to remember the last client identity the user acquired a cred
    kim_error_t kim_preferences_get_remember_client_identity kim_error kim_preferences_get_remember_client_identity (kim_preferences_t kim_preferences  in_preferences,
    kim_boolean_t * kim_boolean *  out_remember_client_identity 
    out_remember_client_identity on exit, a boolean value indicating whether or in_preferences will remember the last client identity for which a credential was acquired.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_set_remember_client_identity()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_preferences_set_remember_client_identity()

    - +

    - + - + - + @@ -445,25 +448,25 @@ Set the minimum credential lifetime for GUI credential lifetime controls.
    kim_error_t kim_preferences_set_minimum_lifetime kim_error kim_preferences_set_minimum_lifetime (kim_preferences_t kim_preferences  io_preferences,
    kim_lifetime_t kim_lifetime  in_minimum_lifetime 
    in_minimum_lifetime a minimum lifetime indicating how small a lifetime the GUI tools should allow the user to specify for credentials.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_get_minimum_lifetime()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_preferences_get_minimum_lifetime()

    - +

    - + - + - + @@ -484,25 +487,25 @@ Get the minimum credential lifetime for GUI credential lifetime controls.
    kim_error_t kim_preferences_get_minimum_lifetime kim_error kim_preferences_get_minimum_lifetime (kim_preferences_t kim_preferences  in_preferences,
    kim_lifetime_t * kim_lifetime *  out_minimum_lifetime 
    out_minimum_lifetime on exit, the minimum lifetime that GUI tools will allow the user to specify for credentials.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_set_minimum_lifetime()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_preferences_set_minimum_lifetime()

    - +

    - + - + - + @@ -523,25 +526,25 @@ Set the maximum credential lifetime for GUI credential lifetime controls.
    kim_error_t kim_preferences_set_maximum_lifetime kim_error kim_preferences_set_maximum_lifetime (kim_preferences_t kim_preferences  io_preferences,
    kim_lifetime_t kim_lifetime  in_maximum_lifetime 
    in_maximum_lifetime a maximum lifetime indicating how large a lifetime the GUI tools should allow the user to specify for credentials.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_get_maximum_lifetime()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_preferences_get_maximum_lifetime()

    - +

    - + - + - + @@ -562,25 +565,25 @@ Get the maximum credential lifetime for GUI credential lifetime controls.
    kim_error_t kim_preferences_get_maximum_lifetime kim_error kim_preferences_get_maximum_lifetime (kim_preferences_t kim_preferences  in_preferences,
    kim_lifetime_t * kim_lifetime *  out_maximum_lifetime 
    out_maximum_lifetime on exit, the maximum lifetime that GUI tools will allow the user to specify for credentials.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_set_maximum_lifetime()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_preferences_set_maximum_lifetime()

    - +

    - + - + - + @@ -601,25 +604,25 @@ Set the minimum credential renewal lifetime for GUI credential lifetime controls
    kim_error_t kim_preferences_set_minimum_renewal_lifetime kim_error kim_preferences_set_minimum_renewal_lifetime (kim_preferences_t kim_preferences  io_preferences,
    kim_lifetime_t kim_lifetime  in_minimum_renewal_lifetime 
    in_minimum_renewal_lifetime a minimum lifetime indicating how small a lifetime the GUI tools should allow the user to specify for credential renewal.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_get_minimum_renewal_lifetime()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_preferences_get_minimum_renewal_lifetime()

    - +

    - + - + - + @@ -640,25 +643,25 @@ Get the minimum credential renewal lifetime for GUI credential lifetime controls
    kim_error_t kim_preferences_get_minimum_renewal_lifetime kim_error kim_preferences_get_minimum_renewal_lifetime (kim_preferences_t kim_preferences  in_preferences,
    kim_lifetime_t * kim_lifetime *  out_minimum_renewal_lifetime 
    out_minimum_renewal_lifetime on exit, the minimum lifetime that GUI tools will allow the user to specify for credential renewal.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_set_minimum_renewal_lifetime()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_preferences_set_minimum_renewal_lifetime()

    - +

    - + - + - + @@ -679,25 +682,25 @@ Set the maximum credential renewal lifetime for GUI credential lifetime controls
    kim_error_t kim_preferences_set_maximum_renewal_lifetime kim_error kim_preferences_set_maximum_renewal_lifetime (kim_preferences_t kim_preferences  io_preferences,
    kim_lifetime_t kim_lifetime  in_maximum_renewal_lifetime 
    in_maximum_renewal_lifetime a maximum lifetime indicating how large a lifetime the GUI tools should allow the user to specify for credential renewal.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_get_minimum_renewal_lifetime()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_preferences_get_minimum_renewal_lifetime()

    - +

    - + - + - + @@ -718,26 +721,26 @@ Get the maximum credential renewal lifetime for GUI credential lifetime controls
    kim_error_t kim_preferences_get_maximum_renewal_lifetime kim_error kim_preferences_get_maximum_renewal_lifetime (kim_preferences_t kim_preferences  in_preferences,
    kim_lifetime_t * kim_lifetime *  out_maximum_renewal_lifetime 
    out_maximum_renewal_lifetime on exit, the maximum lifetime that GUI tools will allow the user to specify for credential renewal.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_set_minimum_renewal_lifetime()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_preferences_set_minimum_renewal_lifetime()

    - +

    - + - - + + - - + + @@ -749,34 +752,45 @@ Get the maximum credential renewal lifetime for GUI credential lifetime controls

    -Set the user's preferred list of identities. +Get the number of favorite identities in a preferences object.

    Parameters:
    kim_error_t kim_preferences_set_favorite_identities kim_error kim_preferences_get_number_of_favorite_identities (kim_preferences_t  io_preferences, kim_preferences  in_preferences,
    kim_favorite_identities_t  in_favorite_identities kim_count *  out_number_of_identities 
    - - + +
    io_preferences a preferences object to modify.
    in_favorite_identities a favorite identities object. See KIM Favorite Identities Overview for more information on KIM Favorite Identities.
    in_preferences a preferences object.
    out_number_of_identities on exit, the number of identities in in_preferences.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_get_favorite_identities()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - - + + + + + + + + + + + + + + @@ -788,27 +802,139 @@ Set the user's preferred list of identities.

    -Get the user's preferred list of identities. +Get the Nth favorite identity in a preferences object.

    Parameters:
    kim_error_t kim_preferences_get_favorite_identities kim_error kim_preferences_get_favorite_identity_at_index (kim_preferences_t kim_preferences  in_preferences,
    kim_favorite_identities_t *  out_favorite_identities kim_count  in_index,
    kim_identity *  out_identity,
    kim_options *  out_options 
    - - + + + + +
    in_preferences a preferences object.
    out_favorite_identities on exit, a copy of the favorite identities specified in in_preferences. See KIM Favorite Identities Overview for more information on KIM Favorite Identities. Must be freed with kim_favorite_identities_free().
    kim_preferences a preferences object.
    in_index a index into the identities list (starting at 0).
    out_identity on exit, the identity at in_index in in_preferences. Must be freed with kim_string_free().
    out_options on exit, the options associated with identity at in_index in in_favorite_identities. May be KIM_OPTIONS_DEFAULT. Pass NULL if you do not want the options associated with the identity. Must be freed with kim_options_free().
    + +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    + +
    +

    + +

    +
    + + + + + + + + + + + + + + + + + + + + + + + + +
    kim_error kim_preferences_add_favorite_identity (kim_preferences  io_preferences,
    kim_identity  in_identity,
    kim_options  in_options 
    )
    +
    +
    + +

    +Add a favorite identity to a preferences object. +

    +

    Parameters:
    + + + + +
    io_preferences a preferences object.
    in_identity an identity to add to io_preferences.
    in_options options which will be associated with that identity. Use KIM_OPTIONS_DEFAULT if the identity should use the user's default options.
    +
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    + +
    +

    + +

    +
    + + + + + + + + + + + + + + + + + + +
    kim_error kim_preferences_remove_favorite_identity (kim_preferences  io_preferences,
    kim_identity  in_identity 
    )
    +
    +
    + +

    +Remove a favorite identity from a preferences object. +

    +

    Parameters:
    + + + +
    io_preferences a preferences object.
    in_identity an identity to remove from io_preferences.
    +
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    + +
    +

    + +

    +
    + + + + + + + + + +
    kim_error kim_preferences_remove_all_favorite_identities (kim_preferences  io_preferences  ) 
    +
    +
    + +

    +Remove all favorite identities in a preferences object. +

    +

    Parameters:
    + +
    io_preferences a preferences object.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_preferences_set_favorite_identities()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + @@ -825,18 +951,18 @@ Synchronize a preferences object with the user's preferences, writing pending ch
    kim_error_t kim_preferences_synchronize kim_error kim_preferences_synchronize (kim_preferences_t kim_preferences  in_preferences  ) 
    in_preferences a preferences object.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + @@ -856,7 +982,7 @@ Free memory associated with a preferences object.

    -

    Generated on Wed May 7 15:22:20 2008 for Kerberos Identity Management by  +
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/group__kim__selection__hints__reference.html b/doc/kim/html/group__kim__selection__hints__reference.html index 85d5c15ab..4676c7a4f 100644 --- a/doc/kim/html/group__kim__selection__hints__reference.html +++ b/doc/kim/html/group__kim__selection__hints__reference.html @@ -7,52 +7,57 @@

    KIM Selection Hints Reference Documentation

    +

    Defines

    +
      +
    • +#define kim_hint_key_client_realm   "kim_hint_key_client_realm" +
    • +#define kim_hint_key_user   "kim_hint_key_user" +
    • +#define kim_hint_key_service_realm   "kim_hint_key_service_realm" +
    • +#define kim_hint_key_service   "kim_hint_key_service" +
    • +#define kim_hint_key_server   "kim_hint_key_server" +
    • +#define kim_hint_key_service_identity   "kim_hint_key_service_identity" +

    Functions

    +
  • kim_error kim_selection_hints_create (kim_selection_hints *out_selection_hints, kim_string in_application_identifier) +
    Create a new selection hints object.
  • kim_error kim_selection_hints_copy (kim_selection_hints *out_selection_hints, kim_selection_hints in_selection_hints) +
    Copy a selection hints object.
  • kim_error kim_selection_hints_set_hint (kim_selection_hints io_selection_hints, kim_string in_hint_key, kim_string in_hint_string) +
    Set the string value of a hint used for identity selection.
  • kim_error kim_selection_hints_get_hint (kim_selection_hints in_selection_hints, kim_string in_hint_key, kim_string *out_hint_string) +
    Get the string value of a hint used for identity selection.
  • kim_error kim_selection_hints_set_application_name (kim_selection_hints io_selection_hints, kim_string in_application_name) +
    Set the application name for use in user interaction.
  • kim_error kim_selection_hints_get_application_name (kim_selection_hints in_selection_hints, kim_string *out_application_name) +
    Get the application name for use in user interaction.
  • kim_error kim_selection_hints_set_explanation (kim_selection_hints io_selection_hints, kim_string in_explanation) +
    Set the strings used to prompt the user to select the identity.
  • kim_error kim_selection_hints_get_explanation (kim_selection_hints in_selection_hints, kim_string *out_explanation) +
    Get the strings used to prompt the user to select the identity.
  • kim_error kim_selection_hints_set_options (kim_selection_hints io_selection_hints, kim_options in_options) +
    Set the options which will be used if credentials need to be acquired.
  • kim_error kim_selection_hints_get_options (kim_selection_hints in_selection_hints, kim_options *out_options) +
    Get the options which will be used if credentials need to be acquired.
  • kim_error kim_selection_hints_set_allow_user_interaction (kim_selection_hints in_selection_hints, kim_boolean in_allow_user_interaction) +
    Set whether or not KIM may interact with the user to select an identity.
  • kim_error kim_selection_hints_get_allow_user_interaction (kim_selection_hints in_selection_hints, kim_boolean *out_allow_user_interaction) +
    Get whether or not KIM may interact with the user to select an identity.
  • kim_error kim_selection_hints_set_remember_identity (kim_selection_hints in_selection_hints, kim_boolean in_remember_identity) +
    Set whether or not KIM will use cached mappings for this selection hints object.
  • kim_error kim_selection_hints_get_remember_identity (kim_selection_hints in_selection_hints, kim_boolean *out_remember_identity) +
    Get whether or not KIM will use cache mappings for this selection hints object.
  • kim_error kim_selection_hints_get_identity (kim_selection_hints in_selection_hints, kim_identity *out_identity) +
    Choose a client identity based on selection hints.
  • kim_error kim_selection_hints_remember_identity (kim_selection_hints in_selection_hints, kim_identity in_identity) +
    Add an entry for the selection hints to the selection hints cache, replacing any existing entry.
  • kim_error kim_selection_hints_forget_identity (kim_selection_hints in_selection_hints) +
    Remove an entry for the selection hints from the selection hints cache.
  • void kim_selection_hints_free (kim_selection_hints *io_selection_hints) +
    Free memory associated with a selection hints object.

    Function Documentation

    - +
    • void kim_preferences_free (kim_preferences_t * kim_preferences *  io_preferences  ) 
    - + - + - + @@ -69,28 +74,28 @@ Create a new selection hints object.

    Parameters:
    kim_error_t kim_selection_hints_create kim_error kim_selection_hints_create (kim_selection_hints_t * kim_selection_hints *  out_selection_hints,
    kim_string_t kim_string  in_application_identifier 
    - +
    out_selection_hints on exit, a new selection hints object. Must be freed with kim_selection_hints_free().
    out_selection_hints on exit, a new selection hints object. Must be freed with kim_selection_hints_free().
    in_application_identifier an application identifier string. Java-style identifiers are recommended to avoid cache entry collisions (eg: "com.example.MyApplication")
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + @@ -107,341 +112,35 @@ Copy a selection hints object.

    Parameters:
    kim_error_t kim_selection_hints_copy kim_error kim_selection_hints_copy (kim_selection_hints_t * kim_selection_hints *  out_selection_hints,
    kim_selection_hints_t kim_selection_hints  in_selection_hints 
    - - -
    out_selection_hints on exit, a new selection hints object which is a copy of in_selection_hints. Must be freed with kim_selection_hints_free().
    in_selection_hints a selection hints object.
    - -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    - -
    -

    - -

    -
    - - - - - - - - - - - - - - - - - - -
    kim_error_t kim_selection_hints_set_service_identity_hint (kim_selection_hints_t  io_selection_hints,
    kim_identity_t  in_service_identity 
    )
    -
    -
    - -

    -Set the preferred service identity. -

    -

    Parameters:
    - - - -
    io_selection_hints a selection hints object to modify.
    in_service_identity a service identity.
    -
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_get_service_identity_hint()
    - -
    -

    - -

    -
    - - - - - - - - - - - - - - - - - - -
    kim_error_t kim_selection_hints_get_service_identity_hint (kim_selection_hints_t  in_selection_hints,
    kim_identity_t *  out_service_identity 
    )
    -
    -
    - -

    -Get the preferred service identity. -

    -

    Parameters:
    - - - -
    in_selection_hints a selection hints object.
    out_service_identity on exit, the service identity specified in in_selection_hints. Must be freed with kim_identity_free().
    -
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_set_service_identity_hint()
    - -
    -

    - -

    -
    - - - - - - - - - - - - - - - - - - -
    kim_error_t kim_selection_hints_set_client_realm_hint (kim_selection_hints_t  io_selection_hints,
    kim_string_t  in_client_realm 
    )
    -
    -
    - -

    -Set the preferred client realm. -

    -

    Parameters:
    - - - -
    io_selection_hints a selection hints object to modify.
    in_client_realm a client realm string.
    -
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_get_client_realm_hint()
    - -
    -

    - -

    -
    - - - - - - - - - - - - - - - - - - -
    kim_error_t kim_selection_hints_get_client_realm_hint (kim_selection_hints_t  in_selection_hints,
    kim_string_t *  out_client_realm 
    )
    -
    -
    - -

    -Get the preferred client realm. -

    -

    Parameters:
    - - - -
    in_selection_hints a selection hints object.
    out_client_realm on exit, the client realm string specified in in_selection_hints. Must be freed with kim_string_free().
    -
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_set_client_realm_hint()
    - -
    -

    - -

    -
    - - - - - - - - - - - - - - - - - - -
    kim_error_t kim_selection_hints_set_user_hint (kim_selection_hints_t  io_selection_hints,
    kim_string_t  in_user 
    )
    -
    -
    - -

    -Set the preferred user name. -

    -

    Parameters:
    - - - -
    io_selection_hints a selection hints object to modify.
    in_user a user name string.
    -
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_get_user_hint()
    - -
    -

    - -

    -
    - - - - - - - - - - - - - - - - - - -
    kim_error_t kim_selection_hints_get_user_hint (kim_selection_hints_t  in_selection_hints,
    kim_string_t *  out_user 
    )
    -
    -
    - -

    -Get the preferred user name. -

    -

    Parameters:
    - + -
    out_selection_hints on exit, a new selection hints object which is a copy of in_selection_hints. Must be freed with kim_selection_hints_free().
    in_selection_hints a selection hints object.
    out_user on exit, the user name string specified in in_selection_hints. Must be freed with kim_string_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_set_user_hint()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - - - - - - - - -
    kim_error_t kim_selection_hints_set_service_realm_hint kim_error kim_selection_hints_set_hint (kim_selection_hints_t kim_selection_hints  io_selection_hints,
    kim_string_t  in_service_realm 
    )
    -
    -
    - -

    -Set the preferred service realm. -

    -

    Parameters:
    - - - -
    io_selection_hints a selection hints object to modify.
    in_service_realm a service realm string.
    -
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_get_service_realm_hint()
    - -
    -

    - -

    -
    - - - - - - - - - - - - - - - - - - -
    kim_error_t kim_selection_hints_get_service_realm_hint (kim_selection_hints_t  io_selection_hints,
    kim_string_t *  out_service_realm 
    )
    -
    -
    - -

    -Get the preferred service realm. -

    -

    Parameters:
    - - - -
    io_selection_hints a selection hints object.
    out_service_realm on exit, the service realm string specified in in_selection_hints. Must be freed with kim_string_free().
    -
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_set_service_realm_hint()
    - -
    -

    - -

    -
    - - - - - - + + - - + + @@ -453,112 +152,41 @@ Get the preferred service realm.

    -Set the preferred service name. +Set the string value of a hint used for identity selection.

    Parameters:
    kim_error_t kim_selection_hints_set_service_hint (kim_selection_hints_t  io_selection_hints, kim_string  in_hint_key,
    kim_string_t  in_service kim_string  in_hint_string 
    - + +
    io_selection_hints a selection hints object to modify.
    in_service a service name string.
    in_hint_key A string representing the type of hint to set.
    in_hint_string A string representation of a hint for in_hint_key to set in in_selection_hints.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_get_service_hint()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_selection_hints_get_hint()

    - +

    - + - + - - - - - - - - -
    kim_error_t kim_selection_hints_get_service_hint kim_error kim_selection_hints_get_hint (kim_selection_hints_t kim_selection_hints  in_selection_hints,
    kim_string_t *  out_service 
    )
    -
    -
    - -

    -Get the preferred service name. -

    -

    Parameters:
    - - - -
    in_selection_hints a selection hints object.
    out_service on exit, the service name string specified in in_selection_hints. Must be freed with kim_string_free().
    -
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_set_service_hint()
    - -
    -

    - -

    -
    - - - - - - - - - - - - - - - - - - -
    kim_error_t kim_selection_hints_set_server_hint (kim_selection_hints_t  io_selection_hints,
    kim_string_t  in_server 
    )
    -
    -
    - -

    -Set the preferred server host name. -

    -

    Parameters:
    - - - -
    io_selection_hints a selection hints object to modify.
    in_server a server host name string.
    -
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_get_server_hint()
    - -
    -

    - -

    -
    - - - - - - + + - - + + @@ -570,33 +198,34 @@ Set the preferred server host name.

    -Get the preferred server host name. +Get the string value of a hint used for identity selection.

    Parameters:
    kim_error_t kim_selection_hints_get_server_hint (kim_selection_hints_t  in_selection_hints, kim_string  in_hint_key,
    kim_string_t *  out_server kim_string *  out_hint_string 
    - + +
    in_selection_hints a selection hints object.
    out_server on exit, the server host name string specified in in_selection_hints. Must be freed with kim_string_free().
    in_hint_key A string representing the type of hint to obtain.
    out_hint_string A string representation of the hint in_hint_key in in_selection_hints. Must be freed with kim_string_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_set_server_hint()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_selection_hints_set_hint()

    - +

    - + - + - + @@ -618,25 +247,25 @@ Set the application name for use in user interaction.
    kim_error_t kim_selection_hints_set_application_name kim_error kim_selection_hints_set_application_name (kim_selection_hints_t kim_selection_hints  io_selection_hints,
    kim_string_t kim_string  in_application_name 
    Note:
    If you do not call this function KIM will attempt to determine the application name at runtime. If that fails (the functionality is only available on some platforms) then KIM will use the application identity string.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_get_application_name()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_selection_hints_get_application_name()

    - +

    - + - + - + @@ -654,28 +283,28 @@ Get the application name for use in user interaction.
    Parameters:
    kim_error_t kim_selection_hints_get_application_name kim_error kim_selection_hints_get_application_name (kim_selection_hints_t kim_selection_hints  in_selection_hints,
    kim_string_t * kim_string *  out_application_name 
    - +
    in_selection_hints a selection hints object.
    out_application_name on exit, the localized full name of the application specified in in_selection_hints. Must be freed with kim_string_free().
    out_application_name on exit, the localized full name of the application specified in in_selection_hints. Must be freed with kim_string_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_set_application_name()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_selection_hints_set_application_name()

    - +

    - + - + - + @@ -696,26 +325,26 @@ Set the strings used to prompt the user to select the identity.
    kim_error_t kim_selection_hints_set_explanation kim_error kim_selection_hints_set_explanation (kim_selection_hints_t kim_selection_hints  io_selection_hints,
    kim_string_t kim_string  in_explanation 
    in_explanation a localized string describing why the caller needs the identity.
    -
    Note:
    If the application only does one thing (the reason it needs an identity is obvious) then you may not need to call this function. You may still need to call kim_selection_hints_set_application_name()
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_get_explanation()
    +
    Note:
    If the application only does one thing (the reason it needs an identity is obvious) then you may not need to call this function. You may still need to call kim_selection_hints_set_application_name()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_selection_hints_get_explanation()

    - +

    - + - + - + @@ -733,28 +362,28 @@ Get the strings used to prompt the user to select the identity.
    Parameters:
    kim_error_t kim_selection_hints_get_explanation kim_error kim_selection_hints_get_explanation (kim_selection_hints_t kim_selection_hints  in_selection_hints,
    kim_string_t * kim_string *  out_explanation 
    - +
    in_selection_hints a selection hints object.
    out_explanation on exit, the localized string specified in in_selection_hints which describes why the caller needs the identity. May be NULL. If non-NULL, must be freed with kim_string_free().
    out_explanation on exit, the localized string specified in in_selection_hints which describes why the caller needs the identity. May be NULL. If non-NULL, must be freed with kim_string_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_set_explanation()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_selection_hints_set_explanation()

    - +

    - + - + - + @@ -775,25 +404,25 @@ Set the options which will be used if credentials need to be acquired.
    kim_error_t kim_selection_hints_set_options kim_error kim_selection_hints_set_options (kim_selection_hints_t kim_selection_hints  io_selection_hints,
    kim_options_t kim_options  in_options 
    in_options options to control credential acquisition.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_get_options()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_selection_hints_get_options()

    - +

    - + - + - + @@ -811,28 +440,28 @@ Get the options which will be used if credentials need to be acquired.
    Parameters:
    kim_error_t kim_selection_hints_get_options kim_error kim_selection_hints_get_options (kim_selection_hints_t kim_selection_hints  in_selection_hints,
    kim_options_t * kim_options *  out_options 
    - +
    in_selection_hints a selection hints object.
    out_options on exit, the options to control credential acquisition specified in in_selection_hints. May be KIM_OPTIONS_DEFAULT. If not, must be freed with kim_options_free().
    out_options on exit, the options to control credential acquisition specified in in_selection_hints. May be KIM_OPTIONS_DEFAULT. If not, must be freed with kim_options_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    -
    See also:
    kim_selection_hints_set_options()
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    +
    See also:
    kim_selection_hints_set_options()

    - +

    - + - + - + @@ -853,26 +482,26 @@ Set whether or not KIM may interact with the user to select an identity.
    kim_error_t kim_selection_hints_set_allow_user_interaction kim_error kim_selection_hints_set_allow_user_interaction (kim_selection_hints_t kim_selection_hints  in_selection_hints,
    kim_boolean_t kim_boolean  in_allow_user_interaction 
    in_allow_user_interaction a boolean value specifying whether or not KIM should ask the user to select an identity for in_selection_hints.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    This setting defaults to TRUE.
    -
    See also:
    kim_selection_hints_get_allow_user_interaction
    +
    See also:
    kim_selection_hints_get_allow_user_interaction

    - +

    - + - + - + @@ -893,26 +522,26 @@ Get whether or not KIM may interact with the user to select an identity.
    kim_error_t kim_selection_hints_get_allow_user_interaction kim_error kim_selection_hints_get_allow_user_interaction (kim_selection_hints_t kim_selection_hints  in_selection_hints,
    kim_boolean_t * kim_boolean *  out_allow_user_interaction 
    out_allow_user_interaction on exit, a boolean value specifying whether or not KIM should ask the user to select an identity for in_selection_hints.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    This setting defaults to TRUE.
    -
    See also:
    kim_selection_hints_set_allow_user_interaction
    +
    See also:
    kim_selection_hints_set_allow_user_interaction

    - +

    - + - + - + @@ -933,26 +562,26 @@ Set whether or not KIM will use cached mappings for this selection hints object.
    kim_error_t kim_selection_hints_set_remember_identity kim_error kim_selection_hints_set_remember_identity (kim_selection_hints_t kim_selection_hints  in_selection_hints,
    kim_boolean_t kim_boolean  in_remember_identity 
    in_remember_identity a boolean value specifying whether or not KIM should use a cached mapping between in_selection_hints and a Kerberos identity.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    This setting defaults to TRUE.
    -
    See also:
    kim_selection_hints_get_remember_identity
    +
    See also:
    kim_selection_hints_get_remember_identity

    - +

    - + - + - + @@ -973,26 +602,26 @@ Get whether or not KIM will use cache mappings for this selection hints object.
    kim_error_t kim_selection_hints_get_remember_identity kim_error kim_selection_hints_get_remember_identity (kim_selection_hints_t kim_selection_hints  in_selection_hints,
    kim_boolean_t * kim_boolean *  out_remember_identity 
    out_remember_identity on exit, a boolean value specifying whether or not KIM will use a cached mapping between in_selection_hints and a Kerberos identity.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    This setting defaults to TRUE.
    -
    See also:
    kim_selection_hints_set_remember_identity
    +
    See also:
    kim_selection_hints_set_remember_identity

    - +

    - + - + - + @@ -1010,28 +639,28 @@ Choose a client identity based on selection hints.
    Parameters:
    kim_error_t kim_selection_hints_get_identity kim_error kim_selection_hints_get_identity (kim_selection_hints_t kim_selection_hints  in_selection_hints,
    kim_identity_t * kim_identity *  out_identity 
    - +
    in_selection_hints the selection hints to add to the cache.
    out_identity the Kerberos identity in_selection_hints maps to. Must be freed with kim_identity_free().
    out_identity the Kerberos identity in_selection_hints maps to. Must be freed with kim_identity_free().
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.
    Note:
    out_identity is the identity mapped to by the current state of in_selection_hints. This function may prompt the user via a GUI to choose that identity. Subsequent modifications to in_selection_hints will not change out_identity.

    - +

    - + - + - + @@ -1052,18 +681,18 @@ Add an entry for the selection hints to the selection hints cache, replacing any
    kim_error_t kim_selection_hints_remember_identity kim_error kim_selection_hints_remember_identity (kim_selection_hints_t kim_selection_hints  in_selection_hints,
    kim_identity_t kim_identity  in_identity 
    in_identity the Kerberos identity in_selection_hints maps to.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + @@ -1080,18 +709,18 @@ Remove an entry for the selection hints from the selection hints cache.
    kim_error_t kim_selection_hints_forget_identity kim_error kim_selection_hints_forget_identity (kim_selection_hints_t kim_selection_hints  in_selection_hints  ) 
    in_selection_hints the selection hints to remove from the cache.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + @@ -1111,7 +740,7 @@ Free memory associated with a selection hints object.

    -

    Generated on Wed May 7 15:22:20 2008 for Kerberos Identity Management by  +
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/group__kim__string__reference.html b/doc/kim/html/group__kim__string__reference.html index 46d225118..df2493dd1 100644 --- a/doc/kim/html/group__kim__string__reference.html +++ b/doc/kim/html/group__kim__string__reference.html @@ -9,25 +9,65 @@

    Functions

    +
  • kim_error kim_string_create_for_error (kim_string *out_string, kim_error in_error) +
    Get a text description of an error.
  • kim_error kim_string_copy (kim_string *out_string, const kim_string in_string) +
    Copy a string.
  • kim_error kim_string_compare (kim_string in_string, kim_string in_compare_to_string, kim_comparison *out_comparison) +
    Compare two strings.
  • void kim_string_free (kim_string *io_string) +
    Free memory associated with a string.

    Function Documentation

    - +
    • void kim_selection_hints_free (kim_selection_hints_t * kim_selection_hints *  io_selection_hints  ) 
    - + - + - + + + + + + + + +
    kim_error_t kim_string_copy kim_error kim_string_create_for_error (kim_string_t * kim_string *  out_string,
    const kim_string_t kim_error  in_error 
    )
    +
    +
    + +

    +Get a text description of an error. +

    +

    Parameters:
    + + + +
    out_string on exit, a human-readable UTF-8 string describing the error represented by in_error. Must be freed with kim_string_free().
    in_error an error code.
    +
    +
    Returns:
    On success, KIM_NO_ERROR. On failure,
    +
    Note:
    If the caller needs an error string, this API should be called immediately after a KIM API returns an error.
    + +
    +

    + +

    +
    + + + + + + + + + + + @@ -44,34 +84,34 @@ Copy a string.

    Parameters:
    kim_error kim_string_copy (kim_string *  out_string,
    const kim_string  in_string 
    - +
    out_string on exit, a new string object which is a copy of in_string. Must be freed with kim_string_free().
    out_string on exit, a new string object which is a copy of in_string. Must be freed with kim_string_free().
    in_string the string to copy.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + - + - + - + @@ -93,18 +133,18 @@ Compare two strings.
    kim_error_t kim_string_compare kim_error kim_string_compare (kim_string_t kim_string  in_string,
    kim_string_t kim_string  in_compare_to_string,
    kim_comparison_t * kim_comparison *  out_comparison 
    out_comparison on exit, a comparison result indicating whether in_string is greater than, less than or equal to in_compare_to_string.
    -
    Returns:
    On success, KIM_NO_ERROR. On failure, an error object representing the failure.
    +
    Returns:
    On success, KIM_NO_ERROR. On failure, an error code representing the failure.

    - +

    - + @@ -124,7 +164,7 @@ Free memory associated with a string.

    -

    Generated on Wed May 7 15:22:20 2008 for Kerberos Identity Management by  +
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/group__kim__types__reference.html b/doc/kim/html/group__kim__types__reference.html index c46ec73e5..3654b9deb 100644 --- a/doc/kim/html/group__kim__types__reference.html +++ b/doc/kim/html/group__kim__types__reference.html @@ -9,48 +9,43 @@

    Defines

    Typedefs

    Enumerations

    Define Documentation

    @@ -80,29 +75,14 @@ kim_credential_opaque *
    void kim_string_free (kim_string_t * kim_string *  io_string  ) 
    - +
    #define KIM_NO_ERROR   ((kim_error_t) NULL) #define KIM_NO_ERROR   ((kim_error) 0)

    -The kim_error_t returned when no error occurred. Does not need to be freed with kim_error_free(). -

    -

    - -

    -
    - - - - -
    #define KIM_NO_ERROR_ECODE   ((kim_error_code_t) 0)
    -
    -
    - -

    -The kim_error_code_t for KIM_NO_ERROR. +The kim_error_t returned when no error occurred.

    @@ -110,7 +90,7 @@ The kim_error_code_t for KIM_NO_ERROR.

    - +
    #define KIM_IDENTITY_ANY   ((kim_identity_t) NULL) #define KIM_IDENTITY_ANY   ((kim_identity) NULL)
    @@ -125,7 +105,7 @@ Constant to specify any Kerberos identity is acceptable.
    - +
    #define KIM_OPTIONS_DEFAULT   ((kim_options_t) NULL) #define KIM_OPTIONS_DEFAULT   ((kim_options) NULL)
    @@ -140,7 +120,7 @@ Specifies the user's default options.
    - +
    #define KIM_OPTIONS_START_IMMEDIATELY   ((kim_time_t) 0) #define KIM_OPTIONS_START_IMMEDIATELY   ((kim_time_t) 0)
    @@ -167,7 +147,7 @@ Specifies that credentials should be valid immediately.

    -Convenience macro for interpreting kim_comparison_t. +Convenience macro for interpreting kim_comparison_t.

    @@ -187,7 +167,7 @@ Convenience macro for interpreting

    -Convenience macro for interpreting kim_comparison_t. +Convenience macro for interpreting kim_comparison_t.

    @@ -207,16 +187,16 @@ Convenience macro for interpreting

    -Convenience macro for interpreting kim_comparison_t. +Convenience macro for interpreting kim_comparison_t.

    Typedef Documentation

    - +
    - +
    typedef int kim_credential_state_t typedef int kim_credential_state
    @@ -226,12 +206,12 @@ Convenience macro for interpreting kim_credential_state_enum for possible values.

    - +

    - +
    typedef uint32_t kim_prompt_type_t typedef uint32_t kim_prompt_type
    @@ -241,12 +221,12 @@ The state of a credential. See Providing a Custom Prompt Callback for more information.

    - +

    - +
    typedef kim_error_code_t(* kim_prompt_callback_t)(kim_options_t *io_options, kim_prompt_type_t in_type, kim_string_t in_title, kim_string_t in_message, kim_string_t in_description, void **out_reply) typedef kim_error(* kim_prompt_callback)(kim_prompt_type in_type, kim_string in_title, kim_string in_message, kim_string in_description, char **out_reply)
    @@ -256,27 +236,27 @@ The type of prompt which needs to be displayed. This value determines what type The prompt callback used to display a prompt to the user. See Providing a Custom Prompt Callback for more information.

    - +

    - +
    typedef int32_t kim_error_code_t typedef int32_t kim_error

    -The KIM String type. See KIM String Overview for more information. +The KIM Error type. See KIM Error Overview for more information.

    - +

    - +
    typedef int64_t kim_time_t typedef int64_t kim_time
    @@ -286,12 +266,12 @@ The KIM String type. See KIM Strin A time value represented in seconds since January 1, 1970.

    - +

    - +
    typedef int64_t kim_lifetime_t typedef int64_t kim_lifetime
    @@ -301,12 +281,12 @@ A time value represented in seconds since January 1, 1970. A duration represented in seconds.

    - +

    - +
    typedef uint64_t kim_count_t typedef uint64_t kim_count
    @@ -316,12 +296,12 @@ A duration represented in seconds. An quantity, usually used to return the number of elements in an array.

    - +

    - +
    typedef int kim_boolean_t typedef int kim_boolean
    @@ -331,12 +311,12 @@ An quantity, usually used to return the number of elements in an array. A boolean value. 0 means false, all other values mean true.

    - +

    - +
    typedef int kim_comparison_t typedef int kim_comparison
    @@ -352,42 +332,42 @@ A comparison between two sortable objects.

    - +

    - +
    typedef const char* kim_string_t typedef const char* kim_context

    -The KIM String type. See KIM String Overview for more information. +The KIM Context type. See kim_context_overview for more information.

    - +

    - +
    typedef struct kim_error_opaque* kim_error_t typedef const char* kim_string

    -A KIM Error object. See KIM Error Overview for more information. +The KIM String type. See KIM String Overview for more information.

    - +

    - +
    typedef struct kim_identity_opaque* kim_identity_t typedef struct kim_identity_opaque* kim_identity
    @@ -397,12 +377,12 @@ A KIM Error object. See KIM Error O A KIM Principal object. See KIM Identity Overview for more information.

    - +

    - +
    typedef struct kim_options_opaque* kim_options_t typedef struct kim_options_opaque* kim_options
    @@ -412,12 +392,12 @@ A KIM Principal object. See KIM A KIM Options object. See KIM Options Overview for more information.

    - +

    - +
    typedef struct kim_selection_hints_opaque* kim_selection_hints_t typedef struct kim_selection_hints_opaque* kim_selection_hints
    @@ -427,27 +407,12 @@ A KIM Options object. See KIM Opt A KIM Selection Hints object. See KIM Selection Hints Overview for more information.

    - +

    - - -
    typedef struct kim_favorite_identities_opaque* kim_favorite_identities_t
    -
    -
    - -

    -A KIM Favorite Realms object. See KIM Favorite Identities Overview for more information. -

    -

    - -

    -
    - - - +
    typedef struct kim_preferences_opaque* kim_preferences_t typedef struct kim_preferences_opaque* kim_preferences
    @@ -457,12 +422,12 @@ A KIM Favorite Realms object. See KIM Preferences Overview for more information.

    - +

    - +
    typedef struct kim_ccache_iterator_opaque* kim_ccache_iterator_t typedef struct kim_ccache_iterator_opaque* kim_ccache_iterator
    @@ -472,12 +437,12 @@ A KIM Preferences object. See Acquiring a CCache from the Cache Collection for more information.

    - +

    - +
    typedef struct kim_ccache_opaque* kim_ccache_t typedef struct kim_ccache_opaque* kim_ccache
    @@ -487,27 +452,27 @@ A KIM CCache Iterator object. See KIM CCache Overview for more information.

    - +

    - +
    typedef struct kim_credential_iterator_opaque* kim_credential_iterator_t typedef struct kim_credential_iterator_opaque* kim_credential_iterator

    -A KIM Credential Iterator object. See Iterating over the Credentials in a CCache for more information. +A KIM Credential Iterator object. See kim_credential_iterator_t for more information.

    - +

    - +
    typedef struct kim_credential_opaque* kim_credential_t typedef struct kim_credential_opaque* kim_credential
    @@ -541,44 +506,38 @@ Possible credential states. Credentials may be:

    Function Documentation

    - +
    - + - - - - - - - + - + - + - + - + @@ -594,44 +553,38 @@ Possible credential states. Credentials may be:
    kim_error_code_t kim_prompt_callback_default kim_error kim_prompt_callback_default (kim_options_t *  io_options,
    kim_prompt_type_t kim_prompt_type  in_type,
    kim_string_t kim_string  in_title,
    kim_string_t kim_string  in_message,
    kim_string_t kim_string  in_description,
    void ** char **  out_reply 
    - + - - - - - - - + - + - + - + - + @@ -647,44 +600,38 @@ The default prompt callback. See Providing a Custom Prompt Callback for more information.

    - +

    kim_error_code_t kim_prompt_callback_gui kim_error kim_prompt_callback_gui (kim_options_t *  io_options,
    kim_prompt_type_t kim_prompt_type  in_type,
    kim_string_t kim_string  in_title,
    kim_string_t kim_string  in_message,
    kim_string_t kim_string  in_description,
    void ** char **  out_reply 
    - + - - - - - - - + - + - + - + - + @@ -700,44 +647,38 @@ The graphical prompt callback. See Providing a Custom Prompt Callback for more information.

    - +

    kim_error_code_t kim_prompt_callback_cli kim_error kim_prompt_callback_cli (kim_options_t *  io_options,
    kim_prompt_type_t kim_prompt_type  in_type,
    kim_string_t kim_string  in_title,
    kim_string_t kim_string  in_message,
    kim_string_t kim_string  in_description,
    void ** char **  out_reply 
    - + - - - - - - - + - + - + - + - + @@ -754,7 +695,7 @@ The prompt callback which always returns an error. Use to turn off prompting ent

    -

    Generated on Wed May 7 15:22:20 2008 for Kerberos Identity Management by  +
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/index.html b/doc/kim/html/index.html index fccd684de..ae9473c86 100644 --- a/doc/kim/html/index.html +++ b/doc/kim/html/index.html @@ -65,7 +65,7 @@ Whether or not you use the credential or ccache APIs depends on whether you want
  • KIM Options Overview
  • KIM Options Reference Documentation

    • KIM Realms List (kim_favorite_identities_t) views and edits the current user's favorite realms list:

    +
  • kim_favorite_identities_overview
  • kim_favorite_identities_reference

    • KIM Preferences (kim_preferences_t) views and edits the current user's preferences:

    @@ -82,7 +82,7 @@ Types and Constants -
    Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  +
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/kim_ccache_overview.html b/doc/kim/html/kim_ccache_overview.html index dded05fcf..16bcf1424 100644 --- a/doc/kim/html/kim_ccache_overview.html +++ b/doc/kim/html/kim_ccache_overview.html @@ -13,53 +13,53 @@ The kim_ccache_t object is a reference to a ccache in the cache collection. If o
    Note:
    KIM ccache APIs are intended for applications and system tools which manage credentials for the user. They are not a substitute for krb5 and GSSAPI functions which obtain service credentials for the purpose of authenticating a client to an application server.

    Acquiring a CCache from the Cache Collection

    -KIM provides a simple iterator API for iterating over the ccaches in the cache collection. First, call kim_ccache_iterator_create() to obtain an iterator for the cache collection. Then loop calling kim_ccache_iterator_next() until either you find the ccache you are looking for or the API returns a NULL ccache, indicating that there are no more ccaches in the cache collection. When you are done with the iterator, call kim_ccache_iterator_free().

    -

    Note:
    kim_ccache_iterator_next() returns ccache objects which must be freed with kim_ccache_free() to avoid leaking memory.
    -KIM also provides a convenient API kim_ccache_create_from_client_identity() which returns the ccache for a specific client identity, if any exists. Typically callers of this API obtain the client identity using kim_selection_hints_get_identity().

    +KIM provides a simple iterator API for iterating over the ccaches in the cache collection. First, call kim_ccache_iterator_create() to obtain an iterator for the cache collection. Then loop calling kim_ccache_iterator_next() until either you find the ccache you are looking for or the API returns a NULL ccache, indicating that there are no more ccaches in the cache collection. When you are done with the iterator, call kim_ccache_iterator_free().

    +

    Note:
    kim_ccache_iterator_next() returns ccache objects which must be freed with kim_ccache_free() to avoid leaking memory.
    +KIM also provides a convenient API kim_ccache_create_from_client_identity() which returns the ccache for a specific client identity, if any exists. Typically callers of this API obtain the client identity using kim_selection_hints_get_identity().

    Acquiring Credentials from the Default CCache

    -kim_ccache_create_from_default() returns the default ccache. The default ccache is a legacy concept which was replaced by selection hints. Prior to the existence of selection hints, applications always looked at the default ccache for credentials. By setting the system default ccache, users could manually control which credentials each application used. As the number of ccaches and applications has grown, this mechanism has become unusable. You should avoid using this API whenever possible.

    +kim_ccache_create_from_default() returns the default ccache. The default ccache is a legacy concept which was replaced by selection hints. Prior to the existence of selection hints, applications always looked at the default ccache for credentials. By setting the system default ccache, users could manually control which credentials each application used. As the number of ccaches and applications has grown, this mechanism has become unusable. You should avoid using this API whenever possible.

    Acquiring New Credentials in a CCache

    -KIM provides the kim_ccache_create_new() API for acquiring new credentials and storing them in a ccache. Credentials can either be obtained for a specific client identity or by specifying KIM_IDENTITY_ANY to allow the user to choose. Typically callers of this API obtain the client identity using kim_selection_hints_get_identity(). Depending on the kim_options specified, kim_ccache_create_new() may present a GUI or command line prompt to obtain information from the user.

    -kim_ccache_create_new_if_needed() searches the cache collection for a ccache for the client identity and if no appropriate ccache is available, attempts to acquire new credentials and store them in a new ccache. Depending on the kim_options specified, kim_ccache_create_new_if_needed() may present a GUI or command line prompt to obtain information from the user. This function exists for convenience and to avoid code duplication. It can be trivially implemented using kim_ccache_create_from_client_identity() and kim_ccache_create_new().

    -KIM provides the kim_ccache_create_from_keytab() to create credentials using a keytab and store them in the cache collection. A keytab is an on-disk copy of a client identity's secret key. Typically sites use keytabs for client identities that identify a machine or service and protect the keytab with disk permissions. Because a keytab is sufficient to obtain credentials, keytabs will normally only be readable by root, Administrator or some other privileged account. Typically applications use credentials obtained from keytabs to obtain credentials for batch processes. These keytabs and credentials are usually for a special identity used for the batch process rather than a user identity.

    +KIM provides the kim_ccache_create_new() API for acquiring new credentials and storing them in a ccache. Credentials can either be obtained for a specific client identity or by specifying KIM_IDENTITY_ANY to allow the user to choose. Typically callers of this API obtain the client identity using kim_selection_hints_get_identity(). Depending on the kim_options specified, kim_ccache_create_new() may present a GUI or command line prompt to obtain information from the user.

    +kim_ccache_create_new_if_needed() searches the cache collection for a ccache for the client identity and if no appropriate ccache is available, attempts to acquire new credentials and store them in a new ccache. Depending on the kim_options specified, kim_ccache_create_new_if_needed() may present a GUI or command line prompt to obtain information from the user. This function exists for convenience and to avoid code duplication. It can be trivially implemented using kim_ccache_create_from_client_identity() and kim_ccache_create_new().

    +KIM provides the kim_ccache_create_from_keytab() to create credentials using a keytab and store them in the cache collection. A keytab is an on-disk copy of a client identity's secret key. Typically sites use keytabs for client identities that identify a machine or service and protect the keytab with disk permissions. Because a keytab is sufficient to obtain credentials, keytabs will normally only be readable by root, Administrator or some other privileged account. Typically applications use credentials obtained from keytabs to obtain credentials for batch processes. These keytabs and credentials are usually for a special identity used for the batch process rather than a user identity.

    Validating Credentials in a CCache

    A credential with a start time in the future (ie: after the issue date) is called a post-dated credential. Because the KDC administrator may wish to disable a identity, once the start time is reached, all post-dated credentials must be validated before they can be used. Otherwise an attacker using a compromised account could acquire lots of post-dated credentials to circumvent the acccount being disabled.

    -KIM provides the kim_ccache_validate() API to validate the TGT credential in a ccache. Note that this API replaces any existing credentials with the validated credential.

    +KIM provides the kim_ccache_validate() API to validate the TGT credential in a ccache. Note that this API replaces any existing credentials with the validated credential.

    Renewing Credentials in a CCache

    A renewable credential can be used to obtain a new identical credential without resending secret information (such as a password) to the KDC. A credential may only be renewed during its renewal lifetime and while valid.

    -KIM provides the kim_ccache_renew() API to renew the TGT credential in a ccache. Note that this API replaces any existing credentials with the renewed credential.

    +KIM provides the kim_ccache_renew() API to renew the TGT credential in a ccache. Note that this API replaces any existing credentials with the renewed credential.

    Verifying Credentials in a CCache

    When a program acquires TGT credentials for the purpose of authenticating itself to the machine it is running on, it is insufficient for the machine to assume that the caller is authorized just because it got credentials. Instead, the credentials must be verified using a key the local machine. The reason this is necessary is because an attacker can trick the machine into obtaining credentials from any KDC, including malicious ones with the same realm name as the local machine's realm. This exploit is called the Zanarotti attack.

    -In order to avoid the Zanarotti attack, the local machine must authenticate the process in the same way an application server would authenticate a client. Like an application server, the local machine must have its own identity in its realm and a keytab for that identity on its local disk. However, rather than forcing system daemons to use the network-oriented calls in the krb5 and GSS APIs, KIM provides the kim_ccache_verify() API to verify credentials directly.

    -The most common reason for using kim_ccache_verify() is user login. If the local machine wants to use Kerberos to verify the username and password provided by the user, it must call kim_ccache_verify() on the credentials it obtains to make sure they are really from a KDC it trusts. Another common case is a server which is only using Kerberos internally. For example an LDAP or web server might use a username and password obtained over the network to get Kerberos credentials. In order to make sure they aren't being tricked into talking to the wrong KDC, these servers must also call kim_ccache_verify().

    -The Zanarotti attack is only a concern if the act of accessing the machine gives the process special access. Thus a managed cluster machine with Kerberos-authenticated networked home directories does not need to call kim_ccache_verify(). Even though an attacker can log in as any user on the cluster machine, the attacker can't actually access any of the user's data or use any of their privileges because those are all authenticated via Kerberized application servers (and thus require actually having credentials for the real local realm).

    -kim_ccache_verify() provides an option to return success even if the machine's host key is not present. This option exists for sites which have a mix of different machines, some of which are vulnerable to the Zanarotti attack and some are not. If this option is used, it is the responsiblity of the machine's maintainer to obtain a keytab for their machine if it needs one.

    +In order to avoid the Zanarotti attack, the local machine must authenticate the process in the same way an application server would authenticate a client. Like an application server, the local machine must have its own identity in its realm and a keytab for that identity on its local disk. However, rather than forcing system daemons to use the network-oriented calls in the krb5 and GSS APIs, KIM provides the kim_ccache_verify() API to verify credentials directly.

    +The most common reason for using kim_ccache_verify() is user login. If the local machine wants to use Kerberos to verify the username and password provided by the user, it must call kim_ccache_verify() on the credentials it obtains to make sure they are really from a KDC it trusts. Another common case is a server which is only using Kerberos internally. For example an LDAP or web server might use a username and password obtained over the network to get Kerberos credentials. In order to make sure they aren't being tricked into talking to the wrong KDC, these servers must also call kim_ccache_verify().

    +The Zanarotti attack is only a concern if the act of accessing the machine gives the process special access. Thus a managed cluster machine with Kerberos-authenticated networked home directories does not need to call kim_ccache_verify(). Even though an attacker can log in as any user on the cluster machine, the attacker can't actually access any of the user's data or use any of their privileges because those are all authenticated via Kerberized application servers (and thus require actually having credentials for the real local realm).

    +kim_ccache_verify() provides an option to return success even if the machine's host key is not present. This option exists for sites which have a mix of different machines, some of which are vulnerable to the Zanarotti attack and some are not. If this option is used, it is the responsiblity of the machine's maintainer to obtain a keytab for their machine if it needs one.

    Examining CCache Properties

      -
    • kim_ccache_get_type() returns the type of the ccache. Types include "API" for CCAPI ccaches, "FILE" for file-based ccaches and "MEMORY" for single-process in-memory ccaches.
      • +
    • kim_ccache_get_type() returns the type of the ccache. Types include "API" for CCAPI ccaches, "FILE" for file-based ccaches and "MEMORY" for single-process in-memory ccaches.
      -
    • kim_ccache_get_name() returns the name of the ccache. A ccache's name identifies the ccache uniquely among ccaches of the same type. Note that two ccaches with different types may have the same name.
      • +
    • kim_ccache_get_name() returns the name of the ccache. A ccache's name identifies the ccache uniquely among ccaches of the same type. Note that two ccaches with different types may have the same name.
      -
    • kim_ccache_get_display_name() returns a display string which uniquely identifies a ccache. A ccache display name is of the form "<type>:<name>" and can be displayed to the user or used as an argument to certain krb5 APIs, such as krb5_cc_resolve().
      • +
    • kim_ccache_get_display_name() returns a display string which uniquely identifies a ccache. A ccache display name is of the form "<type>:<name>" and can be displayed to the user or used as an argument to certain krb5 APIs, such as krb5_cc_resolve().
      -
    • kim_ccache_get_valid_credential() returns the first valid TGT in the ccache for its client identity. If there are no TGTs in the ccache, it returns the first valid non-TGT credential for the ccache's client identity. TGT credentials (ie: "ticket-granting tickets") are credentials for the krbtgt service: a service identity of the form "krbtgt/<REALM>@<REALM>". These credentials allow the entity named by the client identity to obtain additional credentials without resending shared secrets (such as a password) to the KDC. Kerberos uses TGTs to provide single sign-on authentication.
      • +
    • kim_ccache_get_valid_credential() returns the first valid TGT in the ccache for its client identity. If there are no TGTs in the ccache, it returns the first valid non-TGT credential for the ccache's client identity. TGT credentials (ie: "ticket-granting tickets") are credentials for the krbtgt service: a service identity of the form "krbtgt/<REALM>@<REALM>". These credentials allow the entity named by the client identity to obtain additional credentials without resending shared secrets (such as a password) to the KDC. Kerberos uses TGTs to provide single sign-on authentication.
      -
    • kim_ccache_get_start_time() returns when the credential's in a ccache will become valid. Credentials may be "post-dated" which means that their lifetime starts sometime in the future. Note that when a post-dated credential's start time is reached, the credential must be validated. See Validating Credentials for more information.
      • +
    • kim_ccache_get_start_time() returns when the credential's in a ccache will become valid. Credentials may be "post-dated" which means that their lifetime starts sometime in the future. Note that when a post-dated credential's start time is reached, the credential must be validated. See Validating Credentials for more information.
      -
    • kim_ccache_get_expiration_time() returns when the credential's in a ccache will expire. Credentials are time limited by the lifetime of the credential. While you can request a credential of any lifetime, the KDC limits the credential lifetime to a administrator-defined maximum. Typically credential lifetime range from 10 to 21 hours.
      • +
    • kim_ccache_get_expiration_time() returns when the credential's in a ccache will expire. Credentials are time limited by the lifetime of the credential. While you can request a credential of any lifetime, the KDC limits the credential lifetime to a administrator-defined maximum. Typically credential lifetime range from 10 to 21 hours.
      -
    • kim_ccache_get_renewal_expiration_time() returns when the credential's in a ccache will no longer be renewable. Valid credentials may be renewed up until their renewal expiration time. Renewing credentials acquires a fresh set of credentials with a full lifetime without resending secrets to the KDC (such as a password). If credentials are not renewable, this function will return an error.
      • +
    • kim_ccache_get_renewal_expiration_time() returns when the credential's in a ccache will no longer be renewable. Valid credentials may be renewed up until their renewal expiration time. Renewing credentials acquires a fresh set of credentials with a full lifetime without resending secrets to the KDC (such as a password). If credentials are not renewable, this function will return an error.
    -See KIM CCache Reference Documentation and KIM CCache Iterator Reference Documentation for information on specific APIs.
    Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  +See KIM CCache Reference Documentation and KIM CCache Iterator Reference Documentation for information on specific APIs.
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/kim_credential_overview.html b/doc/kim/html/kim_credential_overview.html index cdf33a101..6b47baf76 100644 --- a/doc/kim/html/kim_credential_overview.html +++ b/doc/kim/html/kim_credential_overview.html @@ -8,55 +8,55 @@

    KIM Credential Overview

    Introduction

    A Kerberos credential (also called a "Kerberos ticket") is a time-limited token issued by a KDC which authenticates the entity named by the credential's client identity to the service named by the credential's service identity.

    -The kim_credential_t object contains a single Kerberos credential. KIM credentials objects are always copies of credentials, not references to credentials stored in the cache collection. Modifying credential objects in the ccache collection will not change any existing KIM credential objects.

    +The kim_credential object contains a single Kerberos credential. KIM credentials objects are always copies of credentials, not references to credentials stored in the cache collection. Modifying credential objects in the ccache collection will not change any existing KIM credential objects.

    KIM credential APIs are intended for applications and system tools which manage credentials for the user. They are not a substitute for krb5 and GSSAPI functions which obtain service credentials for the purpose of authenticating a client to an application server.

    Note:
    Many of the APIs listed below have equivalent functions which operate on ccaches. In most cases applications will want to use the ccache versions of these APIs since they automatically store any newly created credentials. See KIM CCache Overview for more information.

    Acquiring New Credentials

    -KIM provides the kim_credential_create_new() API for acquiring new credentials. Credentials can either be obtained for a specific client identity or by specifying KIM_IDENTITY_ANY to allow the user to choose. Typically callers of this API obtain the client identity using kim_selection_hints_get_identity(). Depending on the kim_options specified, kim_credential_create_new() may present a GUI or command line prompt to obtain information from the user.

    -KIM provides the kim_credential_create_from_keytab() to create credentials using a keytab. A keytab is an on-disk copy of a client identity's secret key. Typically sites use keytabs for client identities that identify a machine or service and protect the keytab with disk permissions. Because a keytab is sufficient to obtain credentials, keytabs will normally only be readable by root, Administrator or some other privileged account. Typically applications use credentials obtained from keytabs to obtain credentials for batch processes. These keytabs and credentials are usually for a special identity used for the batch process rather than a user identity.

    +KIM provides the kim_credential_create_new() API for acquiring new credentials. Credentials can either be obtained for a specific client identity or by specifying KIM_IDENTITY_ANY to allow the user to choose. Typically callers of this API obtain the client identity using kim_selection_hints_get_identity(). Depending on the kim_options specified, kim_credential_create_new() may present a GUI or command line prompt to obtain information from the user.

    +KIM provides the kim_credential_create_from_keytab() to create credentials using a keytab. A keytab is an on-disk copy of a client identity's secret key. Typically sites use keytabs for client identities that identify a machine or service and protect the keytab with disk permissions. Because a keytab is sufficient to obtain credentials, keytabs will normally only be readable by root, Administrator or some other privileged account. Typically applications use credentials obtained from keytabs to obtain credentials for batch processes. These keytabs and credentials are usually for a special identity used for the batch process rather than a user identity.

    Validating Credentials

    A credential with a start time in the future (ie: after the issue date) is called a post-dated credential. Because the KDC administrator may wish to disable a identity, once the start time is reached, all post-dated credentials must be validated before they can be used. Otherwise an attacker using a compromised account could acquire lots of post-dated credentials to circumvent the acccount being disabled.

    -KIM provides the kim_credential_validate() API to validate a credential. Note that this API replaces the credential object with a new validated credential object. If you wish to store the new credential in the ccache collection you must either call kim_credential_store() on the validated credential or use kim_ccache_validate() instead.

    +KIM provides the kim_credential_validate() API to validate a credential. Note that this API replaces the credential object with a new validated credential object. If you wish to store the new credential in the ccache collection you must either call kim_credential_store() on the validated credential or use kim_ccache_validate() instead.

    Renewing Credentials

    A renewable credential can be used to obtain a new identical credential without resending secret information (such as a password) to the KDC. A credential may only be renewed during its renewal lifetime and while valid.

    -KIM provides the kim_credential_renew() API to renew a credential. Note that this API replaces the credential object with a new renewed credential object. If you wish to store the new credential in the ccache collection you must either call kim_credential_store() on the renewed credential or use kim_ccache_renew() instead.

    +KIM provides the kim_credential_renew() API to renew a credential. Note that this API replaces the credential object with a new renewed credential object. If you wish to store the new credential in the ccache collection you must either call kim_credential_store() on the renewed credential or use kim_ccache_renew() instead.

    Storing Credentials in the Cache Collection

    -KIM credential objects may be stored in the ccache collection using kim_credential_store(). This function runs any KIM authentication plugins on the credential and if the plugins return successfully, creates a new ccache for the credential's client identity in the cache collection and stores the credential in that ccache. Any existing ccaches and credentials for that client identity will be overwritten. kim_credential_store() may optionally return a kim_ccache_t object for the new ccache if you need to perform further operations on the new ccache.

    -Most of the time if you plan to store the credentials you are manipulating, you should use one of KIM ccache APIs. These functions perform the same operations except that they also call kim_credential_store() any time the credential object changes. See KIM CCache Overview for more information.

    +KIM credential objects may be stored in the ccache collection using kim_credential_store(). This function runs any KIM authentication plugins on the credential and if the plugins return successfully, creates a new ccache for the credential's client identity in the cache collection and stores the credential in that ccache. Any existing ccaches and credentials for that client identity will be overwritten. kim_credential_store() may optionally return a kim_ccache object for the new ccache if you need to perform further operations on the new ccache.

    +Most of the time if you plan to store the credentials you are manipulating, you should use one of KIM ccache APIs. These functions perform the same operations except that they also call kim_credential_store() any time the credential object changes. See KIM CCache Overview for more information.

    Iterating over the Credentials in a CCache

    -KIM provides a simple iterator API for iterating over the credentials in a ccache. First, call kim_credential_iterator_create() to obtain an iterator for a ccache. Then loop calling kim_credential_iterator_next() until either you find the credential you are looking for or the API returns a NULL credential, indicating that there are no more credentials in the ccache. When you are done with the iterator, call kim_credential_iterator_free().

    -

    Note:
    kim_credential_iterator_next() returns credential objects which must be freed with kim_credential_free() to avoid leaking memory.
    +KIM provides a simple iterator API for iterating over the credentials in a ccache. First, call kim_credential_iterator_create() to obtain an iterator for a ccache. Then loop calling kim_credential_iterator_next() until either you find the credential you are looking for or the API returns a NULL credential, indicating that there are no more credentials in the ccache. When you are done with the iterator, call kim_credential_iterator_free().

    +

    Note:
    kim_credential_iterator_next() returns credential objects which must be freed with kim_credential_free() to avoid leaking memory.

    Verifying Credentials

    When a program acquires TGT credentials for the purpose of authenticating itself to the machine it is running on, it is insufficient for the machine to assume that the caller is authorized just because it got credentials. Instead, the credentials must be verified using a key the local machine. The reason this is necessary is because an attacker can trick the machine into obtaining credentials from any KDC, including malicious ones with the same realm name as the local machine's realm. This exploit is called the Zanarotti attack.

    -In order to avoid the Zanarotti attack, the local machine must authenticate the process in the same way an application server would authenticate a client. Like an application server, the local machine must have its own identity in its realm and a keytab for that identity on its local disk. However, rather than forcing system daemons to use the network-oriented calls in the krb5 and GSS APIs, KIM provides the kim_credential_verify() API to verify credentials directly.

    -The most common reason for using kim_credential_verify() is user login. If the local machine wants to use Kerberos to verify the username and password provided by the user, it must call kim_credential_verify() on the credentials it obtains to make sure they are really from a KDC it trusts. Another common case is a server which is only using Kerberos internally. For example an LDAP or web server might use a username and password obtained over the network to get Kerberos credentials. In order to make sure they aren't being tricked into talking to the wrong KDC, these servers must also call kim_credential_verify().

    -The Zanarotti attack is only a concern if the act of accessing the machine gives the process special access. Thus a managed cluster machine with Kerberos-authenticated networked home directories does not need to call kim_credential_verify(). Even though an attacker can log in as any user on the cluster machine, the attacker can't actually access any of the user's data or use any of their privileges because those are all authenticated via Kerberized application servers (and thus require actually having credentials for the real local realm).

    -kim_credential_verify() provides an option to return success even if the machine's host key is not present. This option exists for sites which have a mix of different machines, some of which are vulnerable to the Zanarotti attack and some are not. If this option is used, it is the responsiblity of the machine's maintainer to obtain a keytab for their machine if it needs one.

    +In order to avoid the Zanarotti attack, the local machine must authenticate the process in the same way an application server would authenticate a client. Like an application server, the local machine must have its own identity in its realm and a keytab for that identity on its local disk. However, rather than forcing system daemons to use the network-oriented calls in the krb5 and GSS APIs, KIM provides the kim_credential_verify() API to verify credentials directly.

    +The most common reason for using kim_credential_verify() is user login. If the local machine wants to use Kerberos to verify the username and password provided by the user, it must call kim_credential_verify() on the credentials it obtains to make sure they are really from a KDC it trusts. Another common case is a server which is only using Kerberos internally. For example an LDAP or web server might use a username and password obtained over the network to get Kerberos credentials. In order to make sure they aren't being tricked into talking to the wrong KDC, these servers must also call kim_credential_verify().

    +The Zanarotti attack is only a concern if the act of accessing the machine gives the process special access. Thus a managed cluster machine with Kerberos-authenticated networked home directories does not need to call kim_credential_verify(). Even though an attacker can log in as any user on the cluster machine, the attacker can't actually access any of the user's data or use any of their privileges because those are all authenticated via Kerberized application servers (and thus require actually having credentials for the real local realm).

    +kim_credential_verify() provides an option to return success even if the machine's host key is not present. This option exists for sites which have a mix of different machines, some of which are vulnerable to the Zanarotti attack and some are not. If this option is used, it is the responsiblity of the machine's maintainer to obtain a keytab for their machine if it needs one.

    Examining Credential Properties

      -
    • kim_credential_is_tgt() returns whether the credential is a TGT (ie: "ticket-granting ticket"). TGTs are credentials for the krbtgt service: a service identity of the form "krbtgt/<REALM>@<REALM>". These credentials allow the entity named by the client identity to obtain additional service credentials without resending shared secrets (such as a password) to the KDC. Kerberos uses TGTs to provide single sign-on authentication.
      • +
    • kim_credential_is_tgt() returns whether the credential is a TGT (ie: "ticket-granting ticket"). TGTs are credentials for the krbtgt service: a service identity of the form "krbtgt/<REALM>@<REALM>". These credentials allow the entity named by the client identity to obtain additional service credentials without resending shared secrets (such as a password) to the KDC. Kerberos uses TGTs to provide single sign-on authentication.
    • kim_credential_is_valid() returns whether the credential is valid and if not why the credential is not valid.
      -
    • kim_credential_get_start_time() returns when the credential will become valid. Credentials may be "post-dated" which means that their lifetime starts sometime in the future. Note that when a post-dated credential's start time is reached, the credential must be validated. See Validating Credentials for more information.
      • +
    • kim_credential_get_start_time() returns when the credential will become valid. Credentials may be "post-dated" which means that their lifetime starts sometime in the future. Note that when a post-dated credential's start time is reached, the credential must be validated. See Validating Credentials for more information.
      -
    • kim_credential_get_expiration_time() returns when the credential will expire. Credentials are time limited by the lifetime of the credential. While you can request a credential of any lifetime, the KDC limits the credential lifetime to a administrator-defined maximum. Typically credential lifetime range from 10 to 21 hours.
      • +
    • kim_credential_get_expiration_time() returns when the credential will expire. Credentials are time limited by the lifetime of the credential. While you can request a credential of any lifetime, the KDC limits the credential lifetime to a administrator-defined maximum. Typically credential lifetime range from 10 to 21 hours.
      -
    • kim_credential_get_renewal_expiration_time() returns when the credential will no longer be renewable. Valid credentials may be renewed up until their renewal expiration time. Renewing credentials acquires a fresh set of credentials with a full lifetime without resending secrets to the KDC (such as a password). If credentials are not renewable, this function will return an error.
      • +
    • kim_credential_get_renewal_expiration_time() returns when the credential will no longer be renewable. Valid credentials may be renewed up until their renewal expiration time. Renewing credentials acquires a fresh set of credentials with a full lifetime without resending secrets to the KDC (such as a password). If credentials are not renewable, this function will return an error.
    -See KIM Credential Reference Documentation and KIM Credential Iterator Reference Documentation for information on specific APIs.
    Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  +See KIM Credential Reference Documentation and KIM Credential Iterator Reference Documentation for information on specific APIs.
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/kim_error_overview.html b/doc/kim/html/kim_error_overview.html index 7f3d821c0..b8d02df68 100644 --- a/doc/kim/html/kim_error_overview.html +++ b/doc/kim/html/kim_error_overview.html @@ -5,11 +5,11 @@ -

    KIM Error Overview

    An error object. Error objects consist of a machine readable error code for for programmatic error handling and a string describing the error. All KIM APIs return kim_errors with the exception of memory deallocation functions and the kim_error_t APIs which return pieces of a kim_error_t object.

    -Functions which return successfully will return KIM_NO_ERROR (NULL). Because KIM_NO_ERROR does not need to be freed, you may use if-ladders or goto-style error handling when calling the KIM APIs. In addition, kim_error_free() may be called on KIM_NO_ERROR.

    -

    Note:
    Certain kim_error_t objects are preallocated by the libraries avoid exacerbating existing problems while trying to report an error. For example, the out of memory error object is preallocated. It is safe to call kim_error_free() on these errors, although the function may not actually free the object.
    -By providing an error object rather than a numeric code, the KIM APIs can tailor error strings to the circumstances of the error. So rather than returning error strings like "Client not found in Kerberos database", we can report "'user@REALM' not found in Kerberos database" while still providing the machine readable error KRB5KDC_ERR_C_PRINCIPAL_UNKNOWN.

    -See KIM Error Reference Documentation for information on specific APIs.

    Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  +

    KIM Error Overview

    Like most C APIs, the KIM API returns numeric error codes. These error codes may come from KIM, krb5 or GSS APIs. In most cases the caller will want to handle these error programmatically. However, in some circumstances the caller may wish to print an error string to the user.

    +One problem with just printing the error code to the user is that frequently the context behind the error has been lost. For example if KIM is trying to obtain credentials via referrals, it may fail partway through the process. In this case the error code will be KRB5KDC_ERR_C_PRINCIPAL_UNKNOWN, which maps to "Client not found in Kerberos database". Unfortunately this error isn't terribly helpful because it doesn't tell the user whether they typoed their principal name or if referrals failed.

    +To avoid this problem, KIM maintains an explanatory string for the last error seen in each thread calling into KIM. If a caller wishes to display an error to the user, immediately after getting the error the caller should call kim_string_get_last_error_message() to obtain a copy of the descriptive error message.

    +Note that because this string is stored in thread-specific data, callers must call kim_string_get_last_error_message() before calling any KIM APIs or any other APIs which might call into KIM. Callers who are not going to display this error string immediately should also make a copy of it so that it is not overwritten by the next call into KIM.

    +See KIM Error Reference Documentation for information on specific APIs.

    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/kim_identity_overview.html b/doc/kim/html/kim_identity_overview.html index 6a3aa1678..93ee11d24 100644 --- a/doc/kim/html/kim_identity_overview.html +++ b/doc/kim/html/kim_identity_overview.html @@ -13,33 +13,30 @@ Kerberos identities have both a binary (opaque) representation and also a string Creating and Displaying Identities KIM Identities can be generated from components, their escaped string representation or from a krb5_principal. Once you have a KIM identity object, you can also get the component, string or krb5_principal representations back out:

    - -
    Note:
    If you need to know if two identity objects refer to the same entity, use kim_identity_compare().
    +
    Note:
    If you need to know if two identity objects refer to the same entity, use kim_identity_compare().

    Choosing a Client Identity

    Unfortunately most of the time applications don't know what client identity to use. Users may have identities for multiple Kerberos realms, as well as multiple identities in a single realm (such as a user and administrator identity).

    -To solve this problem, kim_selection_hints_get_identity() takes information from the application in the form of a selection hints object and returns the best matching client identity, if one is available. See KIM Selection Hints Overview for more information.

    +To solve this problem, kim_selection_hints_get_identity() takes information from the application in the form of a selection hints object and returns the best matching client identity, if one is available. See KIM Selection Hints Overview for more information.

    Changing a Identity's Password

    Many Kerberos sites use passwords for user accounts. Because passwords may be stolen or compromised, they must be frequently changed. KIM provides APIs to change the identity's password directly, and also handles changing the identity's password when it has expired.

    -kim_identity_change_password() presents a user interface to obtain the old and new passwords from the user. kim_identity_change_password_with_passwords() takes the old and new passwords as input, but may still present a user interface if it needs to obtain additional information to authenticate.

    +kim_identity_change_password() presents a user interface to obtain the old and new passwords from the user. kim_identity_change_password_with_passwords() takes the old and new passwords as input, but may still present a user interface if it needs to obtain additional information to authenticate.

    Note:
    Not all identities have a password. Some sites use certificates (pkinit) and in the future there may be other authentication mechanisms (eg: smart cards).
    -See KIM Identity Reference Documentation for information on specific APIs.
    Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  +See KIM Identity Reference Documentation for information on specific APIs.
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/kim_options_overview.html b/doc/kim/html/kim_options_overview.html index bd7ad8466..f5e42c355 100644 --- a/doc/kim/html/kim_options_overview.html +++ b/doc/kim/html/kim_options_overview.html @@ -7,42 +7,39 @@

    KIM Options Overview

    Introduction

    -Kerberos Identity Management Options (kim_options_t) allows you to control how the Kerberos library obtains credentials. When the options structure is initialized with kim_options_create(), each option is filled in with a default value which can then be modified with the kim_options_set_*() APIs. If you only want to use the default values, you may pass KIM_OPTIONS_DEFAULT into any KIM function that takes a kim_options_t.

    +Kerberos Identity Management Options (kim_options_t) allows you to control how the Kerberos library obtains credentials. When the options structure is initialized with kim_options_create(), each option is filled in with a default value which can then be modified with the kim_options_set_*() APIs. If you only want to use the default values, you may pass KIM_OPTIONS_DEFAULT into any KIM function that takes a kim_options_t.

    KIM options fall into two major categories: options for controlling how credentials are acquired and options for controlling what properties the newly acquired credentials will have:

    Options for Controlling Credential Acquisition

    In order to acquire credentials, Kerberos needs to obtain one or more secrets from the user. These secrets may be a certificate, password, SecurID pin, or information from a smart card. If obtaining the secret requires interaction with the user, the Kerberos libraries call a "prompter callback" to display a dialog or command line prompt to request information from the user. If you want to provide your own custom dialogs or command line prompts, the KIM APIs provide a mechanism for replacing the default prompt callbacks with your own.

    Providing a Custom Prompt Callback

    -All secrets are obtained from the user through a kim_prompt_callback_t. By default, options use kim_prompt_callback_default, which presents an expanding dialog to request information from the user, or if no graphical access is available, a command line prompt.

    -KIM also provides three other callbacks: kim_prompt_callback_gui only presents a dialog and returns an error if there is no graphical access. kim_prompt_callback_cli only presents a command line interface and returns an error if there is no controlling terminal available. kim_prompt_callback_none always returns an error.

    -Using kim_options_set_prompt_callback(), you can change the prompt callback to one of the above callbacks or a callback you have defined yourself. Callbacks are called in a loop, one for each prompt. Because network traffic may occur between calls to the prompt callback, your prompt interface should support time passing between calls to the prompter. If you are defining a callback yourself, you should also set your own options data with kim_options_set_data() for storing state between calls. Options data is a caller defined pointer value -- the Kerberos libaries make no use of it.

    -Prefetching Prompt Responses

    -Sometimes you may have already collected some of the information needed to acquire Kerberos credentials. Rather than creating a prompt callback, you may also prefetch responses to the options directly with kim_options_set_prompt_response(). Once you have associated your response with a given prompt type, the Kerberos libraries will use this response for the first prompt of that type rather than calling the prompt callback to obtain it.

    -Note that even if you prefetch responses, the prompt callback may still be called if you did not provide all the information required for the identity. You may specify the kim_prompt_callback_none prompt callback to prevent prompting from occuring entirely, however, doing so will tie your application to a particular Kerberos configuration. For example, if your application assumes that all identities only require a password, it will not be able to acquire credentials at sites using SecurID pins.

    +All secrets are obtained from the user through a kim_prompt_callback_t. By default, options use kim_prompt_callback_default, which presents a dialog to request information from the user, or if no graphical access is available, a command line prompt.

    +KIM also provides three other callbacks: kim_prompt_callback_gui only presents a dialog and returns an error if there is no graphical access. kim_prompt_callback_cli only presents a command line interface and returns an error if there is no controlling terminal available. kim_prompt_callback_none always returns an error.

    +Using kim_options_set_prompt_callback(), you can change the prompt callback to one of the above callbacks or a callback you have defined yourself. Callbacks are called in a loop, one for each prompt. Because network traffic may occur between calls to the prompt callback, your prompt interface should support time passing between calls to the prompter. If you are defining a callback yourself, you should also set your own options data with kim_options_set_data() for storing state between calls. Options data is a caller defined pointer value -- the Kerberos libaries make no use of it.

    Options for Controlling Credential Properties

    Kerberos credentials have a number of different properties which can be requested when credentials are acquired. These properties control when and for how long the credentials are valid and what you can do with them.

    Note that setting these properties in the KIM options only changes what the Kerberos libraries request from the KDC. The KDC itself may choose not to honor your requested properties if they violate the site security policy. For example, most sites place an upper bound on how long credentials may be valid. If you request a credential lifetime longer than this upper bound, the KDC may return credentials with a shorter lifetime than you requested.

    Credential Lifetime

    Kerberos credentials have start time and a lifetime during which they are valid. Once the lifetime has passed, credentials "expire" and can no longer be used.

    -The requested credential start time can be set with kim_options_set_start_time() and examined with kim_options_get_start_time(). The requested credential lifetime can be set with kim_options_set_lifetime() and examined with kim_options_get_lifetime().

    +The requested credential start time can be set with kim_options_set_start_time() and examined with kim_options_get_start_time(). The requested credential lifetime can be set with kim_options_set_lifetime() and examined with kim_options_get_lifetime().

    Renewable Credentials

    Credentials with very long lifetimes are more convenient since the user does not have authenticate as often. Unfortunately they are also a higher security risk: if credentials are stolen they can be used until they expire. Credential renewal exists to compromise between these two conflicting goals.

    Renewable credentials are TGT credentials which can be used to obtain new TGT credentials without reauthenticating. By regularly renewing credentials the KDC has an opportunity to check to see if the client's credentials have been reported stolen and refuse to renew them. Renewable credentials have a "renewal lifetime" during which credentials can be renewed. This lifetime is relative to the original credential start time. If credentials are renewed shortly before the end of the renewal lifetime, their lifetime will be capped to the end of the renewal lifetime.

    Note that credentials must be valid to be renewed and therefore may not be an appropriate solution for all use cases. Sites which use renewable credentials often create helper processes running as the user which will automatically renew the user's credentials when they get close to expiration.

    -Use kim_options_set_renewable() to change whether or not the Kerberos libraries request renewable credentials and kim_options_get_renewable() to find out the current setting. Use kim_options_set_renewal_lifetime() to change the requested renewal lifetime and kim_options_get_renewal_lifetime() to find out the current value.

    +Use kim_options_set_renewable() to change whether or not the Kerberos libraries request renewable credentials and kim_options_get_renewable() to find out the current setting. Use kim_options_set_renewal_lifetime() to change the requested renewal lifetime and kim_options_get_renewal_lifetime() to find out the current value.

    Addressless Credentials

    Traditionally Kerberos used the host's IP address as a mechanism to restrict the user's credentials to a specific host, thus making it harder to use stolen credentials. When authenticating to a remote service with credentials containing addresses, the remote service verifies that the client's IP address is one of the addresses listed in the credential. Unfortunately, modern network technologies such as NAT rewrite the IP address in transit, making it difficult to use credentials with addresses in them. As a result, most Kerberos sites now obtain addressless credentials.

    -Use kim_options_set_addressless() to change whether or not the Kerberos libraries request addressless credentials. Use kim_options_get_addressless() to find out the current setting.

    +Use kim_options_set_addressless() to change whether or not the Kerberos libraries request addressless credentials. Use kim_options_get_addressless() to find out the current setting.

    Forwardable Credentials

    Forwardable credentials are TGT credentials which can be forwarded to a service you have authenticated to. If the credentials contain IP addresses, the addresses are changed to reflect the service's IP address. Credential forwarding is most commonly used for Kerberos-authenticated remote login services. By forwarding TGT credentials through the remote login service, the user's credentials will appear on the remote host when the user logs in.

    The forwardable flag only applies to TGT credentials.

    -Use kim_options_set_forwardable() to change whether or not the Kerberos libraries request forwardable credentials. Use kim_options_get_forwardable() to find out the current setting.

    +Use kim_options_set_forwardable() to change whether or not the Kerberos libraries request forwardable credentials. Use kim_options_get_forwardable() to find out the current setting.

    Proxiable Credentials

    Proxiable credentials are similar to forwardable credentials except that instead of forwarding the a TGT credential itself, a service credential is forwarded instead. Using proxiable credentials, a user can permit a service to perform a specific task as the user using one of the user's service credentials.

    Like forwardability, the proxiable flag only applies to TGT credentials. Unlike forwarded credentials, the IP address of proxiable credentials are not modified for the service when being proxied. This can be solved by also requesting addressless credentials.

    -Use kim_options_set_proxiable() to change whether or not the Kerberos libraries request proxiable credentials. Use kim_options_get_proxiable() to find out the current setting.

    +Use kim_options_set_proxiable() to change whether or not the Kerberos libraries request proxiable credentials. Use kim_options_get_proxiable() to find out the current setting.

    Service Name

    -Normally users acquire TGT credentials (ie "ticket granting tickets") and then use those credentials to acquire service credentials. This allows Kerberos to provide single sign-on while still providing mutual authentication to services. However, sometimes you just want an initial credential for a service. KIM options allows you to set the service name with kim_options_set_service_name() and query it with kim_options_get_service_name().

    -See KIM Options Reference Documentation for information on specific APIs.

    Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  +Normally users acquire TGT credentials (ie "ticket granting tickets") and then use those credentials to acquire service credentials. This allows Kerberos to provide single sign-on while still providing mutual authentication to services. However, sometimes you just want an initial credential for a service. KIM options allows you to set the service name with kim_options_set_service_name() and query it with kim_options_get_service_name().

    +See KIM Options Reference Documentation for information on specific APIs.

    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/kim_preferences_overview.html b/doc/kim/html/kim_preferences_overview.html index b388729bb..c42e0878b 100644 --- a/doc/kim/html/kim_preferences_overview.html +++ b/doc/kim/html/kim_preferences_overview.html @@ -9,19 +9,27 @@ Introduction In addition to the site preferences stored in the Kerberos configuration, users may also want to have their own personal preferences for controlling credential acquisition. As a result, KIM provides user preferences for initial credential options and user interface behavior such as the default client identity and the favorite identities list.

    Viewing and Editing the Preferences

    -In order to view and edit the user's preferences, call kim_preferences_create() to acquire a preferences object containing the user's preferences. You can examine preferences with the functions starting with "kim_preferences_get_" and change preferences with the functions starting with "kim_preferences_set_". Once you are done making changes, you can write changes back out to the user's preferences with kim_preferences_synchronize().

    +In order to view and edit the user's preferences, call kim_preferences_create() to acquire a preferences object containing the user's preferences. You can examine preferences with the functions starting with "kim_preferences_get_" and change preferences with the functions starting with "kim_preferences_set_". Once you are done making changes, you can write changes back out to the user's preferences with kim_preferences_synchronize().

    Note:
    The location of user preferences and the semantics of preference synchronization is platform-specific. Where possible KIM will use platform-specific preference mechanisms.

    Initial Credential Options Preferences

    -KIM provides user preferences for initial credential options. These are the options kim_options_create() will use when creating a new KIM options object. They are also the options specified by KIM_OPTIONS_DEFAULT. You can view and edit the initial credential options using kim_preferences_get_options() and kim_preferences_set_options().

    +KIM provides user preferences for initial credential options. These are the options kim_options_create() will use when creating a new KIM options object. They are also the options specified by KIM_OPTIONS_DEFAULT. You can view and edit the initial credential options using kim_preferences_get_options() and kim_preferences_set_options().

    Note:
    Not all credential options in the kim_options_t object have corresponding user preferences. For example, the prompt callback function is not stored in the user preferences since it has no meaning outside of the current application. Some options which are not currently stored in the preferences may be stored there in the future.
    -If you are implementing a user interface for credentials acquisition, you should be aware that KIM has a user preference to manage the initial credential options preferences. If the user successfully acquires credentials with non-default options and kim_preferences_get_remember_options() is set to TRUE, you should store the options used to get credentials with kim_preferences_set_options().

    +If you are implementing a user interface for credentials acquisition, you should be aware that KIM has a user preference to manage the initial credential options preferences. If the user successfully acquires credentials with non-default options and kim_preferences_get_remember_options() is set to TRUE, you should store the options used to get credentials with kim_preferences_set_options().

    Client Identity Preferences

    -KIM also provides user preferences for the default client identity. This identity is used whenever KIM needs to display a graphical dialog for credential acquisition but does not know what client identity to use. You can view and edit the default client identity using kim_preferences_get_client_identity() and kim_preferences_set_client_identity().

    -If you are implementing a user interface for credentials acquisition, you should be aware that KIM has a user preference to manage the client identity preferences. If the user successfully acquires credentials with non-default options and kim_preferences_get_remember_client_identity() is set to TRUE, you should store the client identity for which credentials were acquired using kim_preferences_set_client_identity().

    +KIM also provides user preferences for the default client identity. This identity is used whenever KIM needs to display a graphical dialog for credential acquisition but does not know what client identity to use. You can view and edit the default client identity using kim_preferences_get_client_identity() and kim_preferences_set_client_identity().

    +If you are implementing a user interface for credentials acquisition, you should be aware that KIM has a user preference to manage the client identity preferences. If the user successfully acquires credentials with non-default options and kim_preferences_get_remember_client_identity() is set to TRUE, you should store the client identity for which credentials were acquired using kim_preferences_set_client_identity().

    Favorite Identities Preferences

    -When presenting a graphical interface for credential acquisition, KIM may need to display a list of identities for the user to select from. This list is generated by the user's favorite identities preference. You can view and edit the favorite identities preference using kim_preferences_get_favorite_identities() and kim_preferences_set_favorite_identities(). Please see the KIM Favorite Identities Overview for more information.

    -See KIM Preferences Documentation for information on specific APIs.

    Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  +As Kerberos becomes more widespread, the number of possible Kerberos identities and realms a user might want to use will become very large. Sites may list hundreds of realms in their Kerberos configuration files. In addition, sites may wish to use DNS SRV records to avoid having to list all the realms they use in their Kerberos configuration. As a result, the list of realms in the Kerberos configuration may be exceedingly large and/or incomplete. Users may also use multiple identities from the same realm.

    +On platforms which use a GUI to acquire credentials, the KIM would like to to display a list of identities for the user to select from. Depending on what is appropriate for the platform, identities may be displayed in a popup menu or other list.

    +To solve this problem, the KIM maintains a list of favorite identities specifically for identity selection. This list is a set of unique identities in alphabetical order (as appropriate for the user's language localization).

    +Each identity may optionally have its own options for ticket acquisition. This allows KIM UIs to remember what ticket options worked for a specific identity. For example if the user normally wants renewable tickets but they have one identity at a KDC which rejects requests for renewable tickets, the "not renewable" option can be associated with that identity without changing the user's default preference to get renewable tickets. If an identity should use the default options, just pass KIM_OPTIONS_DEFAULT.

    +Most callers will not need to use the favorite identities APIs. However if you are implementing your own graphical prompt callback or a credential management application, you may to view and/or edit the user's favorite identities.

    +Viewing and Editing the Favorite Identities

    +First, you need to acquire the Favorite Identities stored in the user's preferences using kim_preferences_create().

    +Then use kim_preferences_get_number_of_favorite_identities() and kim_preferences_get_favorite_identity_at_index() to display the identities list. Use kim_preferences_add_favorite_identity() and kim_preferences_remove_favorite_identity() to change which identities are in the identities list. Identities are always stored in alphabetical order and duplicate identities are not permitted, so when you add or remove a identity you should redisplay the entire list. If you wish to replace the identities list entirely, use kim_preferences_remove_all_favorite_identities() to clear the list before adding your identities.

    +Once you are done editing the favorite identities list, store changes in the user's preference file using kim_preferences_synchronize().

    +See KIM Preferences Documentation for information on specific APIs.

    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/kim_selection_hints_overview.html b/doc/kim/html/kim_selection_hints_overview.html index d9be9d260..b8428b885 100644 --- a/doc/kim/html/kim_selection_hints_overview.html +++ b/doc/kim/html/kim_selection_hints_overview.html @@ -29,26 +29,26 @@ For example, if you specify a service identity and a credential for that identit
    Note:
    Due to performance and information exposure concerns, currently all searching is done by examining the cache collection. In the future the KIM may also make network requests as part of its search algorithm. For example it might check to see if the TGT credentials in each ccache can obtain credentials for the service identity specified by the selection hints.

    Selecting an Identity Using Selection Hints

    -Once you have provided search criteria for selecting an identity, use kim_selection_hints_get_identity() to obtain an identity object. You can then use kim_identity_get_gss_name() to obtain a gss_name_t for use in gss_acquire_cred() or use kim_ccache_create_from_client_identity() to obtain a ccache containing credentials for the identity.

    -

    Note:
    kim_selection_hints_get_identity() obtains an identity based on the current state of the selection hints object. If you change the selection hints object you must call kim_selection_hints_get_identity() again.
    +Once you have provided search criteria for selecting an identity, use kim_selection_hints_get_identity() to obtain an identity object. You can then use kim_identity_get_gss_name() to obtain a gss_name_t for use in gss_acquire_cred() or use kim_ccache_create_from_client_identity() to obtain a ccache containing credentials for the identity.

    +

    Note:
    kim_selection_hints_get_identity() obtains an identity based on the current state of the selection hints object. If you change the selection hints object you must call kim_selection_hints_get_identity() again.

    Selection Hint Caching Behavior

    In addition to using selection hints to search for an appropriate client identity, KIM can also use them to remember which client identity worked. KIM maintains a per-user cache mapping selection hints to identities so that applications do not have to maintain their own caches or present user interface for selecting which cache to use.

    -When kim_selection_hints_get_identity() is called KIM looks up in the cache and returns the identity which the selection hints map to. If there is not a preexisting cache entry for the selection hints then kim_selection_hints_get_identity() will search for an identity and prompt the user if it cannot find an appropriate one.

    -If the client identity returned by KIM authenticates and passes authorization checks, you should tell KIM to cache the identity by calling kim_selection_hints_remember_identity(). This will create a cache entry for the mapping between your selection hints and the identity so that subsequent calls to kim_selection_hints_get_identity() do not need to prompt the user.

    -If the client identity returned by KIM fails to authenticate or fails authorization checks, you must call kim_selection_hints_forget_identity() to remove any mapping that already exists. After this function is called, future calls to kim_selection_hints_get_identity() will search for an identity again. You may also wish to call this function if the user changes your application preferences such that the identity might be invalidated.

    -

    Note:
    It is very important that you call kim_selection_hints_forget_identity() if your application fails to successfully establish a connection with the server. Otherwise the user can get "stuck" using the same non-working identity if they chose the wrong one accidentally or if their identity information changes. Because only your application understands the authorization checksof the protocol it uses, KIM cannot tell whether or not the identity worked.
    -If you wish to search and prompt for an identity without using the cached mappings, you can turn off the cached mapping lookups using kim_selection_hints_set_remember_identity(). This is not recommended for most applications since it will result in a lot of unnecessary searching and prompting for identities.

    +When kim_selection_hints_get_identity() is called KIM looks up in the cache and returns the identity which the selection hints map to. If there is not a preexisting cache entry for the selection hints then kim_selection_hints_get_identity() will search for an identity and prompt the user if it cannot find an appropriate one.

    +If the client identity returned by KIM authenticates and passes authorization checks, you should tell KIM to cache the identity by calling kim_selection_hints_remember_identity(). This will create a cache entry for the mapping between your selection hints and the identity so that subsequent calls to kim_selection_hints_get_identity() do not need to prompt the user.

    +If the client identity returned by KIM fails to authenticate or fails authorization checks, you must call kim_selection_hints_forget_identity() to remove any mapping that already exists. After this function is called, future calls to kim_selection_hints_get_identity() will search for an identity again. You may also wish to call this function if the user changes your application preferences such that the identity might be invalidated.

    +

    Note:
    It is very important that you call kim_selection_hints_forget_identity() if your application fails to successfully establish a connection with the server. Otherwise the user can get "stuck" using the same non-working identity if they chose the wrong one accidentally or if their identity information changes. Because only your application understands the authorization checksof the protocol it uses, KIM cannot tell whether or not the identity worked.
    +If you wish to search and prompt for an identity without using the cached mappings, you can turn off the cached mapping lookups using kim_selection_hints_set_remember_identity(). This is not recommended for most applications since it will result in a lot of unnecessary searching and prompting for identities.

    Note:
    Because cache entries key off of selection hints, it is important to always specify the same hints when contacting a particular service. Otherwise KIM will not always find the cache entries.

    Selection Hint Prompting Behavior

    -If valid credentials for identity in the selection hints cache are unavailable or if no identity could be found using searching or caching when kim_selection_hints_get_identity() is called, KIM may present a GUI to ask the user to select an identity or acquire credentials for an identity.

    +If valid credentials for identity in the selection hints cache are unavailable or if no identity could be found using searching or caching when kim_selection_hints_get_identity() is called, KIM may present a GUI to ask the user to select an identity or acquire credentials for an identity.

    Note:
    Because of the caching behavior described above the user will only be prompted to choose an identity when setting up the application or when their identity stops working.
    -In order to let the user know why Kerberos needs their assistance, KIM displays the name of the application which requested the identity selection. Unfortunately, some platforms do not provide a runtime mechanism for determining the name of the calling process. If your application runs on one of these platforms (or is cross-platform) you should provide a localized version of its name with kim_selection_hints_set_application_name(). You can check what name will be used with kim_selection_hints_get_application_name().

    -In many cases a single application may select different identities for different purposes. For example an email application might use different identities to check mail for different accounts. If your application has this property you may need to provide the user with a localized string describing how the identity will be used. You can specify this string with kim_selection_hints_get_explanation(). You can find out what string will be used with kim_selection_hints_set_explanation().

    -Since the user may choose to acquire credentials when selection an identity, KIM also provides kim_selection_hints_set_options() to set what credential acquisition options are used. kim_selection_hints_get_options() returns the options which will be used.

    -If you need to disable user interaction, use kim_selection_hints_set_allow_user_interaction(). Use kim_selection_hints_get_allow_user_interaction() to find out whether or not user interaction is enabled. User interaction is enabled by default.

    -See KIM Selection Hints Reference Documentation for information on specific APIs.

    Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  +In order to let the user know why Kerberos needs their assistance, KIM displays the name of the application which requested the identity selection. Unfortunately, some platforms do not provide a runtime mechanism for determining the name of the calling process. If your application runs on one of these platforms (or is cross-platform) you should provide a localized version of its name with kim_selection_hints_set_application_name(). You can check what name will be used with kim_selection_hints_get_application_name().

    +In many cases a single application may select different identities for different purposes. For example an email application might use different identities to check mail for different accounts. If your application has this property you may need to provide the user with a localized string describing how the identity will be used. You can specify this string with kim_selection_hints_get_explanation(). You can find out what string will be used with kim_selection_hints_set_explanation().

    +Since the user may choose to acquire credentials when selection an identity, KIM also provides kim_selection_hints_set_options() to set what credential acquisition options are used. kim_selection_hints_get_options() returns the options which will be used.

    +If you need to disable user interaction, use kim_selection_hints_set_allow_user_interaction(). Use kim_selection_hints_get_allow_user_interaction() to find out whether or not user interaction is enabled. User interaction is enabled by default.

    +See KIM Selection Hints Reference Documentation for information on specific APIs.

    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/kim_string_overview.html b/doc/kim/html/kim_string_overview.html index 202d2e679..765b4d14e 100644 --- a/doc/kim/html/kim_string_overview.html +++ b/doc/kim/html/kim_string_overview.html @@ -7,7 +7,7 @@

    KIM String Overview

    A UTF8 string.

    Memory management routines are provided for runtime consistency on operating systems with shared libraries and multiple runtimes.

    -See KIM String Reference Documentation for information on specific APIs.

    Generated on Wed May 7 15:22:19 2008 for Kerberos Identity Management by  +See KIM String Reference Documentation for information on specific APIs.
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/doc/kim/html/modules.html b/doc/kim/html/modules.html index ee3e888cb..fb5fc339b 100644 --- a/doc/kim/html/modules.html +++ b/doc/kim/html/modules.html @@ -13,13 +13,12 @@
  • KIM Error Reference Documentation
  • KIM Identity Reference Documentation
  • KIM Options Reference Documentation -
  • KIM Favorite Identities Documentation
  • KIM Preferences Documentation
  • KIM Selection Hints Reference Documentation
  • KIM String Reference Documentation
  • KIM Types and Constants -
    Generated on Wed May 7 15:22:20 2008 for Kerberos Identity Management by  +
    Generated on Thu Sep 18 10:55:28 2008 for Kerberos Identity Management by  doxygen 1.5.3
    diff --git a/src/include/kim/kim_identity.h b/src/include/kim/kim_identity.h index 8e3facada..4461c3163 100644 --- a/src/include/kim/kim_identity.h +++ b/src/include/kim/kim_identity.h @@ -83,8 +83,6 @@ extern "C" { * \li #kim_identity_create_from_krb5_principal() generates an identity object from a krb5_principal object. * \li #kim_identity_get_krb5_principal() returns a krb5_principal object for an identity object. * - * \li #kim_identity_get_gss_name() returns a gss_name_t object for use with gss_acquire_cred(). - * * \note If you need to know if two identity objects refer to the same entity, use #kim_identity_compare(). * * @@ -256,16 +254,6 @@ kim_error kim_identity_get_krb5_principal (kim_identity in_identity, krb5_context in_krb5_context, krb5_principal *out_krb5_principal); -/*! - * \param in_identity an identity object. - * \param out_gss_name on exit, a gss_name_t representation of \a in_identity. - * Must be freed with gss_release_name(). - * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. - * \brief Get the gss_name_t representation of an identity. - */ -kim_error kim_identity_get_gss_name (kim_identity in_identity, - gss_name_t *out_gss_name); - /*! * \param in_identity an identity object whose password will be changed. * \param in_options initial credential options to be used if a new credential is obtained. diff --git a/src/kim/lib/kim_identity.c b/src/kim/lib/kim_identity.c index db4279020..2fd8579d0 100644 --- a/src/kim/lib/kim_identity.c +++ b/src/kim/lib/kim_identity.c @@ -471,7 +471,16 @@ kim_error kim_identity_get_krb5_principal (kim_identity in_identity, } /* ------------------------------------------------------------------------ */ - +/*! + * \param in_identity an identity object. + * \param out_gss_name on exit, a gss_name_t representation of \a in_identity. + * Must be freed with gss_release_name(). + * \return On success, #KIM_NO_ERROR. On failure, an error code representing the failure. + * \brief Get the gss_name_t representation of an identity. + */ +/*kim_error kim_identity_get_gss_name (kim_identity in_identity, + gss_name_t *out_gss_name);*/ +/* kim_error kim_identity_get_gss_name (kim_identity in_identity, gss_name_t *out_gss_name) { @@ -485,7 +494,7 @@ kim_error kim_identity_get_gss_name (kim_identity in_identity, } return check_error (err); -} +}*/ /* ------------------------------------------------------------------------ */ -- 2.26.2
    • kim_error_code_t kim_prompt_callback_none kim_error kim_prompt_callback_none (kim_options_t *  io_options,
    kim_prompt_type_t kim_prompt_type  in_type,
    kim_string_t kim_string  in_title,
    kim_string_t kim_string  in_message,
    kim_string_t kim_string  in_description,
    void ** char **  out_reply