TITLE

AUTHOR
Version 
CREATEDATE

Table of Contents

Table of contents

Kerberos Identity Management (KIM) API Documentation 

Introduction
The Kerberos Identity Management API is a high level API for managing the selection and management of Kerberos credentials. It is intended for use by applications, credential management applications (eg: kinit, kpasswd, etc) and internally by the Kerberos libraries. Under some circumstances client applications may also benefit from the Kerberos Identity Management API.
API Conventions
Although KIM currently only provides a C API, it attempts to make that API as object-oriented as possible. KIM functions are grouped by object and all of the object types are opaque, including errors. The reason for this is two-fold. First, the KIM API is rather large. Grouping functions by object allows the API to be broken up into smaller, more manageable chunks. Second, providing an object-like C API will make it easier to port to object oriented languages.
Because C lacks classes and other object oriented syntax, KIM functions adhere to the following naming conventions to make functions easier to identify:

Functions beginning with kim_object_create  are constructors for an object of type kim_object. On success these functions return a newly allocated object which must later be freed by the caller.

Functions of the form kim_object_copy  are copy constructors. They instantiate a new object of kim_object from an object of the same type.

Functions of the form kim_object_free  are destructors for objects of type kim_object.

Functions beginning with kim_object_get  and kim_object_set  examine and modify properties of objects of type kim_object.

All KIM APIs except destructors and error management APIs return a KIM Error object (kim_error_t).

Terminology
Kerberos organizes its authentication tokens by client identity (the name of the user) and service identity (the name of a service). The following terms are used throughout this documentation:

credential  - A token which authenticates a client identity to a service identity.

ccache  - Short for "credentials cache". A set of credentials for a single client identity.

cache collection  - The set of all credential caches.

default ccache  - A credentials cache that the Kerberos libraries will use if no ccache is specified by the caller. Use of the default ccache is now discouraged. Instead applications should use selection hints to choose an appropriate client identity.

Client Identity Selection APIs
KIM provides high level APIs for applications to select which client identity to use. Use of these APIs is intended to replace the traditional "default ccache" mechanism previously used by Kerberos.
KIM Selection Hints (kim_selection_hints_t)  controls options for selecting a client identity:
KIM Selection Hints Overview 
KIM Selection Hints Reference Documentation 

KIM Identity (kim_identity_t)  provides an immutable Kerberos identity object
KIM Identity Overview 
KIM Identity Reference Documentation 

Credential Management APIs
KIM also provides APIs for acquiring new credentials over the network by contacting a KDC and for viewing and modifying the existing credentials in the cache collection
Whether or not you use the credential or ccache APIs depends on whether you want KIM to store any newly acquired credentials in the cache collection. KIM ccache APIs always create a ccache in the cache collection containing newly acquired credentials whereas the KIM credential APIs just return a credential object. In general most callers want to store newly acquired credentials and should use the KIM ccache APIs when acquiring credentials.
KIM CCache (kim_ccache_t)  manipulates credential caches in the cache collection:
KIM CCache Overview 
KIM CCache Reference Documentation 

KIM Credential (kim_credential_t)  manipulates credentials:
KIM Credential Overview 
KIM Credential Reference Documentation 

KIM Options (kim_options_t)  control options for credential acquisition:
KIM Options Overview 
KIM Options Reference Documentation 

KIM Realms List (kim_favorite_realms_t)  views and edits the current user's favorite realms list:
KIM Favorite Realms Overview 
KIM Favorite Realms Documentation 

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

Miscellaneous APIs
The high and low level APIs depend on the following basic utility classes to manage generic types.
KIM String (kim_string_t)  provides memory management for an immutable string:
KIM String Overview 
KIM String Reference Documentation 

KIM Error (kim_error_t)  provides a machine and user-readable error message:
KIM Error Overview 
KIM Error Reference Documentation 

Types and Constants

KIM Types and Constants  

Kerberos Identity Management Module Index
Kerberos Identity Management Modules
Here is a list of all modules:
KIM CCache Iterator Reference Documentation	pagenum
KIM CCache Reference Documentation	pagenum
KIM Credential Iterator Reference Documentation	pagenum
KIM Credential Reference Documentation	pagenum
KIM Error Reference Documentation	pagenum
KIM Identity Reference Documentation	pagenum
KIM Options Reference Documentation	pagenum
KIM Favorite Realms Documentation	pagenum
KIM Preferences Documentation	pagenum
KIM Selection Hints Reference Documentation	pagenum
KIM String Reference Documentation	pagenum
KIM Types and Constants	pagenum

Kerberos Identity Management Module Documentation
KIM CCache Iterator Reference Documentation

Functions
kim_error_t kim_ccache_iterator_create (kim_ccache_iterator_t *out_ccache_iterator)
Get a ccache iterator to enumerate ccaches in the cache collection. 

kim_error_t kim_ccache_iterator_next (kim_ccache_iterator_t in_ccache_iterator, kim_ccache_t *out_ccache)
Get the next ccache in the cache collection. 

void kim_ccache_iterator_free (kim_ccache_iterator_t *io_ccache_iterator)
Free memory associated with a ccache iterator. 

Function Documentation
kim_error_t kim_ccache_iterator_create (kim_ccache_iterator_t * out_ccache_iterator)
Get a ccache iterator to enumerate ccaches in the cache collection. 

Parameters:
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. 
kim_error_t kim_ccache_iterator_next (kim_ccache_iterator_t in_ccache_iterator, kim_ccache_t * out_ccache)
Get the next ccache in the cache collection. 

Parameters:
in_ccache_iterator a ccache iterator object. 
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. 
void kim_ccache_iterator_free (kim_ccache_iterator_t * io_ccache_iterator)
Free memory associated with a ccache iterator. 

Parameters:
io_ccache_iterator a ccache iterator object to be freed. Set to NULL on exit. 

KIM CCache Reference Documentation

Functions
kim_error_t kim_ccache_create_new (kim_ccache_t *out_ccache, kim_identity_t in_client_identity, kim_options_t in_options)
Acquire a new initial credential and store it in a ccache. 

