kim_selection_hints_overview.html [plain text]
<!-- #bbinclude "header.txt"
#PAGETITLE#="Kerberos Identity Management: KIM Selection Hints 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_selection_hints_overview.html">
<META NAME="keywords" CONTENT="#KEYWORDS#">
<META NAME="description" CONTENT="#DESCRIPTION#">
<TITLE>Kerberos Identity Management: KIM Selection Hints 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_selection_hints_overview">KIM Selection Hints Overview</a></h1><h2><a class="anchor" name="kim_selection_hints_introduction">
Introduction</a></h2>
Most users belong to multiple organizations and thus need to authenticate to multiple Kerberos realms. Traditionally Kerberos sites solved this problem by setting up a cross-realm relationship, which allowed the user to use TGT credentials for their client identity in one realm to obtain credentials in another realm via cross-realm authentication. As a result users could acquire credentials for a single client identity and use them everywhere.<p>
Setting up cross-realm requires that realms share a secret, so sites must coordinate with one another to set up a cross-realm relationship. In addition, sites must set up authorization policies for users from other realms. As Kerberos becomes increasingly wide-spread, many realms will not have cross-realm relationships, and users will need to manually obtain credentials for their client identity at each realm (eg: "user@BANK.COM", "user@UNIVERSITY.EDU", etc). As a result, users will often have multiple credentials caches, one for each client identity.<p>
Unfortunately this presents a problem for applications which need to obtain service credentials. Which client identity should they use? Rather than having each application to manually search the cache collection, KIM provides a selection hints API for choosing the best client identity. This API is intended to simplify the process of choosing credentials and provide consistent behavior across all applications.<p>
Searching the cache collection for credentials may be expensive if there are a large number of caches. If credentials for the client identity are expired or not present, KIM may also wish to prompt the user for new credentials for the appropriate client identity. As a result, applications might want to remember which client identity worked in the past and always request credentials using that identity.<h2><a class="anchor" name="kim_selection_hints_creating">
Creating KIM Selection Hints</a></h2>
A KIM selection hints object consists of an application identifier and one or more pieces of information about the service the client application will be contacting. The application identifier is used by user preferences to control how applications share cache entries. It is important to be consistent about what application identifier you provide. Java-style identifiers are recommended to avoid collisions.<h2><a class="anchor" name="kim_selection_hints_searching">
Selection Hint Search Behavior</a></h2>
When using selection hints to search for an appropriate client identity, KIM uses a consistent hint search order. This allows applications to specify potentially contradictory information without preventing KIM from locating a single ccache. In addition the selection hint search order may change, especially if more hints are added.<p>
As a result, callers are encouraged to provide all relevant search hints, even if only a subset of those search hints are necessary to get reasonable behavior in the current implementation. Doing so will provide the most user-friendly selection experience.<p>
Currently the search order looks like this:<p>
<ul>
<li><b>Service Identity</b> The client identity which has obtained a service credential for this service identity. </li>
<li><b>Hostname</b> A client identity which has obtained a service credential for this server. </li>
<li><b>Service Realm</b> A client identity which has obtained a service credential for this realm. </li>
<li><b>Service</b> A client identity which has obtained a service credential for this service. </li>
<li><b>Client Realm</b> A client identity in this realm. </li>
<li><b>User</b> A client identity whose first component is this user string.</li>
</ul>
For example, if you specify a service identity and a credential for that identity already exists in the ccache collection, KIM may use that ccache, even if your user and client realm entries in the selection hints would lead it to choose a different ccache. If no credentials for the service identity exist then KIM will fall back on the user and realm hints.<p>
<dl compact><dt><b>Note:</b></dt><dd>Due to performance and information exposure concerns, currently all searching is done by examining the cache collection. In the future the KIM may also make network requests as part of its search algorithm. For example it might check to see if the TGT credentials in each ccache can obtain credentials for the service identity specified by the selection hints.</dd></dl>
<h2><a class="anchor" name="kim_selection_hints_selecting">
Selecting an Identity Using Selection Hints</a></h2>
Once you have provided search criteria for selecting an identity, use <a class="el" href="group__kim__selection__hints__reference.html#g4c18a97d53150f0b3536e52ab884973d">kim_selection_hints_get_identity()</a> to obtain an identity object. You can then use <a class="el" href="group__kim__identity__reference.html#g445ddb044181a68fdbad8a63e614add5">kim_identity_get_gss_name()</a> to obtain a gss_name_t for use in gss_acquire_cred() or use <a class="el" href="group__kim__ccache__reference.html#gfc1faee53dbb4b1dab1a5daf8f685f64">kim_ccache_create_from_client_identity()</a> to obtain a ccache containing credentials for the identity.<p>
<dl compact><dt><b>Note:</b></dt><dd><a class="el" href="group__kim__selection__hints__reference.html#g4c18a97d53150f0b3536e52ab884973d">kim_selection_hints_get_identity()</a> obtains an identity based on the current state of the selection hints object. Subsequent changes to the selection hints object will not change the identity.</dd></dl>
<h2><a class="anchor" name="kim_selection_hints_caching">
Selection Hint Caching Behavior</a></h2>
In addition to using selection hints to search for an appropriate client identity, KIM can also use them to remember which client identity worked. When the client identity returned by KIM successfully authenticates to the server and passes authorization checks, you may use <a class="el" href="group__kim__selection__hints__reference.html#g9a9b2ab57d3a9191023231eee8ac2e27">kim_selection_hints_cache_results()</a> to add a mapping to the cache, replacing an existing mapping if there is one. Future calls to KIM using identical selection hints will result in the cached client identity and no searching will occur.<p>
If a cache entry becomes invalid, you can forget the mapping using <a class="el" href="group__kim__selection__hints__reference.html#g19db74acfbbf86d3ea202e5f65f3cb73">kim_selection_hints_forget_cached_results()</a>. If you don't want to remove the mapping but also don't want to use it, you can turn off querying of the cache for a particular selection hints object using <a class="el" href="group__kim__selection__hints__reference.html#g76875288128124ce51be22b2efaadbd1">kim_selection_hints_set_use_cached_results()</a>.<p>
<dl compact><dt><b>Note:</b></dt><dd>Because cache entries key off of selection hints, it is important to always specify the same hints when contacting a particular service. Otherwise KIM will not always find the cache entries.</dd></dl>
<h2><a class="anchor" name="kim_selection_hints_prompt">
Selection Hint Prompting Behavior</a></h2>
If valid credentials for identity in the selection hints cache are unavailable or if no identity could be found using searching or caching when <a class="el" href="group__kim__selection__hints__reference.html#g4c18a97d53150f0b3536e52ab884973d">kim_selection_hints_get_identity()</a> is called, KIM may present a GUI to ask the user to select an identity or acquire credentials for an identity.<p>
<dl compact><dt><b>Note:</b></dt><dd>So long as the caller caches the identity with <a class="el" href="group__kim__selection__hints__reference.html#g9a9b2ab57d3a9191023231eee8ac2e27">kim_selection_hints_cache_results()</a> the user will be prompted only when setting up the application or when credentials expire.</dd></dl>
In order to let the user know why Kerberos needs their assistance, KIM displays the name of the application which requested the identity selection. Unfortunately, some platforms do not provide a runtime mechanism for determining the name of the calling process. If your application runs on one of these platforms (or is cross-platform) you should provide a localized version of its name with <a class="el" href="group__kim__selection__hints__reference.html#g9904e1b83a1082fbb0752853b3c6ece0">kim_selection_hints_set_application_name()</a>. You can check what name will be used with <a class="el" href="group__kim__selection__hints__reference.html#ge254849dd3bf81a295e1e9054220002b">kim_selection_hints_get_application_name()</a>.<p>
In many cases a single application may select different identities for different purposes. For example an email application might use different identities to check mail for different accounts. If your application has this property you may need to provide the user with a localized string describing how the identity will be used. You can specify this string with <a class="el" href="group__kim__selection__hints__reference.html#gca2b7379231b656f6ee2df551bb7972e">kim_selection_hints_get_explanation()</a>. You can find out what string will be used with <a class="el" href="group__kim__selection__hints__reference.html#gdde1a442f7ab9913eed7855f06575f92">kim_selection_hints_set_explanation()</a>.<p>
Since the user may choose to acquire credentials when selection an identity, KIM also provides <a class="el" href="group__kim__selection__hints__reference.html#gae79cd94d2184c8ffe4c7144205fd813">kim_selection_hints_set_options()</a> to set what credential acquisition options are used. <a class="el" href="group__kim__selection__hints__reference.html#ge00f6f57e9d24d2e62694d72d43148a4">kim_selection_hints_get_options()</a> returns the options which will be used.<p>
If you need to disable user interaction, use <a class="el" href="group__kim__selection__hints__reference.html#g8a4f9300250b27fec9b0da4b52f0a781">kim_selection_hints_set_allow_user_interaction</a>. Use <a class="el" href="group__kim__selection__hints__reference.html#g255a01cf3f1e31390b213a802f8b27b4">kim_selection_hints_get_allow_user_interaction</a> to find out whether or not user interaction is enabled. User interaction is enabled by default.<p>
See <a class="el" href="group__kim__selection__hints__reference.html">KIM Selection Hints 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 -->