Edit File: kim_preferences_overview.html
<!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 Preferences 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_preferences_overview">KIM Preferences Overview</a></h1><h2><a class="anchor" name="kim_preferences_introduction"> Introduction</a></h2> In addition to the site preferences stored in the Kerberos configuration, users may also want to have their own personal preferences for controlling credential acquisition. As a result, KIM provides user preferences for initial credential options and user interface behavior such as the default client identity and the favorite identities list.<h2><a class="anchor" name="kim_preferences_edit"> Viewing and Editing the Preferences</a></h2> In order to view and edit the user's preferences, call <a class="el" href="group__kim__preferences__reference.html#gf1dc483fcb582add046d552da9b8485f" title="Create a new preferences object from the current user's preferences.">kim_preferences_create()</a> to acquire a preferences object containing the user's preferences. You can examine preferences with the functions starting with "kim_preferences_get_" and change preferences with the functions starting with "kim_preferences_set_". Once you are done making changes, you can write changes back out to the user's preferences with <a class="el" href="group__kim__preferences__reference.html#g6815e374d78e13714abcddc478145dd9" title="Synchronize a preferences object with the user's preferences, writing pending...">kim_preferences_synchronize()</a>.<p> <dl class="note" 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> <h2><a class="anchor" name="kim_preferences_options"> Initial Credential Options Preferences</a></h2> KIM provides user preferences for initial credential options. These are the options <a class="el" href="group__kim__options__reference.html#ge36eb288b38f18491e4c903f008b1379" title="Create new options with default values.">kim_options_create()</a> will use when creating a new KIM options object. They are also the options specified by KIM_OPTIONS_DEFAULT. You can view and edit the initial credential options using <a class="el" href="group__kim__preferences__reference.html#g68f6bb5bd97d85753d74e958e452560f" title="Get the user's preferred options.">kim_preferences_get_options()</a> and <a class="el" href="group__kim__preferences__reference.html#gc9c1f77fcf571c575664b44267f19fc3" title="Set the user's preferred options.">kim_preferences_set_options()</a>.<p> <dl class="note" compact><dt><b>Note:</b></dt><dd>Not all credential options in the kim_options_t object have corresponding user preferences. For example, the prompt callback function is not stored in the user preferences since it has no meaning outside of the current application. Some options which are not currently stored in the preferences may be stored there in the future.</dd></dl> If you are implementing a user interface for credentials acquisition, you should be aware that KIM has a user preference to manage the initial credential options preferences. If the user successfully acquires credentials with non-default options and <a class="el" href="group__kim__preferences__reference.html#ga4b2b54310c0efb6bbba284395095c0f" title="Get whether or not to remember the last options the user used to acquire a credential...">kim_preferences_get_remember_options()</a> is set to TRUE, you should store the options used to get credentials with <a class="el" href="group__kim__preferences__reference.html#gc9c1f77fcf571c575664b44267f19fc3" title="Set the user's preferred options.">kim_preferences_set_options()</a>.<h2><a class="anchor" name="kim_preferences_client_identity"> Client Identity Preferences</a></h2> KIM also provides user preferences for the default client identity. This identity is used whenever KIM needs to display a graphical dialog for credential acquisition but does not know what client identity to use. You can view and edit the default client identity using <a class="el" href="group__kim__preferences__reference.html#g7e8243e83781035aef702b1882114e57" title="Get the user's preferred client identity.">kim_preferences_get_client_identity()</a> and <a class="el" href="group__kim__preferences__reference.html#g531087a0c7ec0e247eff326066e31b42" title="Set the user's preferred client identity.">kim_preferences_set_client_identity()</a>.<p> If you are implementing a user interface for credentials acquisition, you should be aware that KIM has a user preference to manage the client identity preferences. If the user successfully acquires credentials with non-default options and <a class="el" href="group__kim__preferences__reference.html#g9113eb1a092a9c745d9b724f7890ecb6" title="Get whether or not to remember the last client identity the user acquired a credential...">kim_preferences_get_remember_client_identity()</a> is set to TRUE, you should store the client identity for which credentials were acquired using <a class="el" href="group__kim__preferences__reference.html#g531087a0c7ec0e247eff326066e31b42" title="Set the user's preferred client identity.">kim_preferences_set_client_identity()</a>.<h2><a class="anchor" name="kim_preferences_favorite_identities"> Favorite Identities Preferences</a></h2> As Kerberos becomes more widespread, the number of possible Kerberos identities and realms a user might want to use will become very large. 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. Users may also use multiple identities from the same realm.<p> On platforms which use a GUI to acquire credentials, the KIM would like to to display a list of identities for the user to select from. Depending on what is appropriate for the platform, identities may be displayed in a popup menu or other list.<p> To solve this problem, the KIM maintains a list of favorite identities specifically for identity selection. This list is a set of unique identities in alphabetical order (as appropriate for the user's language localization).<p> Each identity may optionally have its own options for ticket acquisition. This allows KIM UIs to remember what ticket options worked for a specific identity. For example if the user normally wants renewable tickets but they have one identity at a KDC which rejects requests for renewable tickets, the "not renewable" option can be associated with that identity without changing the user's default preference to get renewable tickets. If an identity should use the default options, just pass KIM_OPTIONS_DEFAULT.<p> Most callers will not need to use the favorite identities 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 identities.<h2><a class="anchor" name="kim_favorite_identities_edit"> Viewing and Editing the Favorite Identities</a></h2> First, you need to acquire the Favorite Identities stored in the user's preferences using <a class="el" href="group__kim__preferences__reference.html#gf1dc483fcb582add046d552da9b8485f" title="Create a new preferences object from the current user's preferences.">kim_preferences_create()</a>.<p> Then use <a class="el" href="group__kim__preferences__reference.html#g39ff3407953fedfc861efda92f961f18" title="Get the number of favorite identities in a preferences object.">kim_preferences_get_number_of_favorite_identities()</a> and <a class="el" href="group__kim__preferences__reference.html#g3012077dfb1169ebbbf2d7bf17dbbfdf" title="Get the Nth favorite identity in a preferences object.">kim_preferences_get_favorite_identity_at_index()</a> to display the identities list. Use <a class="el" href="group__kim__preferences__reference.html#gd7ed54017b8d46414c550a87ab775a9d" title="Add a favorite identity to a preferences object.">kim_preferences_add_favorite_identity()</a> and <a class="el" href="group__kim__preferences__reference.html#g85a31ca25607660c9dc2b68527c71f52" title="Remove a favorite identity from a preferences object.">kim_preferences_remove_favorite_identity()</a> to change which identities are in the identities list. Identities are always stored in alphabetical order and duplicate identities are not permitted, so when you add or remove a identity you should redisplay the entire list. If you wish to replace the identities list entirely, use <a class="el" href="group__kim__preferences__reference.html#gc28596bde36d790f569af33d50feedb8" title="Remove all favorite identities in a preferences object.">kim_preferences_remove_all_favorite_identities()</a> to clear the list before adding your identities.<p> Once you are done editing the favorite identities list, store changes in the user's preference file using <a class="el" href="group__kim__preferences__reference.html#g6815e374d78e13714abcddc478145dd9" title="Synchronize a preferences object with the user's preferences, writing pending...">kim_preferences_synchronize()</a>.<p> See <a class="el" href="group__kim__preferences__reference.html">KIM Preferences Documentation</a> for information on specific APIs. <hr size="1"><address style="text-align: right;"><small>Generated on Mon Nov 3 17:45:44 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>
Back to File Manager