# KIM Identity Reference Documentation

## Functions

- kim_error kim_identity_create_from_string (kim_identity *out_identity, kim_string in_string)
    Create a identity from a string.
- 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.
- 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.
- kim_error kim_identity_copy (kim_identity *out_identity, kim_identity in_identity)
    Copy an identity object.
- kim_error kim_identity_compare (kim_identity in_identity, kim_identity in_compare_to_identity, kim_comparison *out_comparison)
    Compare identity objects for equivalency.
- kim_error kim_identity_get_string (kim_identity in_identity, kim_string *out_string)
    Get the string representation of a identity.
- 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.
- kim_error kim_identity_get_realm (kim_identity in_identity, kim_string *out_realm_string)
    Get the realm string of an identity.
- 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.
- 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.
- 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.
- 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.
- kim_error kim_identity_change_password (kim_identity in_identity)
    Change the password for an identity.
- void kim_identity_free (kim_identity *io_identity)
    Free memory associated with an identity.

## 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.