Authen::TOTP - Interface to RFC6238 two factor authentication (2FA)
Version 0.0.7
use Authen::TOTP;
Authen::TOTP is a simple interface for creating and verifying RFC6238 OTPs as used by Google Authenticator, Authy, Duo Mobile etc
Authen::TOTP
It currently passes RFC6238 Test Vectors for SHA1, SHA256, SHA512
my $gen = new Authen::TOTP( secret => "some_random_stuff", ); #will generate a TOTP URI, suitable to use in a QR Code my $uri = $gen->generate_otp(user => 'user\@example.com', issuer => "example.com"); print qq{$uri\n}; #store $gen->secret() or $gen->base32secret() someplace safe! #use Imager::QRCode to plot the secret for the user use Imager::QRCode; my $qrcode = Imager::QRCode->new( size => 4, margin => 3, level => 'L', casesensitive => 1, lightcolor => Imager::Color->new(255, 255, 255), darkcolor => Imager::Color->new(0, 0, 0), ); my $img = $qrcode->plot($uri); $img->write(file => "totp.png", type => "png"); #...or you can pass it to google charts and be done with it #compare user's OTP with computed one if ($gen->validate_otp(otp => <user_input>, secret => <stored_secret>, tolerance => 1)) { #2FA success } else { #no match }
my $gen = new Authen::TOTP( digits => [6|8], period => [30|60], algorithm => "SHA1", #SHA256 and SHA512 are equally valid secret => "some_random_stuff", when => <some_epoch>, tolerance => 0, );
6=> How many digits to produce/compare
6
30=> OTP is valid for this many seconds
30
SHA1=> supported values are SHA1, SHA256 and SHA512, although most clients only support SHA1 AFAIK
SHA1
random_20byte_string=> Secret used as seed for the OTP
random_20byte_string
base32_encoded_random_12byte_string=> Alternative way to set secret (base32 encoded)
base32_encoded_random_12byte_string
epoch=> Time used for comparison of OTPs
epoch
1=> Due to time sync issues, you may want to tune this and compare this many OTPs before and after
1
generate_otp
Create a TOTP URI using the parameters specified or the defaults from the new() method above
Usage:
$gen->generate_otp( digits => [6|8], period => [30|60], algorithm => "SHA1", #SHA256 and SHA512 are equally valid secret => "some_random_stuff", issuer => "example.com", user => "some_identifier", ); Google Authenticator displays <issuer> (<user>) for a TOTP generated like this
validate_otp
Compare a user-supplied TOTP using the parameters specified. Obviously the secret MUST be the same secret you used in generate_otp() above/ Returns 1 on success, undef if OTP doesn't match
$gen->validate_otp( digits => [6|8], period => [30|60], algorithm => "SHA1", #SHA256 and SHA512 are equally valid secret => "the_same_random_stuff_you_used_to_generate_the_TOTP", when => <epoch_to_use_as_reference>, tolerance => <try this many iterations before/after when> otp => <OTP to compare to> );
0.0.7 Moved git repo to github Added CONTRIBUTING.md file Changed gen_secret() to accept secret length as argument and made 20 the default 0.0.6 Another pointless adjustment in cpanfile 0.0.5 Corrected cpanfile to require either MIME::Base32::XS or MIME::Base32 and Digest::SHA or Digest::SHA::PurePerl 0.0.4 Added missing test vectors 0.0.3 Switched to Digest::SHA in order to support SHA256 and SHA512 as well 0.0.2 Added Digest::HMAC_SHA1 and MIME::Base32 to cpanfiles requires (still getting acquainted with Minilla) 0.0.1 Initial Release
one of Digest::SHA or Digest::SHA::PurePerl
and MIME::Base32::XS or MIME::Base32
Imager::QRCode if you want to generate QRCodes as well
Auth::GoogleAuth for a module that does mostly the same thing
https://tools.ietf.org/html/rfc6238 for more info on TOTPs
Some stuff definitely isn't as efficient as it can be
Well, it passes RFC test vectors and has so far proven compatible with Gitlab's 2FA. Let me know if you find anything that's not working
Github user j256 for his example implementation
Gryphon Shafer <gryphon@cpan.org> for his Auth::GoogleAuth module that does mostly the same job, but I discovered after I had written most of this
Thanos Chatziathanassiou <tchatzi@arx.net> http://www.arx.net
Copyright (c) 2020 arx.net - Thanos Chatziathanassiou . All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
See http://www.perl.com/perl/misc/Artistic.html
To install Authen::TOTP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Authen::TOTP
CPAN shell
perl -MCPAN -e shell install Authen::TOTP
For more information on module installation, please visit the detailed CPAN module installation guide.