Comeonin

v3.0.2

Comeonin v3.0.2 Comeonin.Otp

Generate and verify HOTP and TOTP one-time passwords.

Module to generate and check HMAC-based one-time passwords and time-based one-time passwords, in accordance with RFC 4226 and RFC 6238.

Two factor authentication

These one-time passwords are often used together with regular passwords to provide two factor authentication (2FA), which forms a layered approach to user authentication. The advantage of 2FA over just using passwords is that an attacker would face an additional challenge to being authorized.

Warning about implementation

It is important not to allow the one-time password to be reused within the timeframe that it is valid.

For TOTPs, one method of preventing reuse is to compare the output of check_totp (the last value) with the previous output. The output should be greater than the previous last value.

In the case of HOTPs, it is important that the database is locked from the time the last value is checked until the last value is updated.

For an example implementation, see the Openmaize OnetimePass module.

Summary

Functions

check_hotp(token, secret, opts \\ [])

Verify a HMAC-based one-time password

check_totp(token, secret, opts \\ [])

Verify a time-based one-time password

gen_hotp(secret, count, opts \\ [])

Generate a HMAC-based one-time password

gen_secret(secret_length \\ 32)

Generate a secret key to be used with one-time passwords

gen_totp(secret, opts \\ [])

Generate a time-based one-time password

valid_token(token, token_length)

Check the one-time password is valid

Functions

check_hotp(token, secret, opts \\ [])

Verify a HMAC-based one-time password.

There are three options:

  • token_length - the length of the one-time password

    • the default is 6

  • last - the count when the one-time password was last used

    • this count needs to be stored server-side

  • window - the number of future attempts allowed

    • the default is 3
check_totp(token, secret, opts \\ [])

Verify a time-based one-time password.

There are three options:

  • token_length - the length of the one-time password

    • the default is 6

  • interval_length - the length of each timed interval

    • the default is 30 (seconds)

  • window - the number of attempts, before and after the current one, allowed

    • the default is 1 (1 interval before and 1 interval after)
    • you might need to increase this window to allow for clock skew on the server
gen_hotp(secret, count, opts \\ [])

Generate a HMAC-based one-time password.

There is one option:

  • token_length - the length of the one-time password

    • the default is 6
gen_secret(secret_length \\ 32)

Generate a secret key to be used with one-time passwords.

By default, this function creates a 32 character base32 string, which can be used with the other functions in this module.

It is also possible to create a 16 or 24 character long secret, but this is not recommended.

gen_totp(secret, opts \\ [])

Generate a time-based one-time password.

There are two options:

  • token_length - the length of the one-time password

    • the default is 6

  • interval_length - the length of each timed interval

    • the default is 30 (seconds)
valid_token(token, token_length)

Check the one-time password is valid.

The one-time password should be at least 6 characters long, and it should be a string which only contains numeric values.