view release on metacpan or  search on metacpan

lib/Authen/TOTP.pm  view on Meta::CPAN

=item algorithm

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

=item secret

C<random_20byte_string>=> Secret used as seed for the OTP

=item base32secret

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

=item when

C<epoch>=> Time used for comparison of OTPs

=item tolerance

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

=back

=head2 Utility Functions

=over 4

=item C<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

=item C<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>
 );

 $gen->otp( <when> ); # Get the TOTP token at <epoch_to_use>
 
=back

=cut

=head1 Revision History

 0.1.1
    Replace rand() with Crypt::PRNG::random_string_from() following
    advisory from rrwo@cpansec.org and CVE-2026-46473
 0.1.0
	Fix documentation inaccuracies (still referenced MIME::Base32::XS)
 0.0.9
	Added otp method to get user code, and updated tests for this.
 0.0.8
	Remove usage of MIME::Base32::XS, in favor of the faster Encode::Base2N
 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

=head1 DEPENDENCIES

one of 
L<Digest::SHA> or L<Digest::SHA::PurePerl>

and
L<Encode::Base2N> or L<MIME::Base32>

and
L<Crypt::PRNG> since version 0.1.1 for safer random secrets

L<Imager::QRCode> if you want to generate QRCodes as well

=head1 SEE ALSO

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

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

=head1 CAVEATS