NimbleTOTP is a tiny library for Two-factor authentication (2FA) that allows developers to implement Time-Based One-Time Passwords (TOTP) for their applications.

Two-factor authentication (2FA)

The concept of 2FA is quite simple. It's an extra layer of security that demands a user to provide two pieces of evidence (factors) to the authentication system before access can be granted.

One way to implement 2FA is to generate a random secret for the user and whenever the system needs to perform a critical action it will ask the user to enter a validation code. This validation code is a Time-Based One-Time Password (TOTP) based on the user's secret and can be provided by an authentication app like Google Authenticator or Authy, which should be previously installed and configured on a compatible device, e.g. a smartphone.

Note: A critical action can mean different things depending on the application. For instance, while in a banking system the login itself is already considered a critical action, in other systems a user may be allowed to log in using just the password and only when trying to update critical data (e.g. its profile) 2FA will be required.

Using NimbleTOTP

In order to allow developers to implement 2FA, NimbleTOTP provides functions to:

• Generate secrets composed of random bytes.
• Generate URIs to be encoded in a QR Code.
• Generate Time-Based One-Time Passwords (TOTPs) based on a secret.

Generating the secret

The first step to set up 2FA for a user is to generate (and later persist) its random secret. You can achieve that using NimbleTOTP.secret/1.

Example:

secret = NimbleTOTP.secret()
#=> <<178, 117, 46, 7, 172, 202, 108, 127, 186, 180, ...>>

By default, a binary with 20 random bytes is generated per the HOTP RFC.

Generating URIs for QR Code

Before persisting the secret, you need to make sure the user has already configured the authentication app in a compatible device. The most common way to do that is to generate a QR Code that can be read by the app.

You can use NimbleTOTP.otpauth_uri/3 along with eqrcode to generate the QR code as SVG.

Example:

uri = NimbleTOTP.otpauth_uri("Acme:alice", secret, issuer: "Acme")
#=> "otpauth://totp/Acme:alice?secret=MFRGGZA&issuer=Acme"
uri |> EQRCode.encode() |> EQRCode.svg()
#=> "<?xml version=\\"1.0\\" standalone=\\"yes\\"?>\\n<svg version=\\"1.1\\" ...

Generating a Time-Based One-Time Password

After successfully reading the QR Code, the app will start generating a different 6 digit code every 30s. You can compute the verification code with:

NimbleTOTP.verification_code(secret)
#=> "569777"

The code can be validated using the valid?/3 function. Example:

NimbleTOTP.valid?(secret, "569777")
#=> true

NimbleTOTP.valid?(secret, "012345")
#=> false

After validating the code, you can finally persist the user's secret so you use it later whenever you need to authorize any critical action using 2FA, by using the same valid?/2 function.

Grace period

When you generate a verification code, the code will be valid between 0..period seconds, where the default period is 30s. This means that, in the worst case scenario, you may generate a verification code that will become invalid in the next second.

Depending on how you require users to generate codes, it might be beneficial to allow for a larger validity window for the codes. For example, that might be useful if you deliver codes through potentially-slow mediums (like SMS). In this case, consider a number of "previous codes" also valid. To do this, use the :time option in valid?/3 (see the function documentation for more examples).

Preventing codes from being reused

The TOTP RFC requires that a valid code can only be used once. This is a security feature that prevents codes from being reused. For example, a user could legitimately log in with a code, but in the validity window an attacker could gain access to the code and also log in.

To ensure codes are only considered valid if they have not been used, you need to keep track of the last time the user entered a valid TOTP code. For example, you can do that in a database column. Then, you can use the :since option in valid?/3:

NimbleTOTP.valid?(user.totp_secret, code, since: user.last_totp_at)

Assuming the code itself is valid for the given secret:

• If :since is nil, the code will be considered valid.

• If since is given, it will not allow codes in the same time period (30 seconds by default) to be reused. The user will have to wait for the next code to be generated.

Preventing enumeration attacks

If you only store the last time a user entered a valid TOTP code, you can prevent a valid code from being reused. However, this approach by itself doesn't generally prevent an attacker from attempting to "guess" a valid code by enumerating codes. TOTP codes are somewhat short, at only one million possible values. You'll likely have other rate-limiting mechanisms in place that would prevent an attacker from attempting codes in rapid sequence, but if you don't, you'll also want to limit the number of attempts in some way.