kim_identity_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 Identity 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_identity_overview">KIM Identity Overview</a></h1><h2><a class="anchor" name="kim_identity_introduction">
Introduction</a></h2>
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".<p>
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").<p>
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 '\'.<h2><a class="anchor" name="kim_identity_create_display">
Creating and Displaying Identities</a></h2>
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:<p>
<ul>
<li><a class="el" href="group__kim__identity__reference.html#ga7ee7771443a129ab5e28923ccb3f602" title="Create a identity from a realm and component strings.">kim_identity_create_from_components()</a> creates an identity object from a list of components. </li>
<li><a class="el" href="group__kim__identity__reference.html#g96591cf92e03e823efcd4fc54085ca4d" title="Get the number of components of an identity.">kim_identity_get_number_of_components()</a> returns the number of components in an identity object. </li>
<li><a class="el" href="group__kim__identity__reference.html#gec46c138cd20035a12586dba59680728" title="Get the Nth component of an identity.">kim_identity_get_component_at_index()</a> return a component of an identity object. </li>
<li><a class="el" href="group__kim__identity__reference.html#gf102dfe4b89f6e87ac3059f01f174066" title="Get the realm string of an identity.">kim_identity_get_realm()</a> returns the identity's realm.</li>
</ul>
<ul>
<li><a class="el" href="group__kim__identity__reference.html#g23804ae9643100ad5e1fef11f6e5362c" title="Create a identity from a string.">kim_identity_create_from_string()</a> generates an identity object from an escaped string representation. </li>
<li><a class="el" href="group__kim__identity__reference.html#g094e916a4d31556c3ead03f85aafa603" title="Get the string representation of a identity.">kim_identity_get_string()</a> returns the identity's escaped string representation. </li>
<li><a class="el" href="group__kim__identity__reference.html#g59afb84675651930afebeb6fff788eba" title="Get a human-readable string representation of an identity.">kim_identity_get_display_string()</a> returns a non-escaped string for display to the user. This string cannot be passed into <a class="el" href="group__kim__identity__reference.html#g23804ae9643100ad5e1fef11f6e5362c" title="Create a identity from a string.">kim_identity_create_from_string()</a>.</li>
</ul>
<ul>
<li><a class="el" href="group__kim__identity__reference.html#g3a1f84217c02c9b1023e791ae206cf94" title="Create an identity object from a krb5_principal.">kim_identity_create_from_krb5_principal()</a> generates an identity object from a krb5_principal object. </li>
<li><a class="el" href="group__kim__identity__reference.html#gd293289334f024dedae5fa59856049d6" title="Get the krb5_principal representation of an identity.">kim_identity_get_krb5_principal()</a> returns a krb5_principal object for an identity object.</li>
</ul>
<dl class="note" compact><dt><b>Note:</b></dt><dd>If you need to know if two identity objects refer to the same entity, use <a class="el" href="group__kim__identity__reference.html#gd47b876ed3dfa0fd8a419412b46c4867" title="Compare identity objects for equivalency.">kim_identity_compare()</a>.</dd></dl>
<h2><a class="anchor" name="kim_identity_selection">
Choosing a Client Identity</a></h2>
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).<p>
To solve this problem, <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> 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 <a class="el" href="kim_selection_hints_overview.html">KIM Selection Hints Overview</a> for more information.<h2><a class="anchor" name="kim_identity_password">
Changing a Identity's Password</a></h2>
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.<p>
<a class="el" href="group__kim__identity__reference.html#g660c28e70656127c7c723d50414675e8" title="Change the password for an identity.">kim_identity_change_password()</a> presents a user interface to obtain the old and new passwords from the user.<p>
<dl class="note" compact><dt><b>Note:</b></dt><dd>Not all identities have a password. Some sites use certificates (pkinit) and in the future there may be other authentication mechanisms (eg: smart cards).</dd></dl>
See <a class="el" href="group__kim__identity__reference.html">KIM Identity 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>