Projects/Authentication indicator

From K5Wiki
Jump to: navigation, search
This project was completed in release 1.14.

This project will implement a way to restrict access to services based on how the initial authentication was performed.


Kerberos deployments may support pre-authentication mechanisms, such as PKINIT or OTP, which may confer a higher level of confidence in the authentication than the use of a password alone. A deployment may wish to require that some resources can only be accessed using tickets which were obtained using high-confidence pre-authentication.

Currently, the most practical way to enforce this requirement is to make sure that certain principals can only authenticate using high-confidence pre-authentication, and then grant resource access only to those principals. Such principals may be separated from the principals used for day-to-day activities of the end-user by giving them different names (e.g. ghudson/root@ATHENA.MIT.EDU as opposed to ghudson@ATHENA.MIT.EDU), at the cost of complicating realm administration and auditing.

This project will implement a means of restricting access without requiring that a principal always authenticates using high-strength pre-authentication, by marking how the ticket was initially obtained. The Kerberos protocol defines several existing methods for doing this, none of which are sufficiently general:

  • The pre-authent ticket flag indicates that some form of prea-authentication was used, but does not indicate what it was.
  • The hw-authent ticket flag was intended to indicate that a hardware device was used during pre-authentication. It is rarely used, as the KDC usually cannot tell whether a client used a software or hardware device to produce a certificate or OTP token value. While it could be re-purposed to mean "high-confidence pre-authentication" in general, it would still be poorly defined and not very granular.
  • PKINIT (RFC 4556) defines the AD_INITIAL_VERIFIED_CAS authdata type, which shows the certification path of the client certificate. This type is specific to PKINIT, and would be cumbersome for an application server to use as it would have to be configured with specific knowledge about PKINIT certification authorities. There is no equivalent for FAST OTP.
  • RFC 6113 defines AD-authentication-strength, which contains the numeric codes of the pre-authentication types used to authenticate the client, and possibly additional information for each type (but no additional information is currently defined). Again, to use this element, an application server would have to be configured with specific knowledge about pre-authentication mechanisms and the confidence they confer.


This project will implement the AUTHENTICATION-INDICATOR element defined in draft-ietf-kitten-krb-auth-indicator. The KDC makes a determination about pre-authentication confidence at the time of initial authentication, and communicates this to services via one or more site-defined string values. The AUTHENTICATION-INDICATOR element is carried within a CAMMAC (draft-ietf-kitten-cammac), which allows it to be carried from the evidence ticket of an S4U2PROXY request into the delegated ticket.

Access restriction based on AUTHENTICATION-INDICATOR may take place either within a KDC through its ticket policy, or on the application server itself. The latter option allows more fine-grained access control, but also requires changes to application server code. This project will cover only enforcement on the KDC; enforcement on application servers will be a follow-on project.

This project must be useful with the built-in KDB modules. A third-party KDB module may provide additional input into the process, but basic functionality must be present in the core system.


Structural improvements

The KDC authorization data facilities currently center around a private pluggable interface which predates Projects/Plugin support improvements. All internal operations are funneled through that interface's function signature. This interface will be converted to a new-style pluggable interface, which will remain private. Internal operations will be decoupled from the interface and will be directly invoked from handle_authdata(), using signatures tailored to the needs of the specific operation.

AS and TGS requests often load a krbtgt principal entry as part of their processing, but do not always. The current authorization data code makes the assumption that the AS server principal or TGS header ticket server principal are krbtgt principals, and that the principal loaded has the same current key data as for previous operations on the ticket. As a result, there are some obscure bugs in AD-SIGNTICKET processing, and there would be similar bugs in CAMMAC processing if we followed the same assumption. The KDC code will be augmented to load the server realm's local krbtgt principal if it was not already loaded, and the AD-SIGNTICKET code will use that principal entry for its checksums.

CAMMAC and indicator encoding

Private ASN.1 encoders and decoders for CAMMACs and sequences of UTF-8 strings (for auth indicators) will be added to lib/krb5/asn.1.

The KDC will contain functions to generate and verify CAMMACs and to manage lists of authentication indicators. Public interfaces for these data types are not required for the current phase of the project.

The CAMMAC specification allows the kdc-verifier and svc-verifier to be omitted in certain cases. The initial implementation will not include those space optimizations.

Deciding on indicators

The kdcpreauth interface will receive a new callback which allows a module to assert an authentication indicator. The OTP and PKINIT kdcpreauth modules will read configuration options which cause them to assert indicators.

In the future, the KDB module (or a future KDC module type) could participate in this decision based on parameters generated by the kdcpreauth module. Such a facility is not in scope for the initial implementation.

AS and TGS requests

During AS request processing, indicators may be asserted by kdcpreauth modules. These indicators will be passed to handle_authdata(), encoded as sequence of UTF-8 strings, and wrapped in CAMMAC and IF-RELEVANT containers for the issued ticket.

During TGS request processing, indicators will be extracted from the header ticket for normal TGS requests, from the evidence ticket for S4U2Proxy requests, and not at all for S4U2Self requests. Any extracted indicators will be included in the issued ticket.

Cross-realm support requires a certain measure of trust in the remote realm to accurately represent how that realm's clients authenticated. It may also be necessary to translate indicator values if the two realms do not use the same naming semantics. For the initial implementation, indicators will not be accepted from cross-realm TGS header tickets. In the future a string attribute may be added to authorize a cross-realm TGS principal to propagate specific indicator values. Translation of values will probably need to be performed by a plugin module (perhaps the KDB module); this feature is also deferred to the future.

Indicator enforcement