kim_error_t kim_ccache_create_new_if_needed (kim_ccache_t *out_ccache, kim_identity_t in_client_identity, kim_options_t 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_t kim_ccache_create_from_client_identity (kim_ccache_t *out_ccache, kim_identity_t in_client_identity)
Find a ccache for a client identity in the cache collection. 

kim_error_t kim_ccache_create_from_keytab (kim_ccache_t *out_ccache, kim_identity_t in_identity, kim_options_t in_options, kim_string_t in_keytab)
Acquire a new initial credential from a keytab and store it in a ccache. 

kim_error_t kim_ccache_create_from_default (kim_ccache_t *out_ccache)
Get the default ccache. 

kim_error_t kim_ccache_create_from_name_and_type (kim_ccache_t *out_ccache, kim_string_t in_name, kim_string_t in_type)
Get a ccache for a ccache name and type. 

kim_error_t kim_ccache_create_from_krb5_ccache (kim_ccache_t *out_ccache, krb5_ccache in_krb5_ccache, krb5_context in_krb5_context)
Get a ccache for a krb5 ccache. 

kim_error_t kim_ccache_copy (kim_ccache_t *out_ccache, kim_ccache_t in_ccache)
Copy a ccache. 

kim_error_t kim_ccache_get_krb5_ccache (kim_ccache_t in_ccache, krb5_context in_krb5_context, krb5_ccache *out_krb5_ccache)
Get a krb5 ccache for a ccache. 

kim_error_t kim_ccache_get_name (kim_ccache_t in_ccache, kim_string_t *out_name)
Get the name of a ccache. 

kim_error_t kim_ccache_get_type (kim_ccache_t in_ccache, kim_string_t *out_type)
Get the type of a ccache. 

kim_error_t kim_ccache_get_display_name (kim_ccache_t in_ccache, kim_string_t *out_display_name)
Get the type and name for a ccache in display format. 

kim_error_t kim_ccache_get_client_identity (kim_ccache_t in_ccache, kim_identity_t *out_client_identity)
Get the client identity for a ccache. 

kim_error_t kim_ccache_get_valid_credential (kim_ccache_t in_ccache, kim_credential_t *out_credential)
Get the first valid credential in a ccache. 

kim_error_t kim_ccache_get_credential_iterator (kim_ccache_t in_ccache, kim_credential_iterator_t *out_credential_iterator)
Get a credential iterator for a ccache. 

kim_error_t kim_ccache_get_start_time (kim_ccache_t in_ccache, kim_time_t *out_start_time)
Get the time when the credentials in the ccache become valid. 

kim_error_t kim_ccache_get_expiration_time (kim_ccache_t in_ccache, kim_time_t *out_expiration_time)
Get the time when the credentials in the ccache will expire. 

kim_error_t kim_ccache_get_renewal_expiration_time (kim_ccache_t in_ccache, kim_time_t *out_renewal_expiration_time)
Get the time when the credentials in the ccache will no longer be renewable. 

kim_error_t kim_ccache_set_default (kim_ccache_t in_ccache)
Set a ccache to the default ccache. 

kim_error_t kim_ccache_verify (kim_ccache_t in_ccache, kim_identity_t in_service_identity, kim_string_t in_keytab, kim_boolean_t in_fail_if_no_service_key)
Verify the TGT in a ccache. 

kim_error_t kim_ccache_renew (kim_ccache_t in_ccache, kim_options_t in_options)
Renew the TGT in a ccache. 

kim_error_t kim_ccache_validate (kim_ccache_t in_ccache, kim_options_t in_options)
Validate the TGT in a ccache. 

kim_error_t kim_ccache_destroy (kim_ccache_t *io_ccache)
Remove a ccache from the cache collection. 

void kim_ccache_free (kim_ccache_t *io_ccache)
Free memory associated with a ccache. 

Function Documentation
kim_error_t kim_ccache_create_new (kim_ccache_t * out_ccache, kim_identity_t in_client_identity, kim_options_t in_options)
Acquire a new initial credential and store it in a ccache. 

Parameters:
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. 
kim_error_t kim_ccache_create_new_if_needed (kim_ccache_t * out_ccache, kim_identity_t in_client_identity, kim_options_t in_options)
Find a ccache containing a valid initial credential in the cache collection, or if unavailable, acquire and store a new initial credential. 

Parameters:
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. 
kim_error_t kim_ccache_create_from_client_identity (kim_ccache_t * out_ccache, kim_identity_t in_client_identity)
Find a ccache for a client identity in the cache collection. 

Parameters:
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. 
kim_error_t kim_ccache_create_from_keytab (kim_ccache_t * out_ccache, kim_identity_t in_identity, kim_options_t in_options, kim_string_t in_keytab)
Acquire a new initial credential from a keytab and store it in a ccache. 

Parameters:
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. 
kim_error_t kim_ccache_create_from_default (kim_ccache_t * out_ccache)
Get the default ccache. 

Parameters:
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. 
kim_error_t kim_ccache_create_from_name_and_type (kim_ccache_t * out_ccache, kim_string_t in_name, kim_string_t in_type)
Get a ccache for a ccache name and type. 

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

Parameters:
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_ccache a krb5 ccache object. 
in_krb5_context the krb5 context used to create in_krb5_ccache. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_ccache_copy (kim_ccache_t * out_ccache, kim_ccache_t in_ccache)
Copy a ccache. 

Parameters:
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. 
kim_error_t kim_ccache_get_krb5_ccache (kim_ccache_t in_ccache, krb5_context in_krb5_context, krb5_ccache * out_krb5_ccache)
Get a krb5 ccache for a ccache. 

Parameters:
in_ccache a ccache object. 
in_krb5_context a krb5 context which will be used to create out_krb5_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. 
kim_error_t kim_ccache_get_name (kim_ccache_t in_ccache, kim_string_t * out_name)
Get the name of a ccache. 

Parameters:
in_ccache a ccache object. 
out_name on exit, the name string of in_ccache . 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_ccache_get_type (kim_ccache_t in_ccache, kim_string_t * out_type)
Get the type of a ccache. 

Parameters:
in_ccache a ccache object. 
out_type on exit, the type string of in_ccache . 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_ccache_get_display_name (kim_ccache_t in_ccache, kim_string_t * out_display_name)
Get the type and name for a ccache in display format. 

Parameters:
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(). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_ccache_get_client_identity (kim_ccache_t in_ccache, kim_identity_t * out_client_identity)
Get the client identity for a ccache. 

Parameters:
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(). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_ccache_get_valid_credential (kim_ccache_t in_ccache, kim_credential_t * out_credential)
Get the first valid credential in a ccache. 

Parameters:
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. 
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. 
kim_error_t kim_ccache_get_credential_iterator (kim_ccache_t in_ccache, kim_credential_iterator_t * out_credential_iterator)
Get a credential iterator for a ccache. 

Parameters:
in_ccache a ccache object. 
out_credential_iterator on exit, a credential iterator for in_ccache . Must be freed with kim_credential_iterator_free(). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_ccache_get_start_time (kim_ccache_t in_ccache, kim_time_t * out_start_time)
Get the time when the credentials in the ccache become valid. 

Parameters:
in_ccache a ccache object. 
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. 
kim_error_t kim_ccache_get_expiration_time (kim_ccache_t in_ccache, kim_time_t * out_expiration_time)
Get the time when the credentials in the ccache will expire. 

Parameters:
in_ccache a ccache object. 
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. 
kim_error_t kim_ccache_get_renewal_expiration_time (kim_ccache_t in_ccache, kim_time_t * out_renewal_expiration_time)
Get the time when the credentials in the ccache will no longer be renewable. 

Parameters:
in_ccache a ccache object. 
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. 
kim_error_t kim_ccache_set_default (kim_ccache_t in_ccache)
Set a ccache to the default ccache. 

Parameters:
in_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. 
Note:
This API is provided for backwards compatibilty with applications which are not KIM-aware and should be avoided whenever possible. 
kim_error_t kim_ccache_verify (kim_ccache_t in_ccache, kim_identity_t in_service_identity, kim_string_t in_keytab, kim_boolean_t in_fail_if_no_service_key)
Verify the TGT in a ccache. 

Parameters:
in_ccache a ccache object containing the TGT credential to be verified. 
in_service_identity a service identity to look for in the keytab. Specify KIM_IDENTITY_ANY to use the default service identity (usually host/<host's FQDN><host's local realm>). 
in_keytab a path to a keytab. Specify NULL for the default keytab location. 
in_fail_if_no_service_key whether or not the absence of a key for in_service_identity  in the host's keytab will cause a failure. 
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. 
kim_error_t kim_ccache_renew (kim_ccache_t in_ccache, kim_options_t in_options)
Renew the TGT in a ccache. 

Parameters:
in_ccache a ccache object containing a TGT to be renewed. 
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. 
kim_error_t kim_ccache_validate (kim_ccache_t in_ccache, kim_options_t in_options)
Validate the TGT in a ccache. 

Parameters:
in_ccache a ccache object containing a TGT to be validated. 
in_options initial credential options. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_ccache_destroy (kim_ccache_t * io_ccache)
Remove a ccache from the cache collection. 

Parameters:
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. 
void kim_ccache_free (kim_ccache_t * io_ccache)
Free memory associated with a ccache. 

Parameters:
io_ccache a ccache object to be freed. Set to NULL on exit. 

KIM Credential Iterator Reference Documentation

Functions
kim_error_t kim_credential_iterator_create (kim_credential_iterator_t *out_credential_iterator, kim_ccache_t in_ccache)
Get a credential iterator to enumerate credentials in a ccache. 

kim_error_t kim_credential_iterator_next (kim_credential_iterator_t in_credential_iterator, kim_credential_t *out_credential)
Get the next credential in a ccache. 

void kim_credential_iterator_free (kim_credential_iterator_t *io_credential_iterator)
Free memory associated with a credential iterator. 

Function Documentation
kim_error_t kim_credential_iterator_create (kim_credential_iterator_t * out_credential_iterator, kim_ccache_t in_ccache)
Get a credential iterator to enumerate credentials in a ccache. 

Parameters:
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. 
kim_error_t kim_credential_iterator_next (kim_credential_iterator_t in_credential_iterator, kim_credential_t * out_credential)
Get the next credential in a ccache. 

Parameters:
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. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
void kim_credential_iterator_free (kim_credential_iterator_t * io_credential_iterator)
Free memory associated with a credential iterator. 

Parameters:
io_credential_iterator a credential iterator object to be freed. Set to NULL on exit. 

KIM Credential Reference Documentation

Functions
kim_error_t kim_credential_create_new (kim_credential_t *out_credential, kim_identity_t in_client_identity, kim_options_t in_options)
Acquire a new initial credential. 

kim_error_t kim_credential_create_from_keytab (kim_credential_t *out_credential, kim_identity_t in_identity, kim_options_t in_options, kim_string_t in_keytab)
Acquire a new initial credential from a keytab. 

kim_error_t kim_credential_create_from_krb5_creds (kim_credential_t *out_credential, krb5_creds *in_krb5_creds, krb5_context in_krb5_context)
Copy a credential from a krb5 credential object. 

kim_error_t kim_credential_copy (kim_credential_t *out_credential, kim_credential_t in_credential)
Copy a credential object. 

kim_error_t kim_credential_get_krb5_creds (kim_credential_t in_credential, krb5_context in_krb5_context, krb5_creds **out_krb5_creds)
Get a krb5 credentials object for a credential object. 

kim_error_t kim_credential_get_client_identity (kim_credential_t in_credential, kim_identity_t *out_client_identity)
Get the client identity of a credential object. 

kim_error_t kim_credential_get_service_identity (kim_credential_t in_credential, kim_identity_t *out_service_identity)
Get the service identity of a credential object. 

kim_error_t kim_credential_is_tgt (kim_credential_t in_credential, kim_boolean_t *out_is_tgt)
Check if a credential is a ticket granting ticket. 

kim_error_t kim_credential_is_valid (kim_credential_t in_credential, kim_boolean_t *out_valid)
Check if a credential is valid. 

kim_error_t kim_credential_get_start_time (kim_credential_t in_credential, kim_time_t *out_start_time)
Get the time when the credentials become valid. 

kim_error_t kim_credential_get_expiration_time (kim_credential_t in_credential, kim_time_t *out_expiration_time)
Get the time when the credentials will expire. 

kim_error_t kim_credential_get_renewal_expiration_time (kim_credential_t in_credential, kim_time_t *out_renewal_expiration_time)
Get the time when the credentials will no longer be renewable. 

kim_error_t kim_credential_store (kim_credential_t in_credential, kim_identity_t in_client_identity, kim_ccache_t *out_ccache)
Store a credential in a ccache in the cache collection. 

kim_error_t kim_credential_verify (kim_credential_t in_credential, kim_identity_t in_service_identity, kim_string_t in_keytab, kim_boolean_t in_fail_if_no_service_key)
Verify a TGT credential. 

kim_error_t kim_credential_renew (kim_credential_t *io_credential, kim_options_t in_options)
Renew a TGT credential. 

kim_error_t kim_credential_validate (kim_credential_t *io_credential, kim_options_t in_options)
Validate a TGT credential. 

void kim_credential_free (kim_credential_t *io_credential)
Free memory associated with a credential object. 

Function Documentation
kim_error_t kim_credential_create_new (kim_credential_t * out_credential, kim_identity_t in_client_identity, kim_options_t in_options)
Acquire a new initial credential. 

Parameters:
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 
kim_error_t kim_credential_create_from_keytab (kim_credential_t * out_credential, kim_identity_t in_identity, kim_options_t in_options, kim_string_t in_keytab)
Acquire a new initial credential from a keytab. 

Parameters:
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 
kim_error_t kim_credential_create_from_krb5_creds (kim_credential_t * out_credential, krb5_creds * in_krb5_creds, krb5_context in_krb5_context)
Copy a credential from a krb5 credential object. 

Parameters:
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_creds a krb5 credential object. 
in_krb5_context the krb5 context used to create in_krb5_creds . 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_credential_copy (kim_credential_t * out_credential, kim_credential_t in_credential)
Copy a credential object. 

Parameters:
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. 
kim_error_t kim_credential_get_krb5_creds (kim_credential_t in_credential, krb5_context in_krb5_context, krb5_creds ** out_krb5_creds)
Get a krb5 credentials object for a credential object. 

Parameters:
in_credential a credential object. 
in_krb5_context a krb5 context which will be used to create out_krb5_creds . 
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. 
kim_error_t kim_credential_get_client_identity (kim_credential_t in_credential, kim_identity_t * out_client_identity)
Get the client identity of a credential object. 

Parameters:
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(). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_credential_get_service_identity (kim_credential_t in_credential, kim_identity_t * out_service_identity)
Get the service identity of a credential object. 

Parameters:
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(). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_credential_is_tgt (kim_credential_t in_credential, kim_boolean_t * out_is_tgt)
Check if a credential is a ticket granting ticket. 

Parameters:
in_credential a credential object. 
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. 
kim_error_t kim_credential_is_valid (kim_credential_t in_credential, kim_boolean_t * out_valid)
Check if a credential is valid. 

Parameters:
in_credential a credential object. 
out_valid on exit, whether or not the credential is valid. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
See also:
kim_ccache_is_valid 
kim_error_t kim_credential_get_start_time (kim_credential_t in_credential, kim_time_t * out_start_time)
Get the time when the credentials become valid. 

Parameters:
in_credential a credential object. 
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 
kim_error_t kim_credential_get_expiration_time (kim_credential_t in_credential, kim_time_t * out_expiration_time)
Get the time when the credentials will expire. 

Parameters:
in_credential a credential object. 
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 
kim_error_t kim_credential_get_renewal_expiration_time (kim_credential_t in_credential, kim_time_t * out_renewal_expiration_time)
Get the time when the credentials will no longer be renewable. 

Parameters:
in_credential a credential object. 
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 
kim_error_t kim_credential_store (kim_credential_t in_credential, kim_identity_t in_client_identity, kim_ccache_t * out_ccache)
Store a credential in a ccache in the cache collection. 

Parameters:
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. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_credential_verify (kim_credential_t in_credential, kim_identity_t in_service_identity, kim_string_t in_keytab, kim_boolean_t in_fail_if_no_service_key)
Verify a TGT credential. 

Parameters:
in_credential a TGT credential to be verified. 
in_service_identity a service identity to look for in the keytab. Specify KIM_IDENTITY_ANY to use the default service identity (usually host/<host's FQDN><host's local realm>). 
in_keytab a path to a keytab. Specify NULL for the default keytab location. 
in_fail_if_no_service_key whether or not the absence of a key for in_service_identity  in the host's keytab will cause a failure. 
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 
kim_error_t kim_credential_renew (kim_credential_t * io_credential, kim_options_t in_options)
Renew a TGT credential. 

Parameters:
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 
kim_error_t kim_credential_validate (kim_credential_t * io_credential, kim_options_t in_options)
Validate a TGT credential. 

Parameters:
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 
void kim_credential_free (kim_credential_t * io_credential)
Free memory associated with a credential object. 

Parameters:
io_credential the credential object to be freed. Set to NULL on exit. 

KIM Error Reference Documentation

Functions
kim_error_t kim_error_copy (kim_error_t *out_error, kim_error_t in_error)
Copy an error. 

kim_error_code_t kim_error_get_code (kim_error_t in_error)
Get a numerical error code for an error. 

const kim_string_t kim_error_get_display_string (kim_error_t in_error)
Get a text description of an error. 

void kim_error_free (kim_error_t *io_error)
Free memory associated with an error. 

Function Documentation
kim_error_t kim_error_copy (kim_error_t * out_error, kim_error_t in_error)
Copy an error. 

Parameters:
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. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
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. 
const 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. 

KIM Identity Reference Documentation

Functions
kim_error_t kim_identity_create_from_string (kim_identity_t *out_identity, kim_string_t in_string)
Create a identity from a string. 

kim_error_t kim_identity_create_from_components (kim_identity_t *out_identity, kim_string_t in_realm, kim_string_t in_1st_component,...)
Create a identity from a realm and component strings. 

kim_error_t kim_identity_create_from_krb5_principal (kim_identity_t *out_identity, krb5_principal in_krb5_principal, krb5_context in_krb5_context)
Create an identity object from a krb5_principal. 

kim_error_t kim_identity_copy (kim_identity_t *out_identity, kim_identity_t in_identity)
Copy an identity object. 

kim_error_t kim_identity_compare (kim_identity_t in_identity, kim_identity_t in_compare_to_identity, kim_boolean_t *out_equivalent)
Compare identity objects for equivalency. 

kim_error_t kim_identity_get_string (kim_identity_t in_identity, kim_string_t *out_string)
Get the string representation of a identity. 

kim_error_t kim_identity_get_display_string (kim_identity_t in_identity, kim_string_t *out_display_string)
Get a human-readable string representation of an identity. 

kim_error_t kim_identity_get_realm (kim_identity_t in_identity, kim_string_t *out_realm_string)
Get the realm string of an identity. 

kim_error_t kim_identity_get_number_of_components (kim_identity_t in_identity, kim_count_t *out_number_of_components)
Get the number of components of an identity. 

kim_error_t kim_identity_get_component_at_index (kim_identity_t in_identity, kim_index_t in_index, kim_string_t *out_component_string)
Get the Nth component of an identity. 

kim_error_t kim_identity_get_krb5_principal (kim_identity_t in_identity, krb5_context in_krb5_context, krb5_principal *out_krb5_principal)
Get the krb5_principal representation of an identity. 

kim_error_t kim_identity_get_gss_name (kim_identity_t in_identity, gss_name_t *out_gss_name)
Get the gss_name_t representation of an identity. 

kim_error_t kim_identity_change_password (kim_identity_t in_identity, kim_options_t in_options)
Change the password for an identity. 

kim_error_t kim_identity_change_password_with_passwords (kim_identity_t in_identity, kim_options_t in_options, kim_string_t in_new_password)
Change the password for an identity to a caller-provided new password. 

void kim_identity_free (kim_identity_t *io_identity)
Free memory associated with an identity. 

Function Documentation
kim_error_t kim_identity_create_from_string (kim_identity_t * out_identity, kim_string_t in_string)
Create a identity from a string. 

Parameters:
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. 
kim_error_t kim_identity_create_from_components (kim_identity_t * out_identity, kim_string_t in_realm, kim_string_t in_1st_component,  ...)
Create a identity from a realm and component strings. 

Parameters:
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). 
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. 
kim_error_t kim_identity_create_from_krb5_principal (kim_identity_t * out_identity, krb5_principal in_krb5_principal, krb5_context in_krb5_context)
Create an identity object from a krb5_principal. 

