OCRA Guide
==========

RFC context
-----------

OCRA is defined in RFC6287. It extends the HOTP family into richer challenge-response flows.

Compared with HOTP and TOTP, OCRA can include:

- a challenge
- an optional counter
- an optional PIN-derived input
- an optional session value
- an optional time input

This makes OCRA suitable for transaction signing and higher-assurance challenge-response scenarios, not just login OTPs.

Understanding the suite string
------------------------------

An OCRA flow is defined by its suite string.

Example:

.. code-block:: text

   OCRA-1:HOTP-SHA256-8:C-QN08-PSHA1

This means:

- ``OCRA-1``: protocol version
- ``HOTP-SHA256``: HMAC family and hash algorithm
- ``8``: output digits
- ``C``: counter is required
- ``QN08``: numeric challenge of length 8
- ``PSHA1``: PIN input is hashed with SHA1

Common suite patterns
---------------------

You will usually encounter OCRA suites in a few recurring categories:

- challenge only
- challenge plus counter
- challenge plus PIN
- challenge plus session
- challenge plus time
- combinations of the above

Examples:

.. code-block:: text

   OCRA-1:HOTP-SHA1-6:QN08
   OCRA-1:HOTP-SHA512-8:C-QN08
   OCRA-1:HOTP-SHA256-8:QN08-PSHA1
   OCRA-1:HOTP-SHA256-8:QN08-S064
   OCRA-1:HOTP-SHA512-8:QN08-T1M
   OCRA-1:HOTP-SHA256-8:C-QN08-PSHA1

Generating a shared secret
--------------------------

OCRA uses a shared secret between client and server, just like the other OTP families.

You can generate one with:

.. code-block:: php

   <?php
   use Infocyph\OTP\OCRA;

   $sharedKey = OCRA::generateSecret();

If your integration needs a specific keying strategy, you can also supply an application-managed shared key when constructing the instance.

Creating an OCRA instance
-------------------------

.. code-block:: php

   <?php
   use Infocyph\OTP\OCRA;

   $ocra = new OCRA('OCRA-1:HOTP-SHA256-8:C-QN08-PSHA1', $sharedKey);
   $ocra->setPin('1234');

   $code = $ocra->generate('12345678', 0);
   $ocra->verify($code, '12345678', 0);

Detailed generation examples
----------------------------

Numeric challenge only
~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: php

   <?php
   $ocra = new OCRA('OCRA-1:HOTP-SHA1-6:QN08', $sharedKey);
   $code = $ocra->generate('12345678');

Counter plus challenge plus PIN:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: php

   <?php
   $ocra = new OCRA('OCRA-1:HOTP-SHA256-8:C-QN08-PSHA1', $sharedKey);
   $ocra->setPin('1234');

   $challenge = '12345678';
   $counter = 5;

   $code = $ocra->generate($challenge, $counter);

Challenge-only flow:
~~~~~~~~~~~~~~~~~~~~

.. code-block:: php

   <?php
   $ocra = new OCRA('OCRA-1:HOTP-SHA1-6:QN08', $sharedKey);
   $code = $ocra->generate('00000000');

Counter without PIN:
~~~~~~~~~~~~~~~~~~~~

.. code-block:: php

   <?php
   $ocra = new OCRA('OCRA-1:HOTP-SHA512-8:C-QN08', $sharedKey);
   $code = $ocra->generate('12345678', 10);

PIN without counter:
~~~~~~~~~~~~~~~~~~~~

.. code-block:: php

   <?php
   $ocra = new OCRA('OCRA-1:HOTP-SHA256-8:QN08-PSHA1', $sharedKey);
   $ocra->setPin('1234');
   $code = $ocra->generate('12345678');

Session-based flow:
~~~~~~~~~~~~~~~~~~~

.. code-block:: php

   <?php
   $ocra = new OCRA('OCRA-1:HOTP-SHA256-8:QN08-S064', $sharedKey);
   $ocra->setSession('A1B2C3D4');
   $code = $ocra->generate('12345678');

Time-based flow:
~~~~~~~~~~~~~~~~

.. code-block:: php

   <?php
   $ocra = new OCRA('OCRA-1:HOTP-SHA512-8:QN08-T1M', $sharedKey);
   $ocra->setTime(new DateTimeImmutable('2026-04-19 12:00:00 UTC'));
   $code = $ocra->generate('12345678');

Alphanumeric challenge flow:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: php

   <?php
   $ocra = new OCRA('OCRA-1:HOTP-SHA256-8:QA08', $sharedKey);
   $code = $ocra->generate('CLI22220SRV11110');

