<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>kim.h</title>
<style type="text/css">
.enscript-comment { font-style: italic; color: rgb(178,34,34); }
.enscript-function-name { font-weight: bold; color: rgb(0,0,255); }
.enscript-variable-name { font-weight: bold; color: rgb(184,134,11); }
.enscript-keyword { font-weight: bold; color: rgb(160,32,240); }
.enscript-reference { font-weight: bold; color: rgb(95,158,160); }
.enscript-string { font-weight: bold; color: rgb(188,143,143); }
.enscript-builtin { font-weight: bold; color: rgb(218,112,214); }
.enscript-type { font-weight: bold; color: rgb(34,139,34); }
.enscript-highlight { text-decoration: underline; color: 0; }
</style>
</head>
<body id="top">
<h1 style="margin:8px;" id="f1">kim.h&nbsp;&nbsp;&nbsp;<span style="font-weight: normal; font-size: 0.5em;">[<a href="kim.h">plain text</a>]</span></h1>
<hr/>
<div></div>
<pre>
<span class="enscript-comment">/*
 * Copyright 2005-2006 Massachusetts Institute of Technology.
 * All Rights Reserved.
 *
 * Export of this software from the United States of America may
 * require a specific license from the United States Government.
 * It is the responsibility of any person or organization contemplating
 * export to obtain such a license before exporting.
 * 
 * WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
 * distribute this software and its documentation for any purpose and
 * without fee is hereby granted, provided that the above copyright
 * notice appear in all copies and that both that copyright notice and
 * this permission notice appear in supporting documentation, and that
 * the name of M.I.T. not be used in advertising or publicity pertaining
 * to distribution of the software without specific, written prior
 * permission.  Furthermore if you modify this software you must label
 * your software as modified software and not distribute it in such a
 * fashion that it might be confused with the original M.I.T. software.
 * M.I.T. makes no representations about the suitability of
 * this software for any purpose.  It is provided &quot;as is&quot; without express
 * or implied warranty.
 */</span>

#<span class="enscript-reference">ifndef</span> <span class="enscript-variable-name">KIM_H</span>
#<span class="enscript-reference">define</span> <span class="enscript-variable-name">KIM_H</span>

#<span class="enscript-reference">ifdef</span> <span class="enscript-variable-name">__cplusplus</span>
<span class="enscript-type">extern</span> <span class="enscript-string">&quot;C&quot;</span> {
#<span class="enscript-reference">endif</span>

#<span class="enscript-reference">include</span> <span class="enscript-string">&lt;Kerberos/kim_types.h&gt;</span>
#<span class="enscript-reference">include</span> <span class="enscript-string">&lt;Kerberos/kim_errors.h&gt;</span>
#<span class="enscript-reference">include</span> <span class="enscript-string">&lt;Kerberos/kim_string.h&gt;</span>
#<span class="enscript-reference">include</span> <span class="enscript-string">&lt;Kerberos/kim_identity.h&gt;</span>
#<span class="enscript-reference">include</span> <span class="enscript-string">&lt;Kerberos/kim_options.h&gt;</span>
#<span class="enscript-reference">include</span> <span class="enscript-string">&lt;Kerberos/kim_selection_hints.h&gt;</span>
#<span class="enscript-reference">include</span> <span class="enscript-string">&lt;Kerberos/kim_preferences.h&gt;</span>
#<span class="enscript-reference">include</span> <span class="enscript-string">&lt;Kerberos/kim_credential.h&gt;</span>
#<span class="enscript-reference">include</span> <span class="enscript-string">&lt;Kerberos/kim_ccache.h&gt;</span>

<span class="enscript-comment">/*!
 * \mainpage Kerberos Identity Management (KIM) API Documentation
 *
 * \section introduction 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.
 *
 *
 * \section conventions 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:
 *
 * \li Functions beginning with \b 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.
 * 
 * \li Functions of the form \b kim_object_copy are copy constructors.  They instantiate
 * a new object of kim_object from an object of the same type.
 * 
 * \li Functions of the form \b kim_object_free are destructors for objects of type 
 * kim_object.  
 *
 * \li Functions beginning with \b kim_object_get and \b kim_object_set
 * examine and modify properties of objects of type kim_object.
 *
 * \li All KIM APIs except destructors and error management APIs return a 
 * KIM Error object (kim_error_t).  
 *
 *
 * \section terminology 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:
 *
 * \li &lt;b&gt;credential&lt;/b&gt; - A token which authenticates a client identity to a 
 *                         service identity. 
 *
 * \li &lt;b&gt;ccache&lt;/b&gt; - Short for &quot;credentials cache&quot;.  A set of credentials for a single 
 *                     client identity.
 *
 * \li &lt;b&gt;cache collection&lt;/b&gt; - The set of all credential caches.
 *
 * \li &lt;b&gt;default ccache&lt;/b&gt; - 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.
 *
 * \section selection_api 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 &quot;default ccache&quot; 
 * mechanism previously used by Kerberos.
 * 
 * &lt;B&gt;KIM Selection Hints (kim_selection_hints_t)&lt;/B&gt; controls options for selecting 
 * a client identity:
 * - \subpage kim_selection_hints_overview
 * - \subpage kim_selection_hints_reference
 *
 * &lt;B&gt;KIM Identity (kim_identity_t)&lt;/B&gt; provides an immutable Kerberos identity object
 * - \subpage kim_identity_overview
 * - \subpage kim_identity_reference
 *
 *
 * \section management_api 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.
 *
 * &lt;B&gt;KIM CCache (kim_ccache_t)&lt;/B&gt; manipulates credential caches in the cache collection:
 * - \subpage kim_ccache_overview
 * - \subpage kim_ccache_reference
 *
 * &lt;B&gt;KIM Credential (kim_credential_t)&lt;/B&gt; manipulates credentials: 
 * - \subpage kim_credential_overview
 * - \subpage kim_credential_reference
 *
 * &lt;B&gt;KIM Options (kim_options_t)&lt;/B&gt; control options for credential acquisition:
 * - \subpage kim_options_overview
 * - \subpage kim_options_reference
 * 
 * &lt;B&gt;KIM Preferences (kim_preferences_t)&lt;/B&gt; views and edits the current user's preferences:
 * - \subpage kim_preferences_overview
 * - \subpage kim_preferences_reference
 *
 *
 * \section utility_apis Miscellaneous APIs
 *
 * The high and low level APIs depend on the following basic utility classes
 * to manage generic types.
 *
 * &lt;B&gt;KIM String (kim_string_t)&lt;/B&gt; provides memory management for an immutable string:
 * - \subpage kim_string_overview
 * - \subpage kim_string_reference
 *
 *
 *
 * \section types Types and Constants
 *
 * \li \subpage kim_types_reference
 */</span>

#<span class="enscript-reference">ifdef</span> <span class="enscript-variable-name">__cplusplus</span>
}
#<span class="enscript-reference">endif</span>

#<span class="enscript-reference">endif</span> <span class="enscript-comment">/* KIM_H */</span>
</pre>
<hr />
</body></html>