TwoFactorInACan v0.1.0 TwoFactorInACan.Totp View Source
Functions for working with time based one time password (TOTP) style two factory authentication as defined in RFC 4226
For details on RFC 4226, see https://tools.ietf.org/rfc/rfc4226.txt.
Link to this section Summary
Functions
Outputs the current TOTP token for the given secret.
Verifies that the provided TOTP token was generated using the provided secret.
Calculates the current time interval as an integer used in the HOTP algorithm to calculate the current token value.
Link to this section Functions
current_token_value(secret, opts \\ []) View Source
Outputs the current TOTP token for the given secret.
Expects a 160-bit binary key by default. To use secrets that are encoded the
:secret_format
option can be supplied. It expects one of the following
values:
:binary
(default):base32
:base64
This function can also accept all of the options accepted by
TwoFactorInACan.Totp.time_interval/1
. It simply passes them through when
retrieving the time interval to pass in as the count to the
TwoFactorInACan.Hotp.generate_token/3
function.
Examples
iex> secret = TwoFactorInACan.Secrets.generate_totp_secret()
iex> TwoFactorInACan.Totp.current_token_value(secret)
"858632"
iex> secret = TwoFactorInACan.Secrets.generate_totp_secret(format: :base32)
iex> TwoFactorInACan.Totp.current_token_value(secret, secret_format: :base32)
"743622"
iex> secret = TwoFactorInACan.Secrets.generate_totp_secret(format: :base64)
iex> TwoFactorInACan.Totp.current_token_value(secret, secret_format: :base64)
"384012"
same_secret?(secret, token, opts \\ []) View Source
Verifies that the provided TOTP token was generated using the provided secret.
This function uses the secret to generate a token. It then compares the generated token to the supplied token. If they match, then it can be probabilistically inferred that the entity that supplied the token also knew the secret.
This function allows a number of options:
:acceptable_past_tokens
(Default:0
) - The number of past tokens which should result in this function returning true. Setting this to1
can be a friendly way to allow users to still verify if they have taken too long to submit their token. It should be noted that this does result in two tokens being valid instead of one, which makes a valid token easeier to guess. This value should not be set too high or security is greatly compromised.:acceptable_future_tokens
(Default:0
) - The number of future tokens which should result in this function returning true. It should be noted that setting this to a nonzero value will allow more tokens to be valid and thus make a valid token easier to guess. This value should not be set too high or security is greatly compromised.:offset_seconds
(Default:0
) - The number of seconds to offset the current timestamp by. If the current timestamp was 600 and the offset was 60, then the timestamp of 660 would be used to calculate the time interval. This can be useful to account for drift or difference in clock times between two entities.:interval_seconds
(Default:30
) - The number of seconds that must pass before a new time_interval (and thus TOTP token) is returned by this function. This should probably never be anything but the default (30 seconds) during actual use, as nearly all apps that generate TOTP tokens assume a 30 second interval.:injected_timestamp
(default: current time) - The unix timestamp to use when calculating the time interval. This should only be used during testing to ensure the same token or interval is always returned. When this option is not supplied, the current timestamp is used.:secret_format
(default::binary
) - The format of the passed in secret. Can be one of:binary
,:base32
, or:base64
.
Examples
iex> secret = TwoFactorInACan.Secrets.generate_totp_secret()
iex> current_token = TwoFactorInACan.Totp.current_token_value(secret)
iex> TwoFactorInACan.Totp.same_secret?(secret, current_token)
true
time_interval(opts \\ [])
View Source
time_interval([{:key, :atom}]) :: integer()
time_interval([{:key, :atom}]) :: integer()
Calculates the current time interval as an integer used in the HOTP algorithm to calculate the current token value.
The following options are supported:
:offset_seconds
(Default: 0) - The number of seconds to offset the current timestamp by. If the current timestamp was 600 and the offset was 60, then the timestamp of 660 would be used to calculate the time interval. This can be useful to account for drift or to purposefully allow the last token to be valid as well in functions that use this function.:interval_seconds
(Default: 30) - The number of seconds that must pass before a new time_interval (and thus TOTP token) is returned by this function. This should probably never be anything but the default (30 seconds) during actual use, as nearly all apps that generate TOTP tokens assume a 30 second interval.:injected_timestamp
(default: current time) - The unix timestamp to use when calculating the time interval. This should only be used during testing to ensure the same token or interval is always returned. When this option is not supplied, the current timestamp is used.
Examples
iex> TwoFactorInACan.Totp.time_interval()
51802243
iex> TwoFactorInACan.Totp.time_interval(offset_seconds: 30)
51802244
iex> TwoFactorInACan.Totp.time_interval(interval_seconds: 60)
25901122
iex> TwoFactorInACan.Totp.time_interval(injected_timestamp: 1554067403)
51802246
iex> TwoFactorInACan.Totp.time_interval(injected_timestamp: 60, interval_seconds: 10)
6