git.sur5r.net Git - openldap/blob - contrib/slapd-modules/passwd/totp/slapo-totp.5

   1 .TH PW-TOTP 5 "2015/7/2" "PW-TOTP"
   2 .\" Copyright 2015 The OpenLDAP Foundation.
   3 .\" Portions Copyright 2015 by Howard Chu, Symas Corp. All rights reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 pw-totp \- TOTP Password handling module
   7 .SH SYNOPSIS
   8 .B moduleload
   9 .I pw-totp.la
  10 .SH DESCRIPTION
  11 The
  12 .B pw-totp
  13 module allows time-based one-time password, AKA "authenticator-style",
  14 authentication to be added to applications that use LDAP for
  15 authentication. In most cases no changes to the applications are needed to switch
  16 to this type of authentication.
  17
  18 With this module, the password needed for a user to authenticate is calculated
  19 based on the current time and a key that is stored in the user's LDAP entry. Since
  20 the password is based on the time, it changes periodically. Once used, it cannot be
  21 used again so keyloggers and shoulder-surfers are thwarted. A mobile
  22 phone application, such as the Google Authenticator (a 'prover'), can be used
  23 to calculate the user's current password, which is expressed as a six-digit
  24 number.
  25 Alternatively, the value can be calculated by some other application with access
  26 to the user's key and delivered to the user through SMS or some other channel.
  27 When prompted to authenticate, the user merely enters the six-digit code provided by
  28 the prover.
  29
  30 This implementation complies with
  31 .B RFC 6238 TOTP Time-based One Time Passwords
  32 and includes support for the SHA-1, SHA-256, and SHA-512 HMAC
  33 algorithms.
  34
  35 The HMAC key used in the TOTP computation is stored in the userPassword attribute
  36 of the user's LDAP entry and the LDAP Password Modify Extended Operation is used to
  37 set and change the value. The
  38 value should correspond to that used by the the prover (authenticator).
  39
  40 .SH CONFIGURATION
  41 Once the module is loaded with the moduleload command from the synopsis,
  42 the {TOTP1}, {TOTP256}, and {TOTP512}
  43 password schemes will be recognized.
  44
  45 On the databases where your users reside you must configure the
  46 totp overlay:
  47
  48 .nf
  49         database mdb
  50         \...
  51         overlay totp
  52         \...
  53 .fi
  54
  55 You can tell OpenLDAP to use one of these new schemes when processing LDAP
  56 Password Modify Extended Operations, thanks to the password-hash option in
  57 slapd.conf. For example:
  58
  59 .nf
  60         password-hash   {TOTP256}
  61 .fi
  62
  63 .SH NOTES
  64 This module includes functionality implemented by the slapo-lastbind overlay
  65 and cannot coexist with it in the same database. Also note
  66 that since the time that the last bind occurred
  67 is needed to properly implement TOTP, provisions need to be made to propagate
  68 the authTimestamp attribute to other servers that are providing authentication
  69 services.
  70
  71 .SH BUGS
  72 The time step is hard-coded to thirty seconds. This should be OK for many use cases,
  73 but it would be nice if the value
  74 could be changed with a configuration keyword or in an attribute value.
  75
  76 The authenticator code that is generated is hard-coded to a length of six digits.
  77 While in most cases
  78 this is probably better than the alternative length of four digits, there may be
  79 cases where a four-digit value is preferred.
  80
  81 There is currently no way to require a separate PIN code with the authenticator
  82 code.
  83
  84 In cases where password-hash lists multiple mechanisms, the TOTP key will also
  85 be changed at the same time. This is likely to be undesirable behavior.
  86
  87 .SH "SEE ALSO"
  88 .BR slapd.conf (5) ldappasswd (1)
  89 .SH ACKNOWLEDGEMENT
  90 This work was developed by Howard Chu of Symas Corporation for inclusion in
  91 OpenLDAP Software.