PW-TOTP(5)

💖 pw-totp — the TOTP password handling module 💖

okay so bestie, this is pw-totp(5), a page from the File Formats Manual, and it's literally about making LDAP logins work with those six-digit authenticator codes. no cap. let's get into it. 🦋

---

✨ NAME ✨

pw-totp — a TOTP password handling module. that's it, that's the name, she's iconic. 👑

---

✨ SYNOPSIS ✨

moduleload pw-totp.la

load her up and she's ready to serve. 💅

---

✨ DESCRIPTION ✨

so the pw-totp module lets apps that use LDAP for authentication add time-based one-time password auth — aka the "authenticator-style" thing you already do with the app on your phone. and the best part?? in most cases no changes to the applications are needed at all to switch over to this type of authentication. plug it in, it just works, we love a low-maintenance queen. 💅

with this module, the password a user needs in order to authenticate is calculated based on the current time plus a key that lives in the user's LDAP entry. since the password is based on the time, it changes periodically. and the way a code cannot be used again once it's been used?? keyloggers and shoulder-surfers are thwarted. goodbye, snoops. 🙈

so how do you actually get the code? a mobile phone application — like Google Authenticator — acts as a 'prover' and calculates the user's current password, which is expressed as a six-digit number. alternatively, the value can be calculated by some other application that has access to the user's key and delivered to the user via SMS or some other channel. when prompted to authenticate, the user merely enters the six-digit code provided by the prover. easy. periodt. 💖

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

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. that value should correspond to the one used by the prover (authenticator). keep them in sync, bestie, or it's giving chaos. 🫶

---

✨ CONFIGURATION ✨

once the module is loaded with the moduleload command from the synopsis, these password schemes get recognized: {TOTP1}, {TOTP256}, {TOTP512}, {TOTP1ANDPW}, {TOTP256ANDPW}, and {TOTP512ANDPW}. six schemes, all stunning, no notes. 👑

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

database mdb
...
overlay totp
...

and 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}

that's the whole vibe. set it and forget it. ✨

---

✨ NOTES ✨

heads up bestie, this one matters!! 📣

this module includes functionality implemented by the slapo-lastbind overlay and cannot coexist with it in the same database. so don't try to run both, they will not share the aux cord. 😭

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. iykyk — if you've got multiple servers doing auth, they all need that timestamp. 🦋

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 (|). 🎀

---

✨ BUGS ✨

okay so the tea is: ☕

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 — and this part is iconic — 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. so yeah, generous. 🫶

the authenticator code that is generated is also 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. personal choice, honestly, we don't judge. 💅

and 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. big oof, be careful out there. 💀

---

✨ SEE ALSO ✨

• slapd.conf(5)
• ldappasswd(1)

go read those next, bestie, they're slay. 📚

---

✨ ACKNOWLEDGEMENT ✨

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

password + TOTP support was added by Greg Veldman on behalf of SCinet. 🫶

---

and that's the whole page, angel. this is PW-TOTP(5) from 2015/7/2 — yes she's a little vintage but she still eats. go forth and authenticate responsibly. 🌸👑✨