slapo-totp.5 3.78 KB
Newer Older
1
.TH PW-TOTP 5 "2015/7/2" "PW-TOTP"
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
2
.\" Copyright 2015-2019 The OpenLDAP Foundation.
3
.\" Portions Copyright 2015 by Howard Chu, Symas Corp. All rights reserved.
4
5
.\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
.SH NAME
6
pw-totp \- TOTP Password handling module
7
.SH SYNOPSIS
8
9
.B moduleload
.I pw-totp.la
10
11
.SH DESCRIPTION
The
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
.B pw-totp
module allows time-based one-time password, AKA "authenticator-style",
authentication to be added to applications that use LDAP for
authentication. In most cases no changes to the applications are needed to switch
to this type of authentication.

With this module, the password needed for a user to authenticate is calculated
based on the current time and a key that is stored in the user's LDAP entry. Since
the password is based on the time, it changes periodically. Once used, it cannot be
used again so keyloggers and shoulder-surfers are thwarted. A mobile
phone application, such as the Google Authenticator (a 'prover'), can be used
to calculate the user's current password, which is expressed as a six-digit
number.
Alternatively, the value can be calculated by some other application with access
to the user's key and delivered to the user through SMS or some other channel.
When prompted to authenticate, the user merely enters the six-digit code provided by
the prover.

This implementation complies with 
.B RFC 6238 TOTP Time-based One Time Passwords
and includes support for the SHA-1, SHA-256, and SHA-512 HMAC
algorithms.

The HMAC key used in the TOTP computation is stored in the userPassword attribute
of the user's LDAP entry and the LDAP Password Modify Extended Operation is used to
set and change the value. The
value should correspond to that used by the the prover (authenticator). 
39
40

.SH CONFIGURATION
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
Once the module is loaded with the moduleload command from the synopsis, 
the {TOTP1}, {TOTP256}, and {TOTP512}
password schemes will be recognized.

On the databases where your users reside you must configure the
totp overlay:

.nf
	database mdb
	\...
	overlay totp
	\...
.fi

You can tell OpenLDAP to use one of these new schemes when processing LDAP
Password Modify Extended Operations, thanks to the password-hash option in
slapd.conf. For example:

.nf
	password-hash   {TOTP256}
.fi
62
63

.SH NOTES
64
65
66
67
68
69
This module includes functionality implemented by the slapo-lastbind overlay
and cannot coexist with it in the same database. Also note
that since the time that the last bind occurred
is needed to properly implement TOTP, provisions need to be made to propagate
the authTimestamp attribute to other servers that are providing authentication
services.
70

71
72
73
74
.SH BUGS
The time step is hard-coded to thirty seconds. This should be OK for many use cases,
but it would be nice if the value
could be changed with a configuration keyword or in an attribute value.
Greg Veldman's avatar
Greg Veldman committed
75
76
77
78
79
80
81
However, after one successful initial authentication (to verify
the clocks on the server and the user's prover are in sync) the TOTP
value of the previous time window may also be used to successfully
authenticate, provided no successful bind has been performed already
in the current or previous time window.  This eliminates false
negatives caused by user or network delays
entering or transmitting the TOTP value.
82

83
84
85
86
The authenticator code that is generated is hard-coded to a length of six digits.
While in most cases
this is probably better than the alternative length of four digits, there may be
cases where a four-digit value is preferred.
87

88
89
There is currently no way to require a separate PIN code with the authenticator
code.
90

91
92
In cases where password-hash lists multiple mechanisms, the TOTP key will also
be changed at the same time. This is likely to be undesirable behavior.
93

94
95
96
97
98
.SH "SEE ALSO"
.BR slapd.conf (5) ldappasswd (1) 
.SH ACKNOWLEDGEMENT
This work was developed by Howard Chu of Symas Corporation for inclusion in
OpenLDAP Software.