KIM CCache Reference Documentation

Functions

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.