From: Greg Hudson Date: Mon, 23 Mar 2015 17:03:32 +0000 (-0400) Subject: Document authentication indicators X-Git-Tag: krb5-1.14-alpha1~51 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=491b012b49ce687ffd4a26f5d0f6114d8411d04d;p=thirdparty%2Fkrb5.git 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 5572b34cc7..be874b1a53 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 0000000000..e971aa90eb --- /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 ` or :ref:`OTP `. 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 d2b468126e..80a43f63df 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 3cd57f5242..b702f40214 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 5fa1aabd61..7b0712265d 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 26552235bb..99696fa695 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