KIM Identity Overview

Introduction

Identities in Kerberos are named by "principals". These identies may be people (users) or services (a server running on a host). When Kerberos issues credentials which authenticate one identity to another, the identity being authenticated is called the "client identity" and the identity being authenticated to is called the "service identity".

Kerberos identities are made up of one or more components, as well as the Kerberos realm the entity belongs to. For client identities the first component is usually the client username (eg: "jdoe"). For service identities the first component is the name of the service (eg: "imap").

Kerberos identities have both a binary (opaque) representation and also a string representation. The string representation consists of the components separated by '/' followed by an '@' and then the realm. For example, the identity "jdoe/admin@EXAMPLE.COM" represents John Doe's administrator identity at the realm EXAMPLE.COM. Note that identity components may contain both '/' and '@' characters. When building a identity from its string representation these syntactic characters must be escaped with '\'.

Creating and Displaying Identities

KIM Identities can be generated from components, their escaped string representation or from a krb5_principal. Once you have a KIM identity object, you can also get the component, string or krb5_principal representations back out:

kim_identity_create_from_components() creates an identity object from a list of components.
kim_identity_get_number_of_components() returns the number of components in an identity object.
kim_identity_get_component_at_index() return a component of an identity object.
kim_identity_get_realm() returns the identity's realm.

kim_identity_create_from_string() generates an identity object from an escaped string representation.
kim_identity_get_string() returns the identity's escaped string representation.
kim_identity_get_display_string() returns a non-escaped string for display to the user. This string cannot be passed into kim_identity_create_from_string().

kim_identity_create_from_krb5_principal() generates an identity object from a krb5_principal object.
kim_identity_get_krb5_principal() returns a krb5_principal object for an identity object.

kim_identity_get_gss_name() returns a gss_name_t object for use with gss_acquire_cred().

Note:: If you need to know if two identity objects refer to the same entity, use kim_identity_compare().

Choosing a Client Identity

Unfortunately most of the time applications don't know what client identity to use. Users may have identities for multiple Kerberos realms, as well as multiple identities in a single realm (such as a user and administrator identity).

To solve this problem, kim_selection_hints_get_identity() takes information from the application in the form of a selection hints object and returns the best matching client identity, if one is available. See KIM Selection Hints Overview for more information.

Changing a Identity's Password

Many Kerberos sites use passwords for user accounts. Because passwords may be stolen or compromised, they must be frequently changed. KIM provides APIs to change the identity's password directly, and also handles changing the identity's password when it has expired.

kim_identity_change_password() presents a user interface to obtain the old and new passwords from the user. kim_identity_change_password_with_passwords() takes the old and new passwords as input, but may still present a user interface if it needs to obtain additional information to authenticate.

Note:: Not all identities have a password. Some sites use certificates (pkinit) and in the future there may be other authentication mechanisms (eg: smart cards).

See KIM Identity Reference Documentation for information on specific APIs.