Projects/Client principal selection

This is an early stage project for MIT Kerberos. It is being fleshed out by its proponents. Feel free to help flesh out the details of this project. After the project is ready, it will be presented for review and approval.

This project is targeted at release 1.10.

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.

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 id);

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. Destroying a DIR:dirname cache destroys all caches within the directory.

• 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.