CrOTP - One Time Passwords for Crystal
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
example
spec
src
.gitignore
.travis.yml
CHANGELOG.md
LICENSE
README.md
shard.yml
test.cr

README.md

CrOTP

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

Build Status

Installation

Add this to your application's shard.yml:

dependencies:
  crotp:
    github: philnash/crotp

Usage

HOTP

require "crotp"

hotp = CrOTP::HOTP.new("secret")
counter = 1

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

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

TOTP

require "crotp"

totp = CrOTP::TOTP.new("secret")

# Generate a code at a specific time stamp (by default, #generate will make a
# code using Time.now)
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

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.

HOTP

# 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: "philnash@example.com")
# => otpauth://hotp/Test%20app:philnash%40example.com?secret=ONSWG4TFOQ&algorithm=SHA1&counter=0&digits=6&issuer=Test%20app

TOTP

# 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: "philnash@example.com")
# => otpauth://totp/Test%20app:philnash%40example.com?secret=ONSWG4TFOQ&algorithm=SHA1&period=30&digits=6&issuer=Test%20app

Base 32 secret

puts hotp.base32_secret
# => ONSWG4TFOQ

puts totp.base32_secret
# => ONSWG4TFOQ

You can see and run these examples and more in example/crotp.cr.

Todo

  • 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 https://github.com/philnash/crotp.git
cd crotp

Run the tests with:

crystal spec

Contributing

  1. Fork it ( https://github.com/philnash/crotp/fork )
  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

Contributors