The kdcpreauth interface allows the addition of KDC support for
preauthentication mechanisms beyond those included in the core MIT
krb5 code base. For a detailed description of the kdcpreauth
interface, see the header file <krb5/kdcpreauth_plugin.h>
(or
<krb5/preauth_plugin.h>
before release 1.12).
A kdcpreauth module is generally responsible for:
PA_REPLACES_KEY
flag. If the mechanism
is generally only used with hardware tokens, the PA_HARDWARE
flag allows the mechanism to work with principals which have the
requires_hwauth flag set.A module can create and destroy per-KDC state objects by implementing the init and fini methods. Per-KDC state objects have the type krb5_kdcpreauth_moddata, which is an abstract pointer types. A module should typically cast this to an internal type for the state object.
A module can create a per-request state object by returning one in the verify method, receiving it in the return_padata method, and destroying it in the free_modreq method. Note that these state objects only apply to the processing of a single AS request packet, not to an entire authentication exchange (since an authentication exchange may remain unfinished by the client or may involve multiple different KDC hosts). Per-request state objects have the type krb5_kdcpreauth_modreq, which is an abstract pointer type.
The edata, verify, and return_padata methods have access
to a callback function and handle (called a "rock") which can be used
to get additional information about the current request, including the
maximum allowable clock skew, the client's long-term keys, the
DER-encoded request body, the FAST armor key, string attributes on the
client's database entry, and the client's database entry itself. The
verify method can assert one or more authentication indicators to
be included in the issued ticket using the add_auth_indicator
callback (new in release 1.14).
A module can generate state information to be included with the next
client request using the set_cookie
callback (new in release
1.14). On the next request, the module can read this state
information using the get_cookie
callback. Cookie information is
encrypted, timestamped, and transmitted to the client in a
PA-FX-COOKIE
pa-data item. Older clients may not support cookies
and therefore may not transmit the cookie in the next request; in this
case, get_cookie
will not yield the saved information.
If a module implements a mechanism which requires multiple round
trips, its verify method can respond with the code
KRB5KDC_ERR_MORE_PREAUTH_DATA_REQUIRED
and a list of pa-data in
the e_data parameter to be processed by the client.
The edata and verify methods can be implemented asynchronously. Because of this, they do not return values directly to the caller, but must instead invoke responder functions with their results. A synchronous implementation can invoke the responder function immediately. An asynchronous implementation can use the callback to get an event context for use with the libverto API.