TOTP Guide
==========
RFC context
-----------
TOTP is defined in RFC6238. Conceptually, it is HOTP over a moving time-step instead of a manually tracked counter.
The usual flow is:
- client and server share a secret
- both derive the current time-step from the current Unix timestamp
- both generate the OTP from that time-step
- the server verifies the submitted OTP inside an allowed drift window
This package exposes both the simple boolean verification flow and a richer result-based flow for drift and replay handling.
Generating a secret
-------------------
You can generate a new Base32 secret directly from the TOTP class:
.. code-block:: php
<?php
use Infocyph\OTP\TOTP;
$secret = TOTP::generateSecret();
If you want to control the random byte length:
.. code-block:: php
<?php
$secret = TOTP::generateSecret(64);
Creating a TOTP instance
------------------------
.. code-block:: php
<?php
use Infocyph\OTP\TOTP;
$totp = new TOTP($secret, digitCount: 6, period: 30);
Key parameters:
- ``secret`` is a Base32 secret
- ``digitCount`` is typically ``6`` or ``8``
- ``period`` is the time-step in seconds, commonly ``30``
Generating an OTP
-----------------
.. code-block:: php
<?php
$otp = $totp->getOTP();
Generate for a specific timestamp:
.. code-block:: php
<?php
$otp = $totp->getOTP(1716532624);
Basic verification
------------------
Use ``verify()`` when a boolean is enough:
.. code-block:: php
<?php
$totp->verify($otp);
Or for a specific timestamp:
.. code-block:: php
<?php
$totp->verify($otp, timestamp: 1716532624);
Windowed verification
---------------------
Real-world authenticators can drift slightly. RFC6238 deployments commonly allow a small validation window around the current time-step.
This library supports:
- previous windows only
- future windows only
- symmetric windows
Example with both past and future drift:
.. code-block:: php
<?php
use Infocyph\OTP\ValueObjects\VerificationWindow;
$result = $totp->verifyWithWindow(
$otp,
timestamp: time(),
window: new VerificationWindow(past: 1, future: 0),
);
$result->matched;
$result->matchedTimestep;
$result->driftOffset;
$result->isExact();
$result->isDrifted();
Another example using the lightweight bool API:
.. code-block:: php
<?php
$isValid = $totp->verify(
$otp,
timestamp: time(),
pastWindows: 1,
futureWindows: 1,
);
Time helpers
------------
.. code-block:: php
<?php
$totp->getCurrentTimeStep();
$totp->getRemainingSeconds();
$totp->getTimeStepFromTimestamp(1716532624);
These helpers are useful when you want to:
- display countdown UI
- log or inspect drift
- persist the matched time-step as replay state
Replay protection
-----------------
RFC6238 itself defines the OTP derivation algorithm, but replay prevention is an application responsibility.
Typical server-side policy:
- accept a code once for a given user and time-step
- reject reuse of that accepted time-step
Example with replay-aware verification:
.. code-block:: php
<?php
use Infocyph\OTP\Stores\InMemoryReplayStore;
use Infocyph\OTP\ValueObjects\VerificationWindow;
$store = new InMemoryReplayStore();
$result = $totp->verifyWithWindow(
$otp,
window: new VerificationWindow(past: 1, future: 1),
replayStore: $store,
binding: 'user-42',
);
$result->matched;
$result->replayDetected;
Rotation helper
---------------
When rotating a secret, you may want a controlled overlap period:
.. code-block:: php
<?php
$rotation = $totp->rotateSecret($newSecret, gracePeriodInSeconds: 3600);
$rotation['current'];
$rotation['next'];
$rotation['overlapUntil'];
Provisioning
------------
TOTP is commonly provisioned into authenticator apps using ``otpauth://`` URIs.
.. code-block:: php
<?php
$uri = $totp->getProvisioningUri('alice@example.com', 'Example App');
$svg = $totp->getProvisioningUriQR('alice@example.com', 'Example App');
Detailed QR setup example:
.. code-block:: php
<?php
$payload = $totp->getEnrollmentPayload(
'alice@example.com',
'Example App',
withQrSvg: true,
);
$secret = $payload->secret;
$uri = $payload->uri;
$svg = $payload->qrSvg;
// store $secret securely and render $svg during enrollment
See :doc:`provisioning` for the full provisioning flow.
|
Download
