kim_ccache_overview.html [plain text]
<!-- #bbinclude "header.txt"
#PAGETITLE#="Kerberos Identity Management: KIM CCache Overview"
#ADDITIONALSTYLE#="@import url(doxygen.css);"
-->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<BASE HREF="http://web.mit.edu/macdev/KfM/KerberosFramework/KerberosIdentityManagement/Documentation/html/kim_ccache_overview.html">
<META NAME="keywords" CONTENT="#KEYWORDS#">
<META NAME="description" CONTENT="#DESCRIPTION#">
<TITLE>Kerberos Identity Management: KIM CCache Overview</TITLE>
<STYLE TYPE="text/css">
@import url(../../../../Common/Documentation/templates/site.css);
</STYLE>
</HEAD>
<BODY>
<DIV ID="menu">
<IMG SRC="../../../../Common/Documentation/graphics/Kerberos.jpg" ALT="Kerberos for Macintosh Logo">
<HR>
<P><A HREF="../../../../Common/Documentation/index.html">Home</A></P>
<P><A HREF="http://web.mit.edu/kerberos/">MIT Kerberos</A></P>
<P><A HREF="http://web.mit.edu/ist/">MIT IS&T</A></P>
<HR>
<P><A HREF="../../../../Common/Documentation/news.html">News</A></P>
<P><A HREF="../../../../Common/Documentation/documentation.html">Documentation</A></P>
<P><A HREF="../../../../Common/Documentation/developer.html">Developer Resources</A></P>
<P><A HREF="../../../../Common/Documentation/license.html">License</A></P>
<HR>
<P><A HREF="../../../../Common/Documentation/download.html">Download</A></P>
<P><A HREF="../../../../Common/Documentation/support.html">Support</A></P>
<P><A HREF="../../../../Common/Documentation/contact.html">Contact Us</A></P>
</DIV>
<DIV ID="body">
<!-- end bbinclude -->
<!-- Generated by Doxygen 1.4.6 -->
<h1><a class="anchor" name="kim_ccache_overview">KIM CCache Overview</a></h1><h2><a class="anchor" name="kim_ccache_introduction">
Introduction</a></h2>
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.<p>
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.<p>
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.<p>
<dl compact><dt><b>Note:</b></dt><dd>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.</dd></dl>
<h2><a class="anchor" name="kim_credential_cache_collection">
Acquiring a CCache from the Cache Collection</a></h2>
KIM provides a simple iterator API for iterating over the ccaches in the cache collection. First, call <a class="el" href="group__kim__ccache__iterator__reference.html#g2f116eaf59776453db578c9342b8c3e1">kim_ccache_iterator_create()</a> to obtain an iterator for the cache collection. Then loop calling <a class="el" href="group__kim__ccache__iterator__reference.html#g71dc66abc8b357e318c48debd2cb7916">kim_ccache_iterator_next()</a> 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 <a class="el" href="group__kim__ccache__iterator__reference.html#ged070acdb8996a34c622675369733d12">kim_ccache_iterator_free()</a>.<p>
<dl compact><dt><b>Note:</b></dt><dd><a class="el" href="group__kim__ccache__iterator__reference.html#g71dc66abc8b357e318c48debd2cb7916">kim_ccache_iterator_next()</a> returns ccache objects which must be freed with <a class="el" href="group__kim__ccache__reference.html#g2e9e82cd849c9815857397a9b869c45c">kim_ccache_free()</a> to avoid leaking memory.</dd></dl>
KIM also provides a convenient API <a class="el" href="group__kim__ccache__reference.html#gfc1faee53dbb4b1dab1a5daf8f685f64">kim_ccache_create_from_client_identity()</a> which returns the ccache for a specific client identity, if any exists. Typically callers of this API obtain the client identity using <a class="el" href="group__kim__selection__hints__reference.html#g4c18a97d53150f0b3536e52ab884973d">kim_selection_hints_get_identity()</a>.<h2><a class="anchor" name="kim_ccache_acquire_default">
Acquiring Credentials from the Default CCache</a></h2>
<a class="el" href="group__kim__ccache__reference.html#gec7b1b8d8514d76bb0608670106ab31c">kim_ccache_create_from_default()</a> 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.<h2><a class="anchor" name="kim_ccache_acquire_new">
Acquiring New Credentials in a CCache</a></h2>
KIM provides the <a class="el" href="group__kim__ccache__reference.html#gda206c3632933a811cb895e5be29bba9">kim_ccache_create_new()</a> API for acquiring new credentials and storing them in a ccache. Credentials can either be obtained for a specific client identity or by specifying <a class="el" href="group__kim__types__reference.html#g322f65f7d72470d57e21a4c8777ee9fb">KIM_IDENTITY_ANY</a> to allow the user to choose. Typically callers of this API obtain the client identity using <a class="el" href="group__kim__selection__hints__reference.html#g4c18a97d53150f0b3536e52ab884973d">kim_selection_hints_get_identity()</a>. Depending on the kim_options specified, <a class="el" href="group__kim__ccache__reference.html#gda206c3632933a811cb895e5be29bba9">kim_ccache_create_new()</a> may present a GUI or command line prompt to obtain information from the user.<p>
<a class="el" href="group__kim__ccache__reference.html#gd4242a5d6b2cc7222bcb065deb5fdf17">kim_ccache_create_new_if_needed()</a> 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, <a class="el" href="group__kim__ccache__reference.html#gd4242a5d6b2cc7222bcb065deb5fdf17">kim_ccache_create_new_if_needed()</a> 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 <a class="el" href="group__kim__ccache__reference.html#gfc1faee53dbb4b1dab1a5daf8f685f64">kim_ccache_create_from_client_identity()</a> and <a class="el" href="group__kim__ccache__reference.html#gda206c3632933a811cb895e5be29bba9">kim_ccache_create_new()</a>.<p>
KIM provides the <a class="el" href="group__kim__ccache__reference.html#g21a41ecd65dcb9d5b6a2e4d45d3f690b">kim_ccache_create_from_keytab()</a> 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.<h2><a class="anchor" name="kim_ccache_validate">
Validating Credentials in a CCache</a></h2>
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.<p>
KIM provides the <a class="el" href="group__kim__ccache__reference.html#g8bb7d46268621e73629dceefd15ff639">kim_ccache_validate()</a> API to validate the TGT credential in a ccache. Note that this API replaces any existing credentials with the validated credential.<h2><a class="anchor" name="kim_ccache_renew">
Renewing Credentials in a CCache</a></h2>
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.<p>
KIM provides the <a class="el" href="group__kim__ccache__reference.html#gafb44675df9d05af5b899996be14e2b4">kim_ccache_renew()</a> API to renew the TGT credential in a ccache. Note that this API replaces any existing credentials with the renewed credential.<h2><a class="anchor" name="kim_ccache_verify">
Verifying Credentials in a CCache</a></h2>
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.<p>
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 <a class="el" href="group__kim__ccache__reference.html#g3d293fc7338ff9b654e167153df33b5c">kim_ccache_verify()</a> API to verify credentials directly.<p>
The most common reason for using <a class="el" href="group__kim__ccache__reference.html#g3d293fc7338ff9b654e167153df33b5c">kim_ccache_verify()</a> is user login. If the local machine wants to use Kerberos to verify the username and password provided by the user, it must call <a class="el" href="group__kim__ccache__reference.html#g3d293fc7338ff9b654e167153df33b5c">kim_ccache_verify()</a> 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 <a class="el" href="group__kim__ccache__reference.html#g3d293fc7338ff9b654e167153df33b5c">kim_ccache_verify()</a>.<p>
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 <a class="el" href="group__kim__ccache__reference.html#g3d293fc7338ff9b654e167153df33b5c">kim_ccache_verify()</a>. 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).<p>
<a class="el" href="group__kim__ccache__reference.html#g3d293fc7338ff9b654e167153df33b5c">kim_ccache_verify()</a> 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.<h2><a class="anchor" name="kim_ccache_properties">
Examining CCache Properties</a></h2>
<ul>
<li><a class="el" href="group__kim__ccache__reference.html#gbf079f8dff05db6bb9aa152df83029fb">kim_ccache_get_type()</a> 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>
</ul>
<ul>
<li><a class="el" href="group__kim__ccache__reference.html#gec1c9af407a6554401a7f32c49cabd6a">kim_ccache_get_name()</a> 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>
</ul>
<ul>
<li><a class="el" href="group__kim__ccache__reference.html#g3a0f51defaf127b77b1e44092a352e31">kim_ccache_get_display_name()</a> 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>
</ul>
<ul>
<li><a class="el" href="group__kim__ccache__reference.html#gd5abbe1c6e1a0d191695bb373f9a7957">kim_ccache_get_client_identity()</a> returns the ccache's client identity.</li>
</ul>
<ul>
<li><a class="el" href="group__kim__ccache__reference.html#g78ff442478e0faa46c63774c49a7b51e">kim_ccache_get_valid_credential()</a> 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>
</ul>
<ul>
<li><a class="el" href="group__kim__ccache__reference.html#gb8793586b7c4054f2219b28920bf12bd">kim_ccache_get_start_time()</a> 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 <a class="el" href="kim_credential_overview.html#kim_credential_validate">Validating Credentials</a> for more information.</li>
</ul>
<ul>
<li><a class="el" href="group__kim__ccache__reference.html#g2cbb6b78cac2bb2e4359caf8b53d60c5">kim_ccache_get_expiration_time()</a> 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>
</ul>
<ul>
<li><a class="el" href="group__kim__ccache__reference.html#gfaad7545fbdb381faed8d2378009bd6e">kim_ccache_get_renewal_expiration_time()</a> 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.</li>
</ul>
See <a class="el" href="group__kim__ccache__reference.html">KIM CCache Reference Documentation</a> and <a class="el" href="group__kim__ccache__iterator__reference.html">KIM CCache Iterator Reference Documentation</a> for information on specific APIs.
<!-- #bbinclude "footer.txt" -->
</DIV>
<DIV ID="footer">
<P>
Copyright 2006 Massachusetts Institute of Technology.<BR>
Last updated on $Date: 2006-01-06 20:23:52 -0500 (Fri, 06 Jan 2006) $ <BR>
Last modified by $Author: lxs $
</P>
</DIV>
<!-- Begin MIT-use only web reporting counter -->
<IMG SRC="http://counter.mit.edu/tally" WIDTH=1 HEIGHT=1 ALT="">
<!-- End MIT-use only web reporting counter -->
</BODY></HTML>
<!-- end bbinclude -->