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.
In order to view and edit the user's preferences, call kim_preferences_create() 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 kim_preferences_synchronize().
- Note:
- The location of user preferences and the semantics of preference synchronization is platform-specific. Where possible KIM will use platform-specific preference mechanisms.
KIM provides user preferences for initial credential options. These are the options kim_options_create() 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 kim_preferences_get_options() and kim_preferences_set_options().
- Note:
- 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.
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 kim_preferences_get_remember_options() is set to TRUE, you should store the options used to get credentials with kim_preferences_set_options().
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 kim_preferences_get_client_identity() and kim_preferences_set_client_identity().
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 kim_preferences_get_remember_client_identity() is set to TRUE, you should store the client identity for which credentials were acquired using kim_preferences_set_client_identity().
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.
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.
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).
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.
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.
First, you need to acquire the Favorite Identities stored in the user's preferences using kim_preferences_create().
Then use kim_preferences_get_number_of_favorite_identities() and kim_preferences_get_favorite_identity_at_index() to display the identities list. Use kim_preferences_add_favorite_identity() and kim_preferences_remove_favorite_identity() 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 kim_preferences_remove_all_favorite_identities() to clear the list before adding your identities.
Once you are done editing the favorite identities list, store changes in the user's preference file using kim_preferences_synchronize().
See KIM Preferences Documentation for information on specific APIs.
Generated on Mon Nov 3 17:45:44 2008 for Kerberos Identity Management by
1.5.3