slapo-totp(5)

slapo-totp5

Totp password handling module

Usage

moduleload pw-totp.la

Overview

The 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.

Additionally, the overlay can also authenticate TOTP passwords combined with a static password. To do this, utilize one of the {TOTP1ANDPW}, {TOTP256ANDPW}, or {TOTP512ANDPW} password schemes and append the static password scheme value to the end of the userPassword attribute, separated by a pipe (|) character.

This implementation complies with 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).

Configuration

Once the module is loaded with the moduleload command from the synopsis, the {TOTP1}, {TOTP256}, {TOTP512} {TOTP1ANDPW}, {TOTP256ANDPW}, and {TOTP512ANDPW} password schemes will be recognized.

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

	database mdb
	...
	overlay totp
	...

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:

	password-hash   {TOTP256}

Notes

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.

The hash functions for the {TOTP1ANDPW}, {TOTP256ANDPW}, and {TOTP512ANDPW} schemes expect the secret to be entered in the form: <OTP seed><DELIM><static password>, where DELIM is currently defined as the pipe character (|).

Acknowledgement

This work was developed by Howard Chu of Symas Corporation for inclusion in OpenLDAP Software.

Password + TOTP support added by Greg Veldman on behalf of SCinet.

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. 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.

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.

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.

From openldap 2.7.2-2 in Arch Linux 2026-11-01. Parsed by carta from the page's man source.