Provided by: libauth-googleauth-perl_1.03-1_all 
NAME
Auth::GoogleAuth - Google Authenticator TBOT Abstraction
VERSION
version 1.03
SYNOPSIS
use Auth::GoogleAuth;
my $auth = Auth::GoogleAuth->new;
$auth = Auth::GoogleAuth->new({
secret => 'some secret string thing',
issuer => 'Gryphon Shafer',
key_id => 'gryphon@cpan.org',
});
$auth->secret(); # get/set
$auth->secret32(); # get/set
$auth->issuer(); # get/set
$auth->key_id(); # get/set
my $secret32 = $auth->generate_secret32;
$auth->clear;
my $url_0 = $auth->qr_code;
my $url_1 = $auth->qr_code(
'bv5o3disbutz4tl3', # secret32
'gryphon@cpan.org', # key_id
'Gryphon Shafer', # issuer
);
my $url_2 = $auth->qr_code(
'bv5o3disbutz4tl3', 'gryphon@cpan.org', 'Gryphon Shafer', 1,
);
my $otpauth = $auth->otpauth;
my $code_0 = $auth->code;
my $code_1 = $auth->code( 'utz4tl3bv5o3disb', 1438643789, 30 );
my $verification_0 = $auth->verify('879364');
my $verification_1 = $auth->verify(
'879364', # code
1, # range
'utz4tl3bv5o3disb', # secret32
1438643820, # timestamp (defaults to now)
30, # interval (default 30)
);
DESCRIPTION
This module provides a simplified interface to supporting typical two-factor authentication (i.e. "2FA")
with Google Authenticator <https://en.wikipedia.org/wiki/Google_Authenticator> using the TOTP Algorithm
<https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm> as defined by RFC 6238
<http://tools.ietf.org/html/rfc6238>. Although Google Authenticator supports both TOTP and HOTP, at the
moment, this module only supports TOTP.
METHODS
The following are the supported methods of this module:
new
This is a simple instantiator to which you can pass optional default values.
my $auth = Auth::GoogleAuth->new;
$auth = Auth::GoogleAuth->new({
secret => 'some secret string thing',
issuer => 'Gryphon Shafer',
key_id => 'gryphon@cpan.org',
});
The object returned will support the following attribute get/set methods:
secret
This can be any string. It'll be used as the internal secret key to create the QR codes and
authentication codes.
secret32
This is a base-32 encoded copy of the secret string. If this is left undefined and you run one of the
methods that require it (like "qr_code" or "code"), the method called will try to create the "secret32"
by looking for a value in "secret". If none exists, a random "secret32" will be generated.
issuer
This is the label name of the "issuer" of the authentication. See the key URI format wiki page
<https://github.com/google/google-authenticator/wiki/Key-Uri-Format> for more information.
key_id
This is the label name of the "key ID" of the authentication. See the key URI format wiki page
<https://github.com/google/google-authenticator/wiki/Key-Uri-Format> for more information.
otpauth
This method returns the otpauth key URI generated when you call "qr_code".
generate_secret32
This method will generate a reasonable random "secret32" value, store it in the get/set method, and
return it.
my $secret32 = $auth->generate_secret32;
clear
Given that the "secret" and "secret32" values may persist in this object, which could be a bad idea in
some contexts, this "clear" method lets your clear out all attribute values.
$auth->clear;
qr_code
This method will return a Google Chart API URL that will return a QR code based on the data either in the
object or provided to this method.
my $url_0 = $auth->qr_code;
my $url_1 = $auth->qr_code(
'bv5o3disbutz4tl3', # secret32
'gryphon@cpan.org', # key_id
'Gryphon Shafer', # issuer
);
You can optionally add a final true value, and if you do, the method will return the generated otpauth
key URI rather than the Google Chart API URL.
my $url_2 = $auth->qr_code(
'bv5o3disbutz4tl3', 'gryphon@cpan.org', 'Gryphon Shafer', 1,
);
code
This method returns an authentication code, as if you were using Google Authenticator
<https://en.wikipedia.org/wiki/Google_Authenticator> with the "secret32" value.
my $code_0 = $auth->code;
You can optionally pass override values similar to "qr_code":
my $code_1 = $auth->code(
'utz4tl3bv5o3disb', # secret32
1438643789, # timestamp (defaults to now)
30, # interval (default 30)
);
verify
This method is used for verification of codes entered by a user. Pass in the code (required) and
optionally a range value and any override values.
my $verification_0 = $auth->verify('879364');
The range value is useful because the algorithm checks codes that are time- based. If clocks are not
exactly in sync, it's possible that a "nearly valid" code would be entered and should be accepted as
valid but will be seen as invalid. By passing in an integer as a range value, you can stipulate how
"fuzzy" the time should be. The default range is 0. A value of 1 will mean that a code based on a time 1
iteration plus or minus should verify.
my $verification_1 = $auth->verify(
'879364', # code
1, # range
'utz4tl3bv5o3disb', # secret32
1438643820, # timestamp (defaults to now)
30, # interval (default 30)
);
TYPICAL USE-CASE
Typically, you're probably going to want to either randomly generate a secret or secret32
("generate_secret32") for a user and store it, or use a specific value or hash of some value as the
secret. In either case, once you have a secret and its stored, generate a QR code ("qr_code") for the
user. You can alternatively provide the "secret32" to the user for them to manually enter it. That's it
for setup.
To authenticate, present the user with a way to provide you a code (which will be a series of 6-digits).
Verify that code ("verify") with either no range or some small range like 1.
DEPENDENCIES
Digest::HMAC_SHA1, Math::Random::MT, URI::Escape, Convert::Base32, Class::Accessor, Carp.
SEE ALSO
You can look for additional information about this module at:
• GitHub <https://github.com/gryphonshafer/Auth-GoogleAuth>
• MetaCPAN <https://metacpan.org/pod/Auth::GoogleAuth>
• GitHub Actions <https://github.com/gryphonshafer/Auth-GoogleAuth/actions>
• Codecov <https://codecov.io/gh/gryphonshafer/Auth-GoogleAuth>
• CPANTS <http://cpants.cpanauthors.org/dist/Auth-GoogleAuth>
• CPAN Testers <http://www.cpantesters.org/distro/G/Auth-GoogleAuth.html>
You can look for additional information about things related to this module at:
• TOTP Algorithm <https://en.wikipedia.org/wiki/Time-based_One-time_Password_Algorithm>
• RFC 6238 <http://tools.ietf.org/html/rfc6238>
• Google Authenticator <https://en.wikipedia.org/wiki/Google_Authenticator>
• Google Authenticator GitHub <https://github.com/google/google-authenticator>
AUTHOR
Gryphon Shafer <gryphon@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2015-2021 by Gryphon Shafer.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
perl v5.32.0 2021-01-12 Auth::GoogleAuth(3pm)