Difference between revisions of "Projects/KCM client"

Revision as of 11:47, 11 July 2014

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.

Limitations

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

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

TBD

Mailing list discussions

Release notes

TBD