# KIM CCache Reference Documentation

## Functions

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

## Function Documentation

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.