# KIM Credential Reference Documentation

## Functions

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

## Function Documentation

kim_error kim_credential_create_new | ( | kim_credential * | out_credential,
|  | kim_identity | in_client_identity,
|  | kim_options | 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:
  kim_credential_create_new() may present a GUI or command line prompt to obtain information from the user.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_ccache_create_new

kim_error kim_credential_create_new_with_password | ( | kim_credential * | out_credential,
|  | kim_identity | in_client_identity,
|  | kim_options | in_options,
|  | kim_string | in_password |
| ) |  |  |

Acquire a new initial credential using the provided password.

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.
  | in_password | a password to be used while obtaining the credential.

Note:
  kim_credential_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.

See also:
  kim_ccache_create_new

kim_error kim_credential_create_from_keytab | ( | kim_credential * | out_credential,
|  | kim_identity | in_identity,
|  | kim_options | in_options,
|  | kim_string | in_keytab |
| ) |  |  |

Acquire a new initial credential from a keytab.

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

See also:
  kim_ccache_create_from_keytab

kim_error kim_credential_create_from_krb5_creds | ( | kim_credential * | out_credential,
|  | krb5_context | in_krb5_context,
|  | krb5_creds * | in_krb5_creds |
| ) |  |  |

Copy a credential from a krb5 credential object.

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_context | the krb5 context used to create in_krb5_creds.
  | in_krb5_creds | a krb5 credential object.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_credential_copy | ( | kim_credential * | out_credential,
|  | kim_credential | 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 code representing the failure.

kim_error kim_credential_get_krb5_creds | ( | kim_credential | in_credential,
|  | krb5_context | in_krb5_context,
|  | krb5_creds ** | out_krb5_creds |
| ) |  |  |

Get a krb5 credentials object for a credential object.

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

kim_error kim_credential_get_client_identity | ( | kim_credential | in_credential,
|  | kim_identity * | 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 code representing the failure.

kim_error kim_credential_get_service_identity | ( | kim_credential | in_credential,
|  | kim_identity * | 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 code representing the failure.

kim_error kim_credential_is_tgt | ( | kim_credential | in_credential,
|  | kim_boolean * | 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 code representing the failure.

kim_error kim_credential_get_state | ( | kim_credential | in_credential,
|  | kim_credential_state * | out_state |
| ) |  |  |

Check the state of a credential (valid, expired, postdated, etc).

Parameters:

  | in_credential | a credential object.
  | out_state | on exit, the state of the credential. See kim_credential_state_enum for the possible values of out_state.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_credential_get_start_time | ( | kim_credential | in_credential,
|  | kim_time * | 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 code representing the failure.

See also:
  kim_ccache_get_start_time

kim_error kim_credential_get_expiration_time | ( | kim_credential | in_credential,
|  | kim_time * | 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 code representing the failure.

See also:
  kim_ccache_get_expiration_time

kim_error kim_credential_get_renewal_expiration_time | ( | kim_credential | in_credential,
|  | kim_time * | out_renewal_expiration_time |
| ) |  |  |

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

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. If credentials are not renewable at all, returns 0.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

See also:
  kim_ccache_get_renewal_expiration_time

kim_error kim_credential_get_options | ( | kim_credential | in_credential,
|  | kim_options * | out_options |
| ) |  |  |

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

Parameters:

  | in_credential | a credential object.
  | out_options | on exit, an options object reflecting the ticket options of in_credential.

Returns:
  On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_credential_store | ( | kim_credential | in_credential,
|  | kim_identity | in_client_identity,
|  | kim_ccache * | out_ccache |
| ) |  |  |

Store a credential in a ccache in the cache collection.

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

kim_error kim_credential_verify | ( | kim_credential | in_credential,
|  | kim_identity | in_service_identity,
|  | kim_string | in_keytab,
|  | kim_boolean | in_fail_if_no_service_key |
| ) |  |  |

Verify a TGT credential.

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

See also:
  kim_ccache_verify

kim_error kim_credential_renew | ( | kim_credential * | io_credential,
|  | kim_options | 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 code representing the failure.

See also:
  kim_ccache_renew

kim_error kim_credential_validate | ( | kim_credential * | io_credential,
|  | kim_options | 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 code representing the failure.

See also:
  kim_ccache_validate

void kim_credential_free | ( | kim_credential * | io_credential | ) |

Free memory associated with a credential object.

Parameters:

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