Projects/Client principal selection
This project's goal is to extend the core krb5 code to allow users to maintain credentials for multiple identities and for the GSSAPI client code to automatically select credentials based on the target service and hostname.
Background and previous work
Existing cache collection APIs
MIT krb5 and Heimdal implement the functions krb5_cccol_cursor_new(), krb5_cccol_cursor_next(), and krb5_cccol_cursor_free() to iterate over a global collection of credential caches. The caller does not provide any name or hint information for the location of the collection, other than a krb5 library context.
The MIT implementation of this API yields the context default cache, the default cache from the environment (if different), the OS default cache (if different), and then a series of caches determined by each available cache type. The FILE type yields all currently open (resolved and not closed) FILE caches. The MEMORY type yields all existing (created and not destroyed) memory ccaches within the process. The API type (on non-Unix platforms) yields all caches held by the daemon.
The Heimdal implementation of this API yields a series of caches determined by each available cache type. The FILE type yields the context default cache if it is of type FILE. The MEMORY type yields all existing memory caches within the process. The API and KCM types yield all caches held by the daemon for the uid of the requesting process.
Heimdal also supports the function krb5_cc_cache_match() to search the collection for a cache whose default principal matches a specified principal, and the functions krb5_cc_cache_get_first() and krb5_cc_cache_next() to iterate over the caches for a specified type.
In MIT krb5 and Heimdal, the function krb5_cc_new_unique() generates a new unique cache of a specified type. The function takes a "hint" parameter, but it is currently unused and there is no guidance on how to set it.
Heimdal supports the function krb5_cc_switch() to select a cache as the persistent default for its cache type. The function krb5_cc_support_switch() queries whether a cache type supports the switch operation.
KIM and KfM
Heimdal
Architectural components
Additions to the ccache API
The krb5_cc_switch(), krb5_cc_support_switch(), and krb5_cc_cache_match() APIs from Heimdal will be added to MIT krb5. They have the following signatures:
krb5_boolean krb5_cc_support_switch(krb5_context context, const char *type);
krb5_error_code krb5_cc_switch(krb5_context context, krb5_ccache id);
krb5_error_code krb5_cc_cache_match(krb5_context context,
krb5_principal client, krb5_ccache *ccache);
The DIR credential cache type
Currently, no cache type available on Unix supports a persistent collection of caches. There is an early project to port CCAPI to Unix, but it is unclear how much time this would take to complete. Also, some deployments might prefer a more lightweight option, or an option which works over distributed filesystems.
A DIR cache is represented in the filesystem by a directory (which must be created out of band) containing zero or more cache files in FILE format, each with a name beginning with "tkt". The directory also contains a file named "selection" (which will be created automatically on first access) containing a single line naming the currently selected cache.
Caches of type DIR have one of two forms:
- DIR:dirname refers to the selected cache file within the directory for cache operations, and to the collection itself for type operations.
- DIR::pathname refers to a subsidiary cache file within the directory. Switching to a cache of this type updates the selection file to refer to the named file.
Because the krb5_cccol and krb5_cc_new_unique APIs do not name the collections they operate on, we use the context default cache name for this purpose. If the default cache name is of the form DIR:dirname, then the DIR cache type will add the caches within that directory to the collection as DIR::pathname caches and will generate new caches within that directory. If the default cache name is not of this form, the DIR type will yield no caches in the global connection, and attempting to create a new unique cache of the DIR type will return an error.
Tool alterations to use cache collection
The following tool behavior changes will be implemented, modeled after similar changes in Heimdal:
- kdestroy -a will destroy all caches in the collection.
- If the default cache type supports switching, "kinit princname" will search the collection for a matching cache and store credentials there, or will store credentials in a new unique cache of the default type if no existing cache for the principal exists. Either way, kinit will switch to the selected cache.
- klist -l will list the caches in the collection.
- klist -A will show the content of all caches in the collection.
- kswitch -p princname will search the collection for a matching cache and switch to it.
- kswitch -c cachename will switch to a specified cache.
kswitch is a new command.
Changes to the krb5_cccol implementation
The three "high-priority" caches (context default, environment default, and OS default) will be removed from the cache collection, so the cache collection iterates only over the per-type cursors. Instead, following Heimdal's lead, the FILE type will yield the default ccache if it is of type FILE, in addition to its usual list.
There are three reasons for this. First, it is inappropriate to include a default cache which has been overridden by another mechanism; for instance, kdestroy -A should not destroy the per-uid OS default file ccache if KRB5CCNAME has been set to something else. Second, if the default ccache name is of type DIR:dirname, yielding the default ccache in addition to all of the subsidiary DIR::pathname ccaches would wind up duplicating the primary ccache. Third, this change makes our behavior closer to Heimdal's, which is generally beneficial.
