Document authentication indicators

Add a new file auth_indicator.rst to the admin guide.  Also document
the pkinit_indicator and OTP indicator profile variables, the
require_auth string attribute, and the add_auth_indicator kdcpreauth
callback.  Add references to the new public constants in
appdev/refs/macros/index.rst.

ticket: 8157

diff --git a/doc/admin/admin_commands/kadmin_local.rst b/doc/admin/admin_commands/kadmin_local.rst
index 5572b34cc7f4dcbaa58922f9c83d71fbbeb79a98..be874b1a5363754acce75bea460415f4fed85d30 100644 (file)
--- a/doc/admin/admin_commands/kadmin_local.rst
+++ b/doc/admin/admin_commands/kadmin_local.rst
@@ -632,6 +632,12 @@ supply per-principal configuration to the KDC and some KDC plugin
 modules.  The following string attribute names are recognized by the
 KDC:
 
+**require_auth**
+    Specifies an authentication indicator which is required to
+    authenticate to the principal as a service.  Multiple indicators
+    can be specified, separated by spaces; in this case any of the
+    specified indicators will be accepted.  (New in release 1.14.)
+
 **session_enctypes**
     Specifies the encryption types supported for session keys when the
     principal is authenticated to as a server.  See

diff --git a/doc/admin/auth_indicator.rst b/doc/admin/auth_indicator.rst
new file mode 100644 (file)
index 0000000..e971aa9
--- /dev/null
+++ b/doc/admin/auth_indicator.rst
@@ -0,0 +1,52 @@
+.. _auth_indicator:
+
+Authentication indicators
+=========================
+
+As of release 1.14, the KDC can be configured to annotate tickets if
+the client authenticated using a stronger preauthentication mechanism
+such as :ref:`PKINIT <pkinit>` or :ref:`OTP <otp_preauth>`.  These
+annotations are called "authentication indicators."  Service
+principals can be configured to require particular authentication
+indicators in order to authenticate to that service.  An
+authentication indicator value can be any string chosen by the KDC
+administrator; there are no pre-set values.
+
+To use authentication indicators with PKINIT or OTP, first configure
+the KDC to include an indicator when that preauthentication mechanism
+is used.  For PKINIT, use the **pkinit_indicator** variable in
+:ref:`kdc.conf(5)`.  For OTP, use the **indicator** variable in the
+token type definition.
+
+To require an indicator to be present in order to authenticate to a
+service principal, set the **require_auth** string attribute on the
+principal to the indicator value to be required.  If you wish to allow
+one of several indicators to be accepted, you can specify multiple
+indicator values separated by spaces.
+
+For example, a realm could be configured to set the authentication
+indicator value "strong" when PKINIT is used to authenticate, using a
+setting in the :ref:`kdc_realms` subsection::
+
+    pkinit_indicator = strong
+
+A service principal could be configured to require the "strong"
+authentication indicator value::
+
+    $ kadmin setstr host/high.value.server require_auth strong
+    Password for user/admin@KRBTEST.COM:
+
+A user who authenticates with PKINIT would be able to obtain a ticket
+for the service principal::
+
+    $ kinit -X X509_user_identity=FILE:/my/cert.pem,/my/key.pem user
+    $ kvno host/high.value.server
+    host/high.value.server@KRBTEST.COM: kvno = 1
+
+but a user who authenticates with a password would not::
+
+    $ kinit user
+    Password for user@KRBTEST.COM:
+    $ kvno host/high.value.server
+    kvno: KDC policy rejects request while getting credentials for
+      host/high.value.server@KRBTEST.COM

diff --git a/doc/admin/conf_files/kdc_conf.rst b/doc/admin/conf_files/kdc_conf.rst
index d2b468126ece5be9818be28d0505bd0787a6993c..80a43f63df4d13be671738295cf4f200ea8be767 100644 (file)
--- a/doc/admin/conf_files/kdc_conf.rst
+++ b/doc/admin/conf_files/kdc_conf.rst
@@ -578,6 +578,11 @@ For each token type, the following tags may be specified:
     passed to the RADIUS server.  Otherwise, the realm will be
     included.  The default value is ``true``.
 
+**indicator**
+    This tag specifies an authentication indicator to be included in
+    the ticket if this token type is used to authenticate.  This
+    option may be specified multiple times.  (New in release 1.14.)
+
 In the following example, requests are sent to a remote server via UDP::
 
     [otp]
@@ -671,6 +676,11 @@ For information about the syntax of some of these options, see
     Specifies the location of the KDC's X.509 identity information.
     This option is required if pkinit is to be supported by the KDC.
 
+**pkinit_indicator**
+    Specifies an authentication indicator to include in the ticket if
+    pkinit is used to authenticate.  This option may be specified
+    multiple times.  (New in release 1.14.)
+
 **pkinit_kdc_ocsp**
     Specifies the location of the KDC's OCSP.
 

diff --git a/doc/admin/index.rst b/doc/admin/index.rst
index 3cd57f524236059922df6487bfaab56507ec213a..b702f4021452bdbd77befa02c5eefd83d16373a8 100644 (file)
--- a/doc/admin/index.rst
+++ b/doc/admin/index.rst
@@ -18,6 +18,7 @@ For administrators
    princ_dns.rst
    enctypes.rst
    https.rst
+   auth_indicator.rst
 
 .. toctree::
    :maxdepth: 1

diff --git a/doc/appdev/refs/macros/index.rst b/doc/appdev/refs/macros/index.rst
index 5fa1aabd61e9d57fd9c2d0c047287f8e6c35f529..7b0712265de280138e7744689b60d505c8aaafa1 100644 (file)
--- a/doc/appdev/refs/macros/index.rst
+++ b/doc/appdev/refs/macros/index.rst
@@ -88,6 +88,8 @@ Public
    KRB5_AS_REP.rst
    KRB5_AS_REQ.rst
    KRB5_AUTHDATA_AND_OR.rst
+   KRB5_AUTHDATA_AUTH_INDICATOR.rst
+   KRB5_AUTHDATA_CAMMAC.rst
    KRB5_AUTHDATA_ETYPE_NEGOTIATION.rst
    KRB5_AUTHDATA_FX_ARMOR.rst
    KRB5_AUTHDATA_IF_RELEVANT.rst
@@ -159,6 +161,7 @@ Public
    KRB5_KEYUSAGE_AS_REP_ENCPART.rst
    KRB5_KEYUSAGE_AS_REQ.rst
    KRB5_KEYUSAGE_AS_REQ_PA_ENC_TS.rst
+   KRB5_KEYUSAGE_CAMMAC.rst
    KRB5_KEYUSAGE_ENC_CHALLENGE_CLIENT.rst
    KRB5_KEYUSAGE_ENC_CHALLENGE_KDC.rst
    KRB5_KEYUSAGE_FAST_ENC.rst

diff --git a/doc/plugindev/kdcpreauth.rst b/doc/plugindev/kdcpreauth.rst
index 26552235bbc39c3ef1e05a150f3e02f9b4bb1cd3..99696fa6958d52d87f90dcf2e2b021f2ee946d89 100644 (file)
--- a/doc/plugindev/kdcpreauth.rst
+++ b/doc/plugindev/kdcpreauth.rst
@@ -50,7 +50,10 @@ 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.
+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).
 
 The **edata** and **verify** methods can be implemented
 asynchronously.  Because of this, they do not return values directly