twostep
HOTP and TOTP algorithms for 2-step verification (for OCaml).
This project implements algorithms for 2-step verification, being the HMAC-based One-Time Password (see RFC 4226) and the Time-based One-Time Password (see RFC 6238).
Installation
If available on OPAM, try:
opam install twostep
Otherwise, you can install the development version of this
project with OPAM’s pin command.
Usage
The authentication of 2-step verification needs prior known and shared secret between the client and server. If no secret was sent before, you can generate this Base-32 secret with:
let secret: string = Twostep.TOTP.secret();; (* kinda "A222 BBBB 3333 D5D5" *)
As an additional note, the Twostep.TOTP.secret function above uses
a cryptographically safe PRNG, that is, a secure source of pseudo
randomness. To generate an OTP code, you can use this function:
let code: string = Twostep.TOTP.code ~secret:secret ();; (* kinda "098123" *)
The function above assumes the SHA-1 hash algorithm, 30 seconds
as timestep/window before refreshed code, 6 digits for output
number code (padded with zeros on left sometimes) and no clock
drifts / not-sync time between server and client (i.e, no
30 seconds on the past or on the future).
To verify one-time codes from the client, use the following function below:
let valid: bool = Twostep.TOTP.verify ~secret:secret ~code:code ();;
This function assumes the same configuration of Twostep.TOTP.code,
except for the clock drift, where Twostep.TOTP.verify assumes too
past and future 30 seconds (ideal on slow connections or latency
problems). For the full API reference or coverage status, please refer to:
You can test this library against mobile apps such as Google Authenticator or Microsoft Authenticator without any problems (I have tested on both as well). On any doubts to generate a QR-code for the base-32 secret, please refer to Google Authenticator’s Key Uri Format (for the proper data format on QR-code encoding/decoding):
Security Concerns
The generated secret must be sent for the client in a secure channel, such as HTTPS/TLS, and must be stored encrypted in your servers’ databases. A good approach is to encrypt with a KDF on the client password, after you checking the client password against the strongly hashed version on database (prefer 256/512-bits hash algorithms whenever possible, and a KDF in front of this with server’s salt is ideal too). So, in this approach the front app must send the client password twice, during authentication and during 2-step verification, and after that, erasing the password persisted on front (nice UX for the client to not type twice her own password).
It’s recommended for the OTP authentication to be optional on
most cases. The end-user can opt-in this feature some time later,
and on OTP service setup, she needs to confirm that have
configured things properly through the first-time OTP-code
verification. For the first-time, which means no OTP-prompt-prior-login
until customer confirmation of first-time, you could use
a confirmed boolean (initially false) column aside
encryptedSecret on your storage – so this first-time confirmation
changes confirmed to true and then all logins would request an
OTP code together. Keep in mind that it’s just a design sketch of
implementation, more like an idea than actual RFC recommendation.
Also, you should track valid OTP codes sent from the end user in
a persisted storage (such as databases). This is just to avoid
replay attacks once an attacker intercepts a valid OTP code from
the end user. Your tracking of the OTP code should be a pair
(otpCode, nonce), where nonce is the current interval / period
(if using TOTP algorithm, otherwise nonce will be a HOTP counter)
and the otpCode is verified / checked as valid. Keep in mind that
you should only track valid / verified OTP codes to not waste storage
costs with invalid OTP codes (i.e, codes that can’t be exploited by
replay attacks). After such tracked pairs hit OTP expiration and are
not able to be exploited anymore, you can clean them from the
underlying tracklist storage without problems.
Important: This is a warning / security advice. Implement such system carefully, and if possible, with audits from external experts and security teams. As a disclaimer, I’m not responsible for any damages.
Tips
For stronger / longer secrets, you can use the ~bytes optional parameter
(the default and minimal value is 10,
with the invariant that it must be divisible-by / multiple-of 5):
let secret: string = Twostep.TOTP.secret ~bytes:20 ();;
(* kinda "D3D3 F5F5 A2A2 3B3B GGGG 7K7K 5555 Q2Q2" *)
Remarks
Pull requests are welcome! Happy hacking! Hope this project can help you to solve problems.