For either an AS or TGS request, if the server principal has the require_auth string attribute set, one of the indicators listed in the attribute value must have been asserted or the KDC will reject the request with a policy error.

A service with a required indicator will currently fail all S4U2Self operations, because the real client did not authenticate and therefore no indicator was asserted. In the future, we may develop a simple protocol for services to request indicators to be asserted during S4U2Self operations, and a simple authorization framework for the KDC to decide what indicators a service is allowed to assert (probably the same authorization framework as for cross-realm indicator suport).

In the future the KDB module (or perhaps a future KDC policy module) could participate in this decision. This feature is not part of the initial implementation.


As part of the KDC authdata refactoring work, a C harness will be written for the tests directory which obtains a service ticket with optional request authdata, decrypts it, and displays the leaf authdata contained in the ticket with annotations for any authdata container along the path to the leaf. Tests will be written to verify most of the existing logic for including authdata in the ticket.

Currently, test scripts cannot easily simulate successful S4U2Proxy operations as the default KDB module always rejects constrained delegation requests. A read-only test KDB module will be written which can be used to exercise this and other KDC behavior. The module will read all of its results from the profile, making it easy to control them from the test script.

A test preauth module will be written so that test scripts can easily control the authenticated indicators asserted during an AS request without having to set up PKINIT or OTP. The clpreauth module will transmit the desired indicators (specified using kinit -X) to the kdcpreauth module, which will assert them without performing any meaningful preauthentication.

Currently S4U2Proxy can only be tested by using the GSSAPI harnesses in tests/gssapi, or by using kvno -P which requires also performing S4U2Self. A simple S4U2Proxy test harness will be written for the tests/ directory.

Tests will be written to cover the major cases: AS requests to the local TGS, cross TGS, and service principals; regular TGS requests to the local TGS, cross TGS, and service principals; ticket modifications requests; S4U2Self requests; and S4U2Proxy requests.


A new page admin/auth_indicator.rst will document how to use auth indicators within a realm. The new kdcpreauth callback, configuration variables, and string attributes will be documented in the appropriate places.


  • [krbdev.mit.edu #8157]

CAMMAC discussions on the kitten working group list:

Authentication indicator discussions on the kitten working group list:


Test KDB module:

   c8608c52646a10503b1a950f8df5072d0a583604 Add test KDB module
   e732d9dc3f2e7b01ff3c8305d58a3a754c9e9ec5 Add successful S4U2Proxy test cases

KDC authdata refactoring:

   c96fe6c87a69122e6b699385f52a959d375ca4bb Get rid of static KDC authdata systems
   d87fffd66c208cf6f13d17e4a5e911c2b259db24 Add declarations for new KDC authdata interface
   c538feaaaeb63161c87e965f88d3b3f2795aefc9 Use new KDC authdata interface in kdc_authdata.c
   4325964a5d472422cb0a1600676787d7bcfde5d2 Modernize kdc_authdata.c
   b9820f5b3bfe1347565a39b6f8dce97828e8a2a3 Update test KDC authdata module to new interface
   1c3c40454f18f2165b959e6ecd856d5ddbbcb4c2 Add KDC authdata tests

Loading local TGT:

   7cad84e1df664f9a1513a2899661bf2b62908dd7 Rename krbtgt variable in KDC code
   39548a5b17bbda9eeb63625a201cfd19b9de1c5b Load local TGT in KDC requests
   0c6498b2b9f4f4ad8b9f224714c84714425f2ca3 Use local TGT for AD-SIGNTICKET processing
   1f2060ee1793f1acea81acefa6a8b1e0da4203ce Add tests for AD-SIGNTICKET corner cases
   73efbee640e18ffc53ff4e08c0ce940fb726dcd4 Fix make_signedpath_checksum() initialization bug

CAMMAC and authentication indicator support:

   6a06997f5f15ba81e196ac20c15b0ba17954ac6c Add ASN.1 encoder and decoder for CAMMAC
   d0f63158c3b0e9ebfe76c56136a575b41ec12642 Add ASN.1 encoder/decoder for UTF-8 strings
   4df561263da85d4683864e24de74df3bee18593e Add constants for CAMMAC and auth-indicator
   a19109fffc70cabcabab00d00bf65ea85fd33e1a Filter CAMMAC authdata from non-KDC sources
   5b39ea2b4ed54f4f208246b3cb725e7b1113d047 Add KDC CAMMAC and auth indicator functions
   dd95e18f5cfa426db0f265172202debd257f3cdb Add kdcpreauth callback for auth indicators
   7601a1c9e103b148d94974bb2ba0c85969055c65 Add authentication indicators in AS-REQs
   97973cf89cdc18a80c2bf5450caa1548c5be0b7b Propagate auth indicators in TGS requests
   24dc279b9b14fe8d6674fdd2a9210c1e1fb52e37 Enforce auth indicator restrictions in KDC
   e64140aba967e3d8a785d4f83b1477ed0bdc85bd Test auth indicator functionality
   e6e6e54e89bc9644144436c3f267796ed790f70c Add indicator support to OTP
   8ca82f0e3059cd8805f4dda388a8aa1d67c80920 Add indicator support to PKINIT
   491b012b49ce687ffd4a26f5d0f6114d8411d04d Document authentication indicators

Release notes

Administrator experience:

  • Add support for authentication indicators, which are ticket annotations to indicate the strength of the initial authentication. Add support for the "require_auth" string attribute, which can be set on server principal entries to require an indicator when authenticating to the server.

Developer experience:

  • Add an add_auth_indicator() callback to the kdcpreauth interface, allowing pre-authentication modules to assert authentication indicators.