POT

• Introduction
• Version History
• Usage
• Function Reference
• Examples (Erlang)
• Examples (Elixir)
• Credits
• Licence

Introduction

POT is an Erlang library for generating one time passwords. It supports both HMAC-based one time passwords (HOTP) and time based ones (TOTP). The generated passwords are based on [RFC 4226][rfc4226] and [RFC 6238][rfc6238], compatible with [Google Authenticator][google_auth_wiki].

POT is an almost direct translation of the Python [OneTimePass][onetimepass] library.

POT should work with any recent version of [Erlang/OTP][erlang], [Elixir][elixir], and other Erlang VM based languages.

In order to learn more about one time password generation, see the following Wikipedia articles:

• [Google Authenticator][google_auth_wiki]
• [HMAC-based One-time Password Algorithm][hotp_wiki] ([RFC 4226][rfc4226])
• [Time-based One-time Password Algorithm][totp_wiki] ([RFC 6238][rfc6238])

Version History

2021-08-07

• Released version 1.0.2 with the following changes:

  • Fix type specs (Thanks to Krzysztof Jurewicz)
  • Added OTP 24.0 to CI (Thanks to Julius Beckmann)

2021-03-28

• Released version 1.0.1 with the following changes:

  • Migrate from Travis to GitHub Actions (Thanks to Nicholas Lundgaard)
  • Update pot.erl to support sha256 and not use deprecated :crypto.hmac (Thanks to Francois Paul)

2020-09-15

• Released version 1.0.0 with the following changes:

  • Move coveralls into project_plugins (Thanks to Bryan Paxton)

2020-03-08

• Released version 0.11.0 with the following changes:

  • Improved types, README documentation (Thanks to Nicholas Lundgaard)
  • Add return_interval option to valid_hotp (Thanks to Nicholas Lundgaard)

2019-10-16

• Released version 0.10.2 with the following change:

  • Fix valid_totp to support upper bound on check_candidate (Thanks to Nicholas Lundgaard)

2019-08-03

• Released version 0.10.1 with the following change:

  • Added pot prefix to base32 module avoid name collision (Thanks to Girish Ramnani). This is a breaking change, base32 module was renamed to pot_base32.

2019-07-09

• Released version 0.9.8 with the following bug fix:

  • Return boolean on pot:valid_hotp/2 and pot:valid_hotp/3 (Thanks to Zbigniew Pekala)

2018-02-12

• pot:totp/2 supports setting the timestamp (Thanks to Julius Beckmann)

2017-08-04

• Added options to support Android devices (Thanks to Pedro Vieira)

2016-07-30

• Released version 0.9.5 with bug fixes (Thanks to Peter McLain)

2015-01-20

• Embedded base32_erlang library

2015-01-18

• Initial version

Usage

See the sections below on using pot in your Erlang and Elixir project.

Erlang

We recommend using [rebar3][rebar3] for managing dependencies and building the library. POT is available on hex.pm, so you can just include the following in your rebar.config:

{deps, [pot]}.

See the Erlang examples

Elixir

Include POT in your mix.exs as a dependency:

defp deps do
    [{:pot, "~> 1.0"}]
end

<a id="function-ref"></a>Function Reference

The functions below refer to the following common parameters:

| Parameter | Type | |------------|----------| | Interval | integer | | Secret | string* | | Token | string* |

• Interval is an integer that represents the counter value, the "moving factor" referenced in [RFC 4226][rfc4226]. It is an 8 byte unsigned integer; if a negative and/or too large integer is passed, it will be 2's complemented and truncated appropriately.
• Secret is a base-32-encoded secret key. Generally, it should be at least 128 bits, preferably 160 bits.
• Token is a HOTP/TOTP value represented as a string*. This is generally a 6-digit number, e.g., "123456", but its length may be modulated with the token_length option.

*Note: for [Erlang][erlang] uses of pot, all strings should be in binary() format.

Token Generation Functions

hotp/2,3

Generate an [RFC 4226][rfc4226] compatible HOTP token.

Erlang:

pot:hotp(Secret, Interval) -> Token
pot:hotp(Secret, Interval, Options) -> Token

