krb5 commit: Document authentication indicators
Greg Hudson
ghudson at mit.edu
Wed Jul 22 13:29:46 EDT 2015
https://github.com/krb5/krb5/commit/491b012b49ce687ffd4a26f5d0f6114d8411d04d
commit 491b012b49ce687ffd4a26f5d0f6114d8411d04d
Author: Greg Hudson <ghudson at mit.edu>
Date: Mon Mar 23 13:03:32 2015 -0400
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
doc/admin/admin_commands/kadmin_local.rst | 6 +++
doc/admin/auth_indicator.rst | 52 +++++++++++++++++++++++++++++
doc/admin/conf_files/kdc_conf.rst | 10 +++++
doc/admin/index.rst | 1 +
doc/appdev/refs/macros/index.rst | 3 ++
doc/plugindev/kdcpreauth.rst | 5 ++-
6 files changed, 76 insertions(+), 1 deletions(-)
diff --git a/doc/admin/admin_commands/kadmin_local.rst b/doc/admin/admin_commands/kadmin_local.rst
index 5572b34..be874b1 100644
--- 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
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 at 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 at KRBTEST.COM: kvno = 1
+
+but a user who authenticates with a password would not::
+
+ $ kinit user
+ Password for user at KRBTEST.COM:
+ $ kvno host/high.value.server
+ kvno: KDC policy rejects request while getting credentials for
+ host/high.value.server at KRBTEST.COM
diff --git a/doc/admin/conf_files/kdc_conf.rst b/doc/admin/conf_files/kdc_conf.rst
index d2b4681..80a43f6 100644
--- 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 3cd57f5..b702f40 100644
--- 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 5fa1aab..7b07122 100644
--- 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 2655223..99696fa 100644
--- 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
More information about the cvs-krb5
mailing list