Kerberos Identity Management (KIM) API Documentation
The Kerberos Identity Management API is a high level API for managing the selection and management of Kerberos credentials. It is intended for use by applications, credential management applications (eg: kinit, kpasswd, etc) and internally by the Kerberos libraries. Under some circumstances client applications may also benefit from the Kerberos Identity Management API.
Although KIM currently only provides a C API, it attempts to make that API as object-oriented as possible. KIM functions are grouped by object and all of the object types are opaque, including errors. The reason for this is two-fold. First, the KIM API is rather large. Grouping functions by object allows the API to be broken up into smaller, more manageable chunks. Second, providing an object-like C API will make it easier to port to object oriented languages.
Because C lacks classes and other object oriented syntax, KIM functions adhere to the following naming conventions to make functions easier to identify:
- Functions beginning with kim_object_create are constructors for an object of type kim_object. On success these functions return a newly allocated object which must later be freed by the caller.
- Functions of the form kim_object_copy are copy constructors. They instantiate a new object of kim_object from an object of the same type.
- Functions of the form kim_object_free are destructors for objects of type kim_object.
- Functions beginning with kim_object_get and kim_object_set examine and modify properties of objects of type kim_object.
- All KIM APIs except destructors and error management APIs return a KIM Error object (kim_error_t).
Kerberos organizes its authentication tokens by client identity (the name of the user) and service identity (the name of a service). The following terms are used throughout this documentation:
- credential - A token which authenticates a client identity to a service identity.
- ccache - Short for "credentials cache". A set of credentials for a single client identity.
- cache collection - The set of all credential caches.
- default ccache - A credentials cache that the Kerberos libraries will use if no ccache is specified by the caller. Use of the default ccache is now discouraged. Instead applications should use selection hints to choose an appropriate client identity.
KIM provides high level APIs for applications to select which client identity to use. Use of these APIs is intended to replace the traditional "default ccache" mechanism previously used by Kerberos.
KIM Selection Hints (kim_selection_hints_t) controls options for selecting a client identity:
KIM Identity (kim_identity_t) provides an immutable Kerberos identity object
KIM also provides APIs for acquiring new credentials over the network by contacting a KDC and for viewing and modifying the existing credentials in the cache collection
Whether or not you use the credential or ccache APIs depends on whether you want KIM to store any newly acquired credentials in the cache collection. KIM ccache APIs always create a ccache in the cache collection containing newly acquired credentials whereas the KIM credential APIs just return a credential object. In general most callers want to store newly acquired credentials and should use the KIM ccache APIs when acquiring credentials.
KIM CCache (kim_ccache_t) manipulates credential caches in the cache collection:
KIM Credential (kim_credential_t) manipulates credentials:
KIM Options (kim_options_t) control options for credential acquisition:
KIM Realms List (kim_favorite_identities_t) views and edits the current user's favorite realms list:
KIM Preferences (kim_preferences_t) views and edits the current user's preferences:
The high and low level APIs depend on the following basic utility classes to manage generic types.
KIM String (kim_string_t) provides memory management for an immutable string:
KIM Error (kim_error_t) provides a machine and user-readable error message: