kim_ccache_overview.html [plain text]
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
<title>Kerberos Identity Management: KIM CCache Overview</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">
</head><body>
<!-- Generated by Doxygen 1.5.3 -->
<h1><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 class="note" 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#g3201595a767a17da00f511bf4bb31632" title="Get a ccache iterator to enumerate ccaches in the cache collection.">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#gf695d88e8be91330f23aaf765f3d19bc" title="Get the next ccache in the cache collection.">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#g2af38d7f654d6cd513fb4bf7cf35ce21" title="Free memory associated with a ccache iterator.">kim_ccache_iterator_free()</a>.<p>
<dl class="note" compact><dt><b>Note:</b></dt><dd><a class="el" href="group__kim__ccache__iterator__reference.html#gf695d88e8be91330f23aaf765f3d19bc" title="Get the next ccache in the cache collection.">kim_ccache_iterator_next()</a> returns ccache objects which must be freed with <a class="el" href="group__kim__ccache__reference.html#g6c6be543e0ea2b518612be4255e15b9a" title="Free memory associated with a ccache.">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#g6ecc14b94ffb57ca8008d0a407bb9c7d" title="Find a ccache for a client identity in the cache collection.">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#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">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#g137761ce872ca756c08e7c31e4101df5" title="Get the default ccache.">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#gcdc80c9bfa368eca7cc2d3710b4c0fa9" title="Acquire a new initial credential and store it in a ccache.">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#g5f4130fa05e937b749d7cc5347531abe" title="Choose a client identity based on selection hints.">kim_selection_hints_get_identity()</a>. Depending on the kim_options specified, <a class="el" href="group__kim__ccache__reference.html#gcdc80c9bfa368eca7cc2d3710b4c0fa9" title="Acquire a new initial credential and store it in a ccache.">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#g52fa72130f4ba6de8cce1224578102ce" title="Find a ccache containing a valid initial credential in the cache collection, or if...">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#g52fa72130f4ba6de8cce1224578102ce" title="Find a ccache containing a valid initial credential in the cache collection, or if...">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#g6ecc14b94ffb57ca8008d0a407bb9c7d" title="Find a ccache for a client identity in the cache collection.">kim_ccache_create_from_client_identity()</a> and <a class="el" href="group__kim__ccache__reference.html#gcdc80c9bfa368eca7cc2d3710b4c0fa9" title="Acquire a new initial credential and store it in a ccache.">kim_ccache_create_new()</a>.<p>
For legacy password-based Kerberos environments KIM also provides <a class="el" href="group__kim__ccache__reference.html#ge796642d7eb76bc05142ad8112d398e5" title="Acquire a new initial credential and store it in a ccache using the provided password...">kim_ccache_create_new_with_password()</a> and <a class="el" href="group__kim__ccache__reference.html#g462285a95435cf403b0330be13a515d7" title="Find a ccache containing a valid initial credential in the cache collection, or if...">kim_ccache_create_new_if_needed_with_password()</a>. You should not use these functions unless you know that they will only be used in environments using passwords. Otherwise users without passwords may be prompted for them.<p>
KIM provides the <a class="el" href="group__kim__ccache__reference.html#g15cb7e1b9069a610030211cecc5e6232" title="Acquire a new initial credential from a keytab and store it in a ccache.">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#g73f5b201d24a58936244fc4e43cd3d59" title="Validate the TGT in a ccache.">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#g574a0ef674116589dcf57460af81de39" title="Renew the TGT in a ccache.">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#g8836113dd86a0dc3cf60df0d76280de6" title="Verify the TGT in a ccache.">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#g8836113dd86a0dc3cf60df0d76280de6" title="Verify the TGT in a ccache.">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#g8836113dd86a0dc3cf60df0d76280de6" title="Verify the TGT in a ccache.">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#g8836113dd86a0dc3cf60df0d76280de6" title="Verify the TGT in a ccache.">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#g8836113dd86a0dc3cf60df0d76280de6" title="Verify the TGT in a ccache.">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#g8836113dd86a0dc3cf60df0d76280de6" title="Verify the TGT in a ccache.">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#ge49fc64af74ad437de6becdbee876117" title="Get the type of a ccache.">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#g18d612eddf05b4deb11e97071b5ad17b" title="Get the name of a ccache.">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#ga89f6bfa35c436621ff324b805a7c669" title="Get the type and name for a ccache in display format.">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#g754252665d1cd87d9ee8f6f51d62f211" title="Get the client identity for a ccache.">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#g0fbacc48909c484623329b8131bfb3d0" title="Get the first valid credential in a ccache.">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#gb2165acd652eddaeb61c8f6b8c3a16f7" title="Get the time when the credentials in the ccache become valid.">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#g52693fc485cf2e3bd5cf0c0a3d414d8a" title="Get the time when the credentials in the ccache will expire.">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#g01b4cbb88abf6aafd2efdaad91d74f0f" title="Get the time when the credentials in the ccache will no longer be renewable.">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>
<ul>
<li><a class="el" href="group__kim__ccache__reference.html#g9ad7a15bf94420675c17bc61e83e47da" title="Get a kim_options object based on a ccache's credential attributes.">kim_ccache_get_options()</a> returns a kim_options object with the credential options of the credentials in the ccache. This function is intended to be used when adding an identity with existing credentials to the favorite identities list. By passing in the options returned by this call, future requests for the favorite identity will use the same credential options.</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. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:43 2008 for Kerberos Identity Management by
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.3 </small></address>
</body>
</html>