KIM Identity Reference Documentation

Functions

Function Documentation

kim_error kim_identity_create_from_string ( kim_identity *  out_identity,
kim_string  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 code representing the failure.

kim_error kim_identity_create_from_components ( kim_identity *  out_identity,
kim_string  in_realm,
kim_string  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 code representing the failure.

kim_error kim_identity_create_from_krb5_principal ( kim_identity *  out_identity,
krb5_context  in_krb5_context,
krb5_principal  in_krb5_principal 
)

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_context the krb5 context used to create in_krb5_principal.
in_krb5_principal a krb5 principal object.
Returns:
On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_identity_copy ( kim_identity *  out_identity,
kim_identity  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 code representing the failure.

kim_error kim_identity_compare ( kim_identity  in_identity,
kim_identity  in_compare_to_identity,
kim_comparison *  out_comparison 
)

Compare identity objects for equivalency.

Parameters:
in_identity an identity object.
in_compare_to_identity an identity object.
out_comparison on exit, a comparison of in_identity and in_compare_to_identity which determines whether or not the two identities are equivalent and their sort order (for display to the user) if they are not.
Returns:
On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_identity_get_string ( kim_identity  in_identity,
kim_string *  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 code representing the failure.
Note:
Special characters such as '@' and '/' will be escaped with '\'.

kim_error kim_identity_get_display_string ( kim_identity  in_identity,
kim_string *  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 code 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() because it does not uniquely specify a principal. The result of this function should only be used to display to the user.

kim_error kim_identity_get_realm ( kim_identity  in_identity,
kim_string *  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 code representing the failure.

kim_error kim_identity_get_number_of_components ( kim_identity  in_identity,
kim_count *  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 code representing the failure.

kim_error kim_identity_get_component_at_index ( kim_identity  in_identity,
kim_count  in_index,
kim_string *  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 code representing the failure.

kim_error kim_identity_get_components_string ( kim_identity  in_identity,
kim_string *  out_components 
)

Get a display string of the non-realm components of an identity.

Parameters:
in_identity an identity object.
out_components on exit, a string of the non-realm components of in_identity separated by '/' characters. Must be freed with kim_string_free().
Returns:
On success, KIM_NO_ERROR. On failure, an error code representing the failure.

kim_error kim_identity_get_krb5_principal ( kim_identity  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 code representing the failure.

kim_error kim_identity_change_password ( kim_identity  in_identity  ) 

Change the password for an identity.

Parameters:
in_identity an identity object whose password will be changed.
Returns:
On success, KIM_NO_ERROR. On failure, an error code representing the failure.
Note:
kim_identity_change_password() will acquire a temporary credential to change the password.

void kim_identity_free ( kim_identity *  io_identity  ) 

Free memory associated with an identity.

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

Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by  doxygen 1.5.3