Parameters:
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_principal a krb5 identity object. 
in_krb5_context the krb5 context used to create in_krb5_principal . 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_identity_copy (kim_identity_t * out_identity, kim_identity_t in_identity)
Copy an identity object. 

Parameters:
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. 
kim_error_t kim_identity_compare (kim_identity_t in_identity, kim_identity_t in_compare_to_identity, kim_boolean_t * out_equivalent)
Compare identity objects for equivalency. 

Parameters:
in_identity an identity object. 
in_compare_to_identity an identity object. 
out_equivalent on exit, whether or not in_identity  and in_compare_to_identity  represent the same identity. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_identity_get_string (kim_identity_t in_identity, kim_string_t * out_string)
Get the string representation of a identity. 

Parameters:
in_identity an identity object. 
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. 
Note:
Special characters such as '@' and '/' will be escaped with '\'. 
kim_error_t kim_identity_get_display_string (kim_identity_t in_identity, kim_string_t * out_display_string)
Get a human-readable string representation of an identity. 

Parameters:
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(). 
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(). 
kim_error_t kim_identity_get_realm (kim_identity_t in_identity, kim_string_t * out_realm_string)
Get the realm string of an identity. 

Parameters:
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(). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_identity_get_number_of_components (kim_identity_t in_identity, kim_count_t * out_number_of_components)
Get the number of components of an identity. 

