https://github.com/mdp/rotp

Ruby One Time Password library
https://github.com/mdp/rotp

Keywords from Contributors

rubygem activerecord activejob mvc gem rack rspec crash-reporting sinatra feature-flag

Last synced: about 18 hours ago
JSON representation

Repository metadata

Ruby One Time Password library

Host: GitHub
URL: https://github.com/mdp/rotp
Owner: mdp
License: mit
Created: 2011-02-13T18:20:59.000Z (almost 15 years ago)
Default Branch: main
Last Pushed: 2025-11-24T21:17:25.000Z (20 days ago)
Last Synced: 2025-12-08T01:10:45.239Z (7 days ago)
Language: Ruby
Homepage: http://rubydoc.info/github/mdp/rotp/master/frames
Size: 290 KB
Stars: 1,652
Watchers: 22
Forks: 474
Open Issues: 10
Releases: 1
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE

Webauthn and the future of 2FA

Although this library will continue to be maintained, if you're implementing a 2FA solution today, you should take a look at Webauthn. It doesn't involve shared secrets and it's supported by most modern browsers and operating systems.

Ruby resources for Webauthn

The Ruby One Time Password Library

A ruby library for generating and validating one time passwords (HOTP & TOTP) according to RFC 4226 and RFC 6238.

ROTP is compatible with Google Authenticator available for Android and iPhone and any other TOTP based implementations.

Many websites use this for multi-factor authentication, such as GMail, Facebook, Amazon EC2, WordPress, and Salesforce. You can find a more complete list here.

Dependencies

OpenSSL
Ruby 2.3 or higher

Breaking changes

Breaking changes in >= 6.0

Dropping support for Ruby <2.3

Breaking changes in >= 5.0

ROTP::Base32.random_base32 is now ROTP::Base32.random and the argument
has changed from secret string length to byte length to allow for more
precision. There is an alias to allow for random_base32 for the time being.
Cleaned up the Base32 implementation to match Google Authenticator's version.

Breaking changes in >= 4.0

Simplified API
- verify now takes options for drift and after,padding is no longer an option
- verify returns a timestamp if true, nil if false
Dropping support for Ruby < 2.0
Docs for 3.x can be found here

Installation

gem install rotp

Library Usage

Time based OTP's

totp = ROTP::TOTP.new("base32secret3232", issuer: "My Service")
totp.now # => "492039"

# OTP verified for current time - returns timestamp of the current interval
# period.
totp.verify("492039") # => 1474590700

sleep 30

# OTP fails to verify - returns nil
totp.verify("492039") # => nil

Counter based OTP's

hotp = ROTP::HOTP.new("base32secretkey3232")
hotp.at(0) # => "786922"
hotp.at(1) # => "595254"
hotp.at(1401) # => "259769"

# OTP verified with a counter
hotp.verify("259769", 1401) # => 1401
hotp.verify("259769", 1402) # => nil

Preventing reuse of Time based OTP's

By keeping track of the last time a user's OTP was verified, we can prevent token reuse during
the interval window (default 30 seconds)

The following is an example of this in action:

user = User.find(someUserID)
totp = ROTP::TOTP.new(user.otp_secret)
totp.now # => "492039"

# Let's take a look at the last time the user authenticated with an OTP
user.last_otp_at # => 1432703530

# Verify the OTP
last_otp_at = totp.verify("492039", after: user.last_otp_at) #=> 1472145760
# ROTP returns the timestamp(int) of the current period

# Store this on the user's account
user.update(last_otp_at: last_otp_at)

# Someone attempts to reuse the OTP inside the 30s window
last_otp_at = totp.verify("492039", after: user.last_otp_at) #=> nil
# It fails to verify because we are still in the same 30s interval window

Verifying a Time based OTP with drift

Some users may enter a code just after it has expired. By adding 'drift' you can allow
for a recently expired token to remain valid.

totp = ROTP::TOTP.new("base32secret3232")
now = Time.at(1474590600) #2016-09-23 00:30:00 UTC
totp.at(now) # => "250939"

