kim_credential_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 Credential 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_credential_overview">KIM Credential Overview</a></h1><h2><a class="anchor" name="kim_credential_introduction">
Introduction</a></h2>
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.<p>
The kim_credential 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.<p>
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.<p>
<dl class="note" compact><dt><b>Note:</b></dt><dd>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 <a class="el" href="kim_ccache_overview.html">KIM CCache Overview</a> for more information.</dd></dl>
<h2><a class="anchor" name="kim_credential_acquire_new">
Acquiring New Credentials</a></h2>
KIM provides the <a class="el" href="group__kim__credential__reference.html#ga02a96b9ad6fbc64007f741fa21c8814" title="Acquire a new initial credential.">kim_credential_create_new()</a> API for acquiring new credentials. 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__credential__reference.html#ga02a96b9ad6fbc64007f741fa21c8814" title="Acquire a new initial credential.">kim_credential_create_new()</a> may present a GUI or command line prompt to obtain information from the user.<p>
For legacy password-based Kerberos environments KIM also provides <a class="el" href="group__kim__credential__reference.html#g5a91166863595b457a2c98e622f0c526" title="Acquire a new initial credential using the provided password.">kim_credential_create_new_with_password()</a>. You should not use this function unless you know that it 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__credential__reference.html#g42c9498e4e928fce495867a1d1835dc3" title="Acquire a new initial credential from a keytab.">kim_credential_create_from_keytab()</a> 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.<h2><a class="anchor" name="kim_credential_validate">
Validating Credentials</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__credential__reference.html#g63a591ef509219ae83d11b635065984d" title="Validate a TGT credential.">kim_credential_validate()</a> 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 <a class="el" href="group__kim__credential__reference.html#g52db69b8f2289a4b60a3eddb5cb6b671" title="Store a credential in a ccache in the cache collection.">kim_credential_store()</a> on the validated credential or use <a class="el" href="group__kim__ccache__reference.html#g73f5b201d24a58936244fc4e43cd3d59" title="Validate the TGT in a ccache.">kim_ccache_validate()</a> instead.<h2><a class="anchor" name="kim_credential_renew">
Renewing Credentials</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__credential__reference.html#g18f43112f7ae046b2a5918b061a2072d" title="Renew a TGT credential.">kim_credential_renew()</a> 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 <a class="el" href="group__kim__credential__reference.html#g52db69b8f2289a4b60a3eddb5cb6b671" title="Store a credential in a ccache in the cache collection.">kim_credential_store()</a> on the renewed credential or use <a class="el" href="group__kim__ccache__reference.html#g574a0ef674116589dcf57460af81de39" title="Renew the TGT in a ccache.">kim_ccache_renew()</a> instead.<h2><a class="anchor" name="kim_credential_storing">
Storing Credentials in the Cache Collection</a></h2>
KIM credential objects may be stored in the ccache collection using <a class="el" href="group__kim__credential__reference.html#g52db69b8f2289a4b60a3eddb5cb6b671" title="Store a credential in a ccache in the cache collection.">kim_credential_store()</a>. 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. <a class="el" href="group__kim__credential__reference.html#g52db69b8f2289a4b60a3eddb5cb6b671" title="Store a credential in a ccache in the cache collection.">kim_credential_store()</a> may optionally return a kim_ccache object for the new ccache if you need to perform further operations on the new ccache.<p>
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 <a class="el" href="group__kim__credential__reference.html#g52db69b8f2289a4b60a3eddb5cb6b671" title="Store a credential in a ccache in the cache collection.">kim_credential_store()</a> any time the credential object changes. See <a class="el" href="kim_ccache_overview.html">KIM CCache Overview</a> for more information.<h2><a class="anchor" name="kim_credential_iterator">
Iterating over the Credentials in a CCache</a></h2>
KIM provides a simple iterator API for iterating over the credentials in a ccache. First, call <a class="el" href="group__kim__credential__iterator__reference.html#g5211e3c0c8881cd869eb20c03881304a" title="Get a credential iterator to enumerate credentials in a ccache.">kim_credential_iterator_create()</a> to obtain an iterator for a ccache. Then loop calling <a class="el" href="group__kim__credential__iterator__reference.html#g68e99dbf9a54dff3f47a0852b17efd1f" title="Get the next credential in a ccache.">kim_credential_iterator_next()</a> 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 <a class="el" href="group__kim__credential__iterator__reference.html#gd6c2fc4ec6698769434ad6ed28828933" title="Free memory associated with a credential iterator.">kim_credential_iterator_free()</a>.<p>
<dl class="note" compact><dt><b>Note:</b></dt><dd><a class="el" href="group__kim__credential__iterator__reference.html#g68e99dbf9a54dff3f47a0852b17efd1f" title="Get the next credential in a ccache.">kim_credential_iterator_next()</a> returns credential objects which must be freed with <a class="el" href="group__kim__credential__reference.html#g5609d3883f82eb3938a2d80e06bd0845" title="Free memory associated with a credential object.">kim_credential_free()</a> to avoid leaking memory.</dd></dl>
<h2><a class="anchor" name="kim_credential_verify">
Verifying Credentials</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__credential__reference.html#gf10b622ed5ea209bf06ba708732b6c07" title="Verify a TGT credential.">kim_credential_verify()</a> API to verify credentials directly.<p>
The most common reason for using <a class="el" href="group__kim__credential__reference.html#gf10b622ed5ea209bf06ba708732b6c07" title="Verify a TGT credential.">kim_credential_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__credential__reference.html#gf10b622ed5ea209bf06ba708732b6c07" title="Verify a TGT credential.">kim_credential_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__credential__reference.html#gf10b622ed5ea209bf06ba708732b6c07" title="Verify a TGT credential.">kim_credential_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__credential__reference.html#gf10b622ed5ea209bf06ba708732b6c07" title="Verify a TGT credential.">kim_credential_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__credential__reference.html#gf10b622ed5ea209bf06ba708732b6c07" title="Verify a TGT credential.">kim_credential_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_credential_properties">
Examining Credential Properties</a></h2>
<ul>
<li><a class="el" href="group__kim__credential__reference.html#g823f10b2a4db687fb555920808113392" title="Get the client identity of a credential object.">kim_credential_get_client_identity()</a> returns the credential's client identity.</li>
</ul>
<ul>
<li><a class="el" href="group__kim__credential__reference.html#g05208e303966c4c89371c18135de9cd7" title="Get the service identity of a credential object.">kim_credential_get_service_identity()</a> returns the credential's service identity.</li>
</ul>
<ul>
<li><a class="el" href="group__kim__credential__reference.html#gcf207597546b2397e8534c5bb354001a" title="Check if a credential is a ticket granting ticket.">kim_credential_is_tgt()</a> 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>
</ul>
<ul>
<li><a class="el" href="group__kim__credential__reference.html#g214a9d5e947d7947132a2849826a93f4" title="Check the state of a credential (valid, expired, postdated, etc).">kim_credential_get_state()</a> returns a <a class="el" href="group__kim__types__reference.html#g48e19d7e4aec7dc6662149cab39bbe20">kim_credential_state</a> containing the state of the credential. Possible values are: * kim_credentials_state_valid * kim_credentials_state_expired * kim_credentials_state_not_yet_valid * kim_credentials_state_needs_validation * kim_credentials_state_address_mismatch</li>
</ul>
<ul>
<li><a class="el" href="group__kim__credential__reference.html#gcae9e3e2b129e68215eedf588da60bea" title="Get the time when the credentials become valid.">kim_credential_get_start_time()</a> 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 <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__credential__reference.html#gba6367f04f832e086a8b0c01ebd3f77e" title="Get the time when the credentials will expire.">kim_credential_get_expiration_time()</a> 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>
</ul>
<ul>
<li><a class="el" href="group__kim__credential__reference.html#g4e50b4abf3efc36ed10c3049c9ff9a48" title="Get the time when the credentials will no longer be renewable.">kim_credential_get_renewal_expiration_time()</a> 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 a renewal expiration time of 0.</li>
</ul>
<ul>
<li><a class="el" href="group__kim__credential__reference.html#g6d0cb540926a4d95923709a5104fb298" title="Get a kim_options object based on a credential's attributes.">kim_credential_get_options()</a> returns a kim_options object with the credential options of the credential. 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__credential__reference.html">KIM Credential Reference Documentation</a> and <a class="el" href="group__kim__credential__iterator__reference.html">KIM Credential 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>