Parameters:
in_identity an identity object. 
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. 
kim_error_t kim_identity_get_component_at_index (kim_identity_t in_identity, kim_index_t in_index, kim_string_t * out_component_string)
Get the Nth component of an identity. 

Parameters:
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(). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_identity_get_krb5_principal (kim_identity_t in_identity, krb5_context in_krb5_context, krb5_principal * out_krb5_principal)
Get the krb5_principal representation of an identity. 

Parameters:
in_identity an identity object. 
in_krb5_context a krb5 context object. 
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. 
kim_error_t kim_identity_get_gss_name (kim_identity_t 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. 
kim_error_t kim_identity_change_password (kim_identity_t in_identity, kim_options_t in_options)
Change the password for an identity. 

Parameters:
in_identity an identity object whose password will be changed. 
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. 
kim_error_t kim_identity_change_password_with_passwords (kim_identity_t in_identity, kim_options_t in_options, kim_string_t in_new_password)
Change the password for an identity to a caller-provided new password. 

Parameters:
in_identity an identity object whose password will be changed. 
in_options initial credential options to be used if a new credential is obtained. 
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. 
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. 
void kim_identity_free (kim_identity_t * io_identity)
Free memory associated with an identity. 

Parameters:
io_identity the identity object to be freed. Set to NULL on exit. 

KIM Options Reference Documentation

Functions
kim_error_t kim_options_create (kim_options_t *out_options)
Create new options with default values. 

kim_error_t kim_options_copy (kim_options_t *out_options, kim_options_t in_options)
Copy options. 

kim_error_t kim_options_set_prompt_callback (kim_options_t io_options, kim_prompt_callback_t in_prompt_callback)
Set the prompt callback for obtaining information from the user. 

kim_error_t kim_options_get_prompt_callback (kim_options_t in_options, kim_prompt_callback_t *out_prompt_callback)
Get the prompt callback for obtaining information from the user. 

kim_error_t kim_options_set_data (kim_options_t io_options, void *in_data)
Set caller-specific data for use in library callbacks. 

kim_error_t kim_options_get_data (kim_options_t in_options, void **out_data)
Get caller-specific data for use in library callbacks. 

kim_error_t kim_options_set_prompt_response (kim_options_t io_options, kim_prompt_type_t in_prompt_type, void *in_response)
Set a response for a prompt for use when acquiring credentials. 

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. 

kim_error_t kim_options_set_start_time (kim_options_t io_options, kim_time_t in_start_time)
Set the date when a credential should become valid. 

kim_error_t kim_options_get_start_time (kim_options_t in_options, kim_time_t *out_start_time)
Get the date when a credential should become valid. 

kim_error_t kim_options_set_lifetime (kim_options_t io_options, kim_lifetime_t in_lifetime)
Set the duration during which a credential should be valid. 

kim_error_t kim_options_get_lifetime (kim_options_t in_options, kim_lifetime_t *out_lifetime)
Get the duration during which an acquired credential should be valid. 

kim_error_t kim_options_set_renewable (kim_options_t io_options, kim_boolean_t in_renewable)
Set whether or not to request a renewable credential. 

kim_error_t kim_options_get_renewable (kim_options_t in_options, kim_boolean_t *out_renewable)
Get whether or not to request a renewable credential. 

kim_error_t kim_options_set_renewal_lifetime (kim_options_t io_options, kim_lifetime_t in_renewal_lifetime)
Set the duration during which a valid credential should be renewable. 

kim_error_t kim_options_get_renewal_lifetime (kim_options_t in_options, kim_lifetime_t *out_renewal_lifetime)
Get the duration during which a valid credential should be renewable. 

kim_error_t kim_options_set_forwardable (kim_options_t io_options, kim_boolean_t in_forwardable)
Set whether or not to request a forwardable credential. 

kim_error_t kim_options_get_forwardable (kim_options_t in_options, kim_boolean_t *out_forwardable)
Get whether or not to request a forwardable credential. 

kim_error_t kim_options_set_proxiable (kim_options_t io_options, kim_boolean_t in_proxiable)
Set whether or not to request a proxiable credential. 

kim_error_t kim_options_get_proxiable (kim_options_t in_options, kim_boolean_t *out_proxiable)
Get whether or not to request a proxiable credential. 

kim_error_t kim_options_set_addressless (kim_options_t io_options, kim_boolean_t in_addressless)
Set whether or not to request an addressless credential. 

kim_error_t kim_options_get_addressless (kim_options_t in_options, kim_boolean_t *out_addressless)
Get whether or not to request an addressless credential. 

kim_error_t kim_options_set_service_identity (kim_options_t io_options, kim_identity_t in_service_identity)
Set the service identity to request a credential for. 

kim_error_t kim_options_get_service_identity (kim_options_t in_options, kim_identity_t *out_service_identity)
Get the service identity to request a credential for. 

void kim_options_free (kim_options_t *io_options)
Free memory associated with an options object. 

Function Documentation
kim_error_t kim_options_create (kim_options_t * out_options)
Create new options with default values. 

Parameters:
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. 
kim_error_t kim_options_copy (kim_options_t * out_options, kim_options_t in_options)
Copy options. 

Parameters:
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. 
kim_error_t kim_options_set_prompt_callback (kim_options_t io_options, kim_prompt_callback_t in_prompt_callback)
Set the prompt callback for obtaining information from the user. 

Parameters:
io_options an options object to modify. 
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() 
kim_error_t kim_options_get_prompt_callback (kim_options_t in_options, kim_prompt_callback_t * out_prompt_callback)
Get the prompt callback for obtaining information from the user. 

Parameters:
in_options an options object. 
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() 
kim_error_t kim_options_set_data (kim_options_t io_options, void * in_data)
Set caller-specific data for use in library callbacks. 

Parameters:
io_options an options object to modify. 
in_data a pointer to caller-specific data. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object 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() 
kim_error_t kim_options_get_data (kim_options_t in_options, void ** out_data)
Get caller-specific data for use in library callbacks. 

Parameters:
in_options an options object. 
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. 
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() 
kim_error_t kim_options_set_prompt_response (kim_options_t 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() 
kim_error_t kim_options_set_start_time (kim_options_t io_options, kim_time_t in_start_time)
Set the date when a credential should become valid. 

Parameters:
io_options an options object to modify. 
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. 
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() 
kim_error_t kim_options_get_start_time (kim_options_t in_options, kim_time_t * out_start_time)
Get the date when a credential should become valid. 

Parameters:
in_options an options object. 
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. 
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() 
kim_error_t kim_options_set_lifetime (kim_options_t io_options, kim_lifetime_t in_lifetime)
Set the duration during which a credential should be valid. 

Parameters:
io_options an options object to modify. 
in_lifetime a lifetime duration (in seconds). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object 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() 
Default value
Read from the user's preferences and the Kerberos configuration. 10 hours if unspecified. 
kim_error_t kim_options_get_lifetime (kim_options_t in_options, kim_lifetime_t * out_lifetime)
Get the duration during which an acquired credential should be valid. 

Parameters:
in_options an options object. 
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. 
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() 
kim_error_t kim_options_set_renewable (kim_options_t io_options, kim_boolean_t in_renewable)
Set whether or not to request a renewable credential. 

Parameters:
io_options an options object to modify. 
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. 
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified. 
See also:
kim_options_get_renewable() 
kim_error_t kim_options_get_renewable (kim_options_t in_options, kim_boolean_t * out_renewable)
Get whether or not to request a renewable credential. 

Parameters:
in_options an options object. 
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. 
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified. 
See also:
kim_options_set_renewable() 
kim_error_t kim_options_set_renewal_lifetime (kim_options_t io_options, kim_lifetime_t in_renewal_lifetime)
Set the duration during which a valid credential should be renewable. 

Parameters:
io_options an options object to modify. 
in_renewal_lifetime a renewal lifetime duration (in seconds). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object 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() 
kim_error_t kim_options_get_renewal_lifetime (kim_options_t in_options, kim_lifetime_t * out_renewal_lifetime)
Get the duration during which a valid credential should be renewable. 

Parameters:
in_options an options object. 
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. 
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() 
kim_error_t kim_options_set_forwardable (kim_options_t io_options, kim_boolean_t in_forwardable)
Set whether or not to request a forwardable credential. 

Parameters:
io_options an options object to modify. 
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. 
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified. 
See also:
kim_options_get_forwardable() 
kim_error_t kim_options_get_forwardable (kim_options_t in_options, kim_boolean_t * out_forwardable)
Get whether or not to request a forwardable credential. 

Parameters:
in_options an options object. 
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. 
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified. 
See also:
kim_options_set_forwardable() 
kim_error_t kim_options_set_proxiable (kim_options_t io_options, kim_boolean_t in_proxiable)
Set whether or not to request a proxiable credential. 

Parameters:
io_options an options object to modify. 
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. 
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified. 
See also:
kim_options_get_proxiable() 
kim_error_t kim_options_get_proxiable (kim_options_t in_options, kim_boolean_t * out_proxiable)
Get whether or not to request a proxiable credential. 

Parameters:
in_options an options object. 
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. 
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified. 
See also:
kim_options_set_proxiable() 
kim_error_t kim_options_set_addressless (kim_options_t io_options, kim_boolean_t in_addressless)
Set whether or not to request an addressless credential. 

Parameters:
io_options an options object to modify. 
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. 
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified. 
See also:
kim_options_get_addressless() 
kim_error_t kim_options_get_addressless (kim_options_t in_options, kim_boolean_t * out_addressless)
Get whether or not to request an addressless credential. 

Parameters:
in_options an options object. 
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. 
Default value
Read from the user's preferences and the Kerberos configuration. TRUE if unspecified. 
See also:
kim_options_set_addressless() 
kim_error_t kim_options_set_service_identity (kim_options_t io_options, kim_identity_t in_service_identity)
Set the service identity to request a credential for. 

Parameters:
io_options an options object to modify. 
in_service_identity a service identity. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
Default value
NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service. 
See also:
kim_options_get_service_identity() 
kim_error_t kim_options_get_service_identity (kim_options_t in_options, kim_identity_t * out_service_identity)
Get the service identity to request a credential for. 

Parameters:
in_options an options object. 
out_service_identity on exit, the service identity specified in in_options . Must be freed with kim_identity_free(). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
Default value
NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service. 
See also:
kim_options_set_service_identity() 
void kim_options_free (kim_options_t * io_options)
Free memory associated with an options object. 

Parameters:
io_options the options object to be freed. Set to NULL on exit. 

KIM Favorite Realms Documentation

Functions
kim_error_t kim_favorite_realms_create (kim_favorite_realms_t *out_favorite_realms)
Create a new a realms list. 

kim_error_t kim_favorite_realms_copy (kim_favorite_realms_t *out_favorite_realms, kim_favorite_realms_t in_favorite_realms)
Copy a realms list. 

kim_error_t kim_favorite_realms_get_number_of_realms (kim_favorite_realms_t in_favorite_realms, kim_count_t *out_number_of_realms)
Get the number of realms in a realms list. 

kim_error_t kim_favorite_realms_get_realm_at_index (kim_favorite_realms_t in_favorite_realms, kim_index_t in_index, kim_string_t *out_realm)
Get the Nth realm in a realms list. 

kim_error_t kim_favorite_realms_add_realm (kim_favorite_realms_t io_favorite_realms, kim_string_t in_realm)
Add a realm string to a realms list. 

kim_error_t kim_favorite_realms_remove_realm (kim_favorite_realms_t io_favorite_realms, kim_string_t in_realm)
Remove a realm string from a realms list. 

kim_error_t kim_favorite_realms_remove_all_realms (kim_favorite_realms_t io_favorite_realms)
Empty a realms list. 

void kim_favorite_realms_free (kim_favorite_realms_t *io_favorite_realms)
Free memory associated with a realms list. 

Function Documentation
kim_error_t kim_favorite_realms_create (kim_favorite_realms_t * out_favorite_realms)
Create a new a realms list. 

Parameters:
out_favorite_realms on exit, a new favorite realms object. Must be freed with kim_favorite_realms_free(). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_favorite_realms_copy (kim_favorite_realms_t * out_favorite_realms, kim_favorite_realms_t in_favorite_realms)
Copy a realms list. 

Parameters:
out_favorite_realms on exit, a new favorite realms object which is a copy of in_favorite_realms. Must be freed with kim_favorite_realms_free(). 
in_favorite_realms a favorite realms object. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_favorite_realms_get_number_of_realms (kim_favorite_realms_t in_favorite_realms, kim_count_t * out_number_of_realms)
Get the number of realms in a realms list. 

Parameters:
in_favorite_realms a favorite realms object. 
out_number_of_realms on exit, the number of realms in in_favorite_realms . 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_favorite_realms_get_realm_at_index (kim_favorite_realms_t in_favorite_realms, kim_index_t in_index, kim_string_t * out_realm)
Get the Nth realm in a realms list. 

Parameters:
in_favorite_realms a favorite realms object. 
in_index a index into the realms list (starting at 0). 
out_realm on exit, the realm at in_index  in in_favorite_realms . Must be freed with kim_string_free(). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_favorite_realms_add_realm (kim_favorite_realms_t io_favorite_realms, kim_string_t in_realm)
Add a realm string to a realms list. 

Parameters:
io_favorite_realms a favorite realms object. 
in_realm a realm string to add to in_favorite_realms . 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_favorite_realms_remove_realm (kim_favorite_realms_t io_favorite_realms, kim_string_t in_realm)
Remove a realm string from a realms list. 

Parameters:
io_favorite_realms a favorite realms object. 
in_realm a realm string to remove from in_favorite_realms . 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_favorite_realms_remove_all_realms (kim_favorite_realms_t io_favorite_realms)
Empty a realms list. 

Parameters:
io_favorite_realms a favorite realms object. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
void kim_favorite_realms_free (kim_favorite_realms_t * io_favorite_realms)
Free memory associated with a realms list. 

Parameters:
io_favorite_realms the favorite realms object to be freed. Set to NULL on exit. 

KIM Preferences Documentation

Functions
kim_error_t kim_preferences_create (kim_preferences_t *out_preferences)
Create a new preferences object from the current user's preferences. 

kim_error_t kim_preferences_copy (kim_preferences_t *out_preferences, kim_preferences_t in_preferences)
Copy a preferences object. 

kim_error_t kim_preferences_set_options (kim_preferences_t io_preferences, kim_options_t in_options)
Set the user's preferred options. 

kim_error_t kim_preferences_get_options (kim_preferences_t in_preferences, kim_options_t *out_options)
Get the user's preferred options. 

kim_error_t kim_preferences_set_remember_options (kim_preferences_t io_preferences, kim_boolean_t in_remember_options)
Set whether or not to remember the last options the user used to acquire a credential. 

kim_error_t kim_preferences_get_remember_options (kim_preferences_t in_preferences, kim_boolean_t *out_remember_options)
Get whether or not to remember the last options the user used to acquire a credential. 

kim_error_t kim_preferences_set_client_identity (kim_preferences_t io_preferences, kim_identity_t in_client_identity)
Set the user's preferred client identity. 

kim_error_t kim_preferences_get_client_identity (kim_preferences_t in_preferences, kim_identity_t *out_client_identity)
Get the user's preferred client identity. 

kim_error_t kim_preferences_set_remember_client_identity (kim_preferences_t io_preferences, kim_boolean_t in_remember_client_identity)
Set whether or not to remember the last client identity the user acquired a credential for. 

kim_error_t kim_preferences_get_remember_client_identity (kim_preferences_t in_preferences, kim_boolean_t *out_remember_client_identity)
Get whether or not to remember the last client identity the user acquired a credential for. 

kim_error_t kim_preferences_set_favorite_realms (kim_preferences_t io_preferences, kim_favorite_realms_t in_favorite_realms)
Set the user's preferred list of realms. 

kim_error_t kim_preferences_get_favorite_realms (kim_preferences_t in_preferences, kim_favorite_realms_t *out_favorite_realms)
Get the user's preferred list of realms. 

kim_error_t kim_preferences_synchronize (kim_preferences_t 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_t *io_preferences)
Free memory associated with a preferences object. 

Function Documentation
kim_error_t kim_preferences_create (kim_preferences_t * out_preferences)
Create a new preferences object from the current user's preferences. 

Parameters:
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. 
kim_error_t kim_preferences_copy (kim_preferences_t * out_preferences, kim_preferences_t in_preferences)
Copy a preferences object. 

Parameters:
out_preferences on exit, a new preferences object which is a copy of in_preferences. Must be freed with kim_favorite_realms_free(). 
in_preferences a preferences object. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_preferences_set_options (kim_preferences_t io_preferences, kim_options_t in_options)
Set the user's preferred options. 

Parameters:
io_preferences a preferences object to modify. 
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() 
kim_error_t kim_preferences_get_options (kim_preferences_t in_preferences, kim_options_t * out_options)
Get the user's preferred options. 

Parameters:
in_preferences a preferences object. 
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() 
kim_error_t kim_preferences_set_remember_options (kim_preferences_t io_preferences, kim_boolean_t in_remember_options)
Set whether or not to remember the last options the user used to acquire a credential. 

Parameters:
io_preferences a preferences object to modify. 
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() 
kim_error_t kim_preferences_get_remember_options (kim_preferences_t in_preferences, kim_boolean_t * out_remember_options)
Get whether or not to remember the last options the user used to acquire a credential. 

Parameters:
in_preferences a preferences object. 
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() 
kim_error_t kim_preferences_set_client_identity (kim_preferences_t io_preferences, kim_identity_t in_client_identity)
Set the user's preferred client identity. 

Parameters:
io_preferences a preferences object to modify. 
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() 
kim_error_t kim_preferences_get_client_identity (kim_preferences_t in_preferences, kim_identity_t * out_client_identity)
Get the user's preferred client identity. 

Parameters:
in_preferences a preferences object. 
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() 
kim_error_t kim_preferences_set_remember_client_identity (kim_preferences_t io_preferences, kim_boolean_t in_remember_client_identity)
Set whether or not to remember the last client identity the user acquired a credential for. 

Parameters:
io_preferences a preferences object to modify. 
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() 
kim_error_t kim_preferences_get_remember_client_identity (kim_preferences_t in_preferences, kim_boolean_t * out_remember_client_identity)
Get whether or not to remember the last client identity the user acquired a credential for. 

Parameters:
in_preferences a preferences object. 
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() 
kim_error_t kim_preferences_set_favorite_realms (kim_preferences_t io_preferences, kim_favorite_realms_t in_favorite_realms)
Set the user's preferred list of realms. 

Parameters:
io_preferences a preferences object to modify. 
in_favorite_realms a favorite realms object. See KIM Favorite Realms Overview  for more information on KIM Favorite Realms. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
See also:
kim_preferences_get_favorite_realms() 
kim_error_t kim_preferences_get_favorite_realms (kim_preferences_t in_preferences, kim_favorite_realms_t * out_favorite_realms)
Get the user's preferred list of realms. 

Parameters:
in_preferences a preferences object. 
out_favorite_realms on exit, a copy of the favorite realms specified in in_preferences . See KIM Favorite Realms Overview  for more information on KIM Favorite Realms. Must be freed with kim_favorite_realms_free(). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
See also:
kim_preferences_set_favorite_realms() 
kim_error_t kim_preferences_synchronize (kim_preferences_t in_preferences)
Synchronize a preferences object with the user's preferences, writing pending changes and reading any changes applied by other processes. 

Parameters:
in_preferences a preferences object. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
void kim_preferences_free (kim_preferences_t * io_preferences)
Free memory associated with a preferences object. 

Parameters:
io_preferences the preferences object to be freed. Set to NULL on exit. 

KIM Selection Hints Reference Documentation

Functions
kim_error_t kim_selection_hints_create (kim_selection_hints_t *out_selection_hints, kim_string_t in_application_identifier)
Create a new selection hints object. 

kim_error_t kim_selection_hints_copy (kim_selection_hints_t *out_selection_hints, kim_selection_hints_t in_selection_hints)
Copy a selection hints object. 

kim_error_t kim_selection_hints_set_service_identity (kim_selection_hints_t io_selection_hints, kim_identity_t in_service_identity)
Set the preferred service identity. 

kim_error_t kim_selection_hints_get_service_identity (kim_selection_hints_t in_selection_hints, kim_identity_t *out_service_identity)
Get the preferred service identity. 

kim_error_t kim_selection_hints_set_client_realm (kim_selection_hints_t io_selection_hints, kim_string_t in_client_realm)
Set the preferred client realm. 

kim_error_t kim_selection_hints_get_client_realm (kim_selection_hints_t io_selection_hints, kim_string_t *out_client_realm)
Get the preferred client realm. 

kim_error_t kim_selection_hints_set_user (kim_selection_hints_t io_selection_hints, kim_string_t in_user)
Set the preferred user name. 

kim_error_t kim_selection_hints_get_user (kim_selection_hints_t in_selection_hints, kim_string_t *out_user)
Get the preferred user name. 

kim_error_t kim_selection_hints_set_service_realm (kim_selection_hints_t io_selection_hints, kim_string_t in_service_realm)
Set the preferred service realm. 

kim_error_t kim_selection_hints_get_service_realm (kim_selection_hints_t io_selection_hints, kim_string_t *out_service_realm)
Get the preferred service realm. 

kim_error_t kim_selection_hints_set_service (kim_selection_hints_t io_selection_hints, kim_string_t in_service)
Set the preferred service name. 

kim_error_t kim_selection_hints_get_service (kim_selection_hints_t in_selection_hints, kim_string_t *out_service)
Get the preferred service name. 

kim_error_t kim_selection_hints_set_hostname (kim_selection_hints_t io_selection_hints, kim_string_t in_hostname)
Set the preferred server host name. 

kim_error_t kim_selection_hints_get_hostname (kim_selection_hints_t in_selection_hints, kim_string_t *out_hostname)
Get the preferred server host name. 

kim_error_t kim_selection_hints_set_application_name (kim_selection_hints_t io_selection_hints, kim_string_t in_application_name)
Set the application name for use in user interaction. 

kim_error_t kim_selection_hints_get_application_name (kim_selection_hints_t in_selection_hints, kim_string_t *out_application_name)
Get the application name for use in user interaction. 

kim_error_t kim_selection_hints_set_explanation (kim_selection_hints_t io_selection_hints, kim_string_t in_explanation)
Set the strings used to prompt the user to select the identity. 

kim_error_t kim_selection_hints_get_explanation (kim_selection_hints_t in_selection_hints, kim_string_t *out_explanation)
Get the strings used to prompt the user to select the identity. 

kim_error_t kim_selection_hints_set_options (kim_selection_hints_t io_selection_hints, kim_options_t in_options)
Set the options which will be used if credentials need to be acquired. 

kim_error_t kim_selection_hints_get_options (kim_selection_hints_t in_selection_hints, kim_options_t *out_options)
Get the options which will be used if credentials need to be acquired. 

kim_error_t kim_selection_hints_set_allow_user_interaction (kim_selection_hints_t in_selection_hints, kim_boolean_t in_allow_user_interaction)
Set whether or not KIM may interact with the user to select an identity. 

kim_error_t kim_selection_hints_get_allow_user_interaction (kim_selection_hints_t in_selection_hints, kim_boolean_t *out_allow_user_interaction)
Get whether or not KIM may interact with the user to select an identity. 

kim_error_t kim_selection_hints_set_use_cached_results (kim_selection_hints_t in_selection_hints, kim_boolean_t in_use_cached_results)
Set whether or not KIM will cache mappings generated by this selection hints object. 

kim_error_t kim_selection_hints_get_use_cached_results (kim_selection_hints_t in_selection_hints, kim_boolean_t *out_use_cached_results)
Get whether or not KIM will cache mappings generated by this selection hints object. 

kim_error_t kim_selection_hints_get_identity (kim_selection_hints_t in_selection_hints, kim_identity_t *out_identity)
Choose a client identity based on selection hints. 

kim_error_t kim_selection_hints_cache_results (kim_selection_hints_t in_selection_hints, kim_identity_t in_identity)
Add an entry for the selection hints to the selection hints cache, replacing any existing entry. 

kim_error_t kim_selection_hints_forget_cached_results (kim_selection_hints_t in_selection_hints)
Remove an entry for the selection hints from the selection hints cache. 

void kim_selection_hints_free (kim_selection_hints_t *io_selection_hints)
Free memory associated with a selection hints object. 

Function Documentation
kim_error_t kim_selection_hints_create (kim_selection_hints_t * out_selection_hints, kim_string_t in_application_identifier)
Create a new selection hints object. 

Parameters:
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. 
kim_error_t kim_selection_hints_copy (kim_selection_hints_t * out_selection_hints, kim_selection_hints_t in_selection_hints)
Copy a selection hints object. 

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. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_selection_hints_set_service_identity (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() 
kim_error_t kim_selection_hints_get_service_identity (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() 
kim_error_t kim_selection_hints_set_client_realm (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() 
kim_error_t kim_selection_hints_get_client_realm (kim_selection_hints_t io_selection_hints, kim_string_t * out_client_realm)
Get the preferred client realm. 

Parameters:
io_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() 
kim_error_t kim_selection_hints_set_user (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() 
kim_error_t kim_selection_hints_get_user (kim_selection_hints_t in_selection_hints, kim_string_t * out_user)
Get the preferred user name. 

Parameters:
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() 
kim_error_t kim_selection_hints_set_service_realm (kim_selection_hints_t 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() 
kim_error_t kim_selection_hints_get_service_realm (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() 
kim_error_t kim_selection_hints_set_service (kim_selection_hints_t io_selection_hints, kim_string_t in_service)
Set the preferred service name. 

Parameters:
io_selection_hints a selection hints object to modify. 
in_service a service name string. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
See also:
kim_selection_hints_get_service() 
kim_error_t kim_selection_hints_get_service (kim_selection_hints_t 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() 
kim_error_t kim_selection_hints_set_hostname (kim_selection_hints_t io_selection_hints, kim_string_t in_hostname)
Set the preferred server host name. 

Parameters:
io_selection_hints a selection hints object to modify. 
in_hostname 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_hostname() 
kim_error_t kim_selection_hints_get_hostname (kim_selection_hints_t in_selection_hints, kim_string_t * out_hostname)
Get the preferred server host name. 

Parameters:
in_selection_hints a selection hints object. 
out_hostname on exit, the server host 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_hostname() 
kim_error_t kim_selection_hints_set_application_name (kim_selection_hints_t io_selection_hints, kim_string_t in_application_name)
Set the application name for use in user interaction. 

Parameters:
io_selection_hints a selection hints object to modify. 
in_application_name a localized string containing the full name of the application. 
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() 
kim_error_t kim_selection_hints_get_application_name (kim_selection_hints_t in_selection_hints, kim_string_t * out_application_name)
Get the application name for use in user interaction. 

Parameters:
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(). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
See also:
kim_selection_hints_set_application_name() 
kim_error_t kim_selection_hints_set_explanation (kim_selection_hints_t io_selection_hints, kim_string_t in_explanation)
Set the strings used to prompt the user to select the identity. 

Parameters:
io_selection_hints a selection hints object to modify. 
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() 
kim_error_t kim_selection_hints_get_explanation (kim_selection_hints_t in_selection_hints, kim_string_t * out_explanation)
Get the strings used to prompt the user to select the identity. 

Parameters:
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(). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
See also:
kim_selection_hints_set_explanation() 
kim_error_t kim_selection_hints_set_options (kim_selection_hints_t io_selection_hints, kim_options_t in_options)
Set the options which will be used if credentials need to be acquired. 

Parameters:
io_selection_hints a selection hints object to modify. 
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() 
kim_error_t kim_selection_hints_get_options (kim_selection_hints_t in_selection_hints, kim_options_t * out_options)
Get the options which will be used if credentials need to be acquired. 

Parameters:
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(). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
See also:
kim_selection_hints_set_options() 
kim_error_t kim_selection_hints_set_allow_user_interaction (kim_selection_hints_t in_selection_hints, kim_boolean_t in_allow_user_interaction)
Set whether or not KIM may interact with the user to select an identity. 

Parameters:
in_selection_hints a selection hints object to modify 
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. 
Note:
This setting defaults to TRUE. 
See also:
kim_selection_hints_get_allow_user_interaction 
kim_error_t kim_selection_hints_get_allow_user_interaction (kim_selection_hints_t in_selection_hints, kim_boolean_t * out_allow_user_interaction)
Get whether or not KIM may interact with the user to select an identity. 

Parameters:
in_selection_hints a selection hints object to modify 
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. 
Note:
This setting defaults to TRUE. 
See also:
kim_selection_hints_set_allow_user_interaction 
kim_error_t kim_selection_hints_set_use_cached_results (kim_selection_hints_t in_selection_hints, kim_boolean_t in_use_cached_results)
Set whether or not KIM will cache mappings generated by this selection hints object. 

Parameters:
in_selection_hints a selection hints object to modify 
in_use_cached_results 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. 
Note:
This setting defaults to TRUE. 
See also:
kim_selection_hints_get_use_cached_results 
kim_error_t kim_selection_hints_get_use_cached_results (kim_selection_hints_t in_selection_hints, kim_boolean_t * out_use_cached_results)
Get whether or not KIM will cache mappings generated by this selection hints object. 

Parameters:
in_selection_hints a selection hints object to modify 
out_use_cached_results 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. 
Note:
This setting defaults to TRUE. 
See also:
kim_selection_hints_set_use_cached_results 
kim_error_t kim_selection_hints_get_identity (kim_selection_hints_t in_selection_hints, kim_identity_t * out_identity)
Choose a client identity based on selection hints. 

Parameters:
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(). 
Returns:
On success, KIM_NO_ERROR. On failure, an error object 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 . 
kim_error_t kim_selection_hints_cache_results (kim_selection_hints_t in_selection_hints, kim_identity_t in_identity)
Add an entry for the selection hints to the selection hints cache, replacing any existing entry. 

Parameters:
in_selection_hints the selection hints to add to the cache. 
in_identity the Kerberos identity in_selection_hints  maps to. 
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure. 
kim_error_t kim_selection_hints_forget_cached_results (kim_selection_hints_t in_selection_hints)
Remove an entry for the selection hints from the selection hints cache. 

Parameters:
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. 
void kim_selection_hints_free (kim_selection_hints_t * io_selection_hints)
Free memory associated with a selection hints object. 

Parameters:
io_selection_hints the selection hints object to be freed. Set to NULL on exit. 

KIM String Reference Documentation

Functions
kim_error_t kim_string_copy (kim_string_t *out_string, const kim_string_t in_string)
Copy a string. 

void kim_string_free (kim_string_t *io_string)
Free memory associated with a string. 

Function Documentation
kim_error_t kim_string_copy (kim_string_t * out_string, const kim_string_t in_string)
Copy a string. 

Parameters:
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. 
void kim_string_free (kim_string_t * io_string)
Free memory associated with a string. 

Parameters:
io_string a string to be freed. Set to NULL on exit. 

KIM Types and Constants

Defines
#define KIM_NO_ERROR  ((kim_error_t) NULL)
#define KIM_NO_ERROR_ECODE  ((kim_error_code_t) 0)
#define KIM_IDENTITY_ANY  ((kim_identity_t) NULL)
#define KIM_OPTIONS_DEFAULT  ((kim_options_t) NULL)
#define KIM_OPTIONS_START_IMMEDIATELY  ((kim_time_t) 0)
Typedefs
typedef uint32_t kim_prompt_type_t
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 int32_t kim_error_code_t
typedef int64_t kim_time_t
typedef int64_t kim_lifetime_t
typedef uint64_t kim_index_t
typedef uint64_t kim_count_t
typedef int kim_boolean_t
typedef const char * kim_string_t
typedef kim_error_opaque * kim_error_t
typedef kim_identity_opaque * kim_identity_t
typedef kim_options_opaque * kim_options_t
typedef kim_selection_hints_opaque * kim_selection_hints_t
typedef kim_favorite_realms_opaque * kim_favorite_realms_t
typedef kim_preferences_opaque * kim_preferences_t
typedef kim_ccache_iterator_opaque * kim_ccache_iterator_t
typedef kim_ccache_opaque * kim_ccache_t
typedef kim_credential_iterator_opaque * kim_credential_iterator_t
typedef kim_credential_opaque * kim_credential_t
Enumerations
enum kim_prompt_type_enum { kim_prompt_type_password =  0, kim_prompt_type_challenge =  1 }
Variables
const kim_prompt_callback_t kim_prompt_callback_default
const kim_prompt_callback_t kim_prompt_callback_gui
const kim_prompt_callback_t kim_prompt_callback_cli
const kim_prompt_callback_t kim_prompt_callback_none

Define Documentation
#define KIM_NO_ERROR  ((kim_error_t) NULL)
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. 
#define KIM_IDENTITY_ANY  ((kim_identity_t) NULL)
Constant to specify any Kerberos identity is acceptable. 
#define KIM_OPTIONS_DEFAULT  ((kim_options_t) NULL)
Specifies the user's default options. 
#define KIM_OPTIONS_START_IMMEDIATELY  ((kim_time_t) 0)
Specifies that credentials should be valid immediately. 

Typedef Documentation
typedef uint32_t kim_prompt_type_t
The type of prompt which needs to be displayed. This value determines what type of user interface is displayed. 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)
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
The KIM String type. See KIM String Overview  for more information. 
typedef int64_t kim_time_t
A time value represented in seconds since January 1, 1970. 
typedef int64_t kim_lifetime_t
A duration represented in seconds. 
typedef uint64_t kim_index_t
An 0-based index into an array (ie: zero is the first element in the array). 
typedef uint64_t kim_count_t
An quantity, usually used to return the number of elements in an array. 
typedef int kim_boolean_t
A boolean value. 0 means false, all other values mean true. 
typedef const char* kim_string_t
The KIM String type. See KIM String Overview  for more information. 
typedef struct kim_error_opaque* kim_error_t
A KIM Error object. See KIM Error Overview  for more information. 
typedef struct kim_identity_opaque* kim_identity_t
A KIM Principal object. See KIM Identity Overview  for more information. 
typedef struct kim_options_opaque* kim_options_t
A KIM Options object. See KIM Options Overview  for more information. 
typedef struct kim_selection_hints_opaque* kim_selection_hints_t
A KIM Selection Hints object. See KIM Selection Hints Overview  for more information. 
typedef struct kim_favorite_realms_opaque* kim_favorite_realms_t
A KIM Favorite Realms object. See KIM Favorite Realms Overview  for more information. 
typedef struct kim_preferences_opaque* kim_preferences_t
A KIM Preferences object. See KIM Preferences Overview  for more information. 
typedef struct kim_ccache_iterator_opaque* kim_ccache_iterator_t
A KIM CCache Iterator object. See Acquiring a CCache from the Cache Collection  for more information. 
typedef struct kim_ccache_opaque* kim_ccache_t
A KIM CCache object. See KIM CCache Overview  for more information. 
typedef struct kim_credential_iterator_opaque* kim_credential_iterator_t
A KIM Credential Iterator object. See Iterating over the Credentials in a CCache  for more information. 
typedef struct kim_credential_opaque* kim_credential_t
A KIM Credential object. See KIM Credential Overview  for more information. 

Variable Documentation
const kim_prompt_callback_t kim_prompt_callback_default
The default prompt callback. See Providing a Custom Prompt Callback  for more information. 
const kim_prompt_callback_t kim_prompt_callback_gui
The graphical prompt callback. See Providing a Custom Prompt Callback  for more information. 
const kim_prompt_callback_t kim_prompt_callback_cli
The command line prompt callback. See Providing a Custom Prompt Callback  for more information. 
const kim_prompt_callback_t kim_prompt_callback_none
The prompt callback which always returns an error. Use to turn off prompting entirely. 
Note:
Using this callback may prevent the user from authenicating. See Providing a Custom Prompt Callback  for more information. 

Kerberos Identity Management Page Documentation
KIM CCache Overview

Introduction
Kerberos credentials are stored in "ccaches" (short for "credentials caches"). The set of all ccaches which the KIM can use is called the "cache collection". Each ccache has a name and type which uniquely identify it in the cache collection and a client identity. The ccache's client identity is the identity whose credentials are stored in the ccache. This allows for easy lookup of all the credentials for a given identity.
KIM attempts to preserve a one-to-one relationship between client identities and ccaches. If the KIM is used to manipulate the cache collection, there will be one ccache per identity. However, because low-level APIs allow callers to create multiple ccaches for the same client identity or a single ccache containing credentials for different client identities, KIM handles those situations. In general when searching KIM will find the first ccache matching the requested client identity. It will not find credentials for the requested client identity if they are in a ccache with a different client identity.
The kim_ccache_t object is a reference to a ccache in the cache collection. If other applications make changes to the the ccache pointed to by a KIM ccache object, the object will immediately show those changes. KIM performs locking on the cache collection to prevent deadlocks and maintain a consistent behavior when multiple applications attempt to modify the cache collection.
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().
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.
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.
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.
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.
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.
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_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_client_identity() returns the ccache's client identity.

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_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.
See KIM CCache Reference Documentation  and KIM CCache Iterator Reference Documentation  for information on specific APIs. 
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.
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.
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 this API 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 this API 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.
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.

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.
Examining Credential Properties

kim_credential_get_client_identity() returns the credential's client identity.

kim_credential_get_service_identity() returns the credential's service identity.

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_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.
See KIM Credential Reference Documentation  and KIM Credential Iterator Reference Documentation  for information on specific APIs. 
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. 
KIM Identity Overview

Introduction
Identities in Kerberos are named by "principals". These identies may be people (users) or services (a server running on a host). When Kerberos issues credentials which authenticate one identity to another, the identity being authenticated is called the "client identity" and the identity being authenticated to is called the "service identity".
Kerberos identities are made up of one or more components, as well as the Kerberos realm the entity belongs to. For client identities the first component is usually the client username (eg: "jdoe"). For service identities the first component is the name of the service (eg: "imap").
Kerberos identities have both a binary (opaque) representation and also a string representation. The string representation consists of the components separated by '/' followed by an '@' and then the realm. For example, the identity "jdoe/admin@EXAMPLE.COM" represents John Doe's administrator identity at the realm EXAMPLE.COM. Note that identity components may contain both '/' and '@' characters. When building a identity from its string representation these syntactic characters must be escaped with '\'.
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:

kim_identity_create_from_components() creates an identity object from a list of components. 
kim_identity_get_number_of_components() returns the number of components in an identity object. 
kim_identity_get_component_at_index() return a component of an identity object. 
kim_identity_get_realm() returns the identity's realm.

kim_identity_create_from_string() generates an identity object from an escaped string representation. 
kim_identity_get_string() returns the identity's escaped string representation. 
kim_identity_get_display_string() returns a non-escaped string for display to the user. This string cannot be passed into kim_identity_create_from_string().

kim_identity_create_from_krb5_principal() generates an identity object from a krb5_principal object. 
kim_identity_get_krb5_principal() returns a krb5_principal object for an identity object.

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().

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.
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.
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. 
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.
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.

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().
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.
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.
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.
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.
Service Identity
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 identity with kim_options_set_service_identity() and query it with kim_options_get_service_identity().
See KIM Options Reference Documentation  for information on specific APIs. 

KIM Favorite Realms Overview

Introduction
As Kerberos becomes more widespread, the number of possible Kerberos realms a user might want to contact will become very large. As a result, 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.
On platforms which use a GUI to acquire credentials, the KIM would like to to display a list of realms for the user to select from. Depending on what is appropriate for the platform, realms may be displayed in a popup menu or other list. Incredibly long lists of realms are undesirable since they may force the user to scroll excessively to get to their desired realm. And if the list does not contain realms available via DNS SRV records, the user would be forced to type their realm every time they acquire initial credentials.
To solve this problem, the KIM maintains a list of favorite realms specifically for graphical realm selection. This list is a set of unique realm names in alphabetical order (as appropriate for the user's language localization) and is never used for realm configuration.
On most platforms the list of favorite realms has both an administrator preference and a user preference which overrides it. The administrator preference exists only to initialize the Favorite Realms for new user accounts. Once the user modifies the list their favorite realms may diverge from the site favorite realms preference.
Note:
The location of user preferences and the semantics of preference synchronization is platform-specific. Where possible KIM will use platform-specific preference mechanisms.
Most callers will not need to use the favorite realms 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 realms.
Viewing and Editing the Favorite Realms
First, you need to acquire the Favorite Realms stored in the user's preferences using kim_preferences_create() and kim_preferences_get_favorite_realms(). Or you can use kim_favorite_realms_create() to get an empty realms list if you want to overwrite the user's realms list entirely. See KIM Preferences Overview  for more information on modifying the user's preferences.
Then use kim_favorite_realms_get_number_of_realms() and kim_favorite_realms_get_realm_at_index() to display the realms list. Use kim_favorite_realms_add_realm() and kim_favorite_realms_remove_realm() to change which realms are in the realms list. Realms are always stored in alphabetical order and duplicate realms are not permitted, so when you add or remove a realm you should redisplay the entire list.
Once you are done editing the realms list, store changes in the user's preference file using kim_preferences_set_favorite_realms() and kim_preferences_synchronize().
See KIM Favorite Realms Documentation  for information on specific APIs. 
KIM Preferences Overview

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 realms 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().
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().
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().
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().
Favorite Realms Preferences
When presenting a graphical interface for credential acquisition, KIM may need to display a list of realms for the user to select from. This list is generated by the user's favorite realms preference. You can view and edit the favorite realms preference using kim_preferences_get_favorite_realms() and kim_preferences_set_favorite_realms(). Please see the KIM Favorite Realms Overview  for more information.
See KIM Preferences Documentation  for information on specific APIs. 
KIM Selection Hints Overview

Introduction
Most users belong to multiple organizations and thus need to authenticate to multiple Kerberos realms. Traditionally Kerberos sites solved this problem by setting up a cross-realm relationship, which allowed the user to use TGT credentials for their client identity in one realm to obtain credentials in another realm via cross-realm authentication. As a result users could acquire credentials for a single client identity and use them everywhere.
Setting up cross-realm requires that realms share a secret, so sites must coordinate with one another to set up a cross-realm relationship. In addition, sites must set up authorization policies for users from other realms. As Kerberos becomes increasingly wide-spread, many realms will not have cross-realm relationships, and users will need to manually obtain credentials for their client identity at each realm (eg: "user@BANK.COM", "user@UNIVERSITY.EDU", etc). As a result, users will often have multiple credentials caches, one for each client identity.
Unfortunately this presents a problem for applications which need to obtain service credentials. Which client identity should they use? Rather than having each application to manually search the cache collection, KIM provides a selection hints API for choosing the best client identity. This API is intended to simplify the process of choosing credentials and provide consistent behavior across all applications.
Searching the cache collection for credentials may be expensive if there are a large number of caches. If credentials for the client identity are expired or not present, KIM may also wish to prompt the user for new credentials for the appropriate client identity. As a result, applications might want to remember which client identity worked in the past and always request credentials using that identity.
Creating KIM Selection Hints
A KIM selection hints object consists of an application identifier and one or more pieces of information about the service the client application will be contacting. The application identifier is used by user preferences to control how applications share cache entries. It is important to be consistent about what application identifier you provide. Java-style identifiers are recommended to avoid collisions.
Selection Hint Search Behavior
When using selection hints to search for an appropriate client identity, KIM uses a consistent hint search order. This allows applications to specify potentially contradictory information without preventing KIM from locating a single ccache. In addition the selection hint search order may change, especially if more hints are added.
As a result, callers are encouraged to provide all relevant search hints, even if only a subset of those search hints are necessary to get reasonable behavior in the current implementation. Doing so will provide the most user-friendly selection experience.
Currently the search order looks like this:

Service Identity  The client identity which has obtained a service credential for this service identity. 
Hostname  A client identity which has obtained a service credential for this server. 
Service Realm  A client identity which has obtained a service credential for this realm. 
Service  A client identity which has obtained a service credential for this service. 
Client Realm  A client identity in this realm. 
User  A client identity whose first component is this user string.
For example, if you specify a service identity and a credential for that identity already exists in the ccache collection, KIM may use that ccache, even if your user and client realm entries in the selection hints would lead it to choose a different ccache. If no credentials for the service identity exist then KIM will fall back on the user and realm hints.
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. Subsequent changes to the selection hints object will not change the identity.

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. When the client identity returned by KIM successfully authenticates to the server and passes authorization checks, you may use kim_selection_hints_cache_results() to add a mapping to the cache, replacing an existing mapping if there is one. Future calls to KIM using identical selection hints will result in the cached client identity and no searching will occur.
If a cache entry becomes invalid, you can forget the mapping using kim_selection_hints_forget_cached_results(). If you don't want to remove the mapping but also don't want to use it, you can turn off querying of the cache for a particular selection hints object using kim_selection_hints_set_use_cached_results().
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.
Note:
So long as the caller caches the identity with kim_selection_hints_cache_results() the user will be prompted only when setting up the application or when credentials expire.
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. 
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. 

Index
INDEX