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 folder src 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');