NAME

       slapo-otp - OATH One-Time Password module

SYNOPSIS

       moduleload otp.la

DESCRIPTION

       The  otp  module  allows time-based one-time password, AKA "authenticator-style", and HMAC-based one-time
       password authentication to  be  used  in  conjunction  with  a  standard  LDAP  password  for  two-factor
       authentication.

       With  this  module,  users  would use their password, followed with the one-time password in the password
       prompt to authenticate.

       The password needed for a user to authenticate is calculated based on a counter (current time in case  of
       TOTP)  and  a key that is referenced in the user's LDAP entry. Since the password is based on the time or
       number of uses, 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 or YubiKey (a prover),
       can  be  used  to  calculate  the user's current one-time password, which is expressed as a (usually 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
       appends the code provided by the prover at the end of their password when authenticating.

       This implementation complies with RFC 4226 HOTP HMAC-Based One Time Passwords and  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 OTP computation is stored in the oathOTPToken entry referenced in the user's
       LDAP entry and the parameters are stored in the oathOTPParams LDAP entry referenced in the token.

CONFIGURATION

       Once the module is configured on the database, it will intercept LDAP simple binds for users  whose  LDAP
       entry has any of the oathOTPUser derived objectlasses attached to it. The attributes linking the user and
       the shared secret are:

              oathTOTPToken: <dn>
                     Mandatory  for oathTOTPUser, indicates that the named entry is designated to hold the time-
                     based one-time password shared secret and the last password used.

              oathHOTPToken: <dn>
                     Mandatory for oathHOTPUser, indicates that the named entry is designated to hold  the  one-
                     time password shared secret and the last password used.

              oathTOTPParams: <dn>
                     Mandatory  for  oathTOTPToken,  indicates  that  the  named entry is designated to hold the
                     parameters to generate time-based one-time password shared secret: its length and algorithm
                     to use as well as the length of each time step and the grace period.

              oathHOTPParams: <dn>
                     Mandatory for oathHOTPToken, indicates that the named  entry  is  designated  to  hold  the
                     parameters  to generate one-time password shared secret: its length and algorithm to use as
                     well as the permitted number of passwords to skip.

       The following parts of the OATH-LDAP schema are implemented.

       General attributes:

              oathSecret: <data>
                     The shared secret is stored here as raw bytes.

              oathOTPLength: <length>
                     The password length, usually 6.

              oathHMACAlgorithm: <OID>
                     The OID of the hash algorithm to use as defined in RFC 8018.  Supported algorithms  include
                     SHA1, SHA224, SHA256, SHA384 and SHA512.

       The HOTP attributes:

              oathHOTPLookAhead: <number>
                     The number of successive HOTP tokens that can be skipped.

              oathHOTPCounter: <number>
                     The order of the last HOTP token successfully redeemed by the user.

       The TOTP attributes:

              oathTOTPTimeStepPeriod: <seconds>
                     The length of the time-step period for TOTP calculation.

              oathTOTPLastTimeStep: <number>
                     The order of the last TOTP token successfully redeemed by the user.

              oathTOTPTimeStepWindow: <number>
                     The  number  of  time  periods  around  the  current time to try when checking the password
                     provided by the user.

              oathTOTPTimeStepDrift: <number>
                     If the client didn't provide the correct token but it still fit with oathTOTPTimeStepWindow
                     above, this attribute records the current offset to provide for slow  clock  drift  of  the
                     client device.

SEE ALSO

       slapd-config(5).

ACKNOWLEDGEMENT

       This  work  was  developed by Ondřej Kuzník and Howard Chu of Symas Corporation for inclusion in OpenLDAP
       Software.

       This work reuses the OATH-LDAP schema developed by Michael Ströder.

SLAPO-OTP                                           2018/6/29                                       SLAPO_OTP(5)