Provided by: libauth-googleauth-perl_1.02-1_all bug

NAME

       Auth::GoogleAuth - Google Authenticator TBOT Abstraction

VERSION

       version 1.02

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>

       •   CPAN <http://search.cpan.org/dist/Auth-GoogleAuth>

       •   MetaCPAN <https://metacpan.org/pod/Auth::GoogleAuth>

       •   AnnoCPAN <http://annocpan.org/dist/Auth-GoogleAuth>

       •   Travis CI <https://travis-ci.org/gryphonshafer/Auth-GoogleAuth>

       •   Coveralls <https://coveralls.io/r/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) 2018 by Gryphon Shafer.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.