# OTP verified for current time along with 15 seconds earlier
# ie. User enters a code just after it expired
totp.verify("250939", drift_behind: 15, at: now + 35) # => 1474590600
# User waits too long. Fails to validate previous OTP
totp.verify("250939", drift_behind: 15, at: now + 45) # => nil

Generating a Base32 Secret key

ROTP::Base32.random  # returns a 160 bit (32 character) base32 secret. Compatible with Google Authenticator

Note: The Base32 format conforms to RFC 4648 Base32

Generating QR Codes for provisioning mobile apps

Provisioning URI's generated by ROTP are compatible with most One Time Password applications, including
Google Authenticator.

totp = ROTP::TOTP.new("base32secret3232", issuer: "My Service")
totp.provisioning_uri("alice@google.com") # => 'otpauth://totp/My%20Service:alice%40google.com?secret=base32secret3232&issuer=My%20Service'

hotp = ROTP::HOTP.new("base32secret3232", issuer: "My Service")
hotp.provisioning_uri("alice@google.com", 0) # => 'otpauth://hotp/My%20Service:alice%40google.com?secret=base32secret3232&issuer=My%20Service&counter=0'

This can then be rendered as a QR Code which the user can scan using their mobile phone and the appropriate application.

Working example

Scan the following barcode with your phone, using Google Authenticator

QR Code for OTP

Now run the following and compare the output

require 'rubygems'
require 'rotp'
totp = ROTP::TOTP.new("JBSWY3DPEHPK3PXP")
p "Current OTP: #{totp.now}"

Testing

bundle install
bundle exec rspec

Testing with Docker

In order to make it easier to test against different ruby version, ROTP comes
with a set of Dockerfiles for each version that we test against in Travis

docker build -f Dockerfile-2.6 -t rotp_2.6 .
docker run --rm -v $(pwd):/usr/src/app rotp_2.6

Alternately, you may use docker-compose to run all the tests:

docker-compose up

Executable Usage

The rotp rubygem includes CLI version to help with testing and debugging

# Try this to get an overview of the commands
rotp --help

# Examples
rotp --secret p4ssword                       # Generates a time-based one-time password
rotp --hmac --secret p4ssword --counter 42   # Generates a counter-based one-time password

Contributors

Have a look at the contributors graph on Github.

License

Other implementations

A list can be found at Wikipedia.

Owner metadata

Name: Mark Percival
Login: mdp
Email:
Kind: user
Description:
Website: https://mdp.github.io
Location: Atlanta, GA
Twitter: mdp
Company:
Icon url: https://avatars.githubusercontent.com/u/2868?u=90e0995d4bdae3bfdb66b47b3864a423d72398d7&v=4
Repositories: 188
Last ynced at: 2024-04-14T08:26:15.914Z
Profile URL: https://github.com/mdp

GitHub Events

Total

Issues event: 2
Watch event: 53
Issue comment event: 15
Push event: 14
Pull request review event: 2
Pull request review comment event: 1
Pull request event: 15
Fork event: 4
Create event: 7

Last Year

Issues event: 2
Watch event: 44
Issue comment event: 14
Push event: 14
Pull request review event: 2
Pull request review comment event: 1
Pull request event: 15
Fork event: 4
Create event: 7

Committers metadata

Last synced: 9 days ago

Total Commits: 234
Total Committers: 46
Avg Commits per committer: 5.087
Development Distribution Score (DDS): 0.419

Commits in past year: 7
Committers in past year: 2
Avg Commits per committer in past year: 3.5
Development Distribution Score (DDS) in past year: 0.143

