KIM CCache Reference Documentation

Functions

Function Documentation

kim_error kim_ccache_create_new ( kim_ccache *  out_ccache,
kim_identity  in_client_identity,
kim_options  in_options 
)

Acquire a new initial credential and store it in a ccache.

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:
kim_ccache_create_new() may present a GUI or command line prompt to obtain information from the user.
Returns:
On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_ccache_create_new_with_password ( kim_ccache *  out_ccache,
kim_identity  in_client_identity,
kim_options  in_options,
kim_string  in_password 
)

Acquire a new initial credential and store it in a ccache using the provided password..

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.
in_password a password to be used while obtaining credentials.
Note:
kim_ccache_create_new_with_password() exists to support legacy password-based Kerberos environments. You should not use this function unless you know that it will only be used in environments using passwords. This function may also present a GUI or command line prompt to obtain additional information needed to obtain credentials (eg: SecurID pin).
Returns:
On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_ccache_create_new_if_needed ( kim_ccache *  out_ccache,
kim_identity  in_client_identity,
kim_options  in_options 
)

Find a ccache containing a valid initial credential in the cache collection, or if unavailable, acquire and store a new initial credential.

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:
kim_ccache_create_new_if_needed() may present a GUI or command line prompt to obtain information from the user.
Returns:
On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_ccache_create_new_if_needed_with_password ( kim_ccache *  out_ccache,
kim_identity  in_client_identity,
kim_options  in_options,
kim_string  in_password 
)

Find a ccache containing a valid initial credential in the cache collection, or if unavailable, acquire and store a new initial credential using the provided password.

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).
in_password a password to be used while obtaining credentials.
Note:
kim_ccache_create_new_if_needed_with_password() exists to support legacy password-based Kerberos environments. You should not use this function unless you know that it will only be used in environments using passwords. This function may also present a GUI or command line prompt to obtain additional information needed to obtain credentials (eg: SecurID pin).
Returns:
On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_ccache_create_from_client_identity ( kim_ccache *  out_ccache,
kim_identity  in_client_identity 
)

Find a ccache for a client identity in the cache collection.

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 find a ccache for. If in_client_identity is KIM_IDENTITY_ANY, this function returns the default ccache (ie: is equivalent to kim_ccache_create_from_default()).
Returns:
On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_ccache_create_from_keytab ( kim_ccache *  out_ccache,
kim_identity  in_identity,
kim_options  in_options,
kim_string  in_keytab 
)

Acquire a new initial credential from a keytab and store it in a ccache.

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 code representing the failure.

kim_error kim_ccache_create_from_default ( kim_ccache *  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 code representing the failure.

kim_error kim_ccache_create_from_display_name ( kim_ccache *  out_ccache,
kim_string  in_display_name 
)

Get a ccache for a ccache display name.

Parameters:
out_ccache on exit, a ccache object for the ccache identified by in_display_name. Must be freed with kim_ccache_free().
in_display_name a ccache display name string (ie: "TYPE:NAME").
Returns:
On success, KIM_NO_ERROR. On failure, an error code representing the failure.
Note:
This API is used to obtain a kim_ccache for a ccache name entered by the user.

kim_error kim_ccache_create_from_type_and_name ( kim_ccache *  out_ccache,
kim_string  in_type,
kim_string  in_name 
)

Get a ccache for a ccache type and name.

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

kim_error kim_ccache_create_from_krb5_ccache ( kim_ccache *  out_ccache,
krb5_context  in_krb5_context,
krb5_ccache  in_krb5_ccache 
)

Get a ccache for a krb5 ccache.

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_context the krb5 context used to create in_krb5_ccache.
in_krb5_ccache a krb5 ccache object.
Returns:
On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_ccache_copy ( kim_ccache *  out_ccache,
kim_ccache  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 code representing the failure.

kim_error kim_ccache_compare ( kim_ccache  in_ccache,
kim_ccache  in_compare_to_ccache,
kim_comparison *  out_comparison 
)

Compare ccache objects.

Parameters:
in_ccache a ccache object.
in_compare_to_ccache a ccache object.
out_comparison on exit, a comparison of in_ccache and in_compare_to_ccache which determines whether or not the two ccache objects refer to the same ccache.
Returns:
On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_ccache_get_krb5_ccache ( kim_ccache  in_ccache,
krb5_context  in_krb5_context,
krb5_ccache *  out_krb5_ccache 
)

Get a krb5 ccache for a ccache.

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 code representing the failure.

kim_error kim_ccache_get_name ( kim_ccache  in_ccache,
kim_string *  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 code representing the failure.

kim_error kim_ccache_get_type ( kim_ccache  in_ccache,
kim_string *  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 code representing the failure.

kim_error kim_ccache_get_display_name ( kim_ccache  in_ccache,
kim_string *  out_display_name 
)

Get the type and name for a ccache in display format.

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 code representing the failure.

kim_error kim_ccache_get_client_identity ( kim_ccache  in_ccache,
kim_identity *  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 code representing the failure.

kim_error kim_ccache_get_valid_credential ( kim_ccache  in_ccache,
kim_credential *  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 code representing the failure.
Note:
This function prefers valid TGT credentials. If there are only non-valid TGTs in the ccache, it will always return an error. However, if there are no TGTs at all, it will return the first valid non-TGT credential. If you only want TGTs, use kim_credential_is_tgt() to verify that out_credential is a tgt.

kim_error kim_ccache_get_state ( kim_ccache  in_ccache,
kim_credential_state *  out_state 
)

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

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

kim_error kim_ccache_get_start_time ( kim_ccache  in_ccache,
kim_time *  out_start_time 
)

Get the time when the credentials in the ccache become valid.

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 code representing the failure.

kim_error kim_ccache_get_expiration_time ( kim_ccache  in_ccache,
kim_time *  out_expiration_time 
)

Get the time when the credentials in the ccache will expire.

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 code representing the failure.

kim_error kim_ccache_get_renewal_expiration_time ( kim_ccache  in_ccache,
kim_time *  out_renewal_expiration_time 
)

Get the time when the credentials in the ccache will no longer be renewable.

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 code representing the failure.

kim_error kim_ccache_get_options ( kim_ccache  in_ccache,
kim_options *  out_options 
)

Get a kim_options object based on a ccache's credential attributes.

Parameters:
in_ccache a ccache object.
out_options on exit, an options object reflecting the ticket options of the credentials in in_ccache.
Returns:
On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_ccache_set_default ( kim_ccache  io_ccache  ) 

Set a ccache to the default ccache.

Parameters:
io_ccache a ccache object which will be set to the default ccache.
Returns:
On success, KIM_NO_ERROR. On failure, an error code representing the failure.
Note:
This API is provided for backwards compatibilty with applications which are not KIM-aware and should be avoided whenever possible.

kim_error kim_ccache_verify ( kim_ccache  in_ccache,
kim_identity  in_service_identity,
kim_string  in_keytab,
kim_boolean  in_fail_if_no_service_key 
)

Verify the TGT in a ccache.

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 code representing the failure.

kim_error kim_ccache_renew ( kim_ccache  in_ccache,
kim_options  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 code representing the failure.

kim_error kim_ccache_validate ( kim_ccache  in_ccache,
kim_options  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 code representing the failure.

kim_error kim_ccache_destroy ( kim_ccache *  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 code 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 *  io_ccache  ) 

Free memory associated with a ccache.

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

Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by  doxygen 1.5.3