Module Twostep.TOTP

Module for TOTP algorithm.

This algorithm is useful on contexts of password managers, authenticator mobile applications or hardware vaults, that is, where the end-user has full control of OTP token generation.

val secret : ?bytes:int -> unit -> string

Generates a valid Base-32 OTP secret (for both HOTP and TOTP algorithms, but don't mix them with the same secret, instead, generate a secret for every kind of usage). The optional bytes parameter represents the size of underlying binary/blob string of the encoded Base-32 secret. Such parameter must be at least 10 and an integer divisible by 5.

val code : ?window:int -> ?drift:int -> ?digits:int -> ?hash:string -> secret:string -> unit -> string

Generates an OTP token given valid Base-32 secret. The interval to expire the token is configured by the window optional parameter (defaults to 30 seconds). A clock drift of either positive or negative integers can be used when the server attempts to verify on past or future too. The drift parameter defaults to 0, non-zero values are used mostly for custom verification, but it's not recommended that use. Instead, rely on TOTP.verify operation, which attempts to verify with clock drifts -1, 0 and 1 (30 seconds on past, now and 30 seconds on future, assuming that window is 30 seconds). Remaining optional parameters digits and hash are used to configure the token size (defaults to 6 characters) and HMAC hash (defaults to "SHA-1", "SHA-256" and "SHA-512" are available too), respectively.

val verify : ?window:int -> ?digits:int -> ?hash:string -> secret:string -> code:string -> unit -> bool

Operation to verify TOTP codes. Optional parameters are window (how much seconds to expire the TOTP code/token, defaults to 30 seconds), digits (number of code/token characters, defaults to 6) and hash (hash algorithm for internal HMAC, defaults to "SHA-1", other options are "SHA-256" and "SHA-512"). The required secret parameter must be a valid Base-32 string, under the same format of TOTP.secret() operation. Returns a boolean flag for authentication/proof (true for valid token, false for invalid one).