Name	Email	Commits
Mark Percival	m@m****m	136
Mark Percival	m**k@m**m	15
halo	g**b@p**g	14
Alex Cruice	a**e@g**m	7
David Vrensk	d**d@v**m	6
Mark Percival	m**k@m**s	4
Asmod4n	A****n	3
Sam Clegg	s**g@o**v	3
Gus Bonfant	g**t@m**m	2
Keeyan Nejad	k**n@k**k	2
Ilya Sabanin	i**n@g**m	2
Ivan Povalyukhin	i**l@g**m	2
Jeremy Evans	c**e@j**t	2
Olle Jonsson	o**n@g**m	2
dependabot[bot]	4****]	2
Shai Rosenfeld & Michael Brodhead	s**d@e**m	2
github-actions[bot]	4****]	1
amanda	m**5@1**m	1
Tristan Morgan	t****n	1
Surendra Singhi	s**i@k**m	1
Bruno Oliveira	b**o@a**g	1
Fup Duck	g**b@d**g	1
Guillaume Rose	r**e@n**r	1
Joe Faber	j**r@s**m	1
Micah Gates	g**b@m**m	1
Michael Brodhead & Shai Rosenfeld	m**d@e**m	1
Nathan Reynolds	g**b@n**k	1
Sergey Petrenko	s**o@o**m	1
Ylan Segal	y**l@m**m	1
mdp	m**p@y**m	1
and 16 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 16 days ago

Total issues: 46
Total pull requests: 93
Average time to close issues: 3 months
Average time to close pull requests: 4 months
Total issue authors: 46
Total pull request authors: 45
Average comments per issue: 2.22
Average comments per pull request: 1.12
Merged pull request: 60
Bot issues: 0
Bot pull requests: 9

Past year issues: 1
Past year pull requests: 19
Past year average time to close issues: N/A
Past year average time to close pull requests: 25 days
Past year issue authors: 1
Past year pull request authors: 7
Past year average comments per issue: 0.0
Past year average comments per pull request: 1.0
Past year merged pull request: 5
Past year bot issues: 0
Past year bot pull requests: 5

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/mdp/rotp

Top Issue Authors

olleolleolle (1)
kapitolinakuznetsova (1)
evolve2k (1)
samueltangz (1)
fydelio (1)
thomasdziedzic (1)
prvinuch (1)
artmotion (1)
kesha-antonov (1)
btalbot (1)
HParker (1)
ZempTime (1)
braindev (1)
jDessicVaZ92 (1)
amitiitm (1)

Top Pull Request Authors

mdp (24)
dependabot[bot] (7)
olleolleolle (4)
jeremyevans (3)
ssinghi (3)
sbc100 (3)
halo (3)
dvrensk (2)
KNejad (2)
tsogbadrakh-qp (2)
wdalzalat (2)
luong-komorebi (2)
Earlopain (2)
github-actions[bot] (2)
hieuk09 (2)

Top Issue Labels

Top Pull Request Labels

dependencies (7)
github_actions (3)
autorelease: pending (2)

Package metadata

Total packages: 5
Total downloads:
- rubygems: 236,093,031 total
Total docker downloads: 1,390,445,648
Total dependent packages: 64 (may contain duplicates)
Total dependent repositories: 3,074 (may contain duplicates)
Total versions: 101
Total maintainers: 1
Total advisories: 1

gem.coop: rotp

Works for both HOTP and TOTP, and includes QR Code provisioning

Homepage: https://github.com/mdp/rotp
Documentation: http://www.rubydoc.info/gems/rotp/
Licenses: MIT
Latest release: 6.3.0 (published over 2 years ago)
Last Synced: 2025-12-12T22:04:48.271Z (2 days ago)
Versions: 38
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 118,063,013 Total
Docker Downloads: 695,222,824
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 0.086%
- Docker downloads count: 0.133%
- Downloads: 0.211%
Maintainers (1)
- mdp

rubygems.org: rotp

Works for both HOTP and TOTP, and includes QR Code provisioning

