kim_credential_overview.html [plain text]
<!-- #bbinclude "header.txt"
#PAGETITLE#="Kerberos Identity Management: KIM Credential 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_credential_overview.html">
<META NAME="keywords" CONTENT="#KEYWORDS#">
<META NAME="description" CONTENT="#DESCRIPTION#">
<TITLE>Kerberos Identity Management: KIM Credential 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_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_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.<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 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#g318fdf6ea1e937a35e947dab6efa695d">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#g4c18a97d53150f0b3536e52ab884973d">kim_selection_hints_get_identity()</a>. Depending on the kim_options specified, <a class="el" href="group__kim__credential__reference.html#g318fdf6ea1e937a35e947dab6efa695d">kim_credential_create_new()</a> may present a GUI or command line prompt to obtain information from the user.<p>
KIM provides the <a class="el" href="group__kim__credential__reference.html#g465dab295b62d786d7e83e95409fae94">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#g9cd6ba59236babb4e79a680fa54b5037">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 this API in the ccache collection you must either call <a class="el" href="group__kim__credential__reference.html#g894c7144185b1112f6872fdf27fb016d">kim_credential_store()</a> on the validated credential or use <a class="el" href="group__kim__ccache__reference.html#g8bb7d46268621e73629dceefd15ff639">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#g99ac2c178bec484311cd7fc2cbb7e05e">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 this API in the ccache collection you must either call <a class="el" href="group__kim__credential__reference.html#g894c7144185b1112f6872fdf27fb016d">kim_credential_store()</a> on the renewed credential or use <a class="el" href="group__kim__ccache__reference.html#gafb44675df9d05af5b899996be14e2b4">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#g894c7144185b1112f6872fdf27fb016d">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#g894c7144185b1112f6872fdf27fb016d">kim_credential_store()</a> may optionally return a kim_ccache_t 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#g894c7144185b1112f6872fdf27fb016d">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_t">
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#g4a1f55aa90053b8d59281a0f7d12590c">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#ge7f5bc2cf2cc42c3e39fd4f945b474cd">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#gb32e376af0b819cb3c9ca30f3db1c86b">kim_credential_iterator_free()</a>.<p>
<dl compact><dt><b>Note:</b></dt><dd><a class="el" href="group__kim__credential__iterator__reference.html#ge7f5bc2cf2cc42c3e39fd4f945b474cd">kim_credential_iterator_next()</a> returns credential objects which must be freed with <a class="el" href="group__kim__credential__reference.html#gb92567dd6b60e525f343cc401e1949aa">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#g390a74d4d834fd1b5c2e7aebcd783e32">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#g390a74d4d834fd1b5c2e7aebcd783e32">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#g390a74d4d834fd1b5c2e7aebcd783e32">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#g390a74d4d834fd1b5c2e7aebcd783e32">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#g390a74d4d834fd1b5c2e7aebcd783e32">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#g390a74d4d834fd1b5c2e7aebcd783e32">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#gfab660faba5a6b2dc0f067dfe3e6235f">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#g3bf00a133fbfe8fd3f9b6cba55ac6045">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#gdf4e9b444c5050199476721a5cec67f7">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#g2171ecabb146065cb67d35ac40f9eb1f">kim_credential_is_valid()</a> returns whether the credential is valid and if not why the credential is not valid.</li>
</ul>
<ul>
<li><a class="el" href="group__kim__credential__reference.html#g48b41bc28845e209c41b087d28250e2a">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#g07fc4d11e42bf7d32be67fcac531c372">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#g1723a7c06e32ee954be214767bc55194">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 an error.</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.
<!-- #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 -->