Projects/KCM client

This project was completed in release 1.13.

Background

Heimdal implements a credential cache type named "KCM" where operations are transmitted to a daemon process which manages the actual cache contents. The KCM daemon can be contacted via a Unix domain socket or, on OS X only, via Mach RPC. (There is also incomplete support in the source code for using Doors on Solaris.)

On OS X 10.7 and later, the native default credential cache type uses the KCM protocol via Mach RPC. It is typically referred to via the "API" cache type for continuity with Kerberos for Macintosh; the API and KCM cache types have the same namespace in the native OS X Kerberos.

Kerberos for Windows and Kerberos for Macintosh also implement a daemon-based cache type named "API". It uses a different protocol and transports.

Scope

This project adds support for the KCM cache type within libkrb5. It does not implement a KCM server. The primary short-term benefit is to allow access to the native default credential cache on OS X. The default ccache name in a default built of krb5 on OS X 10.7+ will become "KCM:" instead of "FILE:/tmp/krb5cc_%{uid}".

Protocol notes

The KCM transports implement a simple request-response protocol where requests and responses are byte strings of known length. Responses are accompanied with a status code.

A request byte string begins with an 8-bit major version, an 8-bit minor version, and a 16-bit big-endian opcode. A response byte string begins with a 32-bit big-endian status code. Beyond the header, requests and responses can contain concatenated parameters of the following types:

• Cache name: a string of bytes terminated by a 0 byte
• Flag words and time offsets: 32-bit big-endian integers
• Principals and credentials: marshalled in the version 4 FILE cache format
• Matching credentials: see below
• UUID lists: a concatenation of zero or more 16-byte UUID strings (not delimited, so must appear last within a request or response)

Matching credentials are marshalled similarly to credentials, but begin with a flag word indicating which fields are present. Fields not present in the flag word are omitted from the marshalling.

Behavior notes

Two new profile variables in [libdefaults], kcm_mach_service and kcm_socket, will determine the bootstrap service and Unix socket address used to contact the KCM daemon. The defaults are the hardcoded values used in Heimdal.

The KCM client code will only place KCM caches in the global collection if the context's default ccache uses the KCM type. This has a minor performance advantage, in that we won't routinely attempt to contact a KCM daemon on hosts which don't run one. It also yields less surprising behavior in many user situations; see, for example, this discussion on the Heimdal mailing list: http://kerberos.996246.n3.nabble.com/KRB5CCNAME-new-semantics-under-Maverick-td40272.html

The KCM protocol does not contain an opcode for getting the last change time of a cache, so for now the KCM cache type will return the last change time made through the cache handle, which is mostly useless. The KEYRING ccache type behaves similarly.

Testing

Automated testing as part of "make check" is currently impossible, even if we can find a Heimdal kcm program in the path, because Heimdal's KCM daemon cannot be configured to change the location of its Unix domain socket. (It has a '-s' option which is supposed to do so, but it isn't implemented.) Text will be added to Manual_Testing describing how to test this cache type. When we implement our own KCM daemon, we can create automated tests.

Documentation

krb5_conf.rst will be amended to describe the two new credential cache profile variables. ccache_def.rst will be amended to describe the KCM cache type.

Commmits

   651f3af251d172361a954f55f2d87561ae42c2d0 Modify k5buf interfaces for easier use
   8641f87bab24926688a91590040e5b8903e10897 Adjust marshalling interfaces for KCM
   2fa226e13ee3e7a6fddbfb68b27ed6b2c14c8474 Add KCM credential cache type (client only)
   f2aabecc10508c01b289e147a4c5f41969ab768f Make KCM the default ccache on OS X
   4ac345865276e8848546ba75e09feecc23e8a040 Document KCM ccache type

Finished in [krbdev.mit.edu #7964].

Release notes

User experience:

• Add client support for the Kerberos Cache Manager protocol. If the host is running a Heimdal kcm daemon, caches served by the daemon can be accessed with the KCM: cache type.

• When built on OS X 10.7 and higher, use "KCM:" as the default cache type, unless overridden by command-line options or krb5-config values.