Scroll to navigation

Auth::GoogleAuth(3pm) User Contributed Perl Documentation Auth::GoogleAuth(3pm)

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:

You can look for additional information about things related to this module at:

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)
2021-01-12 perl v5.32.0