Hexadecimal challenge flow:
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: php

   <?php
   $ocra = new OCRA('OCRA-1:HOTP-SHA256-8:QH08', $sharedKey);
   $code = $ocra->generate('A1B2C3D4');

Verification examples
---------------------

Basic verification:

.. code-block:: php

   <?php
   $isValid = $ocra->verify($code, '12345678', 0);

Challenge-only verification:

.. code-block:: php

   <?php
   $challengeOnly = new OCRA('OCRA-1:HOTP-SHA1-6:QN08', $sharedKey);
   $otp = $challengeOnly->generate('00000000');
   $isValid = $challengeOnly->verify($otp, '00000000');

Rich verification result:

.. code-block:: php

   <?php
   $result = $ocra->verifyWithResult($code, '12345678', 0);

   $result->matched;
   $result->matchedCounter;
   $result->replayDetected;

Verification with replay tracking:

.. code-block:: php

   <?php
   use Infocyph\OTP\Stores\InMemoryReplayStore;

   $store = new InMemoryReplayStore();
   $result = $ocra->verifyWithResult(
       $code,
       '12345678',
       0,
       $store,
       'user-42',
   );

Optional suite inputs
---------------------

Depending on the suite, you may need:

- ``setPin()``
- ``setSession()``
- ``setTime()``

Example with a session value:

.. code-block:: php

   <?php
   $ocra = new OCRA('OCRA-1:HOTP-SHA256-8:QN08-S064', $sharedKey);
   $ocra->setSession('A1B2C3D4');
   $code = $ocra->generate('12345678');

Example with both counter and PIN:

.. code-block:: php

   <?php
   $ocra = new OCRA('OCRA-1:HOTP-SHA256-8:C-QN08-PSHA1', $sharedKey);
   $ocra->setPin('1234');
   $code = $ocra->generate('12345678', 7);

Notes on optional inputs:

- if the suite includes ``C``, you should provide a counter
- if the suite includes ``PSHA1`` / ``PSHA256`` / ``PSHA512``, you should call ``setPin()``
- if the suite includes ``Snnn``, you should call ``setSession()``
- if the suite includes ``T...``, you can optionally call ``setTime()`` to verify or generate for a specific moment

Parsed suite details
--------------------

.. code-block:: php

   <?php
   $suite = $ocra->getSuite();

   $suite->algorithm;
   $suite->digits;
   $suite->counterEnabled;
   $suite->challengeFormat;
   $suite->challengeLength;
   $suite->optionals;

Challenge formats
-----------------

The library supports the major RFC challenge styles:

- ``QNxx``: numeric challenge
- ``QAxx``: alphanumeric challenge
- ``QHxx``: hexadecimal challenge

Examples:

.. code-block:: php

   <?php
   (new OCRA('OCRA-1:HOTP-SHA1-6:QN08', $sharedKey))->generate('12345678');
   (new OCRA('OCRA-1:HOTP-SHA256-8:QA08', $sharedKey))->generate('CLI22220SRV11110');
   (new OCRA('OCRA-1:HOTP-SHA256-8:QH08', $sharedKey))->generate('A1B2C3D4');

In practice:

- ``QNxx`` is useful for numeric server-issued challenges
- ``QAxx`` is useful for mixed transaction strings or structured references
- ``QHxx`` is useful when challenge material is already represented in hexadecimal form

Replay protection
-----------------

RFC6287 defines the derivation rules, but replay prevention is still a server-side policy concern.

For many OCRA use cases, you should reject:

- reused challenge values
- reused counter values where counters are present
- previously accepted challenge and counter combinations

Example:

.. code-block:: php

   <?php
   use Infocyph\OTP\Stores\InMemoryReplayStore;

   $result = $ocra->verifyWithResult(
       $code,
       challenge: '12345678',
       counter: 0,
       replayStore: new InMemoryReplayStore(),
       binding: 'user-42',
   );

When to choose OCRA
-------------------

Choose OCRA when you need more than a simple login OTP, for example:

- transaction confirmation
- challenge-response MFA
- flows combining PIN, counter, and challenge data

If you only need rotating time-based login codes, TOTP is usually simpler.

Provisioning and QR examples
----------------------------

If your OCRA client workflow supports provisioning via ``otpauth://``, you can generate both the URI and an SVG QR:

.. code-block:: php

   <?php
   $uri = $ocra->getProvisioningUri('alice@example.com', 'Example App');
   $svg = $ocra->getProvisioningUriQR('alice@example.com', 'Example App');

See :doc:`provisioning` for the general provisioning flow.