/ 
Authen-TOTP-0.0.7
River stage zero No dependents
/ Authen::TOTP

NAME

Authen::TOTP - Interface to RFC6238 two factor authentication (2FA)

Version 0.0.7

SYNOPSIS

use Authen::TOTP;

DESCRIPTION

Authen::TOTP is a simple interface for creating and verifying RFC6238 OTPs as used by Google Authenticator, Authy, Duo Mobile etc

It currently passes RFC6238 Test Vectors for SHA1, SHA256, SHA512

USAGE

 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
 }

new Authen::TOTP

 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,
 );

Parameters/Properties (defaults listed)

digits

6=> How many digits to produce/compare

period

30=> OTP is valid for this many seconds

algorithm

SHA1=> supported values are SHA1, SHA256 and SHA512, although most clients only support SHA1 AFAIK

secret

random_20byte_string=> Secret used as seed for the OTP

base32secret

base32_encoded_random_12byte_string=> Alternative way to set secret (base32 encoded)

when

epoch=> Time used for comparison of OTPs

tolerance

1=> Due to time sync issues, you may want to tune this and compare this many OTPs before and after

Utility Functions

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

Usage:

 $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>
 );

Revision History

 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

DEPENDENCIES

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

SEE ALSO

Auth::GoogleAuth for a module that does mostly the same thing

https://tools.ietf.org/html/rfc6238 for more info on TOTPs

CAVEATS

Some stuff definitely isn't as efficient as it can be

BUGS

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

ACKNOWLEDGEMENTS

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

AUTHOR

Thanos Chatziathanassiou <tchatzi@arx.net> http://www.arx.net

COPYRIGHT

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