CrOTP - One Time Passwords for Crystal


The Crystal One Time Password library. Use this to generate HOTP or TOTP codes for two factor authentication.

Build Status

Table of Contents


Add this to your application's shard.yml:

    github: philnash/crotp



require "crotp"

hotp ="secret")
counter = 1

# Generate a token
token = hotp.generate(counter)
# => "533881"

# Verify code
result = hotp.verify(token, counter)
# => true


require "crotp"

totp ="secret")

# Generate a code at a specific time stamp (by default, #generate will make a
# code using
token = totp.generate(at: 1484007247)
# => "020567"

# Verify code at a specific time stamp
result = totp.verify(token, at: 1484007247)
# => true

# Verify code at different time stamp, with allowed drift
result = totp.verify(token, at: 1484007299, allowed_drift: 1)
# => true

# Verify code at different time stamp, outside allowed drift
result = totp.verify(token, at: 1484007300, allowed_drift: 1)
# => false

TOTP hashing algorithms

According to RFC 6238 section 1.2:

TOTP implementations MAY use HMAC-SHA-256 or HMAC-SHA-512 functions, based on SHA-256 or SHA-512 hash functions, instead of the HMAC-SHA-1 function that has been specified for the HOTP computation in RFC4226.

To use either SHA-256 or SHA-512 as the hashing function, initialise your CrOTP::TOTP object with the algorithm you want:

require "crotp"

totp ="secret", algorithm: OpenSSL::Algorithm::SHA512)

Note: authenticator applications may ignore the algorithm parameter when you encode your secret in a URL/QR code as below.

Authenticator applications

To share secrets with an authenticator application, like Authy or Google Authenticator you need a URI that you can share as a QR code. The implementation details for the URI are in the Google Authenticator wiki.

Here is how you can get the URI and, in case your user can't scan the code, the base 32 representation of the secret.


# For HOTP you need the initial counter and an issuer
puts hotp.authenticator_uri(initial_counter: 0, issuer: "Test app")
# => otpauth://hotp/Test%20app?secret=ONSWG4TFOQ&algorithm=SHA1&counter=0&digits=6&issuer=Test%20app

# You can add a user account detail too, normally an email address or username, that shows up in the authenticator app
puts hotp.authenticator_uri(initial_counter: 0, issuer: "Test app", user: "")
# => otpauth://hotp/


# For TOTP you only need an issuer
puts totp.authenticator_uri(issuer: "Test app")
# => otpauth://totp/Test%20app?secret=ONSWG4TFOQ&algorithm=SHA1&period=30&digits=6&issuer=Test%20app

# You can add a user detail here too
puts totp.authenticator_uri(issuer: "Test app", user: "")
# => otpauth://totp/

Base 32 secret

puts hotp.base32_secret

puts totp.base32_secret

You can see and run these examples and more in example/


  • Basic HOTP and TOTP generation and verification
  • Rewrite int_to_bytes and extract from CrOTP::OTP
  • Verifying a token over a window of counters/time
  • Google Authenticator otpauth URI generation
  • Ability to choose algorithm (currently only sha1)
  • Ability to choose size of period in TOTP
  • Example application using Kemal
  • Much more documentation

Running the project locally

First clone the project:

git clone
cd crotp

Run the tests with:

crystal spec


  1. Fork it ( )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request


This code is available as open source under the terms of the MIT License.


Change Log

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

[0.5.0] - 2019-10-09

  • Crystal 0.31.0 changed the behaviour of Int#/ in favour of Int#// for integer division. This affected the base32 module, which no longer builds. Updated to point at a fork of base32 that does build in 0.31.0.

[0.4.0] - 2019-08-18


  • Crystal 0.30.0 deprecated URI.escape in favour of URI.encode_www_form. Updated this to match the original behaviour (with space_to_plus: false).
  • Crystal 0.28.0 deprecated Updated to use Time.utc which is actually more correct according to the RFC.
  • Crystal 0.29.0 deprecated the behaviour of Int#/ to return integers. Changed to use Int#// instead.

[0.3.0] - 2019-07-27


  • Support and tests for TOTP with SHA256 and SHA512


  • Crystal 0.28.0 changed the first argument for OpenSSL::HMAC#digest from a symbol to a type of OpenSSL::Algorithm. Updated this within the library thanks to @Xosmond.

[0.2.0] - 2019-03-28


  • Crystal 0.27.0 changed Time#epoch to Time#to_unix, updated within the library thanks to @Xosmond

[0.1.3] - 2018-05-27


  • Added authenticator_uri to HOTP and TOTP objects to generate URIs for 2FA authenticator apps.
  • Added base32_secret to both objects so that users who can't use the URI or QR code can copy the base32 secret to their authenticator app.

[0.1.2] - 2018-05-26


  • Added an allowed_drift to verify methods so that codes can be valid longer.

[0.1.1] - 2017-01-10


  • Replaced implementation of int_to_bytes with IO::ByteFormat::LittleEndian.encode thanks to @benoist

[0.1.0] - 2017-01-07


  • Initial implementation of HOTP and TOTP.
Github statistic:
  • 42
  • 3
  • 7
  • 1
  • 0
  • 10 days ago


MIT License