Home | History | Annotate | Line # | Download | only in man 
      1 .lf 1 stdin
      2 .TH SLAPO_OTP 5 "2018/6/29" "SLAPO-OTP"
      3 .\" Copyright 2015-2024 The OpenLDAP Foundation.
      4 .\" Portions Copyright 2015 by Howard Chu, Symas Corp. All rights reserved.
      5 .\" Portions Copyright 2018 by Ondej Kuznk, Symas Corp. All rights reserved.
      6 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
      7 .SH NAME
      8 slapo-otp \- OATH One-Time Password module
      9 .SH SYNOPSIS
     10 .B moduleload
     11 .I otp.la
     12 .SH DESCRIPTION
     13 The
     14 .B otp
     15 module allows time-based one-time password, AKA "authenticator-style", and
     16 HMAC-based one-time password authentication to be used in conjunction with
     17 a standard LDAP password for two-factor authentication.
     18 
     19 With this module, users would use their password, followed with the one-time
     20 password in the password prompt to authenticate.
     21 
     22 The password needed for a user to authenticate is calculated based on a counter
     23 (current time in case of TOTP) and a key that is referenced in the user's LDAP
     24 entry. Since the password is based on the time or number of uses, it changes
     25 periodically. Once used, it cannot be used again so keyloggers and
     26 shoulder-surfers are thwarted. A mobile phone application, such as the Google
     27 Authenticator or YubiKey (a
     28 .BR prover ),
     29 can be used to calculate the user's current one-time password, which is
     30 expressed as a (usually six-digit) number.
     31 
     32 Alternatively, the value can be calculated by some other application with
     33 access to the user's key and delivered to the user through SMS or some other
     34 channel. When prompted to authenticate, the user merely appends the code
     35 provided by the prover at the end of their password when authenticating.
     36 
     37 This implementation complies with
     38 .B RFC 4226 HOTP HMAC-Based One Time Passwords
     39 and
     40 .B RFC 6238 TOTP Time-based One Time Passwords
     41 and includes support for the SHA-1, SHA-256, and SHA-512 HMAC
     42 algorithms.
     43 
     44 The HMAC key used in the OTP computation is stored in the oathOTPToken entry referenced in
     45 the user's LDAP entry and the parameters are stored in the oathOTPParams LDAP
     46 entry referenced in the token.
     47 
     48 .SH CONFIGURATION
     49 Once the module is configured on the database, it will intercept LDAP simple
     50 binds for users whose LDAP entry has any of the
     51 .B oathOTPUser
     52 derived objectlasses attached to it. The attributes linking the user and the
     53 shared secret are:
     54 
     55 .RS
     56 .TP
     57 .B oathTOTPToken: <dn>
     58 Mandatory for
     59 .BR oathTOTPUser ,
     60 indicates that the named entry is designated to hold the time-based one-time
     61 password shared secret and the last password used.
     62 .TP
     63 .B oathHOTPToken: <dn>
     64 Mandatory for
     65 .BR oathHOTPUser ,
     66 indicates that the named entry is designated to hold the one-time password
     67 shared secret and the last password used.
     68 .TP
     69 .B oathTOTPParams: <dn>
     70 Mandatory for
     71 .BR oathTOTPToken ,
     72 indicates that the named entry is designated to hold the parameters to generate
     73 time-based one-time password shared secret: its length and algorithm to use as
     74 well as the length of each time step and the grace period.
     75 .TP
     76 .B oathHOTPParams: <dn>
     77 Mandatory for
     78 .BR oathHOTPToken ,
     79 indicates that the named entry is designated to hold the parameters to generate
     80 one-time password shared secret: its length and algorithm to use as well as the
     81 permitted number of passwords to skip.
     82 .RE
     83 
     84 The following parts of the OATH-LDAP schema are implemented.
     85 
     86 General attributes:
     87 
     88 .RS
     89 .TP
     90 .B oathSecret: <data>
     91 The shared secret is stored here as raw bytes.
     92 .TP
     93 .B oathOTPLength: <length>
     94 The password length, usually 6.
     95 .TP
     96 .B oathHMACAlgorithm: <OID>
     97 The OID of the hash algorithm to use as defined in RFC 8018.
     98 Supported algorithms include SHA1, SHA224, SHA256, SHA384 and SHA512.
     99 .RE
    100 
    101 The HOTP attributes:
    102 
    103 .RS
    104 .TP
    105 .B oathHOTPLookAhead: <number>
    106 The number of successive HOTP tokens that can be skipped.
    107 .TP
    108 .B oathHOTPCounter: <number>
    109 The order of the last HOTP token successfully redeemed by the user.
    110 .RE
    111 
    112 The TOTP attributes:
    113 
    114 .RS
    115 .TP
    116 .B oathTOTPTimeStepPeriod: <seconds>
    117 The length of the time-step period for TOTP calculation.
    118 .TP
    119 .B oathTOTPLastTimeStep: <number>
    120 The order of the last TOTP token successfully redeemed by the user.
    121 .TP
    122 .B oathTOTPTimeStepWindow: <number>
    123 The number of time periods around the current time to try when checking the
    124 password provided by the user.
    125 .TP
    126 .B oathTOTPTimeStepDrift: <number>
    127 If the client didn't provide the correct token but it still fit with
    128 oathTOTPTimeStepWindow above, this attribute records the current offset to
    129 provide for slow clock drift of the client device.
    130 .RE
    131 
    132 .SH "SEE ALSO"
    133 .BR slapd\-config (5).
    134 
    135 .SH ACKNOWLEDGEMENT
    136 This work was developed by Ondej Kuznk and Howard Chu of Symas Corporation
    137 for inclusion in OpenLDAP Software.
    138 
    139 This work reuses the OATH-LDAP schema developed by Michael Strder.
    140