From 4b5dd8bcfb10af254fb9efbe4cf39befe5b1e6ac Mon Sep 17 00:00:00 2001 From: Nathaniel McCallum Date: Wed, 3 Apr 2013 12:38:05 -0400 Subject: Add server-side otp preauth plugin This plugin implements the proposal for providing OTP support by proxying requests to RADIUS. Details can be found inside the provided documentation as well as on the project page. http://k5wiki.kerberos.org/wiki/Projects/OTPOverRADIUS ticket: 7678 --- doc/admin/conf_files/kdc_conf.rst | 66 ++++++++++++++++++++++++++++++ doc/admin/index.rst | 1 + doc/admin/otp.rst | 85 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 152 insertions(+) create mode 100644 doc/admin/otp.rst (limited to 'doc') diff --git a/doc/admin/conf_files/kdc_conf.rst b/doc/admin/conf_files/kdc_conf.rst index c7007d647b..3b56e61e82 100644 --- a/doc/admin/conf_files/kdc_conf.rst +++ b/doc/admin/conf_files/kdc_conf.rst @@ -491,6 +491,72 @@ administrative server will be appended to the file admin_server = DEVICE=/dev/tty04 +.. _otp: + +[otp] +~~~~~ + +Each subsection of [otp] is the name of an OTP token type. The tags +within the subsection define the configuration required to forward a +One Time Password request to a RADIUS server. + +For each token type, the following tags may be specified: + +**server** + This is the server to send the RADIUS request to. It can be a + hostname with optional port, an ip address with optional port, or + a Unix domain socket address. The default is + |kdcdir|\ ``/.socket``. + +**secret** + This tag indicates a filename (which may be relative to |kdcdir|) + containing the secret used to encrypt the RADIUS packets. The + secret should appear in the first line of the file by itself; + leading and trailing whitespace on the line will be removed. If + the value of **server** is a Unix domain socket address, this tag + is optional, and an empty secret will be used if it is not + specified. Otherwise, this tag is required. + +**timeout** + An integer which specifies the time in seconds during which the + KDC should attempt to contact the RADIUS server. This tag is the + total time across all retries and should be less than the time + which an OTP value remains valid for. The default is 5 seconds. + +**retries** + This tag specifies the number of retries to make to the RADIUS + server. The default is 3 retries (4 tries). + +**strip_realm** + If this tag is ``true``, the principal without the realm will be + passed to the RADIUS server. Otherwise, the realm will be + included. The default value is ``true``. + +In the following example, requests are sent to a remote server via UDP. + + :: + + [otp] + MyRemoteTokenType = { + server = radius.mydomain.com:1812 + secret = SEmfiajf42$ + timeout = 15 + retries = 5 + strip_realm = true + } + +An implicit default token type named ``DEFAULT`` is defined for when +the per-principal configuration does not specify a token type. Its +configuration is shown below. You may override this token type to +something applicable for your situation. + + :: + + [otp] + DEFAULT = { + strip_realm = false + } + PKINIT options -------------- diff --git a/doc/admin/index.rst b/doc/admin/index.rst index c40d51016c..3406843b10 100644 --- a/doc/admin/index.rst +++ b/doc/admin/index.rst @@ -14,6 +14,7 @@ For administrators host_config.rst backup_host.rst pkinit.rst + otp.rst princ_dns.rst enctypes.rst diff --git a/doc/admin/otp.rst b/doc/admin/otp.rst new file mode 100644 index 0000000000..0abd5ff837 --- /dev/null +++ b/doc/admin/otp.rst @@ -0,0 +1,85 @@ +OTP Preauthentication +===================== + +OTP is a preauthentication mechanism for Kerberos 5 which uses One +Time Passwords (OTP) to authenticate the client to the KDC. The OTP +is passed to the KDC over an encrypted FAST channel in clear-text. +The KDC uses the password along with per-user configuration to proxy +the request to a third-party RADIUS system. This enables +out-of-the-box compatibility with a large number of already widely +deployed proprietary systems. + +Additionally, our implementation of the OTP system allows for the +passing of RADIUS requests over a UNIX domain stream socket. This +permits the use of a local companion daemon which can handle the +details of authentication. + + +Defining token types +-------------------- + +Token types are defined in either krb5.conf or kdc.conf according to +the following format:: + + [otp] + = { + server = (default: $KDCDIR/.socket) + secret = + timeout = (default: 5 [seconds]) + retries = (default: 3) + strip_realm = (default: true) + } + +If the server field begins with '/', it will be interpreted as a UNIX +socket. Otherwise, it is assumed to be in the format host:port. When +a UNIX domain socket is specified, the secret field is optional and an +empty secret is used by default. + +When forwarding the request over RADIUS, by default the principal is +used in the User-Name attribute of the RADIUS packet. The strip_realm +parameter controls whether the principal is forwarded with or without +the realm portion. + + +The default token type +---------------------- + +A default token type is used internally when no token type is specified for a +given user. It is defined as follows:: + + [otp] + DEFAULT = { + strip_realm = false + } + +The administrator may override the internal ``DEFAULT`` token type +simply by defining a configuration with the same name. + + +Token instance configuration +---------------------------- + +To enable OTP for a client principal, the administrator must define +the **otp** string attribute for that principal. The **otp** user +string is a JSON string of the format:: + + [{ + "type": , + "username": + }, ...] + +This is an array of token objects. Both fields of token objects are +optional. The **type** field names the token type of this token; if +not specified, it defaults to ``DEFAULT``. The **username** field +specifies the value to be sent in the User-Name RADIUS attribute. If +not specified, the principal name is sent, with or without realm as +defined in the token type. + +For ease of configuration, an empty array (``[]``) is treated as +equivalent to one DEFAULT token (``[{}]``). + + +Other considerations +-------------------- + +#. FAST is required for OTP to work. -- cgit