Elixir:

:pot.hotp(Secret, Interval) -> Token
:pot.hotp(Secret, Interval, Options) -> Token

The following Options are allowed:

| Option | Type | Default | |-----------------|-------------|---------| | digest_method | atom | sha | | token_length | integer > 0 | 6 |

• digest_method controls the signing algorithm passed to the [Erlang][erlang] crypto module's [hmac][crypto_hmac] function. For [RFC 4226][rfc4226] compliant tokens, it must be set to sha. For [RFC 6238][rfc6238] compliant tokens, additional values such as sha256 or sha512 may be used.
• token_length controls the number of digits in output Token.

totp/1,2

Generate an [RFC 6238][rfc6238] compatible TOTP token.

Erlang:

pot:totp(Secret) -> Token
pot:totp(Secret, Options) -> Token

Elixir:

:pot.totp(Secret) -> Token
:pot.totp(Secret, Options) -> Token

The following Options are allowed:

| Option | Type | Default/Reference | |-------------------|-------------|--------------------------| | addwindow | integer | 0 | | digest_method | atom | from hotp/2,3 | | interval_length | integer > 0 | 30 | | timestamp | timestamp | [os:timestamp()][ts] | | token_length | integer > 0 | from hotp/2,3 |

• addwindow acts as an offset to the Interval extrapolated from dividing the timestamp by the interval_length per the algorithm described in [RFC 6238][rfc6238].
• interval_length controls the number of seconds for the Interval computation.
• timestamp may be passed to specify a custom timestamp (in Erlang [timestamp][ts] format) to use for computing the Interval used to generate a Token.

Token Validation Functions

valid_token/1,2

Validate that a given Token has the correct format (correct length, all digits).

Erlang:

pot:valid_token(Token) -> Boolean
pot:valid_token(Token, Options) -> Boolean

Elixir:

:pot.valid_token(Token) -> Boolean
:pot.valid_token(Token, Options) -> Boolean

The following Options are allowed:

| Option | Type | Default/Reference | |-------------------|-------------|--------------------------| | token_length | integer > 0 | from hotp/2,3 |

valid_hotp/2,3

Validate an [RFC 4226][rfc4226] compatible HOTP token. Returns true if the Token is valid.

Erlang:

pot:valid_hotp(Token, Secret) -> Boolean
pot:valid_hotp(Token, Secret, Options) -> Boolean | {true, interval()}

Elixir:

:pot.valid_hotp(Token, Secret) -> Boolean
:pot.valid_hotp(Token, Secret, Options) -> Boolean | {true, interval()}

The following Options are allowed:

| Option | Type | Default/Reference | |-------------------|-------------|--------------------------| | digest_method | atom | from hotp/2,3 | | last | integer | 1 | | return_interval | boolean | false | | token_length | integer > 0 | from hotp/2,3 | | trials | integer > 0 | 1000 |

• last is the Interval value of the previous valid Token; the next Interval after last is used as the first candidate for validating the Token.
• trials controls the number of incremental Interval values after last to try when validating the Token. If a matching candidate is not found within trials attempts, the Token is considered invalid.
• return_interval controls whether the matching Interval of a valid Token is returned with the result. if set to true, then valid_hotp/2 will return {true, Interval} (e.g., {true, 123}) when a valid Token is provided.

valid_totp/2,3

Validate an [RFC 6238][rfc6238] compatible TOTP token. Returns true if the Token is valid.

Erlang:

pot:valid_totp(Token, Secret) -> Boolean
pot:valid_totp(Token, Secret, Options) -> Boolean

Elixir:

:pot.valid_totp(Token, Secret) -> Boolean
:pot.valid_totp(Token, Secret, Options) -> Boolean

The following Options are allowed:

| Option | Type | Default/Reference | |-------------------|-------------|--------------------------| | addwindow | integer | from totp/1,2 | | digest_method | atom | from hotp/2,3 | | interval_length | integer > 0 | from totp/1,2 | | timestamp | timestamp | from totp/1,2 | | token_length | integer > 0 | from [hotp