Homepage: https://github.com/mdp/rotp
Documentation: http://www.rubydoc.info/gems/rotp/
Licenses: MIT
Latest release: 6.3.0 (published over 2 years ago)
Last Synced: 2025-12-12T03:31:11.597Z (3 days ago)
Versions: 38
Dependent Packages: 64
Dependent Repositories: 3,073
Downloads: 118,010,846 Total
Docker Downloads: 695,222,824
Rankings:
- Docker downloads count: 0.186%
- Downloads: 0.267%
- Dependent packages count: 0.466%
- Dependent repos count: 0.563%
- Average: 0.675%
- Forks count: 1.283%
- Stargazers count: 1.288%
Maintainers (1)
- mdp
Advisories:
- ROTP 6.2.2 and 6.2.1 has 0666 permissions for the .rb files.

proxy.golang.org: github.com/mdp/rotp

Homepage:
Documentation: https://pkg.go.dev/github.com/mdp/rotp#section-documentation
Licenses: mit
Latest release: v6.3.1+incompatible (published 6 months ago)
Last Synced: 2025-12-10T22:01:14.386Z (4 days ago)
Versions: 19
Dependent Packages: 0
Dependent Repositories: 0
Rankings:
- Forks count: 1.399%
- Stargazers count: 1.702%
- Average: 5.87%
- Dependent packages count: 9.576%
- Dependent repos count: 10.802%

gem.coop: sjcl

A Ruby library for interopping with SJCL's AES crypto

Homepage: http://github.com/mdp/rotp
Documentation: http://www.rubydoc.info/gems/sjcl/
Licenses: MIT
Latest release: 1.0.1 (published almost 11 years ago)
Last Synced: 2025-12-10T22:01:14.066Z (4 days ago)
Versions: 3
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 9,586 Total
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 15.96%
- Downloads: 47.881%
Maintainers (1)
- mdp

rubygems.org: sjcl

A Ruby library for interopping with SJCL's AES crypto

Homepage: http://github.com/mdp/rotp
Documentation: http://www.rubydoc.info/gems/sjcl/
Licenses: MIT
Latest release: 1.0.1 (published almost 11 years ago)
Last Synced: 2025-12-10T22:01:13.989Z (4 days ago)
Versions: 3
Dependent Packages: 0
Dependent Repositories: 1
Downloads: 9,586 Total
Rankings:
- Forks count: 1.274%
- Stargazers count: 1.288%
- Dependent packages count: 15.782%
- Average: 17.686%
- Dependent repos count: 21.706%
- Downloads: 48.382%
Maintainers (1)
- mdp

Dependencies

rotp.gemspec rubygems

rake ~> 13.0 development
rspec ~> 3.5 development
simplecov ~> 0.12 development
timecop ~> 0.8 development

.github/workflows/test.yaml actions

actions/checkout v3 composite
ruby/setup-ruby 359bebbc29cbe6c87da6bc9ea3bc930432750108 composite

.devcontainer/Dockerfile docker

mcr.microsoft.com/vscode/devcontainers/ruby 0-${VARIANT} build

.github/workflows/release.yaml actions

actions/checkout v4 composite
google-github-actions/release-please-action v4 composite
ruby/setup-ruby v1 composite

docker-compose.yml docker

Gemfile rubygems

Score: 32.454140738768686

https://github.com/mdp/rotp

Keywords from Contributors

Repository metadata

README.md

Webauthn and the future of 2FA

Ruby resources for Webauthn

The Ruby One Time Password Library

Dependencies

Breaking changes

Breaking changes in >= 6.0

Breaking changes in >= 5.0

Breaking changes in >= 4.0

Installation

Library Usage

Time based OTP's

Counter based OTP's

Preventing reuse of Time based OTP's

Verifying a Time based OTP with drift

Generating a Base32 Secret key

Generating QR Codes for provisioning mobile apps

Working example

Testing

Testing with Docker

Executable Usage

Contributors

License

Other implementations

Owner metadata

GitHub Events

Total

Last Year

Committers metadata

Committer domains:

Issue and Pull Request metadata

Top Issue Authors

Top Pull Request Authors

Top Issue Labels

Top Pull Request Labels

Package metadata

gem.coop: rotp

rubygems.org: rotp

proxy.golang.org: github.com/mdp/rotp

gem.coop: sjcl

rubygems.org: sjcl

Dependencies