PHP Luminova: Time-Based One-Time Password Authenticator

The TOTP class simplifies the integration of Time-Based One-Time Passwords (TOTP) in your application. It provides user-friendly methods to specify an authenticator client, ensuring consistency across your implementation.

By default, the Google Authenticator client Luminova\Security\Authenticator\Google is used. To use a different client, simply implement the \Luminova\Interface\AuthenticatorInterface interface to create a custom authenticator.

Usage Examples

Create a TOTP Instance

use Luminova\Security\TOTP;
use Luminova\Security\Authenticator\Google;
use Luminova\Cache\FileCache;
use DateTimeZone;

// Initialize the TOTP authenticator
$auth = TOTP::create(
    new Google(
        'MySiteAuthenticator',
        '[email protected]',
        new DateTimeZone('Africa/Lagos'), // Optional timezone
        new FileCache('authenticator')   // Optional PSR-6 cache instance
    )
);

Setup TOTP for a New User

// Generate a secret and associate it with the user
$secret = $auth->secret(Google::generateSecret());

// Display the QR Code image and secret for the user
echo $auth->image();
echo "\nScan this QR Code\nYour Authenticator Secret: {$secret}";

Verify User Secret and TOTP Code

$user_secret = 'EWQAIIFPZPDLFS2K'; // User's secret
$code = '12345'; // TOTP code provided by the user

// Assign the user's secret to the authenticator
$auth->secret($user_secret);

// Validate the provided code
if ($auth->validate($code)) {
    echo 'Token is valid';
} else {
    echo 'Token is invalid';
}

Class Definition

• Class namespace: \Luminova\Security\TOTP
• This class is marked as final and can't be subclassed\

Methods

create

Factory method to create a TOTP instance.

public static create(?Luminova\Interface\AuthenticatorInterface $client = null): self

Parameters:

Return Value:

self - Return a new TOTP instance.

secret

Get or set the secret key used for TOTP (Time-Based One-Time Password).

This method allows you to either retrieve the current secret key or set a new one.If a secret is provided, it will be set as the new secret key.If no secret is provided, the current secret key will be returned.

public secret(?string $secret = null): ?string

Parameters:

Return Value:

string|null - Returns the newly set secret key if a new secret was provided, or the current secret key if no new secret was given. Returns null if no secret is set and none was provided.

url

Generate the QR code URL for the authenticator.

public url(): string

Return Value:

string - Return the URL for the QR code.

Throws:

• \Luminova\Exceptions\EncryptionException - If called without a valid authentication secret.

image

Generate the QR code image for the TOTP setup.

This method generates a QR code image for Time-Based One-Time Password (TOTP) setup.It can create the image in different formats and sizes, either using an installed QR code library or a fallback method using an external service.

public image(int $size = 200, string $format = 'svg'): string

Parameters:

Return Value:

string - Return the QR code image as HTML element, depending on the chosen format and generation method.

Throws:

• \Luminova\Exceptions\EncryptionException - If the 'base64' format is requested but the QR code library is not installed, or if called without a valid authentication secret.

label

Retrieve the label for the TOTP account.

public label(): string

Return Value:

string - Return the label for the account.

account

Retrieve the account identifier used for the TOTP.

public account(): string

Return Value:

string - Return the account identifier.

validate

Validate a TOTP code.

public validate(string $code, int $discrepancy = 1, int $timeStep = 30): bool

Parameters:

Return Value:

bool - Return true if the code is valid; otherwise, false.

Throws:

• \Luminova\Exceptions\EncryptionException - If called without a valid authentication secret or an invalid base32 character is found in secret.