Gryphon Shafer

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 using the TOTP Algorithm as defined by RFC 6238. 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 for more information.

key_id

This is the label name of the "key ID" of the authentication. See the key URI format wiki page 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 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) 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.