chillerlan / php-googleauth
A generator for counter- and time based authentication codes. PHP 7+
This package is not auto-updated.
Last update: 2019-02-20 18:47:32 UTC
README
A generator for counter based (RFC 4226) and time based (RFC 6238) authentication codes. (a.k.a. Yet Another Google Authenticator Implementation!)
Documentation
Requirements
- PHP 7+
- 64bit
Installation
requires composer
composer.json (note: replace dev-master
with a version boundary)
{ "require": { "php": ">=7.0.3", "chillerlan/php-qrcode": "dev-master" } }
Manual installation
Download the desired version of the package from master or release and extract the contents to your project folder. After that:
- run
composer install
to install the required dependencies and generate/vendor/autoload.php
. - if you use a custom autoloader, point the namespace
chillerlan\Authenticator
to the foldersrc
of the package
Profit!
Usage
Create a secret
The secret is usually being created once during the activation process in a user control panel. So all you need to do there is to display it to the user in a convenient way - as a text string and QR code for example - and save it somewhere with the user data.
$authenticator = new \chillerlan\Authenticator\Authenticator; // create a secret (stored somewhere in a *safe* place on the server. safe... hahaha) $secret = $authenticator->createSecret(); // you can also specify the length of the secret key $secret = $authenticator->createSecret(20); // set an existing secret $authenticator->setSecret($secret);
A secret created with Authenticator::createSecret()
will also be stored internally, so that you don't need to provide the one you just created on follow-up operations for the same secret.
Verify a one time code
Now during the login process - after the user has successfully entered their credentials - you would ask them for a one time code to check it against the secret from your user database.
// verify the code if($authenticator->verify($code)){ // that's it - 2FA has never been easier! :D }
time based (TOTP)
Verify adjacent codes
$p = $authenticator->getPeriod(); // try the first adjacent $authenticator->verify($code, time() - $p); // -> true // try the second adjacent, default is 1 $authenticator->verify($code, time() + 2 * $p); // -> false // allow 2 adjacent codes $authenticator->verify($code, time() + 2 * $p, 2); // -> true
Create a code for a UNIX timestamp
// let's assume your server's timezone is an hour off and beyond your control $timeslice = $authenticator->timeslice(time() - 3600); // current code $code = $authenticator->code($timeslice); // adjacent codes $prev = $authenticator->code($timeslice - 1); $next = $authenticator->code($timeslice + 1);
counter based (HOTP)
// switch mode to HOTP $authenticator->setMode('hotp'); // user sends code #42, equivalent to $code = $authenticator->code(42); // try the first adjacent $authenticator->verify($code, $counterValueFromUserDatabase + 1) // -> true // the internal counter will be increased by 1 on a successful verify $authenticator->getCounter(); // -> 43, save // user sends following code (#43) $authenticator->verify($nextCode, $counterValueFromUserDatabase); // -> true $authenticator->getCounter(); // -> 44, save...
URI creation
In order to display a QR code for a mobile authenticator you'll need an otpauth://
URI, which can be created using the following method.
$label
should be something that identifies the account to which the secret belongs$issuer
is the name of your website or company for example, so that the user is able to identify multiple accounts.
$uri = $authenticator->getUri($label, $issuer); // -> otpauth://totp/my%20label?secret=NKSOQG7UKKID4IXW&issuer=chillerlan.net&digits=6&period=30&algorithm=SHA1
Notes
Keep in mind that several URI settings are not (yet) recognized by all authenticators. Check the Google Authenticator wiki for more info.
// code length, currently 6 through 8 $authenticator->setDigits(8); // valid period between 10 and 60 seconds $authenticator->setPeriod(45); // set the HMAC hash algorithm $authenticator->setAlgorithm('SHA512');