Move KIM implementation to the krb5 repository

Moved sources and headers.

ticket: new
status: open

git-svn-id: svn://anonsvn.mit.edu/krb5/trunk@20314 dc483132-0cff-0310-8789-dd5450dbe970

10 files changed, 3581 insertions, 0 deletions

diff --git a/src/include/kim/kim.h b/src/include/kim/kim.h
new file mode 100644
index 0000000000..893891defd
--- /dev/null
+++ b/src/include/kim/kim.h
@@ -0,0 +1,176 @@
+/*
+ * 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 "as is" without express
+ * or implied warranty.
+ */
+
+#ifndef KIM_H
+#define KIM_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <kim/kim_types.h>
+#include <kim/kim_string.h>
+#include <kim/kim_error.h>
+#include <kim/kim_identity.h>
+#include <kim/kim_options.h>
+#include <kim/kim_selection_hints.h>
+#include <kim/kim_preferences.h>
+#include <kim/kim_credential.h>
+#include <kim/kim_ccache.h>
+
+/*!
+ * \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 <b>credential</b> - A token which authenticates a client identity to a 
+ *                         service identity. 
+ *
+ * \li <b>ccache</b> - Short for "credentials cache".  A set of credentials for a single 
+ *                     client identity.
+ *
+ * \li <b>cache collection</b> - The set of all credential caches.
+ *
+ * \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.
+ *
+ * \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 "default ccache" 
+ * mechanism previously used by Kerberos.
+ * 
+ * <B>KIM Selection Hints (kim_selection_hints_t)</B> controls options for selecting 
+ * a client identity:
+ * - \subpage kim_selection_hints_overview
+ * - \subpage kim_selection_hints_reference
+ *
+ * <B>KIM Identity (kim_identity_t)</B> 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.
+ *
+ * <B>KIM CCache (kim_ccache_t)</B> manipulates credential caches in the cache collection:
+ * - \subpage kim_ccache_overview
+ * - \subpage kim_ccache_reference
+ *
+ * <B>KIM Credential (kim_credential_t)</B> manipulates credentials: 
+ * - \subpage kim_credential_overview
+ * - \subpage kim_credential_reference
+ *
+ * <B>KIM Options (kim_options_t)</B> control options for credential acquisition:
+ * - \subpage kim_options_overview
+ * - \subpage kim_options_reference
+ * 
+ * <B>KIM Realms List (kim_favorite_identities_t)</B> views and edits the current user's favorite realms list:
+ * - \subpage kim_favorite_identities_overview
+ * - \subpage kim_favorite_identities_reference
+ *
+ * <B>KIM Preferences (kim_preferences_t)</B> 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.
+ *
+ * <B>KIM String (kim_string_t)</B> provides memory management for an immutable string:
+ * - \subpage kim_string_overview
+ * - \subpage kim_string_reference
+ *
+ * <B>KIM Error (kim_error_t)</B> provides a machine and user-readable error message:
+ * - \subpage kim_error_overview
+ * - \subpage kim_error_reference
+ *
+ *
+ * \section types Types and Constants
+ *
+ * \li \subpage kim_types_reference
+ */
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* KIM_H */
diff --git a/src/include/kim/kim_ccache.h b/src/include/kim/kim_ccache.h
new file mode 100644
index 0000000000..ad3ee16260
--- /dev/null
+++ b/src/include/kim/kim_ccache.h
@@ -0,0 +1,554 @@
+/*
+ * 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 "as is" without express
+ * or implied warranty.
+ */
+
+#ifndef KIM_CCACHE_H
+#define KIM_CCACHE_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <kim/kim_types.h>
+    
+/*!
+ * \page kim_ccache_overview KIM CCache Overview
+ *
+ * \section kim_ccache_introduction Introduction
+ *
+ * Kerberos credentials are stored in "ccaches" (short for "credentials caches").
+ * The set of all ccaches which the KIM can use is called the "cache collection".   
+ * Each ccache has a name and type which uniquely identify it in the cache 
+ * collection and a client identity.  The ccache's client identity is the 
+ * identity whose credentials are stored in the ccache.  This allows for easy  
+ * lookup of all the credentials for a given identity. 
+ *
+ * KIM attempts to preserve a one-to-one relationship between client identities
+ * and ccaches.  If the KIM is used to manipulate the cache collection, there
+ * will be one ccache per identity.  However, because low-level APIs allow callers
+ * to create multiple ccaches for the same client identity or a single ccache 
+ * containing credentials for different client identities, KIM handles those
+ * situations.  In general when searching KIM will find the first ccache matching 
+ * the requested client identity.  It will not find credentials for the requested  
+ * client identity if they are in a ccache with a different client identity.
+ *
+ * The kim_ccache_t object is a reference to a ccache in the cache collection.  
+ * If other applications make changes to the the ccache pointed to by a KIM ccache 
+ * object, the object will immediately show those changes.  KIM performs locking 
+ * on the cache collection to prevent deadlocks and maintain a consistent behavior 
+ * when multiple applications attempt to modify the cache collection.
+ *
+ * \note KIM ccache APIs are intended for applications and system 
+ * tools which manage credentials for the user.  They are not a substitute for
+ * krb5 and GSSAPI functions which obtain service credentials for the purpose
+ * of authenticating a client to an application server.
+ * 
+ * \section kim_credential_cache_collection Acquiring a CCache from the Cache Collection
+ *
+ * KIM provides a simple iterator API for iterating over the ccaches
+ * in the cache collection.  First, call #kim_ccache_iterator_create() to obtain 
+ * an iterator for the cache collection.  Then loop calling 
+ * #kim_ccache_iterator_next() until either you find the ccache you are looking 
+ * for or the API returns a NULL ccache, indicating that there are no more
+ * ccaches in the cache collection.  When you are done with the iterator, call
+ * #kim_ccache_iterator_free().
+ *
+ * \note #kim_ccache_iterator_next() returns ccache objects which
+ * must be freed with #kim_ccache_free() to avoid leaking memory.
+ *
+ * KIM also provides a convenient API #kim_ccache_create_from_client_identity()
+ * which returns the ccache for a specific client identity, if any exists.
+ * Typically callers of this API obtain the client identity using
+ * #kim_selection_hints_get_identity().
+ * 
+ *
+ * \section kim_ccache_acquire_default Acquiring Credentials from the Default CCache
+ *
+ * #kim_ccache_create_from_default() returns the default ccache.
+ * The default ccache is a legacy concept which was replaced by selection 
+ * hints.  Prior to the existence of selection hints, applications always 
+ * looked at the default ccache for credentials.  By setting the system default 
+ * ccache, users could manually control which credentials each application used.  
+ * As the number of ccaches and applications has grown, this mechanism has become
+ * unusable.  You should avoid using this API whenever possible.
+ *
+ *
+ * \section kim_ccache_acquire_new Acquiring New Credentials in a CCache
+ *
+ * KIM provides the #kim_ccache_create_new() API for acquiring new
+ * credentials and storing them in a ccache.  Credentials can either be 
+ * obtained for a specific client identity or by specifying 
+ * #KIM_IDENTITY_ANY to allow the user to choose.  Typically 
+ * callers of this API obtain the client identity using 
+ * #kim_selection_hints_get_identity().  Depending on the kim_options
+ * specified, #kim_ccache_create_new() may present a GUI or command line 
+ * prompt to obtain information from the user.
+ * 
+ * #kim_ccache_create_new_if_needed() 
+ * searches the cache collection for a ccache for the client identity
+ * and if no appropriate ccache is available, attempts to acquire
+ * new credentials and store them in a new ccache.  Depending on the 
+ * kim_options specified, #kim_ccache_create_new_if_needed() may 
+ * present a GUI or command line prompt to obtain information from the 
+ * user. This function exists for convenience and to avoid code duplication.  
+ * It can be trivially implemented using 
+ * #kim_ccache_create_from_client_identity() and #kim_ccache_create_new().  
+ *
+ * KIM provides the #kim_ccache_create_from_keytab() to create credentials 
+ * using a keytab and store them in the cache collection. A keytab is an 
+ * on-disk copy of a client identity's secret key.  Typically sites use 
+ * keytabs for client identities that identify a machine or service and 
+ * protect the keytab with disk permissions.  Because a keytab is 
+ * sufficient to obtain credentials, keytabs will normally only be readable 
+ * by root, Administrator or some other privileged account.  
+ * Typically applications use credentials obtained from keytabs to obtain
+ * credentials for batch processes.  These keytabs and credentials are usually 
+ * for a special identity used for the batch process rather than a user
+ * identity.
+ *
+ *
+ * \section kim_ccache_validate Validating Credentials in a CCache
+ *
+ * A credential with a start time in the future (ie: after the issue date)
+ * is called a post-dated credential.  Because the KDC administrator may 
+ * wish to disable a identity, once the start time is reached, all post-dated
+ * credentials must be validated before they can be used.  Otherwise an
+ * attacker using a compromised account could acquire lots of post-dated 
+ * credentials to circumvent the acccount being disabled.
+ *
+ * KIM provides the #kim_ccache_validate() API to validate the TGT  
+ * credential in a ccache. Note that this API replaces any existing 
+ * credentials with the validated credential.
+ * 
+ *
+ * \section kim_ccache_renew Renewing Credentials in a CCache
+ *
+ * A renewable credential can be used to obtain a new identical credential
+ * without resending secret information (such as a password) to the KDC.
+ * A credential may only be renewed during its renewal lifetime and while
+ * valid.
+ *
+ * KIM provides the #kim_ccache_renew() API to renew the TGT credential
+ * in a ccache. Note that this API replaces any existing credentials with the 
+ * renewed credential.
+ *
+ *
+ * \section kim_ccache_verify Verifying Credentials in a CCache
+ *
+ * When a program acquires TGT credentials for the purpose of authenticating
+ * itself to the machine it is running on, it is insufficient for the machine 
+ * to assume that the caller is authorized just because it got credentials.  
+ * Instead, the credentials must be verified using a key the local machine.  
+ * The reason this is necessary is because an attacker can trick the  
+ * machine into obtaining credentials from any KDC, including malicious ones
+ * with the same realm name as the local machine's realm.  This exploit is 
+ * called the Zanarotti attack.  
+ *
+ * In order to avoid the Zanarotti attack, the local machine must authenticate
+ * the process in the same way an application server would authenticate a client.
+ * Like an application server, the local machine must have its own identity in 
+ * its realm and a keytab for that identity on its local disk.    However,
+ * rather than forcing system daemons to use the network-oriented calls in the 
+ * krb5 and GSS APIs, KIM provides the #kim_ccache_verify() API to 
+ * verify credentials directly.  
+ * 
+ * The most common reason for using #kim_ccache_verify() is user login.  
+ * If the local machine wants to use Kerberos to verify the username and password
+ * provided by the user, it must call #kim_ccache_verify() on the credentials
+ * it obtains to make sure they are really from a KDC it trusts.  Another common
+ * case is a server which is only using Kerberos internally.  For example an
+ * LDAP or web server might use a username and password obtained over the network
+ * to get Kerberos credentials.  In order to make sure they aren't being tricked 
+ * into talking to the wrong KDC, these servers must also call 
+ * #kim_ccache_verify().
+ * 
+ * The Zanarotti attack is only a concern if the act of accessing the machine 
+ * gives the process special access.  Thus a managed cluster machine with 
+ * Kerberos-authenticated networked home directories does not need to call 
+ * #kim_ccache_verify().  Even though an attacker can log in as any user on   
+ * the cluster machine, the attacker can't actually access any of the user's data 
+ * or use any of their privileges because those are all authenticated via  
+ * Kerberized application servers (and thus require actually having credentials 
+ * for the real local realm).
+ *
+ * #kim_ccache_verify() provides an option to 
+ * return success even if the machine's host key is not present.  This option 
+ * exists for sites which have a mix of different machines, some of which are  
+ * vulnerable to the Zanarotti attack and some are not.  If this option is used, 
+ * it is the responsiblity of the machine's maintainer to obtain a keytab
+ * for their machine if it needs one.
+ *
+ *
+ * \section kim_ccache_properties Examining CCache Properties
+ *
+ * \li #kim_ccache_get_type() returns the type of the ccache.  Types include
+ * "API" for CCAPI ccaches, "FILE" for file-based ccaches and "MEMORY" for
+ * single-process in-memory ccaches.
+ *
+ * \li #kim_ccache_get_name() returns the name of the ccache.  A ccache's name
+ * identifies the ccache uniquely among ccaches of the same type.  Note that
+ * two ccaches with different types may have the same name.
+ *
+ * \li #kim_ccache_get_display_name() returns a display string which uniquely
+ * identifies a ccache.  A ccache display name is of the form "<type>:<name>"
+ * and can be displayed to the user or used as an argument to certain krb5
+ * APIs, such as krb5_cc_resolve().
+ * 
+ * \li #kim_ccache_get_client_identity()
+ * returns the ccache's client identity.
+ *
+ * \li #kim_ccache_get_valid_credential() 
+ * returns the first valid TGT in the ccache for its client identity.  
+ * If there are no TGTs in the ccache, it returns the first
+ * valid non-TGT credential for the ccache's client identity. 
+ * TGT credentials (ie: "ticket-granting tickets") are credentials for  
+ * the krbtgt service: a service identity of the form "krbtgt/<REALM>@<REALM>".   
+ * These credentials allow the entity named by the client identity to obtain  
+ * additional credentials without resending shared secrets (such as a password)
+ * to the KDC. Kerberos uses TGTs to provide single sign-on authentication.
+ *
+ * \li #kim_ccache_get_start_time() 
+ * returns when the credential's in a ccache will become valid.  
+ * Credentials may be "post-dated" which means that their lifetime starts sometime 
+ * in the future.  Note that when a post-dated credential's start time is reached, 
+ * the credential must be validated.  See \ref kim_credential_validate for more information.
+ *
+ * \li #kim_ccache_get_expiration_time() 
+ * returns when the credential's in a ccache will expire. 
+ * Credentials are time limited by the lifetime of the credential.  While you can 
+ * request a credential of any lifetime, the KDC limits the credential lifetime 
+ * to a administrator-defined maximum.  Typically credential lifetime range from 10
+ * to 21 hours.
+ *
+ * \li #kim_ccache_get_renewal_expiration_time() 
+ * returns when the credential's in a ccache will no longer be renewable. 
+ * Valid credentials may be renewed up until their renewal expiration time.  
+ * Renewing credentials acquires a fresh set of credentials with a full lifetime 
+ * without resending secrets to the KDC (such as a password).  If credentials are 
+ * not renewable, this function will return an error.
+ *
+ * See \ref kim_ccache_reference and \ref kim_ccache_iterator_reference for 
+ * information on specific APIs.
+ */
+
+
+/*!
+ * \defgroup kim_ccache_iterator_reference KIM CCache Iterator Reference Documentation
+ * @{
+ */
+
+/*!
+ * \param out_ccache_iterator on exit, a ccache iterator object for the cache collection.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get a ccache iterator to enumerate ccaches in the cache collection.
+ */
+kim_error_t kim_ccache_iterator_create (kim_ccache_iterator_t *out_ccache_iterator);
+
+/*!
+ * \param in_ccache_iterator a ccache iterator object.
+ * \param out_ccache         on exit, the next ccache in the cache collection. If there are 
+ *                           no more ccaches in the cache collection this argument will be 
+ *                           set to NULL.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the next ccache in the cache collection.
+ */
+kim_error_t kim_ccache_iterator_next (kim_ccache_iterator_t  in_ccache_iterator,
+                                      kim_ccache_t          *out_ccache);
+
+/*!
+ * \param io_ccache_iterator a ccache iterator object to be freed.  Set to NULL on exit.
+ * \brief Free memory associated with a ccache iterator.
+ */
+void kim_ccache_iterator_free (kim_ccache_iterator_t *io_ccache_iterator);
+
+/*!@}*/
+
+/*!
+ * \defgroup kim_ccache_reference KIM CCache Reference Documentation
+ * @{
+ */
+
+/*!
+ * \param out_ccache          on exit, a new cache object for a ccache containing a newly acquired 
+ *      		      initial credential.  Must be freed with kim_ccache_free().
+ * \param in_client_identity  a client identity to obtain a credential for.   Specify KIM_IDENTITY_ANY to 
+ *                            allow the user to choose.
+ * \param in_options          options to control credential acquisition. 
+ * \note Depending on the kim_options specified, #kim_ccache_create_new() may 
+ * present a GUI or command line prompt to obtain information from the user. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Acquire a new initial credential and store it in a ccache.
+ */
+kim_error_t kim_ccache_create_new (kim_ccache_t          *out_ccache,
+                                   kim_identity_t         in_client_identity,
+                                   kim_options_t          in_options);
+
+/*!
+ * \param out_ccache          on exit, a ccache object for a ccache containing a newly acquired   
+ *                            initial credential. Must be freed with kim_ccache_free().
+ * \param in_client_identity  a client identity to obtain a credential for.
+ * \param in_options          options to control credential acquisition (if a credential is acquired). 
+ * \note Depending on the kim_options specified, #kim_ccache_create_new_if_needed() may 
+ * present a GUI or command line prompt to obtain information from the user. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Find a ccache containing a valid initial credential in the cache collection, or if
+ *        unavailable, acquire and store a new initial credential.
+ */
+kim_error_t kim_ccache_create_new_if_needed (kim_ccache_t   *out_ccache,
+                                             kim_identity_t  in_client_identity,
+                                             kim_options_t   in_options);
+
+/*!
+ * \param out_ccache          on exit, a ccache object for a ccache containing a TGT  
+ *                            credential. Must be freed with kim_ccache_free().
+ * \param in_client_identity  a client identity to obtain a credential for.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Find a ccache for a client identity in the cache collection.
+ */
+kim_error_t kim_ccache_create_from_client_identity (kim_ccache_t   *out_ccache,
+                                                    kim_identity_t  in_client_identity);
+
+/*!
+ * \param out_ccache      on exit, a new ccache object containing an initial credential 
+ *      		  for the client identity \a in_identity obtained using in_keytab.  
+ *      		  Must be freed with kim_ccache_free().
+ * \param in_identity     a client identity to obtain a credential for.  Specify NULL for
+ *      		  the first client identity in the keytab.
+ * \param in_options      options to control credential acquisition. 
+ * \param in_keytab       a path to a keytab.  Specify NULL for the default keytab location. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Acquire a new initial credential from a keytab and store it in a ccache.
+ */
+kim_error_t kim_ccache_create_from_keytab (kim_ccache_t    *out_ccache,
+                                           kim_identity_t   in_identity,
+                                           kim_options_t    in_options,
+                                           kim_string_t     in_keytab);
+
+/*!
+ * \param out_ccache on exit, a ccache object for the default ccache.  
+ *                   Must be freed with kim_ccache_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the default ccache.
+ */
+kim_error_t kim_ccache_create_from_default (kim_ccache_t *out_ccache);
+
+/*!
+ * \param out_ccache  on exit, a ccache object for the ccache identified by 
+ *                    \a in_type and \a in_name.  Must be freed with kim_ccache_free().
+ * \param in_type     a ccache type string. 
+ * \param in_name     a ccache name string. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \note This API is provided for backwards compatibilty with applications which are not
+ *       KIM-aware and should be avoided whenever possible.
+ * \brief Get a ccache for a ccache type and name.
+ */
+kim_error_t kim_ccache_create_from_type_and_name (kim_ccache_t  *out_ccache,
+                                                  kim_string_t   in_type,
+                                                  kim_string_t   in_name);
+
+/*!
+ * \param out_ccache      on exit, a new ccache object which is a copy of in_krb5_ccache.  
+ *      		  Must be freed with kim_ccache_free().
+ * \param in_krb5_context the krb5 context used to create \a in_krb5_ccache. 
+ * \param in_krb5_ccache  a krb5 ccache object. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get a ccache for a krb5 ccache.
+ */
+kim_error_t kim_ccache_create_from_krb5_ccache (kim_ccache_t  *out_ccache,
+                                                krb5_context   in_krb5_context,
+                                                krb5_ccache    in_krb5_ccache);
+
+/*!
+ * \param out_ccache on exit, the new ccache object which is a copy of in_ccache.  
+ *      	     Must be freed with kim_ccache_free().
+ * \param in_ccache  a ccache object. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Copy a ccache.
+ */
+kim_error_t kim_ccache_copy (kim_ccache_t  *out_ccache,
+                             kim_ccache_t   in_ccache);
+
+/*!
+ * \param in_ccache        a ccache object. 
+ * \param in_krb5_context  a krb5 context which will be used to create out_krb5_ccache. 
+ * \param out_krb5_ccache  on exit, a new krb5 ccache object which is a copy of in_ccache.  
+ *      		   Must be freed with krb5_cc_close() or krb5_cc_destroy().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get a krb5 ccache for a ccache.
+ */
+kim_error_t kim_ccache_get_krb5_ccache (kim_ccache_t  in_ccache,
+                                        krb5_context  in_krb5_context,
+                                        krb5_ccache  *out_krb5_ccache);
+
+/*!
+ * \param in_ccache  a ccache object. 
+ * \param out_name   on exit, the name string of \a in_ccache.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the name of a ccache.
+ */
+kim_error_t kim_ccache_get_name (kim_ccache_t  in_ccache,
+                                 kim_string_t *out_name);
+
+/*!
+ * \param in_ccache  a ccache object. 
+ * \param out_type   on exit, the type string of \a in_ccache.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the type of a ccache.
+ */
+kim_error_t kim_ccache_get_type (kim_ccache_t  in_ccache,
+                                 kim_string_t *out_type);
+
+/*!
+ * \param in_ccache        a ccache object. 
+ * \param out_display_name on exit, the type and name of \a in_ccache in a format appropriate for  
+ *                         display to the user in command line programs.  (ie: "<type>:<name>")
+ *      		   Must be freed with kim_string_free().
+ *                         Note: this string can also be passed to krb5_cc_resolve().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the type and name for a ccache in display format.
+ */
+kim_error_t kim_ccache_get_display_name (kim_ccache_t  in_ccache,
+                                         kim_string_t *out_display_name);
+
+/*!
+ * \param in_ccache            a ccache object. 
+ * \param out_client_identity  on exit, an identity object containing the client identity of   
+ *      		       \a in_ccache. Must be freed with kim_identity_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the client identity for a ccache.
+ */
+kim_error_t kim_ccache_get_client_identity (kim_ccache_t    in_ccache,
+                                            kim_identity_t *out_client_identity);
+
+/*!
+ * \param in_ccache       a ccache object. 
+ * \param out_credential  on exit, the first valid credential in \a in_ccache. 
+ *      		  Must be freed with kim_credential_free().  Set to NULL
+ *                        if you only want return value, not the actual credential.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the first valid credential in a ccache.
+ * \note This function prefers TGT credentials.  If there are any non-valid TGTs
+ *       in the ccache, it will always return an error.  However, if there are no 
+ *       TGTs at all, it will return the first valid non-TGT credential. If you only want 
+ *       TGTs, use kim_credential_is_tgt() to verify that \a out_credential is a tgt.
+ */
+kim_error_t kim_ccache_get_valid_credential (kim_ccache_t      in_ccache,
+                                             kim_credential_t *out_credential);
+
+/*!
+ * \param in_ccache      a ccache object. 
+ * \param out_start_time on exit, the time when the credentials in \a in_ccache
+ *                       become valid.  May be in the past or future.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the time when the credentials in the ccache become valid.
+ */
+kim_error_t kim_ccache_get_start_time (kim_ccache_t  in_ccache,
+                                       kim_time_t   *out_start_time);
+
+/*!
+ * \param in_ccache           a ccache object. 
+ * \param out_expiration_time on exit, the time when the credentials in 
+ *                            \a in_ccache will expire.  May be in the past or future.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the time when the credentials in the ccache will expire.
+ */
+kim_error_t kim_ccache_get_expiration_time (kim_ccache_t  in_ccache,
+                                            kim_time_t   *out_expiration_time);
+
+/*!
+ * \param in_ccache                   a ccache object. 
+ * \param out_renewal_expiration_time on exit, the time when the credentials in \a in_ccache 
+ *                                    will no longer be renewable. May be in the past or future.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the time when the credentials in the ccache will no longer be renewable.
+ */
+kim_error_t kim_ccache_get_renewal_expiration_time (kim_ccache_t  in_ccache,
+                                                    kim_time_t   *out_renewal_expiration_time);
+
+/*!
+ * \param io_ccache a ccache object which will be set to the default ccache. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \note This API is provided for backwards compatibilty with applications which are not
+ *       KIM-aware and should be avoided whenever possible.
+ * \brief Set a ccache to the default ccache.
+ */
+kim_error_t kim_ccache_set_default (kim_ccache_t io_ccache);
+
+/*!
+ * \param in_ccache              a ccache object containing the TGT credential to be verified. 
+ * \param in_service_identity    a service identity to look for in the keytab.  Specify 
+ *                               KIM_IDENTITY_ANY to use the default service identity
+ *                               (usually host/<host's FQDN>@<host's local realm>).
+ * \param in_keytab              a path to a keytab.  Specify NULL for the default keytab location. 
+ * \param in_fail_if_no_service_key whether or not the absence of a key for \a in_service_identity
+ *                                  in the host's keytab will cause a failure. 
+ * \note specifying FALSE for \a in_fail_if_no_service_key may expose the calling program to 
+ * the Zanarotti attack if the host has no keytab installed.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Verify the TGT in a ccache.
+ */
+kim_error_t kim_ccache_verify (kim_ccache_t   in_ccache,
+                               kim_identity_t in_service_identity,
+                               kim_string_t   in_keytab,
+                               kim_boolean_t  in_fail_if_no_service_key);
+
+/*!
+ * \param in_ccache  a ccache object containing a TGT to be renewed. 
+ * \param in_options initial credential options to be used if a new credential is obtained.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Renew the TGT in a ccache.
+ */
+kim_error_t kim_ccache_renew (kim_ccache_t  in_ccache,
+                              kim_options_t in_options);
+
+/*!
+ * \param in_ccache  a ccache object containing a TGT to be validated. 
+ * \param in_options initial credential options.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Validate the TGT in a ccache.
+ */
+kim_error_t kim_ccache_validate (kim_ccache_t  in_ccache,
+                                 kim_options_t in_options);
+
+/*!
+ * \param io_ccache  a ccache object to be destroyed.  Set to NULL on exit.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Remove a ccache from the cache collection.
+ * \note Frees memory associated with the ccache.  Do not call kim_ccache_free()
+ *       after calling this function.
+ */
+kim_error_t kim_ccache_destroy (kim_ccache_t *io_ccache);
+
+/*!
+ * \param io_ccache a ccache object to be freed.  Set to NULL on exit.
+ * \brief Free memory associated with a ccache.
+ */
+void kim_ccache_free (kim_ccache_t *io_ccache);
+
+/*!@}*/
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* KIM_CCACHE_H */
diff --git a/src/include/kim/kim_credential.h b/src/include/kim/kim_credential.h
new file mode 100644
index 0000000000..03fe50c493
--- /dev/null
+++ b/src/include/kim/kim_credential.h
@@ -0,0 +1,519 @@
+/*
+ * 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 "as is" without express
+ * or implied warranty.
+ */
+
+#ifndef KIM_CREDENTIAL_H
+#define KIM_CREDENTIAL_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <kim/kim_types.h>
+#include <krb5.h>
+    
+/*!
+ * \addtogroup kim_types_reference
+ * @{
+ */
+    
+/*!
+ * Possible credential states.  Credentials may be:
+ * \li valid - The credential can be used.
+ * \li expired - The credential's lifetime has been exceeded.
+ * \li not_yet_valid - The credential is post dated and the time when 
+ *                     it becomes valid has not yet been reached.
+ * \li needs_validation - The credential is post-dated and although
+ *                        the time when it becomes valid has been reached
+ *                        it has not yet been validated.
+ * \li address_mismatch - The credential contains IP address(es) which do 
+ *                        not match the host's local address(es).
+ */
+enum kim_credential_state_enum {
+    kim_credentials_state_valid            = 0,
+    kim_credentials_state_expired          = 1,
+    kim_credentials_state_not_yet_valid    = 2,
+    kim_credentials_state_needs_validation = 3,
+    kim_credentials_state_address_mismatch = 4
+};
+
+/*!
+ * The state of a credential.  See #kim_credential_state_enum for
+ * possible values.
+ */
+typedef int kim_credential_state_t;
+    
+/*! @} */    
+    
+/*!
+ * \page kim_credential_overview KIM Credential Overview
+ *
+ * \section kim_credential_introduction Introduction
+ *
+ * A Kerberos credential (also called a "Kerberos ticket") is a time-limited  
+ * token issued by a KDC which authenticates the entity named by the credential's 
+ * client identity to the service named by the credential's service identity. 
+ *
+ * The kim_credential_t object contains a single Kerberos credential.  KIM credentials
+ * objects are always copies of credentials, not references to credentials
+ * stored in the cache collection.  Modifying credential objects in the ccache 
+ * collection will not change any existing KIM credential objects.
+ *
+ * KIM credential APIs are intended for applications and system 
+ * tools which manage credentials for the user.  They are not a substitute for
+ * krb5 and GSSAPI functions which obtain service credentials for the purpose
+ * of authenticating a client to an application server.
+ *
+ * \note Many of the APIs listed below have equivalent functions which
+ * operate on ccaches.  In most cases applications will want to use the
+ * ccache versions of these APIs since they automatically store any
+ * newly created credentials.  See \ref kim_ccache_overview for more 
+ * information.
+ *
+ *
+ * \section kim_credential_acquire_new Acquiring New Credentials
+ *
+ * KIM provides the #kim_credential_create_new() API for acquiring new
+ * credentials.  Credentials can either be obtained for a specific
+ * client identity or by specifying #KIM_IDENTITY_ANY to allow  
+ * the user to choose.  Typically callers of this API obtain the client
+ * identity using #kim_selection_hints_get_identity().  Depending on the 
+ * kim_options specified, #kim_credential_create_new() may present a 
+ * GUI or command line prompt to obtain information from the user.
+ *
+ * KIM provides the #kim_credential_create_from_keytab() to create credentials 
+ * using a keytab. A keytab is an on-disk copy of a client identity's secret 
+ * key.  Typically sites use keytabs for client identities that identify a 
+ * machine or service and protect the keytab with disk permissions.  Because 
+ * a keytab is sufficient to obtain credentials, keytabs will normally only 
+ * be readable by root, Administrator or some other privileged account.  
+ * Typically applications use credentials obtained from keytabs to obtain
+ * credentials for batch processes.  These keytabs and credentials are usually 
+ * for a special identity used for the batch process rather than a user
+ * identity.
+ *
+ *
+ * \section kim_credential_validate Validating Credentials
+ *
+ * A credential with a start time in the future (ie: after the issue date)
+ * is called a post-dated credential.  Because the KDC administrator may 
+ * wish to disable a identity, once the start time is reached, all post-dated
+ * credentials must be validated before they can be used.  Otherwise an
+ * attacker using a compromised account could acquire lots of post-dated 
+ * credentials to circumvent the acccount being disabled.
+ *
+ * KIM provides the #kim_credential_validate() API to validate a credential.
+ * Note that this API replaces the credential object with a new validated 
+ * credential object.  If you wish to store the new credential in the 
+ * ccache collection you must either call #kim_credential_store() on the 
+ * validated credential or use #kim_ccache_validate() instead.
+ * 
+ *
+ * \section kim_credential_renew Renewing Credentials
+ *
+ * A renewable credential can be used to obtain a new identical credential
+ * without resending secret information (such as a password) to the KDC.
+ * A credential may only be renewed during its renewal lifetime and while
+ * valid.
+ *
+ * KIM provides the #kim_credential_renew() API to renew a credential.
+ * Note that this API replaces the credential object with a new renewed 
+ * credential object.  If you wish to store the new credential in the 
+ * ccache collection you must either call #kim_credential_store() on the 
+ * renewed credential or use #kim_ccache_renew() instead.
+ *
+ *
+ * \section kim_credential_storing Storing Credentials in the Cache Collection
+ *
+ * KIM credential objects may be stored in the ccache collection using 
+ * #kim_credential_store().  This function runs any KIM authentication
+ * plugins on the credential and if the plugins return successfully, creates a 
+ * new ccache for the credential's client identity in the cache collection 
+ * and stores the credential in that ccache.  Any existing ccaches and credentials 
+ * for that client identity will be overwritten.   #kim_credential_store() may
+ * optionally return a kim_ccache_t object for the new ccache if you need to perform
+ * further operations on the new ccache.
+ *
+ * Most of the time if you plan to store the credentials you are manipulating, you
+ * should use one of KIM ccache APIs.  These functions perform the same operations
+ * except that they also call #kim_credential_store() any time the credential object
+ * changes.  See \ref kim_ccache_overview for more information.
+ *
+ *
+ * \section kim_credential_iterator_t Iterating over the Credentials in a CCache
+ *
+ * KIM provides a simple iterator API for iterating over the credentials
+ * in a ccache.  First, call #kim_credential_iterator_create() to obtain 
+ * an iterator for a ccache.  Then loop calling #kim_credential_iterator_next()
+ * until either you find the credential you are looking for or the API 
+ * returns a NULL credential, indicating that there are no more
+ * credentials in the ccache.  When you are done with the iterator, call
+ * #kim_credential_iterator_free().
+ *
+ * \note #kim_credential_iterator_next() returns credential objects which
+ * must be freed with #kim_credential_free() to avoid leaking memory.
+ *
+ *
+ * \section kim_credential_verify Verifying Credentials
+ *
+ * When a program acquires TGT credentials for the purpose of authenticating
+ * itself to the machine it is running on, it is insufficient for the machine 
+ * to assume that the caller is authorized just because it got credentials.  
+ * Instead, the credentials must be verified using a key the local machine.  
+ * The reason this is necessary is because an attacker can trick the  
+ * machine into obtaining credentials from any KDC, including malicious ones
+ * with the same realm name as the local machine's realm.  This exploit is 
+ * called the Zanarotti attack.  
+ *
+ * In order to avoid the Zanarotti attack, the local machine must authenticate
+ * the process in the same way an application server would authenticate a client.
+ * Like an application server, the local machine must have its own identity in 
+ * its realm and a keytab for that identity on its local disk.    However,
+ * rather than forcing system daemons to use the network-oriented calls in the 
+ * krb5 and GSS APIs, KIM provides the #kim_credential_verify() API to 
+ * verify credentials directly.  
+ * 
+ * The most common reason for using #kim_credential_verify() is user login.  
+ * If the local machine wants to use Kerberos to verify the username and password
+ * provided by the user, it must call #kim_credential_verify() on the credentials
+ * it obtains to make sure they are really from a KDC it trusts.  Another common
+ * case is a server which is only using Kerberos internally.  For example an
+ * LDAP or web server might use a username and password obtained over the network
+ * to get Kerberos credentials.  In order to make sure they aren't being tricked 
+ * into talking to the wrong KDC, these servers must also call 
+ * #kim_credential_verify().
+ * 
+ * The Zanarotti attack is only a concern if the act of accessing the machine 
+ * gives the process special access.  Thus a managed cluster machine with 
+ * Kerberos-authenticated networked home directories does not need to call 
+ * #kim_credential_verify().  Even though an attacker can log in as any user on   
+ * the cluster machine, the attacker can't actually access any of the user's data 
+ * or use any of their privileges because those are all authenticated via  
+ * Kerberized application servers (and thus require actually having credentials 
+ * for the real local realm).
+ *
+ * #kim_credential_verify() provides an option to 
+ * return success even if the machine's host key is not present.  This option 
+ * exists for sites which have a mix of different machines, some of which are  
+ * vulnerable to the Zanarotti attack and some are not.  If this option is used, 
+ * it is the responsiblity of the machine's maintainer to obtain a keytab
+ * for their machine if it needs one.
+ *
+ *
+ * \section kim_credential_properties Examining Credential Properties
+ * 
+ * \li #kim_credential_get_client_identity()
+ *     returns the credential's client identity.
+ *
+ * \li #kim_credential_get_service_identity() 
+ *     returns the credential's service identity.
+ *
+ * \li #kim_credential_is_tgt() 
+ *     returns whether the credential is a TGT (ie: "ticket-granting ticket").  TGTs are  
+ *     credentials for the krbtgt service: a service identity of the form "krbtgt/<REALM>@<REALM>".   
+ *     These credentials allow the entity named by the client identity to obtain  
+ *     additional service credentials without resending shared secrets (such as a password)
+ *     to the KDC. Kerberos uses TGTs to provide single sign-on authentication.
+ *
+ * \li #kim_credential_is_valid() 
+ *     returns whether the credential is valid and if not why the credential is not valid.
+ *
+ * \li #kim_credential_get_start_time() 
+ *     returns when the credential will become valid.  
+ *     Credentials may be "post-dated" which means that their lifetime starts sometime 
+ *     in the future.  Note that when a post-dated credential's start time is reached, 
+ *     the credential must be validated.  See \ref kim_credential_validate for more information.
+ *
+ * \li #kim_credential_get_expiration_time() 
+ *     returns when the credential will expire. 
+ *     Credentials are time limited by the lifetime of the credential.  While you can 
+ *     request a credential of any lifetime, the KDC limits the credential lifetime 
+ *     to a administrator-defined maximum.  Typically credential lifetime range from 10
+ *     to 21 hours.
+ *
+ * \li #kim_credential_get_renewal_expiration_time() 
+ *     returns when the credential will no longer be renewable. 
+ *     Valid credentials may be renewed up until their renewal expiration time.  
+ *     Renewing credentials acquires a fresh set of credentials with a full lifetime 
+ *     without resending secrets to the KDC (such as a password).  If credentials are 
+ *     not renewable, this function will return an error.
+ *
+ *
+ * See \ref kim_credential_reference and \ref kim_credential_iterator_reference for 
+ * information on specific APIs.
+ */
+
+/*!
+ * \defgroup kim_credential_iterator_reference KIM Credential Iterator Reference Documentation
+ * @{
+ */
+
+/*!
+ * \param out_credential_iterator on exit, a credential iterator object for \a in_ccache.
+ *                                Must be freed with kim_credential_iterator_free().
+ * \param in_ccache               a ccache object.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get a credential iterator to enumerate credentials in a ccache.
+ */
+
+kim_error_t kim_credential_iterator_create (kim_credential_iterator_t *out_credential_iterator,
+                                            kim_ccache_t               in_ccache);
+
+/*!
+ * \param in_credential_iterator a credential iterator object.
+ * \param out_credential         on exit, the next credential in the ccache iterated by 
+ *                               \a in_credential_iterator.   Must be freed with 
+ *                               kim_credential_free(). If there are no more credentials
+ *                               this argument will be set to NULL.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the next credential in a ccache.
+ */
+
+kim_error_t kim_credential_iterator_next (kim_credential_iterator_t  in_credential_iterator,
+                                          kim_credential_t          *out_credential);
+
+/*!
+ * \param io_credential_iterator a credential iterator object to be freed.  Set to NULL on exit.
+ * \brief Free memory associated with a credential iterator.
+ */
+void kim_credential_iterator_free (kim_credential_iterator_t *io_credential_iterator);
+
+/*!@}*/
+
+/*!
+ * \defgroup kim_credential_reference KIM Credential Reference Documentation
+ * @{
+ */
+
+/*!
+ * \param out_credential      on exit, a new credential object containing a newly acquired 
+ *                            initial credential.  Must be freed with kim_credential_free().
+ * \param in_client_identity  a client identity to obtain a credential for.   Specify NULL to 
+ *                            allow the user to choose the identity
+ * \param in_options          options to control credential acquisition. 
+ * \note Depending on the kim_options specified, #kim_credential_create_new() may 
+ * present a GUI or command line prompt to obtain information from the user. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Acquire a new initial credential.
+ * \sa kim_ccache_create_new
+ */
+kim_error_t kim_credential_create_new (kim_credential_t *out_credential,
+                                       kim_identity_t    in_client_identity,
+                                       kim_options_t     in_options);
+
+/*!
+ * \param out_credential  on exit, a new credential object containing an initial credential
+ *                        for \a in_identity obtained using \a in_keytab.  
+ *                        Must be freed with kim_credential_free().
+ * \param in_identity     a client identity to obtain a credential for.  Specify NULL for
+ *                        the first identity in the keytab.
+ * \param in_options      options to control credential acquisition. 
+ * \param in_keytab       a path to a keytab.  Specify NULL for the default keytab location. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Acquire a new initial credential from a keytab.
+ * \sa kim_ccache_create_from_keytab
+ */
+kim_error_t kim_credential_create_from_keytab (kim_credential_t *out_credential,
+                                               kim_identity_t    in_identity,
+                                               kim_options_t     in_options,
+                                               kim_string_t      in_keytab);
+
+/*!
+ * \param out_credential  on exit, a new credential object which is a copy of \a in_krb5_creds.  
+ *                        Must be freed with kim_credential_free().
+ * \param in_krb5_context the krb5 context used to create \a in_krb5_creds. 
+ * \param in_krb5_creds   a krb5 credential object. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Copy a credential from a krb5 credential object.
+ */
+kim_error_t kim_credential_create_from_krb5_creds (kim_credential_t *out_credential,
+                                                   krb5_context      in_krb5_context,
+                                                   krb5_creds       *in_krb5_creds);
+
+/*!
+ * \param out_credential  on exit, a new credential object which is a copy of \a in_credential.  
+ *                        Must be freed with kim_credential_free().
+ * \param in_credential   a credential object. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Copy a credential object.
+ */
+kim_error_t kim_credential_copy (kim_credential_t *out_credential,
+                                 kim_credential_t  in_credential);
+
+/*!
+ * \param in_credential    a credential object. 
+ * \param in_krb5_context  a krb5 context which will be used to create \a out_krb5_creds. 
+ * \param out_krb5_creds   on exit, a new krb5 creds object which is a copy of \a in_credential.  
+ *                         Must be freed with krb5_free_creds().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get a krb5 credentials object for a credential object.
+ */
+kim_error_t kim_credential_get_krb5_creds (kim_credential_t   in_credential,
+                                           krb5_context       in_krb5_context,
+                                           krb5_creds       **out_krb5_creds);
+
+/*!
+ * \param in_credential        a credential object. 
+ * \param out_client_identity  on exit, an identity object containing the client identity of   
+ *                             \a in_credential. Must be freed with kim_identity_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the client identity of a credential object.
+ */
+kim_error_t kim_credential_get_client_identity (kim_credential_t  in_credential,
+                                                kim_identity_t   *out_client_identity);
+
+/*!
+ * \param in_credential         a credential object. 
+ * \param out_service_identity  on exit, an identity object containing the service identity of   
+ *                              \a in_credential. Must be freed with kim_identity_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the service identity of a credential object.
+ */
+kim_error_t kim_credential_get_service_identity (kim_credential_t  in_credential,
+                                               kim_identity_t   *out_service_identity);
+
+/*!
+ * \param in_credential a credential object. 
+ * \param out_is_tgt    on exit, whether or not the credential is a TGT.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Check if a credential is a ticket granting ticket.
+ */
+kim_error_t kim_credential_is_tgt (kim_credential_t  in_credential,
+                                   kim_boolean_t     *out_is_tgt);
+
+/*!
+ * \param in_credential a credential object. 
+ * \param out_state     on exit, the state of the credential.  See #kim_credential_state_enum
+ *                      for the possible values of \a out_state.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Check the state of a credential (valid, expired, postdated, etc).
+ */
+kim_error_t kim_credential_get_state (kim_credential_t        in_credential,
+                                      kim_credential_state_t *out_state);
+
+/*!
+ * \param in_credential  a credential object. 
+ * \param out_start_time on exit, the time when \a in_credential becomes valid.
+ *                       May be in the past or future.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the time when the credentials become valid.
+ * \sa kim_ccache_get_start_time
+ */
+kim_error_t kim_credential_get_start_time (kim_credential_t  in_credential,
+                                           kim_time_t       *out_start_time);
+
+/*!
+ * \param in_credential       a credential object. 
+ * \param out_expiration_time on exit, the time when \a in_credential will expire.
+ *                            May be in the past or future.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the time when the credentials will expire.
+ * \sa kim_ccache_get_expiration_time
+ */
+kim_error_t kim_credential_get_expiration_time (kim_credential_t  in_credential,
+                                                kim_time_t       *out_expiration_time);
+
+/*!
+ * \param in_credential               a credential object. 
+ * \param out_renewal_expiration_time on exit, the time when \a in_credential will no longer 
+ *                                    be renewable. May be in the past or future.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the time when the credentials will no longer be renewable.
+ * \sa kim_ccache_get_renewal_expiration_time
+ */
+kim_error_t kim_credential_get_renewal_expiration_time (kim_credential_t  in_credential,
+                                                        kim_time_t       *out_renewal_expiration_time);
+
+
+/*!
+ * \param in_credential       a credential object. 
+ * \param in_client_identity  a client identity.
+ * \param out_ccache          on exit, a ccache object containing \a in_credential with the client  
+ *      		      identity \a in_client_identity.  Must be freed with kim_ccache_free().
+ *                            Specify NULL if you don't want this return value.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Store a credential in a ccache in the cache collection.
+ */
+kim_error_t kim_credential_store (kim_credential_t  in_credential,
+                                  kim_identity_t    in_client_identity,
+                                  kim_ccache_t     *out_ccache);
+
+/*!
+ * \param in_credential          a TGT credential to be verified. 
+ * \param in_service_identity    a service identity to look for in the keytab.  Specify 
+ *                               KIM_IDENTITY_ANY to use the default service identity
+ *                               (usually host/<host's FQDN>@<host's local realm>).
+ * \param in_keytab              a path to a keytab.  Specify NULL for the default keytab location. 
+ * \param in_fail_if_no_service_key whether or not the absence of a key for \a in_service_identity
+ *                                  in the host's keytab will cause a failure. 
+ * \note specifying FALSE for \a in_fail_if_no_service_key may expose the calling program to 
+ * the Zanarotti attack if the host has no keytab installed.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Verify a TGT credential.
+ * \sa kim_ccache_verify
+ */
+kim_error_t kim_credential_verify (kim_credential_t in_credential,
+                                   kim_identity_t   in_service_identity,
+                                   kim_string_t     in_keytab,
+                                   kim_boolean_t    in_fail_if_no_service_key);
+
+/*!
+ * \param io_credential  a TGT credential to be renewed.  On exit, the old credential  
+ *                       object will be freed and \a io_credential will be replaced 
+ *                       with a new renewed credential.  The new credential must be freed 
+ *                       with kim_credential_free().
+ * \param in_options     initial credential options.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Renew a TGT credential.
+ * \sa kim_ccache_renew
+ */
+kim_error_t kim_credential_renew (kim_credential_t *io_credential,
+                                  kim_options_t     in_options);
+
+/*!
+ * \param io_credential  a credential object to be validated. On exit, the old credential  
+ *                       object will be freed and \a io_credential will be replaced 
+ *                       with a new validated credential.  The new credential must be freed 
+ *                       with kim_credential_free().
+ * \param in_options     initial credential options.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Validate a TGT credential.
+ * \sa kim_ccache_validate
+ */
+kim_error_t kim_credential_validate (kim_credential_t *io_credential,
+                                     kim_options_t     in_options);
+
+/*!
+ * \param io_credential the credential object to be freed.  Set to NULL on exit.
+ * \brief Free memory associated with a credential object.
+ */
+void kim_credential_free (kim_credential_t *io_credential);
+
+/*!@}*/
+
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* KIM_CREDENTIAL_H */
diff --git a/src/include/kim/kim_error.h b/src/include/kim/kim_error.h
new file mode 100644
index 0000000000..8a6a4d576a
--- /dev/null
+++ b/src/include/kim/kim_error.h
@@ -0,0 +1,120 @@
+/*
+ * 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 "as is" without express
+ * or implied warranty.
+ */
+
+#ifndef KIM_ERROR_H
+#define KIM_ERROR_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <kim/kim_types.h>
+#include <kim/kim_error_code.h>
+
+/*!
+ * \ingroup kim_types_reference
+ * The kim_error_t returned when no error occurred. 
+ * Does not need to be freed with kim_error_free().
+ */
+#define KIM_NO_ERROR                  ((kim_error_t) NULL)
+
+/*!
+ * \ingroup kim_types_reference
+ * The kim_error_code_t for KIM_NO_ERROR. 
+ */
+#define KIM_NO_ERROR_ECODE            ((kim_error_code_t) 0)
+    
+/*!
+ * \page kim_error_overview KIM Error Overview
+ *
+ * An error object.  Error objects consist of a machine readable error code for 
+ * for programmatic error handling and a string describing the error.  All KIM APIs
+ * return kim_errors with the exception of memory deallocation functions and the
+ * kim_error_t APIs which return pieces of a kim_error_t object.  
+ *
+ * Functions which return successfully will return #KIM_NO_ERROR (NULL).  Because
+ * #KIM_NO_ERROR does not need to be freed, you may use if-ladders or goto-style 
+ * error handling when calling the KIM APIs.  In addition, kim_error_free() may 
+ * be called on #KIM_NO_ERROR.
+ *
+ * \note Certain kim_error_t objects are preallocated by the libraries avoid 
+ * exacerbating existing problems while trying to report an error.  For example,
+ * the out of memory error object is preallocated.  It is safe to call 
+ * #kim_error_free() on these errors, although the function may not actually free
+ * the object.
+ *
+ * By providing an error object rather than a numeric code, the KIM APIs can 
+ * tailor error strings to the circumstances of the error.  So rather than returning 
+ * error strings like "Client not found in Kerberos database", we can report 
+ * "'user@REALM' not found in Kerberos database" while still providing the machine
+ * readable error KRB5KDC_ERR_C_PRINCIPAL_UNKNOWN.
+ *
+ * See \ref kim_error_reference for information on specific APIs.
+ */
+
+/*!
+ * \defgroup kim_error_reference KIM Error Reference Documentation
+ * @{
+ */
+
+/*!
+ * \param out_error on exit, a new error object which is a copy of \a in_error.  
+ *      	    Must be freed with kim_error_free().
+ * \param in_error  the error to copy.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Copy an error.
+ */
+kim_error_t kim_error_copy (kim_error_t *out_error,
+                            kim_error_t  in_error);
+
+/*!
+ * \param in_error an error object.
+ * \return On success, a machine-readable error code describing the error represented 
+ *         by \a in_error. On failure, #KIM_PARAMETER_ECODE.
+ * \brief Get a numerical error code for an error.
+ */
+kim_error_code_t kim_error_get_code (kim_error_t in_error);
+
+/*!
+ * \param in_error an error object.
+ * \return On success, a human-readable error string describing the error represented 
+ *         by \a in_error.  On failure, NULL, indicating that the kim_error_t object was
+ *         invalid.
+ * \brief Get a text description of an error.
+ */
+kim_string_t kim_error_get_display_string (kim_error_t in_error);
+
+/*!
+ * \param io_error the error object to be freed.  Set to NULL on exit.
+ * \brief Free memory associated with an error.
+ */
+void kim_error_free (kim_error_t *io_error);
+
+/*!@}*/
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* KIM_ERROR_H */
diff --git a/src/include/kim/kim_identity.h b/src/include/kim/kim_identity.h
new file mode 100644
index 0000000000..9ee7fc00ec
--- /dev/null
+++ b/src/include/kim/kim_identity.h
@@ -0,0 +1,307 @@
+/*
+ * 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 "as is" without express
+ * or implied warranty.
+ */
+
+#ifndef KIM_IDENTITY_H
+#define KIM_IDENTITY_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <kim/kim_types.h>
+#include <krb5.h>
+#include <gssapi/gssapi.h>
+    
+/*!
+ * \ingroup kim_types_reference
+ * Constant to specify any Kerberos identity is acceptable.
+ */
+#define KIM_IDENTITY_ANY ((kim_identity_t) NULL)
+    
+/*!
+ * \page kim_identity_overview KIM Identity Overview
+ *
+ * \section kim_identity_introduction 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 '\'. 
+ *
+ *
+ * \section kim_identity_create_display 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:
+ *
+ * \li #kim_identity_create_from_components() creates an identity object from a list of components.  
+ * \li #kim_identity_get_number_of_components() returns the number of components in an identity object.
+ * \li #kim_identity_get_component_at_index() return a component of an identity object.
+ * \li #kim_identity_get_realm() returns the identity's realm.
+ *
+ * \li #kim_identity_create_from_string() generates an identity object from an escaped string representation.
+ * \li #kim_identity_get_string() returns the identity's escaped string representation.
+ * \li #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().
+ *
+ * \li #kim_identity_create_from_krb5_principal() generates an identity object from a krb5_principal object.
+ * \li #kim_identity_get_krb5_principal() returns a krb5_principal object for an identity object.
+ *
+ * \li #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().
+ *
+ *
+ * \section kim_identity_selection 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 \ref kim_selection_hints_overview
+ * for more information.
+ * 
+ *
+ * \section kim_identity_password 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 \ref kim_identity_reference for information on specific APIs.
+ */
+
+/*!
+ * \defgroup kim_identity_reference KIM Identity Reference Documentation
+ * @{
+ */
+
+/*!
+ * \param out_identity  on exit, a new identity object. Must be freed with kim_identity_free().
+ * \param in_string     a string representation of a Kerberos identity.  
+ *                      Special characters such as '/' and '@' must be escaped with '\'.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Create a identity from a string.
+ */
+kim_error_t kim_identity_create_from_string (kim_identity_t *out_identity,
+                                             kim_string_t    in_string);
+
+/*!
+ * \param out_identity     on exit, a new identity object.  Must be freed with kim_identity_free().
+ * \param in_realm         a string representation of a Kerberos realm. 
+ * \param in_1st_component a string representing the first component of the identity.
+ * \param ...              zero or more strings of type kim_string_t representing additional components  
+ *                         of the identity followed by a terminating NULL.  Components will be assembled in  
+ *                         order (ie: the 4th argument to kim_identity_create_from_components() will be  
+ *                         the 2nd component of the identity).
+ * \note The last argument must be a NULL or kim_identity_create_from_components() may crash.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Create a identity from a realm and component strings.
+ */
+kim_error_t kim_identity_create_from_components (kim_identity_t *out_identity,
+                                                 kim_string_t    in_realm, 
+                                                 kim_string_t    in_1st_component,
+                                                 ...);
+
+/*!
+ * \param out_identity      on exit, a new identity object which is a copy of \a in_krb5_principal.  
+ *                          Must be freed with kim_identity_free().
+ * \param in_krb5_context   the krb5 context used to create \a in_krb5_principal.
+ * \param in_krb5_principal a krb5 principal object. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Create an identity object from a krb5_principal.
+ */
+kim_error_t kim_identity_create_from_krb5_principal (kim_identity_t *out_identity,
+                                                     krb5_context    in_krb5_context,
+                                                     krb5_principal  in_krb5_principal);
+
+/*!
+ * \param out_identity  on exit, a new identity object which is a copy of \a in_identity.  
+ *                      Must be freed with kim_identity_free().
+ * \param in_identity  an identity object. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Copy an identity object.
+ */
+kim_error_t kim_identity_copy (kim_identity_t *out_identity,
+                               kim_identity_t  in_identity);
+
+
+/*!
+ * \param in_identity             an identity object.
+ * \param in_compare_to_identity  an identity object.
+ * \param out_comparison          on exit, a comparison of \a in_identity and 
+ *                                \a in_compare_to_identity which determines whether
+ *                                or not the two identities are equivalent and their
+ *                                sort order (for display to the user) if they are not.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Compare identity objects for equivalency.
+ */
+kim_error_t kim_identity_compare (kim_identity_t    in_identity,
+                                  kim_identity_t    in_compare_to_identity,
+                                  kim_comparison_t *out_comparison);
+/*!
+ * \param in_identity  an identity object. 
+ * \param out_string   on exit, a string representation of \a in_identity.  
+ *                     Must be freed with kim_string_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the string representation of a identity.
+ * \note  Special characters such as '@' and '/' will be escaped with '\'.
+ */
+kim_error_t kim_identity_get_string (kim_identity_t   in_identity,
+                                     kim_string_t    *out_string);
+
+
+/*!
+ * \param in_identity        an identity object. 
+ * \param out_display_string on exit, a string representation of \a in_identity appropriate for
+ *                           display to the user.  Must be freed with kim_string_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get a human-readable string representation of an identity.
+ * \note Special characters such as '/' and '@' are \em not escaped with '\'.  As a result the
+ *        string returned from this function cannot be used with kim_identity_create_from_string()
+ *        because it does not uniquely specify a principal.
+ *        The result of this function should \em only be used to display to the user.
+ */
+kim_error_t kim_identity_get_display_string (kim_identity_t   in_identity,
+                                             kim_string_t    *out_display_string);
+
+/*!
+ * \param in_identity     an identity object. 
+ * \param out_realm_string on exit, a string representation of \a in_identity's realm.
+ *                         Must be freed with kim_string_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the realm string of an identity.
+ */
+kim_error_t kim_identity_get_realm (kim_identity_t  in_identity,
+                                    kim_string_t   *out_realm_string);
+
+/*!
+ * \param in_identity             an identity object. 
+ * \param out_number_of_components on exit the number of components in \a in_identity.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the number of components of an identity.
+ */
+kim_error_t kim_identity_get_number_of_components (kim_identity_t  in_identity,
+                                                   kim_count_t    *out_number_of_components);
+
+/*!
+ * \param in_identity          an identity object.
+ * \param in_index             the index of the desired component.  Component indexes start at 0.
+ * \param out_component_string on exit, a string representation of the component in \a in_identity 
+ *                             specified by \a in_index.  Must be freed with kim_string_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the Nth component of an identity.
+ */
+kim_error_t kim_identity_get_component_at_index (kim_identity_t  in_identity,
+                                                 kim_count_t     in_index,
+                                                 kim_string_t   *out_component_string);
+
+/*!
+ * \param in_identity        an identity object.
+ * \param in_krb5_context    a krb5 context object.  
+ * \param out_krb5_principal on exit, a krb5_principal representation of \a in_identity
+ *                           allocated with \a in_krb5_context. Must be freed with 
+ *                           krb5_free_principal() using \a in_krb5_context.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the krb5_principal representation of an identity.
+ */
+kim_error_t kim_identity_get_krb5_principal (kim_identity_t  in_identity,
+                                             krb5_context    in_krb5_context,
+                                             krb5_principal *out_krb5_principal);
+
+/*!
+ * \param in_identity   an identity object.
+ * \param out_gss_name  on exit, a gss_name_t representation of \a in_identity.
+ *                      Must be freed with gss_release_name().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the gss_name_t representation of an identity.
+ */
+kim_error_t kim_identity_get_gss_name (kim_identity_t  in_identity,
+                                       gss_name_t     *out_gss_name);
+
+/*!
+ * \param in_identity  an identity object whose password will be changed.
+ * \param in_options   initial credential options to be used if a new credential is obtained.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Change the password for an identity.
+ * \note kim_identity_change_password() will acquire a temporary credential to change 
+ * the password.  It uses the \a in_options structure to obtain information about the desired 
+ * prompter and current password.  
+ */
+kim_error_t kim_identity_change_password (kim_identity_t  in_identity,
+                                          kim_options_t   in_options);
+
+/*!
+ * \param in_identity  an identity object whose password will be changed.
+ * \param in_options   initial credential options to be used if a new credential is obtained.
+ * \param in_new_password a string representation of the identity's new password.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Change the password for an identity to a caller-provided new password.
+ * \note kim_identity_change_password_with_passwords() will acquire a temporary credential 
+ * to change the password. It uses the \a in_options structure to obtain information about   
+ * the desired prompter and current password.  
+ */
+kim_error_t kim_identity_change_password_to_password (kim_identity_t in_identity,
+                                                      kim_options_t   in_options,
+                                                      kim_string_t    in_new_password);
+
+/*!
+ * \param io_identity the identity object to be freed.  Set to NULL on exit.
+ * \brief Free memory associated with an identity.
+ */
+void kim_identity_free (kim_identity_t *io_identity);
+
+/*!@}*/
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* KIM_IDENTITY_H */
diff --git a/src/include/kim/kim_options.h b/src/include/kim/kim_options.h
new file mode 100644
index 0000000000..ebdb791e18
--- /dev/null
+++ b/src/include/kim/kim_options.h
@@ -0,0 +1,637 @@
+/*
+ * 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 "as is" without express
+ * or implied warranty.
+ */
+
+#ifndef KIM_OPTIONS_H
+#define KIM_OPTIONS_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <kim/kim_types.h>
+
+/*!
+ * \addtogroup kim_types_reference
+ * @{
+ */
+
+/*!
+ * Specifies the user's default options.
+ */
+#define KIM_OPTIONS_DEFAULT           ((kim_options_t) NULL)
+
+/*!
+ * Specifies that credentials should be valid immediately.
+ */
+#define KIM_OPTIONS_START_IMMEDIATELY ((kim_time_t) 0)
+
+/*!
+ * The type of prompt which needs to be displayed.
+ * This value determines what type of user interface is displayed.
+ * See \ref kim_options_custom_prompt_callback for more information.
+ */
+typedef uint32_t kim_prompt_type_t;
+
+enum kim_prompt_type_enum {
+    kim_prompt_type_password = 0,
+    kim_prompt_type_challenge = 1
+};
+
+/*!
+ * The prompt callback used to display a prompt to the user.
+ * See \ref kim_options_custom_prompt_callback for more information.
+ */
+typedef kim_error_code_t (*kim_prompt_callback_t) (kim_options_t       *io_options, 
+                                                   kim_prompt_type_t    in_type,
+                                                   kim_string_t         in_title,
+                                                   kim_string_t         in_message,
+                                                   kim_string_t         in_description,
+                                                   void               **out_reply);
+
+/*!
+ * The default prompt callback.
+ * See \ref kim_options_custom_prompt_callback for more information.
+ */
+kim_error_code_t kim_prompt_callback_default (kim_options_t       *io_options, 
+                                              kim_prompt_type_t    in_type,
+                                              kim_string_t         in_title,
+                                              kim_string_t         in_message,
+                                              kim_string_t         in_description,
+                                              void               **out_reply);
+
+/*!
+ * The graphical prompt callback.
+ * See \ref kim_options_custom_prompt_callback for more information.
+ */
+kim_error_code_t kim_prompt_callback_gui (kim_options_t       *io_options, 
+                                          kim_prompt_type_t    in_type,
+                                          kim_string_t         in_title,
+                                          kim_string_t         in_message,
+                                          kim_string_t         in_description,
+                                          void               **out_reply);
+
+/*!
+ * The command line prompt callback.
+ * See \ref kim_options_custom_prompt_callback for more information.
+ */
+kim_error_code_t kim_prompt_callback_cli (kim_options_t       *io_options, 
+                                          kim_prompt_type_t    in_type,
+                                          kim_string_t         in_title,
+                                          kim_string_t         in_message,
+                                          kim_string_t         in_description,
+                                          void               **out_reply);
+
+/*!
+ * The prompt callback which always returns an error.
+ * Use to turn off prompting entirely.
+ * \note Using this callback may prevent the user from authenicating.
+ * See \ref kim_options_custom_prompt_callback for more information.
+ */
+kim_error_code_t kim_prompt_callback_none (kim_options_t       *io_options, 
+                                           kim_prompt_type_t    in_type,
+                                           kim_string_t         in_title,
+                                           kim_string_t         in_message,
+                                           kim_string_t         in_description,
+                                           void               **out_reply);
+
+/*! @} */
+
+/*!
+ * \page kim_options_overview KIM Options Overview
+ *
+ * \section kim_options_introduction Introduction
+ *
+ * Kerberos Identity Management Options (kim_options_t) allows you to control how
+ * the Kerberos library obtains credentials.  When the options structure is initialized with
+ * #kim_options_create(), each option is filled in with a default value which can then be modified
+ * with the kim_options_set_*() APIs.  If you only want to use the default values, you may pass 
+ * #KIM_OPTIONS_DEFAULT into any KIM function that takes a kim_options_t.
+ * 
+ * KIM options fall into two major categories: options for controlling how credentials are 
+ * acquired and options for controlling what properties the newly acquired credentials will have:
+ *
+ * \section kim_options_credential_acquisition Options for Controlling Credential Acquisition
+ * 
+ * In order to acquire credentials, Kerberos needs to obtain one or more secrets from the user.
+ * These secrets may be a certificate, password, SecurID pin, or information from a smart card.  
+ * If obtaining the secret requires interaction with the user, the Kerberos libraries call a
+ * "prompter callback" to display a dialog or command line prompt to request information from
+ * the user.  If you want to provide your own custom dialogs or command line prompts, 
+ * the KIM APIs provide a mechanism for replacing the default prompt callbacks with your own.  
+ *
+ * \subsection kim_options_custom_prompt_callback Providing a Custom Prompt Callback
+ *
+ * All secrets are obtained from the user through a #kim_prompt_callback_t.  By default, 
+ * options use #kim_prompt_callback_default, which presents an expanding dialog to request
+ * information from the user, or if no graphical access is available, a command line prompt.
+ * 
+ * KIM also provides three other callbacks: #kim_prompt_callback_gui only presents
+ * a dialog and returns an error if there is no graphical access. #kim_prompt_callback_cli
+ * only presents a command line interface and returns an error if there is no controlling
+ * terminal available.  #kim_prompt_callback_none always returns an error.
+ *
+ * Using #kim_options_set_prompt_callback(), you can change the prompt callback to one of 
+ * the above callbacks or a callback you have defined yourself.  Callbacks are called in a
+ * loop, one for each prompt.  Because network traffic may occur between calls to the prompt
+ * callback, your prompt interface should support time passing between calls to the prompter.  
+ * If you are defining a callback yourself, you should also set your own options data with 
+ * #kim_options_set_data() for storing state between calls.  Options data is a caller
+ * defined pointer value -- the Kerberos libaries make no use of it.
+ *
+ * \subsection kim_options_preset_prompts Prefetching Prompt Responses
+ * 
+ * Sometimes you may have already collected some of the information needed to acquire 
+ * Kerberos credentials.  Rather than creating a prompt callback, you may also prefetch 
+ * responses to the options directly with #kim_options_set_prompt_response().  Once you 
+ * have associated your response with a given prompt type, the Kerberos libraries will 
+ * use this response for the first prompt of that type rather than calling the prompt 
+ * callback to obtain it.
+ *
+ * Note that even if you prefetch responses, the prompt callback may still be called if
+ * you did not provide all the information required for the identity.  You may specify 
+ * the #kim_prompt_callback_none prompt callback to prevent prompting from occuring entirely,
+ * however, doing so will tie your application to a particular Kerberos configuration.  
+ * For example, if your application assumes that all identities only require a password, 
+ * it will not be able to acquire credentials at sites using SecurID pins.  
+ *
+ * 
+ * \section kim_options_credential_properties Options for Controlling Credential Properties
+ *
+ * Kerberos credentials have a number of different properties which can be requested
+ * when credentials are acquired.  These properties control when and for how long the 
+ * credentials are valid and what you can do with them.  
+ 
+ * Note that setting these properties in the KIM options only changes what the Kerberos 
+ * libraries \em request from the KDC.  The KDC itself may choose not to honor your 
+ * requested properties if they violate the site security policy.  For example, most sites 
+ * place an upper bound on how long credentials may be valid.  If you request a credential 
+ * lifetime longer than this upper bound, the KDC may return credentials with a shorter 
+ * lifetime than you requested.
+ *
+ * \subsection kim_options_lifetimes Credential Lifetime
+ *
+ * Kerberos credentials have start time and a lifetime during which they are valid.  
+ * Once the lifetime has passed, credentials "expire" and can no longer be used.  
+ *
+ * The requested credential start time can be set with #kim_options_set_start_time() 
+ * and examined with #kim_options_get_start_time().  The requested credential
+ * lifetime can be set with #kim_options_set_lifetime() and examined with
+ * #kim_options_get_lifetime().
+ * 
+ * \subsection kim_options_renewable Renewable Credentials
+ *
+ * Credentials with very long lifetimes are more convenient since the user does not
+ * have authenticate as often.  Unfortunately they are also a higher security 
+ * risk: if credentials are stolen they can be used until they expire.
+ * Credential renewal exists to compromise between these two conflicting goals.
+ *
+ * Renewable credentials are TGT credentials which can be used to obtain new
+ * TGT credentials without reauthenticating.  By regularly renewing credentials
+ * the KDC has an opportunity to check to see if the client's credentials have been
+ * reported stolen and refuse to renew them.  Renewable credentials have a "renewal
+ * lifetime" during which credentials can be renewed.  This lifetime is relative
+ * to the original credential start time.  If credentials are renewed shortly before
+ * the end of the renewal lifetime, their lifetime will be capped to the end of the
+ * renewal lifetime.
+ *
+ * Note that credentials must be valid to be renewed and therefore may not be 
+ * an appropriate solution for all use cases.  Sites which use renewable
+ * credentials often create helper processes running as the user which will 
+ * automatically renew the user's credentials when they get close to expiration.
+ * 
+ * Use #kim_options_set_renewable() to change whether or not the Kerberos libraries
+ * request renewable credentials and #kim_options_get_renewable() to find out the 
+ * current setting.  Use #kim_options_set_renewal_lifetime() to change the requested
+ * renewal lifetime and #kim_options_get_renewal_lifetime() to find out the current 
+ * value.
+ *
+ * \subsection kim_options_addressless Addressless Credentials
+ *
+ * Traditionally Kerberos used the host's IP address as a mechanism to restrict 
+ * the user's credentials to a specific host, thus making it harder to use stolen 
+ * credentials.  When authenticating to a remote service with credentials containing
+ * addresses, the remote service verifies that the client's IP address is one of the 
+ * addresses listed in the credential.  Unfortunately, modern network technologies 
+ * such as NAT rewrite the IP address in transit, making it difficult to use 
+ * credentials with addresses in them.  As a result, most Kerberos sites now obtain 
+ * addressless credentials. 
+ *
+ * Use #kim_options_set_addressless() to change whether or not the Kerberos libraries
+ * request addressless credentials.  Use #kim_options_get_addressless() to find out the 
+ * current setting.
+ *
+ * \subsection kim_options_forwardable Forwardable Credentials
+ *
+ * Forwardable credentials are TGT credentials which can be forwarded to a service 
+ * you have authenticated to.  If the credentials contain IP addresses, the addresses 
+ * are changed to reflect the service's IP address.  Credential forwarding is most 
+ * commonly used for Kerberos-authenticated remote login services.  By forwarding 
+ * TGT credentials through the remote login service, the user's credentials will 
+ * appear on the remote host when the user logs in.  
+ *
+ * The forwardable flag only applies to TGT credentials.
+ *
+ * Use #kim_options_set_forwardable() to change whether or not the Kerberos libraries
+ * request forwardable credentials.  Use #kim_options_get_forwardable() to find out the 
+ * current setting.
+ *
+ * \subsection kim_options_proxiable Proxiable Credentials
+ *
+ * Proxiable credentials are similar to forwardable credentials except that instead of
+ * forwarding the a TGT credential itself, a service credential is forwarded
+ * instead.  Using proxiable credentials, a user can permit a service to perform
+ * a specific task as the user using one of the user's service credentials.  
+ *
+ * Like forwardability, the proxiable flag only applies to TGT credentials.  Unlike
+ * forwarded credentials, the IP address of proxiable credentials are not modified for  
+ * the service when being proxied.  This can be solved by also requesting addressless
+ * credentials.
+ *
+ * Use #kim_options_set_proxiable() to change whether or not the Kerberos libraries
+ * request proxiable credentials.  Use #kim_options_get_proxiable() to find out the 
+ * current setting.
+ *
+ * \subsection kim_options_service_name Service Name
+ *
+ * Normally users acquire TGT credentials (ie "ticket granting tickets") and then 
+ * use those credentials to acquire service credentials.  This allows Kerberos to 
+ * provide single sign-on while still providing mutual authentication to services.  
+ * However, sometimes you just want an initial credential for a service.  KIM 
+ * options allows you to set the service name with 
+ * #kim_options_set_service_name() and query it with 
+ * #kim_options_get_service_name().
+ *
+ * See \ref kim_options_reference for information on specific APIs.
+ */ 
+
+/*!
+ * \defgroup kim_options_reference KIM Options Reference Documentation
+ * @{
+ */
+
+/*!
+ * \param out_options on exit, a new options object.  Must be freed with kim_options_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Create new options with default values.
+ */
+kim_error_t kim_options_create (kim_options_t *out_options);
+
+/*!
+ * \param out_options on exit, a new options object which is a copy of \a in_options.  
+ *                    Must be freed with kim_options_free().
+ * \param in_options  a options object. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Copy options.
+ */
+kim_error_t kim_options_copy (kim_options_t *out_options,
+                              kim_options_t  in_options);
+
+/*!
+ * \param io_options         an options object to modify.
+ * \param in_prompt_callback a prompt callback function.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the prompt callback for obtaining information from the user.
+ * \par Default value
+ * #kim_prompt_callback_default
+ * \sa kim_options_get_prompt_callback()
+ */
+kim_error_t kim_options_set_prompt_callback (kim_options_t         io_options,
+                                             kim_prompt_callback_t in_prompt_callback);
+
+/*!
+ * \param in_options          an options object.
+ * \param out_prompt_callback on exit, the prompt callback specified by in_options. 
+ *                            Does not need to be freed but may become invalid when 
+ *                            \a in_options is freed.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the prompt callback for obtaining information from the user.
+ * \par Default value
+ * #kim_prompt_callback_default
+ * \sa kim_options_set_prompt_callback()
+ */
+kim_error_t kim_options_get_prompt_callback (kim_options_t          in_options,
+                                             kim_prompt_callback_t *out_prompt_callback);
+
+/*!
+ * \param io_options  an options object to modify.
+ * \param in_data     a pointer to caller-specific data.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set caller-specific data for use in library callbacks.
+ * \note This option can be used by the caller to store a pointer to data needed when handling a 
+ *       callback.  The KIM library does not use this options data in any way.
+ * \par Default value
+ * NULL (no data is set by default)
+ * \sa kim_options_get_data()
+ */
+kim_error_t kim_options_set_data (kim_options_t  io_options,
+                                  const void    *in_data);
+
+/*!
+ * \param in_options  an options object.
+ * \param out_data    on exit, the pointer to caller specific data specified by in_options.
+ *                    Does not need to be freed but may become invalid when \a in_options is freed.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get caller-specific data for use in library callbacks.
+ * \note This option can be used by the caller to store a pointer to data needed when handling a 
+ *       callback.  The KIM library does not use this options data in any way.
+ * \par Default value
+ * NULL (no data is set by default)
+ * \sa kim_options_set_data()
+ */
+kim_error_t kim_options_get_data (kim_options_t   in_options,
+                                  const void    **out_data);
+
+/*!
+ * \param io_options     an options object to modify.
+ * \param in_prompt_type a type of prompt.
+ * \param in_response    a response to prompts of \a in_prompt_type.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set a response for a prompt for use when acquiring credentials.
+ * \note Each response only overrides the first prompt of a given prompt type.  If multiple
+ * prompts of the same type are required, or if a prompt of a different type is requested, 
+ * the prompt callback will be called to obtain user input.  If you want to turn off prompting 
+ * entirely, call #kim_options_set_prompt_callback() with #kim_prompt_callback_none.
+ * \par Default value
+ * NULL (no response is set by default)
+ * \sa kim_options_get_prompt_response()
+ */
+kim_error_t kim_options_set_prompt_response (kim_options_t     io_options,
+                                             kim_prompt_type_t in_prompt_type,
+                                             void             *in_response);
+
+/*!
+ * \param in_options     an options object.
+ * \param in_prompt_type a type of prompt.
+ * \param out_response   on exit, the response to prompts of type \a in_prompt_type specified 
+ *                       by \a in_options.  Does not need to be freed but may become invalid
+ *                       when \a in_options is freed.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the response for a prompt for use when acquiring credentials.
+ * \note Each response only overrides the first prompt of a given prompt type.  If multiple
+ * prompts of the same type are required, or if a prompt of a different type is requested, 
+ * the prompt callback will be called to obtain user input.  If you want to turn off prompting 
+ * entirely, call #kim_options_set_prompt_callback() with #kim_prompt_callback_none.
+ * \par Default value
+ * NULL (no response is set by default)
+ * \sa kim_options_set_prompt_response()
+ */
+kim_error_t kim_options_get_prompt_response (kim_options_t       in_options,
+                                             kim_prompt_type_t   in_prompt_type,
+                                             void              **out_response);
+
+/*!
+ * \param io_options    an options object to modify.
+ * \param in_start_time a start date (in seconds since January 1, 1970).  Set to  
+ *                      #KIM_OPTIONS_START_IMMEDIATELY for the acquired credential to be valid 
+ *                      immediately.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the date when a credential should become valid.
+ * \note When using a start time in the future, once the start time has been reached the credential 
+ *       must be validated before it can be used. 
+ * \par Default value
+ * 0, indicating "now".  The credential will be valid immediately.
+ * \sa kim_options_get_start_time(), kim_credential_validate(), kim_ccache_validate(), kim_identity_validate()
+ */
+kim_error_t kim_options_set_start_time (kim_options_t io_options,
+                                        kim_time_t    in_start_time);
+
+/*!
+ * \param in_options     an options object.
+ * \param out_start_time on exit, the start date (in seconds since January 1, 1970) specified by 
+ *                       \a in_options. #KIM_OPTIONS_START_IMMEDIATELY indicates the credential
+ *                       will be valid immediately.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the date when a credential should become valid.
+ * \note When using a start time in the future, once the start time has been reached the credential 
+ *       must be validated before it can be used.
+ * \par Default value
+ * 0, indicating "now".  The credential will be valid immediately.
+ * \sa kim_options_set_start_time(), kim_credential_validate(), kim_ccache_validate(), kim_identity_validate()
+ */
+kim_error_t kim_options_get_start_time (kim_options_t  in_options,
+                                        kim_time_t    *out_start_time);
+
+/*!
+ * \param io_options  an options object to modify.
+ * \param in_lifetime a lifetime duration (in seconds).
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the duration during which a credential should be valid.
+ * \note KDCs have a maximum allowed lifetime per identity (usually 10 to 21 hours).
+ *       As a result the credential will actually have a lifetime which is the minimum of
+ *       \a in_lifetime and the KDC's maximum allowed lifetime.
+ * \sa kim_options_get_lifetime()
+ * \par Default value
+ * Read from the user's preferences and the Kerberos configuration. 10 hours if unspecified.
+ */
+kim_error_t kim_options_set_lifetime (kim_options_t  io_options,
+                                      kim_lifetime_t in_lifetime);
+
+/*!
+ * \param in_options   an options object.
+ * \param out_lifetime on exit, the lifetime duration (in seconds) specified in \a in_options.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the duration during which an acquired credential should be valid.
+ * \note KDCs have a maximum allowed lifetime per identity (usually 10 to 21 hours).
+ *       As a result the credential will actually have a lifetime which is the minimum of
+ *       \a in_lifetime and the KDC's maximum allowed lifetime.
+ * \par Default value
+ * Read from the user's preferences and the Kerberos configuration. 10 hours if unspecified.
+ * \sa kim_options_set_lifetime()
+ */
+kim_error_t kim_options_get_lifetime (kim_options_t   in_options,
+                                      kim_lifetime_t *out_lifetime);
+
+/*!
+* \param io_options    an options object to modify.
+ * \param in_renewable a boolean value indicating whether or not to request a renewable 
+ *                     credential.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set whether or not to request a renewable credential.
+ * \par Default value
+ * Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
+ * \sa kim_options_get_renewable()
+ */
+kim_error_t kim_options_set_renewable (kim_options_t io_options,
+                                       kim_boolean_t in_renewable);
+
+/*!
+* \param in_options     an options object.
+ * \param out_renewable on exit, a boolean value indicating whether or \a in_options will 
+ *                      request a renewable credential.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get whether or not to request a renewable credential.
+ * \par Default value
+ * Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
+ * \sa kim_options_set_renewable()
+ */
+kim_error_t kim_options_get_renewable (kim_options_t  in_options,
+                                       kim_boolean_t *out_renewable);
+
+/*!
+ * \param io_options          an options object to modify.
+ * \param in_renewal_lifetime a renewal lifetime duration (in seconds).
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the duration during which a valid credential should be renewable.
+ * \note KDCs have a maximum allowed renewal lifetime per identity (usually 10 to 21 hours).
+ *       As a result the credential will actually have a lifetime which is the minimum of
+ *       \a in_lifetime and the KDC's maximum allowed lifetime.
+ * \par Default value
+ * Read from the user's preferences and the Kerberos configuration. 7 days if unspecified.
+ * \sa kim_options_get_renewal_lifetime(), kim_identity_renew(), kim_credential_renew(), kim_ccache_renew()
+ */
+kim_error_t kim_options_set_renewal_lifetime (kim_options_t  io_options,
+                                              kim_lifetime_t in_renewal_lifetime);
+
+/*!
+ * \param in_options   an options object.
+ * \param out_renewal_lifetime on exit, the renewal lifetime duration (in seconds) specified  
+ *                             in \a in_options.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the duration during which a valid credential should be renewable.
+ * \note KDCs have a maximum allowed lifetime per identity (usually 10 to 21 hours).
+ *       As a result the credential will actually have a lifetime which is the minimum of
+ *       \a in_lifetime and the KDC's maximum allowed lifetime.
+ * \par Default value
+ * Read from the user's preferences and the Kerberos configuration. 7 days if unspecified.
+ * \sa kim_options_set_renewal_lifetime(), kim_identity_renew(), kim_credential_renew(), kim_ccache_renew()
+ */
+kim_error_t kim_options_get_renewal_lifetime (kim_options_t   in_options,
+                                              kim_lifetime_t *out_renewal_lifetime);
+
+/*!
+ * \param io_options     an options object to modify.
+ * \param in_forwardable a boolean value indicating whether or not to request a forwardable 
+ *                       credential.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set whether or not to request a forwardable credential.
+ * \par Default value
+ * Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
+ * \sa kim_options_get_forwardable()
+ */
+kim_error_t kim_options_set_forwardable (kim_options_t io_options,
+                                         kim_boolean_t in_forwardable);
+
+/*!
+ * \param in_options      an options object.
+ * \param out_forwardable on exit, a boolean value indicating whether or \a in_options will 
+ *                        request a forwardable credential.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get whether or not to request a forwardable credential.
+ * \par Default value
+ * Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
+ * \sa kim_options_set_forwardable()
+ */
+kim_error_t kim_options_get_forwardable (kim_options_t  in_options,
+                                         kim_boolean_t *out_forwardable);
+
+/*!
+ * \param io_options   an options object to modify.
+ * \param in_proxiable a boolean value indicating whether or not to request a proxiable 
+ *                     credential.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set whether or not to request a proxiable credential.
+ * \par Default value
+ * Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
+ * \sa kim_options_get_proxiable()
+ */
+kim_error_t kim_options_set_proxiable (kim_options_t io_options,
+                                       kim_boolean_t in_proxiable);
+
+/*!
+ * \param in_options    an options object.
+ * \param out_proxiable on exit, a boolean value indicating whether or \a in_options will 
+ *                      request a proxiable credential.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get whether or not to request a proxiable credential.
+ * \par Default value
+ * Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
+ * \sa kim_options_set_proxiable()
+ */
+kim_error_t kim_options_get_proxiable (kim_options_t  in_options,
+                                       kim_boolean_t *out_proxiable);
+
+/*!
+ * \param io_options     an options object to modify.
+ * \param in_addressless a boolean value indicating whether or not to request an addressless 
+ *                       credential.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set whether or not to request an addressless credential.
+ * \par Default value
+ * Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
+ * \sa kim_options_get_addressless()
+ */
+kim_error_t kim_options_set_addressless (kim_options_t io_options,
+                                         kim_boolean_t in_addressless);
+
+/*!
+ * \param in_options      an options object.
+ * \param out_addressless on exit, a boolean value indicating whether or \a in_options will 
+ *                        request an addressless credential.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get whether or not to request an addressless credential.
+ * \par Default value
+ * Read from the user's preferences and the Kerberos configuration. TRUE if unspecified.
+ * \sa kim_options_set_addressless()
+ */
+kim_error_t kim_options_get_addressless (kim_options_t  in_options,
+                                         kim_boolean_t *out_addressless);
+
+/*!
+ * \param io_options       an options object to modify.
+ * \param in_service_name  a service name.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the service name to request a credential for.
+ * \par Default value
+ * NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service.
+ * \sa kim_options_get_service_name()
+ */
+kim_error_t kim_options_set_service_name (kim_options_t io_options,
+					  kim_string_t  in_service_name);
+
+/*!
+ * \param in_options        an options object.
+ * \param out_service_name  on exit, the service name specified in \a in_options.
+ *                          Must be freed with kim_string_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the service name to request a credential for.
+ * \par Default value
+ * NULL, indicating "krbtgt@<REALM>", the ticket granting ticket (TGT) service.
+ * \sa kim_options_set_service_name()
+ */
+kim_error_t kim_options_get_service_name (kim_options_t  in_options,
+					  kim_string_t  *out_service_name);
+
+/*!
+ * \param io_options the options object to be freed.  Set to NULL on exit.
+ * \brief Free memory associated with an options object.
+ */
+void kim_options_free (kim_options_t *io_options);
+
+/*!@}*/
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* KIM_OPTIONS_H */
diff --git a/src/include/kim/kim_preferences.h b/src/include/kim/kim_preferences.h
new file mode 100644
index 0000000000..17ca351ede
--- /dev/null
+++ b/src/include/kim/kim_preferences.h
@@ -0,0 +1,485 @@
+/*
+ * 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 "as is" without express
+ * or implied warranty.
+ */
+
+#ifndef KIM_PREFERENCES_H
+#define KIM_PREFERENCES_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <kim/kim_types.h>
+    
+/*!
+ * \page kim_favorite_identities_overview KIM Favorite Identities Overview
+ *
+ * \section kim_favorite_identities_introduction Introduction
+ *
+ * As Kerberos becomes more widespread, the number of possible Kerberos
+ * identities and realms a user might want to use will become very large.
+ * Sites may list hundreds of realms in their Kerberos configuration files. 
+ * In addition, sites may wish to use DNS SRV records to avoid having to list
+ * all the realms they use in their Kerberos configuration.  As a result, the 
+ * list of realms in the Kerberos configuration may be exceedingly large and/or 
+ * incomplete.  Users may also use multiple identities from the same realm.
+ *
+ * On platforms which use a GUI to acquire credentials, the KIM would like
+ * to to display a list of identities for the user to select from.  Depending on 
+ * what is appropriate for the platform, identities may be displayed in a popup 
+ * menu or other list.  
+ *
+ * To solve this problem, the KIM maintains a list of favorite identities 
+ * specifically for identity selection.  This list is a set of unique identities 
+ * in alphabetical order (as appropriate for the user's language localization).  
+ *
+ * On most platforms the list of favorite identities has both an administrator 
+ * preference and a user preference which overrides it.  The administrator 
+ * preference exists only to initialize the favorite identities for new user 
+ * accounts.  Once the user modifies the list their favorite identities may  
+ * diverge from the site favorite identities preference.
+ *
+ * \note The location of user preferences and the semantics of
+ * preference synchronization is platform-specific.  Where possible KIM will use
+ * platform-specific preference mechanisms.
+ *
+ * Most callers will not need to use the favorite identities APIs.  However if you
+ * are implementing your own graphical prompt callback or a credential management 
+ * application, you may to view and/or edit the user's favorite identities.
+ *
+ * \section kim_favorite_identities_edit Viewing and Editing the Favorite Identities
+ * 
+ * First, you need to acquire the Favorite Identities stored in the user's
+ * preferences using #kim_preferences_create() and 
+ * #kim_preferences_get_favorite_identities().  Or you can use 
+ * #kim_favorite_identities_create() to get an empty identities list if you want to 
+ * overwrite the user's identities list entirely.  See \ref kim_preferences_overview 
+ * for more information on modifying the user's preferences.
+ * 
+ * Then use #kim_favorite_identities_get_number_of_identities() and 
+ * #kim_favorite_identities_get_identity_at_index() to display the identities list.  
+ * Use #kim_favorite_identities_add_identity() and #kim_favorite_identities_remove_identity() 
+ * to change which identities are in the identities list.  Identities are always stored in
+ * alphabetical order and duplicate identities are not permitted, so when you add or remove a
+ * identity you should redisplay the entire list.
+ *
+ * Once you are done editing the identities list, store changes in the user's preference file
+ * using #kim_preferences_set_favorite_identities() and #kim_preferences_synchronize().
+ *
+ * See \ref kim_favorite_identities_reference for information on specific APIs.
+ */
+
+/*!
+ * \defgroup kim_favorite_identities_reference KIM Favorite Identities Documentation
+ * @{
+ */
+
+/*!
+ * \param out_favorite_identities on exit, a new favorite identities object.  
+ *                            Must be freed with kim_favorite_identities_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Create a new favorite identities list.
+ */
+kim_error_t kim_favorite_identities_create (kim_favorite_identities_t *out_favorite_identities);
+
+/*!
+ * \param out_favorite_identities on exit, a new favorite identities object which is 
+ *                            a copy of in_favorite_identities.  
+ *                            Must be freed with kim_favorite_identities_free().
+ * \param in_favorite_identities  a favorite identities object. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Copy a favorite identities list.
+ */
+kim_error_t kim_favorite_identities_copy (kim_favorite_identities_t *out_favorite_identities,
+                                          kim_favorite_identities_t  in_favorite_identities);
+
+/*!
+ * \param in_favorite_identities   a favorite identities object.
+ * \param out_number_of_identities on exit, the number of identities in \a in_favorite_identities.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the number of identities in a favorite identities list.
+ */
+kim_error_t kim_favorite_identities_get_number_of_identities (kim_favorite_identities_t  in_favorite_identities,
+                                                              kim_count_t               *out_number_of_identities);
+
+/*!
+ * \param in_favorite_identities a favorite identities object.
+ * \param in_index           a index into the identities list (starting at 0).
+ * \param out_realm          on exit, the identity at \a in_index in \a in_favorite_identities.
+ *                           Must be freed with kim_string_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the Nth identity in a favorite identities list.
+ */
+kim_error_t kim_favorite_identities_get_identity_at_index (kim_favorite_identities_t  in_favorite_identities,
+                                                           kim_count_t                in_index,
+                                                           kim_identity_t            *out_identity);
+/*!
+ * \param io_favorite_identities a favorite identities object.
+ * \param in_identity            an identity string to add to \a in_favorite_identities.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Add an identity to a favorite identities list.
+ */
+kim_error_t kim_favorite_identities_add_identity (kim_favorite_identities_t io_favorite_identities,
+                                                  kim_identity_t            in_identity);
+
+/*!
+ * \param io_favorite_identities a favorite identities object.
+ * \param in_identity            an identity to remove from \a in_favorite_identities.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Remove an identity from a identities list.
+ */
+kim_error_t kim_favorite_identities_remove_identity (kim_favorite_identities_t io_favorite_identities,
+                                                     kim_identity_t            in_identity);
+
+/*!
+ * \param io_favorite_identities a favorite identities object.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Empty a favorite identities list.
+ */
+kim_error_t kim_favorite_identities_remove_all_identities (kim_favorite_identities_t io_favorite_identities);
+
+/*!
+ * \param io_favorite_identities the favorite identities object to be freed.  Set to NULL on exit.
+ * \brief Free memory associated with an identities list.
+ */
+
+void kim_favorite_identities_free (kim_favorite_identities_t *io_favorite_identities);
+
+/*!@}*/
+
+/*!
+ * \page kim_preferences_overview KIM Preferences Overview
+ *
+ * \section kim_preferences_introduction Introduction
+ *
+ * In addition to the site preferences stored in the Kerberos configuration, users may also
+ * want to have their own personal preferences for controlling credential acquisition.  
+ * As a result, KIM provides user preferences for initial credential options and 
+ * user interface behavior such as the default client identity and the favorite identities list.
+ *
+ * \section kim_preferences_edit Viewing and Editing the Preferences
+ * 
+ * In order to view and edit the user's preferences, call #kim_preferences_create() to acquire a 
+ * preferences object containing the user's preferences.  You can examine preferences
+ * with the functions starting with "kim_preferences_get_" and change preferences with
+ * the functions starting with "kim_preferences_set_".  Once you are done making changes,
+ * you can write changes back out to the user's preferences with #kim_preferences_synchronize().
+ *
+ * \note The location of user preferences and the semantics of
+ * preference synchronization is platform-specific.  Where possible KIM will use
+ * platform-specific preference mechanisms.
+ *
+ * \section kim_preferences_options Initial Credential Options Preferences
+ *
+ * KIM provides user preferences for initial credential options.  These
+ * are the options #kim_options_create() will use when creating a new KIM 
+ * options object.  They are also the options specified by KIM_OPTIONS_DEFAULT.
+ * You can view and edit the initial credential options using 
+ * #kim_preferences_get_options() and #kim_preferences_set_options(). 
+ *
+ * \note Not all credential options in the kim_options_t object have corresponding 
+ * user preferences.  For example, the prompt callback function is not stored
+ * in the user preferences since it has no meaning outside of the current 
+ * application.  Some options which are not currently stored in the
+ * preferences may be stored there in the future. 
+ *
+ * If you are implementing a user interface for credentials acquisition, 
+ * you should be aware that KIM has a user preference to manage the initial
+ * credential options preferences. If the user successfully acquires credentials 
+ * with non-default options and #kim_preferences_get_remember_options() is set 
+ * to TRUE, you should store the options used to get credentials with 
+ * #kim_preferences_set_options().  
+ *
+ * \section kim_preferences_client_identity Client Identity Preferences
+ *
+ * KIM also provides user preferences for the default client identity.   
+ * This identity is used whenever KIM needs to display a graphical dialog for
+ * credential acquisition but does not know what client identity to use.
+ * You can view and edit the default client identity using 
+ * #kim_preferences_get_client_identity() and 
+ * #kim_preferences_set_client_identity(). 
+ *
+ * If you are implementing a user interface for credentials acquisition, 
+ * you should be aware that KIM has a user preference to manage 
+ * the client identity preferences. If the user successfully acquires credentials 
+ * with non-default options and #kim_preferences_get_remember_client_identity() is  
+ * set to TRUE, you should store the client identity for which credentials were
+ * acquired using #kim_preferences_set_client_identity(). 
+ * 
+ * \section kim_preferences_favorite_identities Favorite Identities Preferences
+ *
+ * When presenting a graphical interface for credential acquisition, KIM 
+ * may need to display a list of identities for the user to select from.  
+ * This list is generated by the user's favorite identities preference.  
+ * You can view and edit the favorite identities preference using 
+ * #kim_preferences_get_favorite_identities() and 
+ * #kim_preferences_set_favorite_identities().  Please see the
+ * \ref kim_favorite_identities_overview for more information.
+ * 
+ * See \ref kim_preferences_reference for information on specific APIs.
+ */
+
+/*!
+ * \defgroup kim_preferences_reference KIM Preferences Documentation
+ * @{
+ */
+
+/*!
+ * \param out_preferences on exit, a new preferences object.  
+ *                        Must be freed with kim_preferences_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Create a new preferences object from the current user's preferences.
+ */
+kim_error_t kim_preferences_create (kim_preferences_t *out_preferences);
+
+/*!
+ * \param out_preferences on exit, a new preferences object which is a copy of in_preferences.  
+ *                        Must be freed with kim_preferences_free().
+ * \param in_preferences  a preferences object. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Copy a preferences object.
+ */
+kim_error_t kim_preferences_copy (kim_preferences_t *out_preferences,
+                                  kim_preferences_t  in_preferences);
+
+/*!
+ * \param io_preferences a preferences object to modify.
+ * \param in_options     an options object.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the user's preferred options.
+ * \sa kim_preferences_get_options()
+ */
+kim_error_t kim_preferences_set_options (kim_preferences_t io_preferences,
+                                         kim_options_t     in_options);
+
+/*!
+ * \param in_preferences a preferences object.
+ * \param out_options    on exit, the options specified in \a in_preferences.
+ *                        Must be freed with kim_options_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the user's preferred options.
+ * \sa kim_preferences_set_options()
+ */
+kim_error_t kim_preferences_get_options (kim_preferences_t  in_preferences,
+                                         kim_options_t     *out_options);
+
+/*!
+ * \param io_preferences      a preferences object to modify.
+ * \param in_remember_options a boolean value indicating whether or not to remember the last 
+ *                            options used to acquire a credential.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set whether or not to remember the last options the user used to acquire a credential.
+ * \sa kim_preferences_get_remember_options()
+ */
+kim_error_t kim_preferences_set_remember_options (kim_preferences_t io_preferences,
+                                                  kim_boolean_t     in_remember_options);
+
+/*!
+ * \param in_preferences       a preferences object.
+ * \param out_remember_options on exit, a boolean value indicating whether or \a in_preferences will 
+ *                             remember the last options used to acquire a credential.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get whether or not to remember the last options the user used to acquire a credential.
+ * \sa kim_preferences_set_remember_options()
+ */
+kim_error_t kim_preferences_get_remember_options (kim_preferences_t  in_preferences,
+                                                  kim_boolean_t     *out_remember_options);
+
+/*!
+ * \param io_preferences      a preferences object to modify.
+ * \param in_client_identity  a client identity object.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the user's preferred client identity.
+ * \sa kim_preferences_get_client_identity()
+ */
+kim_error_t kim_preferences_set_client_identity (kim_preferences_t io_preferences,
+                                                 kim_identity_t    in_client_identity);
+
+/*!
+ * \param in_preferences       a preferences object.
+ * \param out_client_identity  on exit, the client identity specified in \a in_preferences.
+ *                             Must be freed with kim_identity_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the user's preferred client identity.
+ * \sa kim_preferences_set_client_identity()
+ */
+kim_error_t kim_preferences_get_client_identity (kim_preferences_t  in_preferences,
+                                                 kim_identity_t    *out_client_identity);
+
+/*!
+ * \param io_preferences               a preferences object to modify.
+ * \param in_remember_client_identity  a boolean value indicating whether or not to remember the last 
+ *                                     client identity for which a credential was acquired.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set whether or not to remember the last client identity the user acquired a credential for.
+ * \sa kim_preferences_get_remember_client_identity()
+ */
+kim_error_t kim_preferences_set_remember_client_identity (kim_preferences_t io_preferences,
+                                                          kim_boolean_t     in_remember_client_identity);
+
+/*!
+ * \param in_preferences                a preferences object.
+ * \param out_remember_client_identity  on exit, a boolean value indicating whether or \a in_preferences will 
+ *                                      remember the last client identity for which a credential was acquired.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get whether or not to remember the last client identity the user acquired a credential for.
+ * \sa kim_preferences_set_remember_client_identity()
+ */
+kim_error_t kim_preferences_get_remember_client_identity (kim_preferences_t  in_preferences,
+                                                          kim_boolean_t     *out_remember_client_identity);
+
+/*!
+ * \param io_preferences       a preferences object to modify.
+ * \param in_minimum_lifetime  a minimum lifetime indicating how small a lifetime the
+ *                             GUI tools should allow the user to specify for credentials.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the minimum credential lifetime for GUI credential lifetime controls.
+ * \sa kim_preferences_get_minimum_lifetime()
+ */
+kim_error_t kim_preferences_set_minimum_lifetime (kim_preferences_t io_preferences,
+                                                  kim_lifetime_t    in_minimum_lifetime);
+
+/*!
+ * \param in_preferences        a preferences object.
+ * \param out_minimum_lifetime  on exit, the minimum lifetime that GUI tools will 
+ *                              allow the user to specify for credentials.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the minimum credential lifetime for GUI credential lifetime controls.
+ * \sa kim_preferences_set_minimum_lifetime()
+ */
+kim_error_t kim_preferences_get_minimum_lifetime (kim_preferences_t  in_preferences,
+                                                  kim_lifetime_t    *out_minimum_lifetime);
+
+/*!
+ * \param io_preferences       a preferences object to modify.
+ * \param in_maximum_lifetime  a maximum lifetime indicating how large a lifetime the
+ *                             GUI tools should allow the user to specify for credentials.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the maximum credential lifetime for GUI credential lifetime controls.
+ * \sa kim_preferences_get_maximum_lifetime()
+ */
+kim_error_t kim_preferences_set_maximum_lifetime (kim_preferences_t io_preferences,
+                                                  kim_lifetime_t    in_maximum_lifetime);
+
+/*!
+ * \param in_preferences        a preferences object.
+ * \param out_maximum_lifetime  on exit, the maximum lifetime that GUI tools will 
+ *                              allow the user to specify for credentials.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the maximum credential lifetime for GUI credential lifetime controls.
+ * \sa kim_preferences_set_maximum_lifetime()
+ */
+kim_error_t kim_preferences_get_maximum_lifetime (kim_preferences_t  in_preferences,
+                                                  kim_lifetime_t    *out_maximum_lifetime);
+
+/*!
+ * \param io_preferences               a preferences object to modify.
+ * \param in_minimum_renewal_lifetime  a minimum lifetime indicating how small a lifetime the
+ *                                     GUI tools should allow the user to specify for 
+ *                                     credential renewal.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the minimum credential renewal lifetime for GUI credential lifetime controls.
+ * \sa kim_preferences_get_minimum_renewal_lifetime()
+ */
+kim_error_t kim_preferences_set_minimum_renewal_lifetime (kim_preferences_t io_preferences,
+                                                          kim_lifetime_t    in_minimum_renewal_lifetime);
+
+/*!
+ * \param in_preferences                a preferences object.
+ * \param out_minimum_renewal_lifetime  on exit, the minimum lifetime that GUI tools will 
+ *                                      allow the user to specify for credential renewal.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the minimum credential renewal lifetime for GUI credential lifetime controls.
+ * \sa kim_preferences_set_minimum_renewal_lifetime()
+ */
+kim_error_t kim_preferences_get_minimum_renewal_lifetime (kim_preferences_t  in_preferences,
+                                                          kim_lifetime_t    *out_minimum_renewal_lifetime);
+
+/*!
+ * \param io_preferences               a preferences object to modify.
+ * \param in_maximum_renewal_lifetime  a maximum lifetime indicating how large a lifetime the
+ *                                     GUI tools should allow the user to specify for 
+ *                                     credential renewal.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the maximum credential renewal lifetime for GUI credential lifetime controls.
+ * \sa kim_preferences_get_minimum_renewal_lifetime()
+ */
+kim_error_t kim_preferences_set_maximum_renewal_lifetime (kim_preferences_t io_preferences,
+                                                          kim_lifetime_t    in_maximum_renewal_lifetime);
+
+/*!
+ * \param in_preferences                a preferences object.
+ * \param out_maximum_renewal_lifetime  on exit, the maximum lifetime that GUI tools will 
+ *                                      allow the user to specify for credential renewal.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the maximum credential renewal lifetime for GUI credential lifetime controls.
+ * \sa kim_preferences_set_minimum_renewal_lifetime()
+ */
+kim_error_t kim_preferences_get_maximum_renewal_lifetime (kim_preferences_t  in_preferences,
+                                                          kim_lifetime_t    *out_maximum_renewal_lifetime);
+
+/*!
+ * \param io_preferences         a preferences object to modify.
+ * \param in_favorite_identities a favorite identities object.
+ *                           See \ref kim_favorite_identities_overview for more information on KIM
+ *                           Favorite Identities. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the user's preferred list of identities.
+ * \sa kim_preferences_get_favorite_identities()
+ */
+kim_error_t kim_preferences_set_favorite_identities (kim_preferences_t         io_preferences,
+                                                     kim_favorite_identities_t in_favorite_identities);
+
+/*!
+ * \param in_preferences          a preferences object.
+ * \param out_favorite_identities on exit, a copy of the favorite identities specified in \a in_preferences.
+ *                                See \ref kim_favorite_identities_overview for more information on KIM
+ *                                Favorite Identities.  Must be freed with kim_favorite_identities_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the user's preferred list of identities.
+ * \sa kim_preferences_set_favorite_identities()
+ */
+kim_error_t kim_preferences_get_favorite_identities (kim_preferences_t          in_preferences,
+                                                     kim_favorite_identities_t *out_favorite_identities);
+
+/*!
+ * \param in_preferences a preferences object.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Synchronize a preferences object with the user's preferences, writing pending changes
+ * and reading any changes applied by other processes.
+ */
+kim_error_t kim_preferences_synchronize (kim_preferences_t in_preferences);
+
+/*!
+ * \param io_preferences the preferences object to be freed.  Set to NULL on exit.
+ * \brief Free memory associated with a preferences object.
+ */
+void kim_preferences_free (kim_preferences_t *io_preferences);
+
+/*!@}*/
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* KIM_PREFERENCES_H */
diff --git a/src/include/kim/kim_selection_hints.h b/src/include/kim/kim_selection_hints.h
new file mode 100644
index 0000000000..42ec1f0cda
--- /dev/null
+++ b/src/include/kim/kim_selection_hints.h
@@ -0,0 +1,537 @@
+/*
+ * 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 "as is" without express
+ * or implied warranty.
+ */
+
+#ifndef KIM_SELECTION_HINTS_H
+#define KIM_SELECTION_HINTS_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <kim/kim_types.h>
+    
+/*!
+ * \page kim_selection_hints_overview KIM Selection Hints Overview
+ *
+ * \section kim_selection_hints_introduction Introduction
+ *
+ * Most users belong to multiple organizations and thus need
+ * to authenticate to multiple Kerberos realms.  Traditionally Kerberos sites 
+ * solved this problem by setting up a cross-realm relationship, which allowed 
+ * the user to use TGT credentials for their client identity in one realm 
+ * to obtain credentials in another realm via cross-realm authentication.  As a 
+ * result users could acquire credentials for a single client identity and use 
+ * them everywhere.
+ *
+ * Setting up cross-realm requires that realms share a secret, so sites must 
+ * coordinate with one another to set up a cross-realm relationship.  In 
+ * addition, sites must set up authorization policies for users from other  
+ * realms.  As Kerberos becomes increasingly wide-spread, many realms will 
+ * not have cross-realm relationships, and users will need to   
+ * manually obtain credentials for their client identity at each realm
+ * (eg: "user@BANK.COM", "user@UNIVERSITY.EDU", etc).  As a result, users 
+ * will often have multiple credentials caches, one for each client identity.
+ *
+ * Unfortunately this presents a problem for applications which need to obtain
+ * service credentials.  Which client identity should they use?  
+ * Rather than having each application to manually search the cache collection,
+ * KIM provides a selection hints API for choosing the best client identity.  
+ * This API is intended to simplify the process of choosing credentials 
+ * and provide consistent behavior across all applications.
+ *
+ * Searching the cache collection for credentials may be expensive if there
+ * are a large number of caches.  If credentials for the client identity 
+ * are expired or not present, KIM may also wish to prompt the user for
+ * new credentials for the appropriate client identity.  As a result, 
+ * applications might want to remember which client identity worked in
+ * the past and always request credentials using that identity.  
+ * 
+ *
+ * \section kim_selection_hints_creating Creating KIM Selection Hints
+ * 
+ * A KIM selection hints object consists of an application identifier and one or 
+ * more pieces of information about the service the client application will be 
+ * contacting.  The application identifier is used by user preferences 
+ * to control how applications share cache entries.  It is important to be
+ * consistent about what application identifier you provide.  Java-style  
+ * identifiers are recommended to avoid collisions.
+ *
+ * \section kim_selection_hints_searching Selection Hint Search Behavior
+ *
+ * When using selection hints to search for an appropriate client identity, 
+ * KIM uses a consistent hint search order.  This allows applications to specify 
+ * potentially contradictory information without preventing KIM from locating a 
+ * single ccache.  In addition the selection hint search order may change, 
+ * especially if more hints are added.  
+ *
+ * As a result, callers are encouraged to provide all relevant search hints, 
+ * even if only a subset of those search hints are necessary to get reasonable 
+ * behavior in the current implementation.  Doing so will provide the most
+ * user-friendly selection experience.
+ *
+ * Currently the search order looks like this:
+ *
+ * \li <B>Service Identity</B> The client identity which has obtained a service credential for this service identity.
+ * \li <B>Server</B> A client identity which has obtained a service credential for this server.
+ * \li <B>Service Realm</B> A client identity which has obtained a service credential for this realm.
+ * \li <B>Service</B> A client identity which has obtained a service credential for this service.
+ * \li <B>Client Realm</B> A client identity in this realm.
+ * \li <B>User</B> A client identity whose first component is this user string.
+ *
+ * For example, if you specify a service identity and a credential for 
+ * that identity already exists in the ccache collection, KIM may use that 
+ * ccache, even if your user and client realm entries in the selection hints would  
+ * lead it to choose a different ccache.  If no credentials for the service identity
+ * exist then KIM will fall back on the user and realm hints.
+ *
+ * \note Due to performance and information exposure concerns, currently all 
+ * searching is done by examining the cache collection.  In the future the KIM 
+ * may also make network requests as part of its search algorithm.  For example
+ * it might check to see if the TGT credentials in each ccache can obtain
+ * credentials for the service identity specified by the selection hints.
+ *
+ * \section kim_selection_hints_selecting Selecting an Identity Using Selection Hints
+ *
+ * Once you have provided search criteria for selecting an identity, use
+ * #kim_selection_hints_get_identity() to obtain an identity object.  
+ * You can then use #kim_identity_get_gss_name() to obtain a gss_name_t 
+ * for use in gss_acquire_cred() or use 
+ * #kim_ccache_create_from_client_identity() to obtain a ccache containing 
+ * credentials for the identity.
+ *
+ * \note #kim_selection_hints_get_identity() obtains an identity based on
+ * the current state of the selection hints object.  If you change the 
+ * selection hints object you must call #kim_selection_hints_get_identity()
+ * again.
+ *
+ * \section kim_selection_hints_caching Selection Hint Caching Behavior
+ * 
+ * In addition to using selection hints to search for an appropriate client
+ * identity, KIM can also use them to remember which client identity worked.  
+ * KIM maintains a per-user cache mapping selection hints to identities so
+ * that applications do not have to maintain their own caches or present 
+ * user interface for selecting which cache to use.
+ *
+ * When #kim_selection_hints_get_identity() is called KIM looks up in the
+ * cache and returns the identity which the selection hints map to.  If 
+ * there is not a preexisting cache entry for the selection hints then 
+ * #kim_selection_hints_get_identity() will search for an identity and
+ * prompt the user if it cannot find an appropriate one. 
+ * 
+ * If the client identity returned by KIM authenticates and passes 
+ * authorization checks, you should tell KIM to cache the identity by calling
+ * #kim_selection_hints_remember_identity().  This will create a cache entry
+ * for the mapping between your selection hints and the identity so that 
+ * subsequent calls to #kim_selection_hints_get_identity() do not need to 
+ * prompt the user. 
+ *
+ * If the client identity returned by KIM fails to authenticate or fails
+ * authorization checks, you must call #kim_selection_hints_forget_identity() 
+ * to remove any mapping that already exists.  After this function is called,
+ * future calls to #kim_selection_hints_get_identity() will search for an 
+ * identity again.  You may also wish to call this function if the user 
+ * changes your application preferences such that the identity might be 
+ * invalidated.
+ * 
+ * \note It is very important that you call #kim_selection_hints_forget_identity()
+ * if your application fails to successfully establish a connection with the
+ * server. Otherwise the user can get "stuck" using the same non-working 
+ * identity if they chose the wrong one accidentally or if their identity 
+ * information changes.  Because only your application understands the 
+ * authorization checksof the protocol it uses, KIM cannot tell whether or not
+ * the identity worked.
+ * 
+ * If you wish to search and prompt for an identity without using
+ * the cached mappings, you can turn off the cached mapping lookups using 
+ * #kim_selection_hints_set_remember_identity().  This is not recommended
+ * for most applications since it will result in a lot of unnecessary
+ * searching and prompting for identities.
+ *
+ * \note Because cache entries key off of selection hints, it is important
+ * to always specify the same hints when contacting a particular
+ * service.  Otherwise KIM will not always find the cache entries.
+ *
+ * \section kim_selection_hints_prompt Selection Hint Prompting Behavior
+ * 
+ * If valid credentials for identity in the selection hints cache are
+ * unavailable or if no identity could be found using searching or caching
+ * when #kim_selection_hints_get_identity() is called, KIM may present a 
+ * GUI to ask the user to select an identity or acquire credentials for 
+ * an identity.  
+ *
+ * \note Because of the caching behavior described above the user will 
+ * only be prompted to choose an identity when setting up the application 
+ * or when their identity stops working. 
+ *
+ * In order to let the user know why Kerberos needs their assistance, KIM  
+ * displays the name of the application which requested the identity   
+ * selection. Unfortunately, some platforms do not provide a runtime 
+ * mechanism for determining the name of the calling process.  If your 
+ * application runs on one of these platforms (or is cross-platform) 
+ * you should provide a localized version of its name with 
+ * #kim_selection_hints_set_application_name().  You can check what name 
+ * will be used with #kim_selection_hints_get_application_name().
+ *
+ * In many cases a single application may select different identities for 
+ * different purposes.  For example an email application might use different 
+ * identities to check mail for different accounts.  If your application 
+ * has this property you may need to provide the user with a localized 
+ * string describing how the identity will be used.  You can specify 
+ * this string with #kim_selection_hints_get_explanation().  You can find 
+ * out what string will be used with kim_selection_hints_set_explanation().
+ *
+ * Since the user may choose to acquire credentials when selection an
+ * identity, KIM also provides #kim_selection_hints_set_options() to 
+ * set what credential acquisition options are used.  
+ * #kim_selection_hints_get_options() returns the options which will be used. 
+ *
+ * If you need to disable user interaction, use 
+ * #kim_selection_hints_set_allow_user_interaction().  Use 
+ * #kim_selection_hints_get_allow_user_interaction() to find out whether or
+ * not user interaction is enabled.  User interaction is enabled by default.
+ *
+ * See \ref kim_selection_hints_reference for information on specific APIs.
+ */
+
+/*!
+ * \defgroup kim_selection_hints_reference KIM Selection Hints Reference Documentation
+ * @{
+ */
+
+/*!
+ * \param out_selection_hints       on exit, a new selection hints object.  
+ *                                  Must be freed with kim_selection_hints_free().
+ * \param in_application_identifier an application identifier string.  Java-style identifiers are recommended 
+ *                                  to avoid cache entry collisions (eg: "com.example.MyApplication")
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Create a new selection hints object.
+ */
+kim_error_t kim_selection_hints_create (kim_selection_hints_t *out_selection_hints,
+                                        kim_string_t           in_application_identifier);
+
+/*!
+ * \param out_selection_hints on exit, a new selection hints object which is a copy of in_selection_hints.  
+ *                            Must be freed with kim_selection_hints_free().
+ * \param in_selection_hints  a selection hints object. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Copy a selection hints object.
+ */
+kim_error_t kim_selection_hints_copy (kim_selection_hints_t *out_selection_hints,
+                                      kim_selection_hints_t  in_selection_hints);
+
+/*!
+ * \param io_selection_hints   a selection hints object to modify.
+ * \param in_service_identity  a service identity.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the preferred service identity.
+ * \sa kim_selection_hints_get_service_identity_hint()
+ */
+kim_error_t kim_selection_hints_set_service_identity_hint (kim_selection_hints_t io_selection_hints,
+                                                           kim_identity_t        in_service_identity);
+
+/*!
+ * \param in_selection_hints    a selection hints object.
+ * \param out_service_identity  on exit, the service identity specified in \a in_selection_hints.
+ *                              Must be freed with kim_identity_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the preferred service identity.
+ * \sa kim_selection_hints_set_service_identity_hint()
+ */
+kim_error_t kim_selection_hints_get_service_identity_hint (kim_selection_hints_t  in_selection_hints,
+                                                           kim_identity_t        *out_service_identity);
+
+/*!
+ * \param io_selection_hints a selection hints object to modify.
+ * \param in_client_realm    a client realm string.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the preferred client realm.
+ * \sa kim_selection_hints_get_client_realm_hint()
+ */
+kim_error_t kim_selection_hints_set_client_realm_hint (kim_selection_hints_t io_selection_hints,
+                                                       kim_string_t          in_client_realm);
+
+/*!
+ * \param in_selection_hints a selection hints object.
+ * \param out_client_realm   on exit, the client realm string specified in \a in_selection_hints.
+ *                           Must be freed with kim_string_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the preferred client realm.
+ * \sa kim_selection_hints_set_client_realm_hint()
+ */
+kim_error_t kim_selection_hints_get_client_realm_hint (kim_selection_hints_t  in_selection_hints,
+                                                       kim_string_t          *out_client_realm);
+
+/*!
+ * \param io_selection_hints a selection hints object to modify.
+ * \param in_user            a user name string.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the preferred user name.
+ * \sa kim_selection_hints_get_user_hint()
+ */
+kim_error_t kim_selection_hints_set_user_hint (kim_selection_hints_t io_selection_hints,
+                                               kim_string_t          in_user);
+
+/*!
+ * \param in_selection_hints a selection hints object.
+ * \param out_user           on exit, the user name string specified in \a in_selection_hints.
+ *                           Must be freed with kim_string_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the preferred user name.
+ * \sa kim_selection_hints_set_user_hint()
+ */
+kim_error_t kim_selection_hints_get_user_hint (kim_selection_hints_t  in_selection_hints,
+                                               kim_string_t          *out_user);
+
+
+/*!
+ * \param io_selection_hints a selection hints object to modify.
+ * \param in_service_realm    a service realm string.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the preferred service realm.
+ * \sa kim_selection_hints_get_service_realm_hint()
+ */
+kim_error_t kim_selection_hints_set_service_realm_hint (kim_selection_hints_t io_selection_hints,
+                                                        kim_string_t          in_service_realm);
+
+/*!
+ * \param io_selection_hints a selection hints object.
+ * \param out_service_realm  on exit, the service realm string specified in \a in_selection_hints.
+ *                           Must be freed with kim_string_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the preferred service realm.
+ * \sa kim_selection_hints_set_service_realm_hint()
+ */
+kim_error_t kim_selection_hints_get_service_realm_hint (kim_selection_hints_t  io_selection_hints,
+                                                        kim_string_t          *out_service_realm);
+
+/*!
+ * \param io_selection_hints a selection hints object to modify.
+ * \param in_service         a service name string.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the preferred service name.
+ * \sa kim_selection_hints_get_service_hint()
+ */
+kim_error_t kim_selection_hints_set_service_hint (kim_selection_hints_t io_selection_hints,
+                                                  kim_string_t          in_service);
+
+/*!
+ * \param in_selection_hints a selection hints object.
+ * \param out_service        on exit, the service name string specified in \a in_selection_hints.
+ *                           Must be freed with kim_string_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the preferred service name.
+ * \sa kim_selection_hints_set_service_hint()
+ */
+kim_error_t kim_selection_hints_get_service_hint (kim_selection_hints_t  in_selection_hints,
+                                                  kim_string_t          *out_service);
+
+/*!
+ * \param io_selection_hints a selection hints object to modify.
+ * \param in_server          a server host name string.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the preferred server host name.
+ * \sa kim_selection_hints_get_server_hint()
+ */
+kim_error_t kim_selection_hints_set_server_hint (kim_selection_hints_t io_selection_hints,
+                                                 kim_string_t          in_server);
+
+/*!
+ * \param in_selection_hints a selection hints object.
+ * \param out_server         on exit, the server host name string specified in \a in_selection_hints.
+ *                           Must be freed with kim_string_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the preferred server host name.
+ * \sa kim_selection_hints_set_server_hint()
+ */
+kim_error_t kim_selection_hints_get_server_hint (kim_selection_hints_t  in_selection_hints,
+                                                 kim_string_t          *out_server);
+
+/*!
+ * \param io_selection_hints  a selection hints object to modify.
+ * \param in_application_name a localized string containing the full name of the application.
+ * \note If you do not call this function KIM will attempt to determine the application
+ * name at runtime.  If that fails (the functionality is only available on some platforms)
+ * then KIM will use the application identity string.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the application name for use in user interaction.
+ * \sa kim_selection_hints_get_application_name()
+ */
+kim_error_t kim_selection_hints_set_application_name (kim_selection_hints_t io_selection_hints,
+                                                      kim_string_t          in_application_name);
+
+/*!
+ * \param in_selection_hints   a selection hints object.
+ * \param out_application_name on exit, the localized full name of the application specified 
+ *                             in \a in_selection_hints. Must be freed with kim_string_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the application name for use in user interaction.
+ * \sa kim_selection_hints_set_application_name()
+ */
+kim_error_t kim_selection_hints_get_application_name (kim_selection_hints_t  in_selection_hints,
+                                                      kim_string_t          *out_application_name);
+
+/*!
+ * \param io_selection_hints  a selection hints object to modify.
+ * \param in_explanation      a localized string describing why the caller needs the identity.
+ * \note If the application only does one thing (the reason it needs an identity is obvious) 
+ * then you may not need to call this function.  You may still need to call 
+ * #kim_selection_hints_set_application_name()
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the strings used to prompt the user to select the identity.
+ * \sa kim_selection_hints_get_explanation()
+ */
+kim_error_t kim_selection_hints_set_explanation (kim_selection_hints_t io_selection_hints,
+                                                 kim_string_t          in_explanation);
+
+/*!
+ * \param in_selection_hints   a selection hints object.
+ * \param out_explanation      on exit, the localized string specified in \a in_selection_hints
+ *                             which describes why the caller needs the identity.  May be NULL.
+ *                             If non-NULL, must be freed with kim_string_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the strings used to prompt the user to select the identity.
+ * \sa kim_selection_hints_set_explanation()
+ */
+kim_error_t kim_selection_hints_get_explanation (kim_selection_hints_t  in_selection_hints,
+                                                 kim_string_t          *out_explanation);
+
+
+/*!
+ * \param io_selection_hints  a selection hints object to modify.
+ * \param in_options          options to control credential acquisition. 
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Set the options which will be used if credentials need to be acquired.
+ * \sa kim_selection_hints_get_options()
+ */
+kim_error_t kim_selection_hints_set_options (kim_selection_hints_t io_selection_hints,
+                                             kim_options_t         in_options);
+
+/*!
+ * \param in_selection_hints a selection hints object.
+ * \param out_options        on exit, the options to control credential acquisition  
+ *                           specified in \a in_selection_hints.  May be KIM_OPTIONS_DEFAULT.
+ *                           If not, must be freed with kim_options_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Get the options which will be used if credentials need to be acquired.
+ * \sa kim_selection_hints_set_options()
+ */
+kim_error_t kim_selection_hints_get_options (kim_selection_hints_t  in_selection_hints,
+                                             kim_options_t         *out_options);
+
+/*!
+ * \param in_selection_hints        a selection hints object to modify
+ * \param in_allow_user_interaction a boolean value specifying whether or not KIM should ask
+ *                                  the user to select an identity for \a in_selection_hints.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \note This setting defaults to TRUE.
+ * \brief Set whether or not KIM may interact with the user to select an identity.
+ * \sa kim_selection_hints_get_allow_user_interaction
+ */
+kim_error_t kim_selection_hints_set_allow_user_interaction (kim_selection_hints_t in_selection_hints,
+                                                            kim_boolean_t         in_allow_user_interaction);
+
+/*!
+ * \param in_selection_hints         a selection hints object to modify
+ * \param out_allow_user_interaction on exit, a boolean value specifying whether or not KIM 
+ *                                   should ask the user to select an identity for 
+ *                                   \a in_selection_hints.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \note This setting defaults to TRUE.
+ * \brief Get whether or not KIM may interact with the user to select an identity.
+ * \sa kim_selection_hints_set_allow_user_interaction
+ */
+kim_error_t kim_selection_hints_get_allow_user_interaction (kim_selection_hints_t  in_selection_hints,
+                                                            kim_boolean_t         *out_allow_user_interaction);
+
+/*!
+ * \param in_selection_hints    a selection hints object to modify
+ * \param in_remember_identity  a boolean value specifying whether or not KIM should use a cached
+ *                              mapping between \a in_selection_hints and a Kerberos identity.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \note This setting defaults to TRUE.
+ * \brief Set whether or not KIM will use cached mappings for this selection hints object.
+ * \sa kim_selection_hints_get_remember_identity
+ */
+kim_error_t kim_selection_hints_set_remember_identity (kim_selection_hints_t in_selection_hints,
+                                                       kim_boolean_t         in_remember_identity);
+
+/*!
+ * \param in_selection_hints     a selection hints object to modify
+ * \param out_remember_identity on exit, a boolean value specifying whether or not KIM will use a 
+ *                               cached mapping between \a in_selection_hints and a Kerberos identity.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \note This setting defaults to TRUE.
+ * \brief Get whether or not KIM will use cache mappings for this selection hints object.
+ * \sa kim_selection_hints_set_remember_identity
+ */
+kim_error_t kim_selection_hints_get_remember_identity (kim_selection_hints_t  in_selection_hints,
+                                                       kim_boolean_t         *out_remember_identity);
+
+/*!
+ * \param in_selection_hints the selection hints to add to the cache.
+ * \param out_identity       the Kerberos identity \a in_selection_hints maps to.
+ *                           Must be freed with kim_identity_free().
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \note \a out_identity is the identity mapped to by the current state of \a in_selection_hints.
+ * This function may prompt the user via a GUI to choose that identity.
+ * Subsequent modifications to \a in_selection_hints will not change \a out_identity.
+ * \brief Choose a client identity based on selection hints.
+ */
+
+kim_error_t kim_selection_hints_get_identity (kim_selection_hints_t in_selection_hints,
+                                              kim_identity_t        *out_identity);
+
+/*!
+ * \param in_selection_hints the selection hints to add to the cache.
+ * \param in_identity the Kerberos identity \a in_selection_hints maps to.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Add an entry for the selection hints to the selection hints cache, 
+ * replacing any existing entry.
+ */
+
+kim_error_t kim_selection_hints_remember_identity (kim_selection_hints_t in_selection_hints,
+                                                   kim_identity_t        in_identity);
+
+/*!
+ * \param in_selection_hints the selection hints to remove from the cache.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Remove an entry for the selection hints from the selection hints cache.
+ */
+
+kim_error_t kim_selection_hints_forget_identity (kim_selection_hints_t in_selection_hints);
+
+/*!
+ * \param io_selection_hints the selection hints object to be freed.  Set to NULL on exit.
+ * \brief Free memory associated with a selection hints object.
+ */
+
+void kim_selection_hints_free (kim_selection_hints_t *io_selection_hints);
+
+/*!@}*/
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* KIM_SELECTION_HINTS_H */
diff --git a/src/include/kim/kim_string.h b/src/include/kim/kim_string.h
new file mode 100644
index 0000000000..eb5277ef5e
--- /dev/null
+++ b/src/include/kim/kim_string.h
@@ -0,0 +1,84 @@
+/*
+ * 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 "as is" without express
+ * or implied warranty.
+ */
+
+#ifndef KIM_STRING_H
+#define KIM_STRING_H
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <kim/kim_types.h>
+
+/*!
+ * \page kim_string_overview KIM String Overview
+ *
+ * A UTF8 string.  
+ * 
+ * Memory management routines are provided for runtime consistency on
+ * operating systems with shared libraries and multiple runtimes.
+ *
+ * See \ref kim_string_reference for information on specific APIs.
+ */
+
+/*!
+ * \defgroup kim_string_reference KIM String Reference Documentation
+ * @{
+ */
+
+/*!
+ * \param out_string on exit, a new string object which is a copy of \a in_string.  
+                     Must be freed with kim_string_free().
+ * \param in_string  the string to copy.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Copy a string.
+ */
+kim_error_t kim_string_copy (kim_string_t       *out_string,
+                             const kim_string_t  in_string);
+
+/*!
+ * \param in_string            a string.
+ * \param in_compare_to_string a string to be compared to \a in_string.
+ * \param out_comparison       on exit, a comparison result indicating whether \a in_string
+ *                             is greater than, less than or equal to \a in_compare_to_string.
+ * \return On success, #KIM_NO_ERROR.  On failure, an error object representing the failure.
+ * \brief Compare two strings.
+ */
+kim_error_t kim_string_compare (kim_string_t      in_string, 
+                                kim_string_t      in_compare_to_string,
+                                kim_comparison_t *out_comparison);
+    
+/*!
+ * \param io_string a string to be freed.  Set to NULL on exit.
+ * \brief Free memory associated with a string.
+ */
+void kim_string_free (kim_string_t *io_string);
+
+/*!@}*/
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* KIM_STRING_H */
diff --git a/src/include/kim/kim_types.h b/src/include/kim/kim_types.h
new file mode 100644
index 0000000000..7898e626ef
--- /dev/null
+++ b/src/include/kim/kim_types.h
@@ -0,0 +1,162 @@
+/*
+ * 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 "as is" without express
+ * or implied warranty.
+ */
+
+#ifndef KIM_TYPES_H
+#define KIM_TYPES_H
+
+#include <stdint.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*!
+ * \defgroup kim_types_reference KIM Types and Constants
+ * @{
+ */
+
+/*!
+ * The KIM String type.  See \ref kim_string_overview for more information.
+ */
+typedef int32_t     kim_error_code_t;
+
+/*!
+ * A time value represented in seconds since January 1, 1970.
+ */
+typedef int64_t     kim_time_t;
+
+/*!
+ * A duration represented in seconds.
+ */
+typedef int64_t     kim_lifetime_t;
+
+/*!
+ * An quantity, usually used to return the number of elements in an array.
+ */
+typedef uint64_t    kim_count_t;
+
+/*!
+ * A boolean value.  0 means false, all other values mean true.
+ */
+typedef int         kim_boolean_t;
+
+/*!
+ * A comparison between two sortable objects.
+ * \li Less than 0 means the first object is less than the second.
+ * \li 0 means the two objects are identical.
+ * \li Greater than 0 means the first object is greater than the second.
+ * \note Convenience macros are provided for interpreting kim_comparison_ts
+ * to improve code readability.
+ * See #kim_comparison_is_less_than(), #kim_comparison_is_equal() and 
+ * #kim_comparison_is_greater_than()
+ */
+typedef int         kim_comparison_t;
+
+/*!
+ * Convenience macro for interpreting #kim_comparison_t.
+ */
+#define kim_comparison_is_less_than(c)    (c < 0)
+
+/*!
+ * Convenience macro for interpreting #kim_comparison_t.
+ */
+#define kim_comparison_is_equal_to(c)        (c == 0) 
+
+/*!
+ * Convenience macro for interpreting #kim_comparison_t.
+ */
+#define kim_comparison_is_greater_than(c) (c > 0)
+
+/*!
+ * The KIM String type.  See \ref kim_string_overview for more information.
+ */
+typedef const char *kim_string_t;
+
+struct kim_error_opaque;
+/*!
+ * A KIM Error object.  See \ref kim_error_overview for more information.
+ */
+typedef struct kim_error_opaque *kim_error_t;
+
+struct kim_identity_opaque;
+/*!
+ * A KIM Principal object.  See \ref kim_identity_overview for more information.
+ */
+typedef struct kim_identity_opaque *kim_identity_t;
+
+struct kim_options_opaque;
+/*!
+ * A KIM Options object.  See \ref kim_options_overview for more information.
+ */
+typedef struct kim_options_opaque *kim_options_t;
+
+struct kim_selection_hints_opaque;
+/*!
+ * A KIM Selection Hints object.  See \ref kim_selection_hints_overview for more information.
+ */
+typedef struct kim_selection_hints_opaque *kim_selection_hints_t;
+
+struct kim_favorite_identities_opaque;
+/*!
+ * A KIM Favorite Realms object.  See \ref kim_favorite_identities_overview for more information.
+ */
+typedef struct kim_favorite_identities_opaque *kim_favorite_identities_t;
+
+struct kim_preferences_opaque;
+/*!
+ * A KIM Preferences object.  See \ref kim_preferences_overview for more information.
+ */
+typedef struct kim_preferences_opaque *kim_preferences_t;
+
+struct kim_ccache_iterator_opaque;
+/*!
+ * A KIM CCache Iterator object.  See \ref kim_credential_cache_collection for more information.
+ */
+typedef struct kim_ccache_iterator_opaque *kim_ccache_iterator_t;
+
+struct kim_ccache_opaque;
+/*!
+ * A KIM CCache object.  See \ref kim_ccache_overview for more information.
+ */
+typedef struct kim_ccache_opaque *kim_ccache_t;
+
+struct kim_credential_iterator_opaque;
+/*!
+ * A KIM Credential Iterator object.  See \ref kim_credential_iterator_t for more information.
+ */
+typedef struct kim_credential_iterator_opaque *kim_credential_iterator_t;
+
+struct kim_credential_opaque;
+/*!
+ * A KIM Credential object.  See \ref kim_credential_overview for more information.
+ */
+typedef struct kim_credential_opaque *kim_credential_t;
+
+/*!@}*/
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* KIM_TYPES_H */