Projects/KCM client
Contents
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.
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.
