Auth::GoogleAuth - Google Authenticator TBOT Abstraction
version 1.04
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) );
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.
The following are the supported methods of this module:
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:
This can be any string. It'll be used as the internal secret key to create the QR codes and authentication codes.
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.
qr_code
code
This is the label name of the "issuer" of the authentication. See the key URI format wiki page for more information.
This is the label name of the "key ID" of the authentication. See the key URI format wiki page for more information.
This method returns the otpauth key URI generated when you call qr_code.
This method will generate a reasonable random "secret32" value, store it in the get/set method, and return it.
my $secret32 = $auth->generate_secret32;
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.
clear
$auth->clear;
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, );
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) );
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) );
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.
generate_secret32
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.
verify
Digest::HMAC_SHA1, Math::Random::MT, URI::Escape, Convert::Base32, Class::Accessor, Carp.
You can look for additional information about this module at:
GitHub
MetaCPAN
GitHub Actions
Codecov
CPANTS
CPAN Testers
You can look for additional information about things related to this module at:
TOTP Algorithm
RFC 6238
Google Authenticator
Google Authenticator GitHub
Gryphon Shafer <gryphon@cpan.org>
This software is Copyright (c) 2015-2050 by Gryphon Shafer.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
To install Auth::GoogleAuth, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Auth::GoogleAuth
CPAN shell
perl -MCPAN -e shell install Auth::GoogleAuth
For more information on module installation, please visit the detailed CPAN module installation guide.