PHP Luminova: Time-Based One-Time Password: Google Authenticator Client

The Luminova Authenticator client interface simplify generating and validating Time-Based One-Time Passwords (TOTP). By implementing the Luminova\Interface\AuthenticatorInterface, ensuring compatibility with the Luminova\Security\TOTP class. This design allows flexibility in implementing custom TOTP solutions while maintaining compliance with the Luminova TOTP class. For apps using alternatives to Google Authenticator, implementing the AuthenticatorInterface ensures compatibility with Luminova's MFA system.

Google Authenticator Client

The Google Authenticator client allow the generation of secure authentication secrets, QR code creation, and TOTP validation. It offers flexibility through customizable account details, issuer names, time zones, and caching mechanisms. By adhering to PSR standards, it integrates with various cache implementations, ensuring one-time code usage for enhanced security.

Key features include:

• Generating Base32-encoded secrets for authentication.
• Creating QR codes for easy configuration with TOTP apps.
• Verifying user-provided codes against the stored secret.
• Flexible support for time zones and caching to prevent code reuse.
• Compliance with PSR caching interfaces and the Luminova base cache.

Usage Examples

Initializing the Authenticator

You can create a Google authenticator instance by providing account details, issuer name, and optional time zone or caching instance.

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

$authenticator = new Google(
    '[email protected]',       // Account name (email or username)
    'MyAppName',              // Issuer (your application name)
    new DateTimeZone('UTC'),  // Optional timezone
    new FileCache('totp')     // Optional PSR-compliant cache instance
);

Generating a Secret

Generate a secure Base32-encoded secret key for a new user. The secret is stored and can be used to generate or validate TOTP codes.

$secret = Google::generateSecret(24);
echo "User Secret: {$secret}";

Note: Generate a Base32 secret key of a specific length (must be divisible by 8):

Creating a QR Code

Generate a QR code URL for easy configuration in Google Authenticator or similar apps. The QR code encodes the secret and account details.

$secret = Google::generateSecret();
$authenticator->setSecret($secret); // Generate new secret for user
$qrCodeUrl = $authenticator->getQRCodeUrl();

echo "<img src='{$qrCodeUrl}' alt='Scan this QR Code to configure your authenticator'>";

Validating a Code

Verify a TOTP code provided by the user. Specify optional parameters like time-step duration and allowed discrepancies for added flexibility.

$userProvidedCode = '123456';
$authenticator->setSecret('USER_OLD_SECRET123'); // Set user own secret
$isValid = $authenticator->verify($userProvidedCode);

if ($isValid) {
    echo "Authentication successful!";
} else {
    echo "Invalid code. Please try again.";
}

Updating Secret, Timezone, or Cache

The authenticator instance can be updated dynamically to set a new secret, time zone, or caching instance:

$authenticator->setSecret('NEWSECRET123');
$authenticator->setTimezone(new DateTimeZone('America/New_York'));
$authenticator->setCache(new FileCache('totp-storage'));

Class Definition

• Class namespace: \Luminova\Security\Authenticator\Google
• This class implements:\Luminova\Interface\AuthenticatorInterface

Methods

constructor

Initialize a Google Authenticator instance with the necessary parameters.

public __construct(
    string $accountName, 
    string $issuer, 
    DateTimeZone|string|null $timezone = null, 
    Psr\Cache\CacheItemPoolInterface|Psr\SimpleCache\CacheInterface|Luminova\Base\BaseCache|null $cache = null
): mixed

Parameters:

Throws:

• \Luminova\Exceptions\EncryptionException - If the issuer or account name contains invalid characters (colon :).

getLabel

Get the label used in the TOTP configuration, optionally URL-encoded.

public getLabel(bool $encode = false): string

Parameters:

Return Value:

string - Return the label in the format 'Issuer:AccountName'.

getAccount

Get the account name associated with this instance.

public getAccount(): string

Return Value:

string - Return the account name.

getSecret

Get the shared secret key.

public getSecret(): string

Return Value:

string - Return the shared secret key.

getQRCodeUrl

Generate a QR code URL for configuring Google Authenticator.

public getQRCodeUrl(): string

Return Value:

string - Return the URL for the QR code.

Throws:

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

setSecret

Initialize a Google Authenticator instance with the necessary parameters.

public setSecret(string $secret): self

Parameters:

Return Value:

\Luminova\Interface\AuthenticatorInterface - Return the current instance of authenticator client.

setTimezone

Set the timezone for time-based calculations.

public setTimezone(\DateTimeZone|string|null $timezone): self

Parameters:

Return Value:

\Luminova\Interface\AuthenticatorInterface - Return the current instance of authenticator client.

setCache

Set the cache instance for code reuse prevention.

public setCache(Psr\Cache\CacheItemPoolInterface|Psr\SimpleCache\CacheInterface|Luminova\Base\BaseCache $cache): self

Parameters:

Return Value:

\Luminova\Interface\AuthenticatorInterface - Return the current instance of authenticator client.

generateSecret

Generate a new Base32-encoded secret key.

public static generateSecret(int $length = 16): string

Parameters:

Return Value:

string - Return the generated Base32 secret key.

Throws:

• \Luminova\Exceptions\InvalidArgumentException - If the length is not positive or not divisible by 8.

verify

Verify a given TOTP code against the shared secret.

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

Parameters:

Return Value:

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

Throws:

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