README

A php library for Multi-factor authentication (MFA). MFA also known as 2FA or two factor authentication.

What is TOTP

TOTP, which stands for Time-based One-Time Password, is a computer algorithm that generates a temporary, unique password for authentication. It's widely used in two-factor authentication (2FA) systems to add an extra layer of security beyond a traditional password. The TOTP algorithm follows an open standard documented in RFC 6238. The inputs include a shared secret key and the system time.

What is HOTP

HOTP stands for HMAC-based One-Time Password and is the original standard that TOTP was based on. Both methods use a secret key as one of the inputs, but while TOTP uses the system time for the other input, HOTP uses a counter, which increments with each new validation. With HOTP, both parties increment the counter and use that to compute the one-time password. The HOTP standard is documented in RFC 4226.

Installation

This library can be installed using Composer. To install, please use following command

composer require nishadil/mfa

How to use

Generate Secret Code

To create new secret code for user, call public static mathod Mfa::createSecretCode();

<?php

use Nishadil\Mfa\Mfa;

echo Mfa::createSecretCode();

?>

output:

F6ZHAZMKSLY7ISFO

Generate long Secret Code

By default, we defined secret code length to 16 char long. You can change it if you need to generate long code. Accepted values should be in integer and within range of 16 to 128.

eg: now we want to generate a 32 char long secret code. Mfa::setSecretCodeLength(32); then Mfa::createSecretCode();

<?php

use Nishadil\Mfa\Mfa;

Mfa::setSecretCodeLength(32);
echo Mfa::createSecretCode();

?>

output:

3TYBUTVEXBOBXYTJ6L7NZ4HC7QJWAKMY

Get TOTP from secret code

TOTP stands for Time-based One-Time Passwords and is a common form of Multi-factor authentication (MFA). To generate your TOTP based on your secret key and time you can call public static mathod Mfa::getTOTP( string $secretCode );

<?php

use Nishadil\Mfa\Mfa;

$secretCode = "3TYBUTVEXBOBXYTJ6L7NZ4HC7QJWAKMY";
echo Mfa::getTOTP($secretCode);

?>

output:

557480

Validate TOTP

To validate your TOTP based on your secret key and time you can call public static mathod Mfa::validateTOTP(string $secretCode, string $userProvided_otp, int $tolerance = 1); The $tolerance value is the number of time steps allowed before/after the current window (default 1). Use 0 for strict expiry.

<?php

use Nishadil\Mfa\Mfa;

$secretCode = "3TYBUTVEXBOBXYTJ6L7NZ4HC7QJWAKMY";
$userProvided_otp = "440791";
$tolerance = 0;

echo Mfa::validateTOTP($secretCode, $userProvided_otp, $tolerance);

?>

output:

true

To change the TOTP time step (default 30 seconds), call Mfa::setTimeStep(int $seconds); before generating or validating codes:

<?php

use Nishadil\Mfa\Mfa;

Mfa::setTimeStep(45);

?>

Get HOTP from secret code

HOTP stands for HMAC-based One-Time Password and is the original standard that TOTP was based on. To generate your HOTP based on your secret key and counter value to call public static mathod Mfa::getHOTP( string $secretCode, int $counter );

<?php

use Nishadil\Mfa\Mfa;

$secretCode = "3TYBUTVEXBOBXYTJ6L7NZ4HC7QJWAKMY";
$counter = 100;
echo Mfa::getHOTP($secretCode,$counter);

?>

output:

440791

Validate HOTP

To validate your HOTP based on your secret key and counter value call public static mathod Mfa::validateHOTP(string $secretCode, string $userProvided_otp, int $counter);

<?php

use Nishadil\Mfa\Mfa;

$secretCode = "3TYBUTVEXBOBXYTJ6L7NZ4HC7QJWAKMY";
$counter = 100;
$userProvided_otp = "440791";

echo Mfa::validateHOTP($secretCode, $userProvided_otp, $counter);

?>

output:

true

Create otpauth URI for Authenticator Apps

Many authenticator apps, such as Google Authenticator, Authy, and others, support scanning a QR code to quickly set up a new account. The QR code typically contains a special URI, called an otpauth URI, which holds all the necessary information for the app to generate one-time passwords.

The otpauth URI follows a specific format:

otpauth://[type]/[label]?[parameters]

Generate otpauth URI for TOTP Based method

<?php

use Nishadil\Mfa\Mfa;

$secretCode = "3TYBUTVEXBOBXYTJ6L7NZ4HC7QJWAKMY";

echo Mfa::generateOtpAuthUri($secretCode, "user@example.com", "NishadilApp");

?>

output:

otpauth://totp/NishadilApp:user%40example.com?secret=3TYBUTVEXBOBXYTJ6L7NZ4HC7QJWAKMY&issuer=NishadilApp&digits=6&algorithm=SHA1&period=30

Generate otpauth URI for HOTP Based method

<?php

use Nishadil\Mfa\Mfa;

$secretCode = "3TYBUTVEXBOBXYTJ6L7NZ4HC7QJWAKMY";
$counter = 100;

echo Mfa::generateOtpAuthUri($secretCode, "user@example.com", "NishadilApp", "hotp", $counter);

?>

output:

otpauth://hotp/NishadilApp:user%40example.com?secret=3TYBUTVEXBOBXYTJ6L7NZ4HC7QJWAKMY&issuer=NishadilApp&digits=6&algorithm=SHA1&counter=100

Generate Backup Codes

To generate backup codes, call public static mathod Mfa::generateBackupCodes(int $count = 10, int $length = 8);

<?php

use Nishadil\Mfa\Mfa;

$backupCodes = Mfa::generateBackupCodes();

print_r($backupCodes);

?>

output:

array[
    'QS5HT8FK-2D7LTZGM',
    'S7DS93ON-U8RMR0TY',
    '965F5WEP-KP16XBME',
    'G4E6IQ05-SUFEWHN0',
    'SYS907DN-0JN060EE',
    'IYGGRAXO-739H8TWR',
    'PA79RE4J-4IZ83DB2',
    'YH9YDR3Z-N51CGR4E',
    'V36CMIRZ-1WNEZVN6',
    'O3HU4FBC-V1OPWXZ8'
]

License

This library is licensed for use under the MIT License (MIT)