README

An authenticator (chillerlan/php-authenticator) and a QR Code generator (chillerlan/php-qrcode) bundled together for MFA in frameworks and applications.

Requirements

• PHP 8.4+
  • ext-mbstring
  • optional:
    • ext-gd for QRGdImage based output
    • ext-imagick with ImageMagick installed
    • ext-fileinfo required by QRImagick output
    • optional libraries, see the php-qrcode requirements

Documentation

You can find the documentation of the bundled libraries in their respective repositories:

• chillerlan/php-authenticator
• chillerlan/php-qrcode
  • User manual: https://php-qrcode.readthedocs.io/en/v6.0.x/
  • API documentation: https://chillerlan.github.io/php-qrcode/
• chillerlan/php-settings-container

User Guide

Invocation

Fetch the settings from e.g. a framework config and invoke the TwoFactorQRCodeOptions instance with it. Please note that this object combines the settings for AuthenticatorOptions and QROptions. Alternatively, you can just pass an iterable of options to the TwoFactorQRCode constructor.

use chillerlan\TwoFactorQRCode\TwoFactorQRCode;

$options = [
	'secret_length' => 128,
	'adjacent'      => 2,
];

$twoFactorQRCode = new TwoFactorQRCode($options);

User registration

• Create a secret, present it to the user as text.
• Create a QR Code and present it to the user.
• Generate a backup code and present it as well, save the counter value.
• Let the user create a fresh OTP with the new credentials.
• Save the data on successful verification and let the user triple check if they saved their backup code.

$newSecret = $twoFactorQRCode->createSecret();
$qrcode    = $twoFactorQRCode->getQRCode('label', 'issuer');
$backup    = $twoFactorQRCode->createBackupCode($counterValue);

if($twoFactorQRCode->verifyOTP($newOTP)){
	echo 'yay! do not forget to save your backup code!';
}

Normal usage: log-ins, reverification etc.

• Set the secret from the user's data.
• Present the user with a form field for the OTP and verify it.
• Verify the log-in and redirect to wherever the user was headed.

$twoFactorQRCode->setSecret($userSecret);

if($twoFactorQRCode->verifyOTP($OTP)){
	// do stuff...

	// redirect
	header('Location: ...');
}

Using a backup code

The user has lost access to their authenticator, send them to a form separate from the usual OTP input:

• Verify the given backup OTP against the stored counter value.
• After verification, increase the counter, create a new backup code and save the new counter value.
• Present the new backup code to the user and make them triple check that they have carefully saved it.

$twoFactorQRCode->setSecret($userSecret);

if($twoFactorQRCode->verifyBackupCode($backupOTP, $counterValue)){
	$counterValue++;

	$newBackup = $twoFactorQRCode->createBackupCode($counterValue);

	// redirect
}

Redirect the user to wherever they can manage their 2FA settings and retrieve their secret once again:

$twoFactorQRCode->setSecret($userSecret);

$currentBackup = $twoFactorQRCode->createBackupCode($currentCounterValue);
$qrcode        = $twoFactorQRCode->getQRCode('label', 'issuer');

Validating an e-mail address

The previous flow can also be used for other tasks, such as e-mail verification:

• Create a temporary secret and random counter value.
• Create a verification code from the above data.
• Store the temporary secret and counter together with the email address and the current timestamp.
• Send an e-mail with the code to the given e-mail address.

$tempSecret       = $twoFactorQRCode->createSecret();
$tempCounter      = random_int(1, 999999);
$verificationCode = $twoFactorQRCode->createBackupCode($counterValue);

Now present the user with a form where they can enter the received code:

• Fetch the temporary counter and secret from the storage.
• Verify the code.
• Delete the temporary data after successful verification (or after a defined duration).

$twoFactorQRCode->setSecret($tempSecret);

if($twoFactorQRCode->verifyBackupCode($verificationCode, $tempCounter)){
	// success!
}

A note on the secret length

The secret length as per the specifications (RFCs 4226 and 6238) is the length of the binary string that is given to the HMAC hash function - there is no encoding involved at all. Google's "Key URI format" specification uses base32 encoding in order to make the binary secret string portable (URI safe). The base32 encoding naturally results in longer strings than the original, about 60%, so a secret of 20 bytes length results in a 32 byte long base32 encoded string.

However, some of the top used libraries on packagist use some kind of pseudo base32 encoding, with a shorter secret string than requested as a result (secret length = base32 encoded length), which can compromise the security of the algorithm.

This library refers to the secret length always as the length of the raw binary string.

API

TwoFactorQRCode

The class is not final and you're free to extend it to add/change functionality to your liking.

Anti clanker policy

No fascist plagiarism machines were - or will ever be - used in creating of this and any of the bundled libraries. Clanker created pull requests will not be accepted. However, I have no control over 3rd-party libraries, but will avoid clankers wherever I can.

Disclaimer

Use at your own risk!