Projects/Credential cache collection improvements - Revision history

Ghudson: /* Documentation */

2015-03-24T15:45:38Z

‎Documentation

Ghudson at 17:02, 16 September 2014

2014-09-16T17:02:56Z

Ghudson: /* APIs */

2014-09-11T15:27:00Z

‎APIs

Ghudson at 22:02, 28 August 2014

2014-08-28T22:02:37Z

Ghudson: New page: {{project-early}} This project page is a grab-bag of credential cache collection issues and improvements, some user-visible and some internal. As it proposes only loosely-related interna...

2014-08-28T21:35:55Z

New page: {{project-early}} This project page is a grab-bag of credential cache collection issues and improvements, some user-visible and some internal. As it proposes only loosely-related interna...

New page

{{project-early}}

This project page is a grab-bag of credential cache collection issues and improvements, some user-visible and some internal. As it proposes only loosely-related internal improvements, it will probably not become a formal project page.

==Background==

The concept of a credential cache collection began in release 1.6 with the introduction of the krb5_cccol APIs. In release 1.10, the [[Projects/Client_principal_selection|client principal selection]] project implemented the collection-enabled DIR credential cache type, collection behavior for kinit, klist, and kdestroy, and added the new kswitch command. The behavior of tools on credential cache collections was based largely on the behavior of Heimdal, whose collection semantics in turn were based loosely on Kerberos for Macintosh.

Credential cache types are either collection-enabled (such as DIR) or not (such as FILE). For a collection-enabled type, the residual string may identify a collection (such as DIR:/path/to/directory) or a subsidiary cache within the collection (such as DIR::/path/to/directory/tktXXXXXX). A collection has a primary cache which can be altered by krb5_cc_switch or the kswitch command. Resolving the name of a collection yields a cache whose name is the primary cache within that collection.

If the default credential cache name uses a collection-enabled type, command-line tools behave differently as described in [[Projects/Client_principal_selection#Tool_alterations_to_use_cache_collection|the client principal selection project page]]. Also, GSSAPI client applications will automatically select client principals based on the $HOME/.k5identity file or the realm of the target server.

The krb5_cccol APIs define "the collection" as the union of all per-type collections. These APIs do not accept the name of a particular collection, but the default ccache name of the krb5_context object influences what is in per-type collections. Except for MEMORY, no ccache type adds caches to the collection unless it is used by the default ccache name. If the default ccache name indicates a subsidiary cache for a collection-enabled type, the ccache type only adds the subsidiary cache to the collection, not the full collection contents.

==Possible improvements==

===Documentation improvements===

Collection behavior is described in various parts of the documentation, but there is no documentation dedicated to its use. There is also no documentation of how a ccache type should implementation collection semantics; this documentation would be of internal use only for the moment, but could become public-facing if we implement loadable ccache modules.

===Getting credentials for secondary use===

"kinit princname" with a collection-enabled default cache switches the primary cache to the newly-obtained credentials. If the credentials are being acquired for secondary use, this is inconvenient, as it typically affects all shells and applications within the login system. There are several common use cases like this: the user may be acquiring root instance credentials for use with specific commands, or credentials in a second realm for use only in contacting servers of that realm.

Heimdal implements kinit --no-change-default which overrides this behavior; we do not yet implement it. Implementing this flag in MIT krb5 would be complicated by the lack of long option support in the Unix versions of our tools. It should perhaps have a short option name anyway for convenience.

Explicitly using secondary credentials for an individual shell command is not as easy as it should be; the user has to use "klist -l" to identify the subsidiary cache name, then set the KRB5CCNAME environment variable to that name. One possible solution is to make kswitch support running a command with KRB5CCNAME set to a subsidiary ccache, instead of switching the primary cache for the collection.

===Memory caches===

The MEMORY cache type should probably behave like the FILE cache type, adding no caches to the collection except for the default cache if it is a MEMORY cache. Since 1.10, we have not encountered any benefits of adding all MEMORY caches to the collection, and have encountered minor costs (such as ksu having to use a bogus client principal name for its temporary memory cache).

===Programmatic interfaces===

At least three parts of the system (kinit, ksu, and gss_acquire_cred) decide where to place new credentials for a principal using similar logic. We could provide a library API which implements this logic.

Deciding whether to use collection-enabled semantics currently relies on the result of krb5_cc_support_switch on the cache type. This creates some edge cases which are arguably bugs; for example, if KRB5CCNAME is set to a subsidiary cache name for "kinit princname", kinit will report a confusing error rather than overwriting the cache with a different principal. We could instead introduce a krb5_cc_is_collection API which accepts a ccache name.

==Other discussions==

http://news.gmane.org/gmane.comp.encryption.kerberos.heimdal.general

@@ Line 51: / Line 51: @@
 We will add new pages to doc/user and to doc/appdev describing cache collections from the user and API viewpoints.
-There existing documentation of collection behavior in gssapi.rst, ccache_def.rst, ccselect.rst, klist.rst, kinit.rst, kswitch.rst, kdestroy.rst, k5identity.rst, env_variables.rst, and krb5_conf.rst will be updated to reflect the new architecture.
+The existing documentation of collection behavior in gssapi.rst, ccache_def.rst, ccselect.rst, klist.rst, kinit.rst, kswitch.rst, kdestroy.rst, k5identity.rst, env_variables.rst, and krb5_conf.rst will be updated to reflect the new architecture.
 ==Other discussions==

@@ Line 33: / Line 33: @@
 ===APIs===
-At least three parts of the system (kinit, ksu, and gss_acquire_cred) decide where to place new credentials for a principal using similar logic.  We could provide a library API which implements this logic.
+At least three parts of the system (kinit, ksu, and gss_acquire_cred) decide where to place new credentials for a principal using similar logic, and gss_store_cred will likely do so in the future (see {{bug|8010}}).  We could provide a library API which implements this logic.
 Deciding whether to use collection-enabled semantics currently relies on the result of krb5_cc_support_switch on the cache type.  This creates some edge cases which are arguably bugs; for example, if KRB5CCNAME is set to a subsidiary cache name for "kinit princname", kinit will report a confusing error rather than overwriting the cache with a different principal.  We could instead introduce a krb5_cc_is_collection API which accepts a ccache name.

@@ Line 1: / Line 1: @@
 {{project-early}}
 ==Background==
@@ Line 7: / Line 7: @@
 The concept of a credential cache collection began in release 1.6 with the introduction of the krb5_cccol APIs.  In release 1.10, the [[Projects/Client_principal_selection|client principal selection]] project implemented the collection-enabled DIR credential cache type, collection behavior for kinit, klist, and kdestroy, and added the new kswitch command.  The behavior of tools on credential cache collections was based largely on the behavior of Heimdal, whose collection semantics in turn were based loosely on Kerberos for Macintosh.
-Credential cache types are either collection-enabled (such as DIR) or not (such as FILE).  For a collection-enabled type, the residual string may identify a collection (such as DIR:/path/to/directory) or a subsidiary cache within the collection (such as DIR::/path/to/directory/tktXXXXXX).  A collection has a primary cache which can be altered by krb5_cc_switch or the kswitch command.  Resolving the name of a collection yields a cache whose name is the primary cache within that collection.
+Credential cache types are either collection-enabled (such as DIR) or not (such as FILE).  For a collection-enabled type, the residual string may identify a collection (such as DIR:/path/to/directory) or a subsidiary cache within the collection (such as DIR::/path/to/directory/tktXXXXXX).  A collection has a primary cache which can be altered by krb5_cc_switch or the kswitch command.  Resolving the name of a collection yields a cache handle for the primary cache within that collection.
 ==Other discussions==