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.