Kerberos Identity Management (KIM) API Documentation

Introduction

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.

API Conventions

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:

Terminology

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:

Client Identity Selection APIs

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

Credential Management APIs

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:

Miscellaneous APIs

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:

Types and Constants