/ 
Trog-TOTP-1.001
River stage zero No dependents
/ Trog::TOTP

NAME

Trog::TOTP - Fork of Authen::TOTP

VERSION

version 1.001

DESCRIPTION

Trog::TOTP is a fork of Authen::TOTP.

While patches were initially merged upstream, no CPAN releases happened, so here we are.

NAME

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

USAGE

 my $gen = new Authen::TOTP(
     # not needed when setting up TOTP for the first time; we generate a secret automatically which you should grab and store.
	 secret		=>	"some_random_stuff",
     # ACHTUNG! lots of TOTP apps on various devices straight up ignore this field and hardcode 30s periods.  So probably best to never touch this.
     period     => 30,
     # callback used when emitting messages; use me for integrating into your own logging framework
     logger     => sub { my $msg = shift; ... },
 );

 # Be sure to store this as binary data
 my $secret = $get->secret();

 # This is what you will want to show users for input into their TOTP apps when their camera is failing
 my $b32secret = $gen->base32secret();

 # will generate a TOTP URI, suitable to use in a QR Code
 my $uri = $gen->generate_otp(user => 'user\@example.com', issuer => "example.com");

 # 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");

 #compare user's OTP with computed one
 if ($gen->validate_otp(otp => <user_input>, secret => <stored_secret>, tolerance => 1)) {
	#2FA success
 }
 else {
	#no match
 }

  # Just print out the dang code
  print $gen->expected_totp_code(time);

CONSTRUCTOR

new

 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,
     logger     => sub { my $msg=shift; ... },
 );

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

logger

Log callback subroutine. Use to integrate various messages from this modules into your logging framework.

DEBUG

Turn on extended log messaging.

METHODS

secret

Return the current secret used by this object.

base32secret

Return the base32encoded secret used by this object.

algorithm([STRING $algo])

Returns, and optionally sets the algorithm if passed.

expected_totp_code( TIME_T $when )

Returns what a code "ought" to be at any given unix timestamp. Useful for integrating into command line tooling to fix things when people have "tecmological differences" with their telephone.

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

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/teodesian/Trog-TOTP/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHORS

Current Maintainers:

  • George S. Baugh <teodesian@gmail.com>

CONTRIBUTOR

Thanos Chatziathanassiou <tchatzi@arx.net>

COPYRIGHT AND LICENSE

Copyright (c) 2022 Troglodyne LLC

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.