KIM Identity Reference Documentation

Functions

Function Documentation

kim_error_t kim_identity_create_from_string (  kim_identity_t *  out_identity,
kim_string_t  in_string
) 
 

Create a identity from a string.

Parameters:
out_identity on exit, a new identity object. Must be freed with kim_identity_free().
in_string a string representation of a Kerberos identity. Special characters such as '/' and '@' must be escaped with '\'.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.

kim_error_t kim_identity_create_from_components (  kim_identity_t *  out_identity,
kim_string_t  in_realm,
kim_string_t  in_1st_component,
  ...
) 
 

Create a identity from a realm and component strings.

Parameters:
out_identity on exit, a new identity object. Must be freed with kim_identity_free().
in_realm a string representation of a Kerberos realm.
in_1st_component a string representing the first component of the identity.
... zero or more strings of type kim_string_t representing additional components of the identity followed by a terminating NULL. Components will be assembled in order(ie: the 4th argument to kim_identity_create_from_components() will be the 2nd component of the identity).
Note:
The last argument must be a NULL or kim_identity_create_from_components() may crash.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.

kim_error_t kim_identity_create_from_krb5_principal (  kim_identity_t *  out_identity,
krb5_principal  in_krb5_principal,
krb5_context  in_krb5_context
) 
 

Create an identity object from a krb5_principal.

Parameters:
out_identity on exit, a new identity object which is a copy of in_krb5_principal. Must be freed with kim_identity_free().
in_krb5_principal a krb5 identity object.
in_krb5_context the krb5 context used to create in_krb5_principal.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.

kim_error_t kim_identity_copy (  kim_identity_t *  out_identity,
kim_identity_t  in_identity
) 
 

Copy an identity object.

Parameters:
out_identity on exit, a new identity object which is a copy of in_identity. Must be freed with kim_identity_free().
in_identity an identity object.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.

kim_error_t kim_identity_compare (  kim_identity_t  in_identity,
kim_identity_t  in_compare_to_identity,
kim_boolean_t *  out_equivalent
) 
 

Compare identity objects for equivalency.

Parameters:
in_identity an identity object.
in_compare_to_identity an identity object.
out_equivalent on exit, whether or not in_identity and in_compare_to_identity represent the same identity.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.

kim_error_t kim_identity_get_string (  kim_identity_t  in_identity,
kim_string_t *  out_string
) 
 

Get the string representation of a identity.

Parameters:
in_identity an identity object.
out_string on exit, a string representation of in_identity. Must be freed with kim_string_free().
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Note:
Special characters such as '@' and '/' will be escaped with '\'.

kim_error_t kim_identity_get_display_string (  kim_identity_t  in_identity,
kim_string_t *  out_display_string
) 
 

Get a human-readable string representation of an identity.

Parameters:
in_identity an identity object.
out_display_string on exit, a string representation of in_identity appropriate for display to the user. Must be freed with kim_string_free().
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Note:
Special characters such as '/' and '@' are not escaped with '\'. As a result the string returned from this function cannot be used with kim_identity_create_from_string().

kim_error_t kim_identity_get_realm (  kim_identity_t  in_identity,
kim_string_t *  out_realm_string
) 
 

Get the realm string of an identity.

Parameters:
in_identity an identity object.
out_realm_string on exit, a string representation of in_identity's realm. Must be freed with kim_string_free().
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.

kim_error_t kim_identity_get_number_of_components (  kim_identity_t  in_identity,
kim_count_t *  out_number_of_components
) 
 

Get the number of components of an identity.

Parameters:
in_identity an identity object.
out_number_of_components on exit the number of components in in_identity.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.

kim_error_t kim_identity_get_component_at_index (  kim_identity_t  in_identity,
kim_index_t  in_index,
kim_string_t *  out_component_string
) 
 

Get the Nth component of an identity.

Parameters:
in_identity an identity object.
in_index the index of the desired component. Component indexes start at 0.
out_component_string on exit, a string representation of the component in in_identity specified by in_index. Must be freed with kim_string_free().
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.

kim_error_t kim_identity_get_krb5_principal (  kim_identity_t  in_identity,
krb5_context  in_krb5_context,
krb5_principal *  out_krb5_principal
) 
 

Get the krb5_principal representation of an identity.

Parameters:
in_identity an identity object.
in_krb5_context a krb5 context object.
out_krb5_principal on exit, a krb5_principal representation of in_identity allocated with in_krb5_context. Must be freed with krb5_free_principal() using in_krb5_context.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.

kim_error_t kim_identity_get_gss_name (  kim_identity_t  in_identity,
gss_name_t *  out_gss_name
) 
 

Get the gss_name_t representation of an identity.

Parameters:
in_identity an identity object.
out_gss_name on exit, a gss_name_t representation of in_identity. Must be freed with gss_release_name().
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.

kim_error_t kim_identity_change_password (  kim_identity_t  in_identity,
kim_options_t  in_options
) 
 

Change the password for an identity.

Parameters:
in_identity an identity object whose password will be changed.
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.
Note:
kim_identity_change_password() will acquire a temporary credential to change the password. It uses the in_options structure to obtain information about the desired prompter and current password.

kim_error_t kim_identity_change_password_with_passwords (  kim_identity_t  in_identity,
kim_options_t  in_options,
kim_string_t  in_new_password
) 
 

Change the password for an identity to a caller-provided new password.

Parameters:
in_identity an identity object whose password will be changed.
in_options initial credential options to be used if a new credential is obtained.
in_new_password a string representation of the identity's new password.
Returns:
On success, KIM_NO_ERROR. On failure, an error object representing the failure.
Note:
kim_identity_change_password_with_passwords() will acquire a temporary credential to change the password. It uses the in_options structure to obtain information about the desired prompter and current password.

void kim_identity_free (  kim_identity_t *  io_identity  ) 
 

Free memory associated with an identity.

Parameters:
io_identity the identity object to be freed. Set to NULL on exit.