KIM Favorite Realms Overview

Introduction

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.

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.

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.

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.

Note:
The location of user preferences and the semantics of preference synchronization is platform-specific. Where possible KIM will use platform-specific preference mechanisms.
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.

Viewing and Editing the Favorite Realms

First, you need to acquire the Favorite Realms stored in the user's preferences using kim_preferences_create() and kim_preferences_get_favorite_realms(). Or you can use kim_favorite_realms_create() to get an empty realms list if you want to overwrite the user's realms list entirely. See KIM Preferences Overview for more information on modifying the user's preferences.

Then use kim_favorite_realms_get_number_of_realms() and kim_favorite_realms_get_realm_at_index() to display the realms list. Use kim_favorite_realms_add_realm() and kim_favorite_realms_remove_realm() 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.

Once you are done editing the realms list, store changes in the user's preference file using kim_preferences_set_favorite_realms() and kim_preferences_synchronize().

See KIM Favorite Realms Documentation for information on specific APIs.