File: otp.rst

package info (click to toggle)
krb5 1.12.1+dfsg-19+deb8u4
  • links: PTS, VCS
  • area: main
  • in suites: jessie
  • size: 67,680 kB
  • ctags: 34,155
  • sloc: ansic: 309,213; cpp: 15,753; exp: 13,257; makefile: 7,652; python: 7,228; sh: 6,457; perl: 3,514; asm: 1,544; yacc: 1,187; awk: 396; xml: 368; csh: 147; lisp: 104; sed: 43
file content (86 lines) | stat: -rw-r--r-- 2,926 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
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]
        <name> = {
            server = <host:port or filename> (default: see below)
            secret = <filename>
            timeout = <integer> (default: 5 [seconds])
            retries = <integer> (default: 3)
            strip_realm = <boolean> (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.  If the server field is not
specified, it defaults to |kdcrundir|\ ``/<name>.socket``.

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": <string>,
        "username": <string>
     }, ...]

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.