kim_favorite_realms_overview.html [plain text]
<!-- #bbinclude "header.txt"
#PAGETITLE#="Kerberos Identity Management: KIM Favorite Realms 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_favorite_realms_overview.html">
<META NAME="keywords" CONTENT="#KEYWORDS#">
<META NAME="description" CONTENT="#DESCRIPTION#">
<TITLE>Kerberos Identity Management: KIM Favorite Realms 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_favorite_realms_overview">KIM Favorite Realms Overview</a></h1><h2><a class="anchor" name="kim_favorite_realms_introduction">
Introduction</a></h2>
As Kerberos becomes more widespread, the number of possible Kerberos realms a user might want to contact will become very large. As a result, sites may list hundreds of realms in their Kerberos configuration files. In addition, sites may wish to use DNS SRV records to avoid having to list all the realms they use in their Kerberos configuration. As a result, the list of realms in the Kerberos configuration may be exceedingly large and/or incomplete.<p>
On platforms which use a GUI to acquire credentials, the KIM would like to to display a list of realms for the user to select from. Depending on what is appropriate for the platform, realms may be displayed in a popup menu or other list. Incredibly long lists of realms are undesirable since they may force the user to scroll excessively to get to their desired realm. And if the list does not contain realms available via DNS SRV records, the user would be forced to type their realm every time they acquire initial credentials.<p>
To solve this problem, the KIM maintains a list of favorite realms specifically for graphical realm selection. This list is a set of unique realm names in alphabetical order (as appropriate for the user's language localization) and is never used for realm configuration.<p>
On most platforms the list of favorite realms has both an administrator preference and a user preference which overrides it. The administrator preference exists only to initialize the Favorite Realms for new user accounts. Once the user modifies the list their favorite realms may diverge from the site favorite realms preference.<p>
<dl compact><dt><b>Note:</b></dt><dd>The location of user preferences and the semantics of preference synchronization is platform-specific. Where possible KIM will use platform-specific preference mechanisms.</dd></dl>
Most callers will not need to use the favorite realms APIs. However if you are implementing your own graphical prompt callback or a credential management application, you may to view and/or edit the user's favorite realms.<h2><a class="anchor" name="kim_favorite_realms_edit">
Viewing and Editing the Favorite Realms</a></h2>
First, you need to acquire the Favorite Realms stored in the user's preferences using <a class="el" href="group__kim__preferences__reference.html#g88fba2fb35d73c5905eb21dcfad57578">kim_preferences_create()</a> and <a class="el" href="group__kim__preferences__reference.html#g8830e09ce0640497fa994bd0774c2083">kim_preferences_get_favorite_realms()</a>. Or you can use <a class="el" href="group__kim__favorite__realms__reference.html#g417f55b13a783b4577957da31a53802d">kim_favorite_realms_create()</a> to get an empty realms list if you want to overwrite the user's realms list entirely. See <a class="el" href="kim_preferences_overview.html">KIM Preferences Overview</a> for more information on modifying the user's preferences.<p>
Then use <a class="el" href="group__kim__favorite__realms__reference.html#g637f34925f3a50f73c92c02b54b00d80">kim_favorite_realms_get_number_of_realms()</a> and <a class="el" href="group__kim__favorite__realms__reference.html#g9046964d21873704ecfb0cb0a7e45b04">kim_favorite_realms_get_realm_at_index()</a> to display the realms list. Use <a class="el" href="group__kim__favorite__realms__reference.html#gbd1792ed669426a97c33b6694ed457ad">kim_favorite_realms_add_realm()</a> and <a class="el" href="group__kim__favorite__realms__reference.html#g86e8863084cd174fa16752e1524ff47e">kim_favorite_realms_remove_realm()</a> to change which realms are in the realms list. Realms are always stored in alphabetical order and duplicate realms are not permitted, so when you add or remove a realm you should redisplay the entire list.<p>
Once you are done editing the realms list, store changes in the user's preference file using <a class="el" href="group__kim__preferences__reference.html#gab23bf8c419a21a6fe5a006875eaa5a1">kim_preferences_set_favorite_realms()</a> and <a class="el" href="group__kim__preferences__reference.html#gd4548bdc2cd52ad21d7a3e1bb60edba0">kim_preferences_synchronize()</a>.<p>
See <a class="el" href="group__kim__favorite__realms__reference.html">KIM Favorite Realms 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 -->