KIM Credential Reference Documentation

Functions

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.