<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8"> <title>Kerberos Identity Management: Kerberos Identity Management (KIM) API Documentation</title> <link href="doxygen.css" rel="stylesheet" type="text/css"> <link href="tabs.css" rel="stylesheet" type="text/css"> </head><body> <!-- Generated by Doxygen 1.5.3 --> <h1>Kerberos Identity Management (KIM) API Documentation</h1> <p> <h2><a class="anchor" name="introduction"> Introduction</a></h2> 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.<h2><a class="anchor" name="conventions"> API Conventions</a></h2> 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.<p> Because C lacks classes and other object oriented syntax, KIM functions adhere to the following naming conventions to make functions easier to identify:<p> <ul> <li>Functions beginning with <b>kim_object_create</b> 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.</li> </ul> <ul> <li>Functions of the form <b>kim_object_copy</b> are copy constructors. They instantiate a new object of kim_object from an object of the same type.</li> </ul> <ul> <li>Functions of the form <b>kim_object_free</b> are destructors for objects of type kim_object.</li> </ul> <ul> <li>Functions beginning with <b>kim_object_get</b> and <b>kim_object_set</b> examine and modify properties of objects of type kim_object.</li> </ul> <ul> <li>All KIM APIs except destructors and error management APIs return a KIM Error object (kim_error_t).</li> </ul> <h2><a class="anchor" name="terminology"> Terminology</a></h2> 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:<p> <ul> <li><b>credential</b> - A token which authenticates a client identity to a service identity.</li> </ul> <ul> <li><b>ccache</b> - Short for "credentials cache". A set of credentials for a single client identity.</li> </ul> <ul> <li><b>cache collection</b> - The set of all credential caches.</li> </ul> <ul> <li><b>default ccache</b> - 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.</li> </ul> <h2><a class="anchor" name="selection_api"> Client Identity Selection APIs</a></h2> 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.<p> <b>KIM Selection Hints (kim_selection_hints_t)</b> controls options for selecting a client identity:<ul> <li><a class="el" href="kim_selection_hints_overview.html">KIM Selection Hints Overview</a></li><li><a class="el" href="group__kim__selection__hints__reference.html">KIM Selection Hints Reference Documentation</a></li></ul> <p> <b>KIM Identity (kim_identity_t)</b> provides an immutable Kerberos identity object<ul> <li><a class="el" href="kim_identity_overview.html">KIM Identity Overview</a></li><li><a class="el" href="group__kim__identity__reference.html">KIM Identity Reference Documentation</a></li></ul> <h2><a class="anchor" name="management_api"> Credential Management APIs</a></h2> 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<p> 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.<p> <b>KIM CCache (kim_ccache_t)</b> manipulates credential caches in the cache collection:<ul> <li><a class="el" href="kim_ccache_overview.html">KIM CCache Overview</a></li><li><a class="el" href="group__kim__ccache__reference.html">KIM CCache Reference Documentation</a></li></ul> <p> <b>KIM Credential (kim_credential_t)</b> manipulates credentials:<ul> <li><a class="el" href="kim_credential_overview.html">KIM Credential Overview</a></li><li><a class="el" href="group__kim__credential__reference.html">KIM Credential Reference Documentation</a></li></ul> <p> <b>KIM Options (kim_options_t)</b> control options for credential acquisition:<ul> <li><a class="el" href="kim_options_overview.html">KIM Options Overview</a></li><li><a class="el" href="group__kim__options__reference.html">KIM Options Reference Documentation</a></li></ul> <p> <b>KIM Preferences (kim_preferences_t)</b> views and edits the current user's preferences:<ul> <li><a class="el" href="kim_preferences_overview.html">KIM Preferences Overview</a></li><li><a class="el" href="group__kim__preferences__reference.html">KIM Preferences Documentation</a></li></ul> <h2><a class="anchor" name="utility_apis"> Miscellaneous APIs</a></h2> The high and low level APIs depend on the following basic utility classes to manage generic types.<p> <b>KIM String (kim_string_t)</b> provides memory management for an immutable string:<ul> <li><a class="el" href="kim_string_overview.html">KIM String Overview</a></li><li><a class="el" href="group__kim__string__reference.html">KIM String Reference Documentation</a></li></ul> <h2><a class="anchor" name="types"> Types and Constants</a></h2> <ul> <li><a class="el" href="group__kim__types__reference.html">KIM Types and Constants</a> </li> </ul> <hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:43 2008 for Kerberos Identity Management by <a href="http://www.doxygen.org/index.html"> <img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address> </body> </html>
