first commit
This commit is contained in:
81
docs/security-stack/security/otp/src/ocra/ocra.md
Normal file
81
docs/security-stack/security/otp/src/ocra/ocra.md
Normal file
@@ -0,0 +1,81 @@
|
||||
# `ocra/ocra`
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs --> - ocra.schema — Zod boundary schema for `OcraParams`……
|
||||
- [ocra.schema](./ocra.schema.md) — Zod boundary schema for `OcraParams` — the runtime parameter bag passed alongside a suite string and a key. Optional fi…
|
||||
- [suite](./suite.md) — Parse an OCRA suite string into a typed `OcraSuite` AST per RFC 6287 §6.1. Exposed separately so callers can validate s…
|
||||
- [verify-ocra](./verify-ocra.md) — Constant-time verify of an OCRA response. Recomputes the response under the supplied suite, key, and params, then compa…
|
||||
- ocra.schema — Zod boundary schema for `OcraParams`……
|
||||
|
||||
- [ocra.schema](./ocra.schema.md) — Zod boundary schema for `OcraParams` — the runtime parameter bag passed alongside a suite string and a key. Optional fi…
|
||||
- [suite](./suite.md) — Parse an OCRA suite string into a typed `OcraSuite` AST per RFC 6287 §6.1. Exposed separately so callers can validate s…
|
||||
- [verify-ocra](./verify-ocra.md) — Constant-time verify of an OCRA response. Recomputes the response under the supplied suite, key, and params, then compa…
|
||||
|
||||
- ocra.schema — Zod boundary schema for `OcraParams`……
|
||||
|
||||
- [ocra.schema](./ocra.schema.md) — Zod boundary schema for `OcraParams` — the runtime parameter bag passed alongside a suite string and a key. Optional fi…
|
||||
- [suite](./suite.md) — Parse an OCRA suite string into a typed `OcraSuite` AST per RFC 6287 §6.1. Exposed separately so callers can validate s…
|
||||
- [verify-ocra](./verify-ocra.md) — Constant-time verify of an OCRA response. Recomputes the response under the supplied suite, key, and params, then compa…
|
||||
|
||||
- ocra.schema — Zod boundary schema for `OcraParams`…
|
||||
|
||||
- [ocra.schema](./ocra.schema.md) — Zod boundary schema for `OcraParams` — the runtime parameter bag passed alongside a suite string and a key. Optional fi…
|
||||
- [suite](./suite.md) — Parse an OCRA suite string into a typed `OcraSuite` AST per RFC 6287 §6.1. Exposed separately so callers can validate s…
|
||||
- [verify-ocra](./verify-ocra.md) — Constant-time verify of an OCRA response. Recomputes the response under the supplied suite, key, and params, then compa…
|
||||
- [ocra.schema](./ocra.schema.md) — Zod boundary schema for `OcraParams` — the runtime parameter bag passed alongside a suite string and a key. Optional fi…
|
||||
- [suite](./suite.md) — Parse an OCRA suite string into a typed `OcraSuite` AST per RFC 6287 §6.1. Exposed separately so callers can validate s…
|
||||
- [verify-ocra](./verify-ocra.md) — Constant-time verify of an OCRA response. Recomputes the response under the supplied suite, key, and params, then compa…
|
||||
|
||||
## Purpose
|
||||
|
||||
RFC 6287 OCRA — OATH Challenge-Response Algorithm. Supports the full
|
||||
`OCRA-1:HOTP-{H}-{N}:[C-]Q{A|N|H}NN[-PSHA{1,256,512}][-Snnn][-T{n}{S|M|H}]`
|
||||
suite-string grammar. Validated against RFC 6287 Appendix C.1 reference
|
||||
vectors so call-site implementations have a known-good baseline.
|
||||
|
||||
## Features
|
||||
|
||||
- All hash algorithms: SHA-1 / SHA-256 / SHA-512.
|
||||
- Digits 4 / 6 / 7 / 8 (RFC 6287 §6.2 widens HOTP's 6/7/8 to also include 4).
|
||||
- Optional counter (`C` directive), password hash (`PSHA{1,256,512}`),
|
||||
session info (`Snnn`), and timestamp (`T{n}{S|M|H}`) blocks.
|
||||
- Three challenge formats: `QN` (decimal), `QA` (printable ASCII), `QH` (hex).
|
||||
- Constant-time verify via `verifyOcra`.
|
||||
|
||||
## Usage: Basic Example
|
||||
|
||||
```ts
|
||||
import { ocra } from "@suaveplan/otp/ocra";
|
||||
|
||||
const r = ocra("OCRA-1:HOTP-SHA1-6:QN08", key, { challenge: "12345678" });
|
||||
```
|
||||
|
||||
## Usage: Advanced Example
|
||||
|
||||
```ts
|
||||
import { ocra } from "@suaveplan/otp/ocra";
|
||||
|
||||
// Counter + password-hashed plus timestamp-bound suite.
|
||||
const r = ocra("OCRA-1:HOTP-SHA256-8:C-QN08-PSHA256-T1M", key, {
|
||||
counter: 17n,
|
||||
challenge: "12345678",
|
||||
passwordHash: sha256(passwordBytes),
|
||||
timestampMs: Date.now(),
|
||||
});
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
- `ocra(suite, key, params): string` — primary computation API.
|
||||
- `buildOcraMessage(parsed, params): Uint8Array` — exposed for benchmarks
|
||||
and KAT harnesses that want to inspect the pre-HMAC byte stream.
|
||||
- `OcraDigits` — alias for the digit literal-union shared with HOTP.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
The HMAC input layout follows RFC 6287 §5.1 exactly: suite ASCII, NUL
|
||||
separator, then the directive blocks in fixed order (counter, challenge,
|
||||
password hash, session info, timestamp). Each block is omitted if the suite
|
||||
does not declare it; callers supplying an unexpected block are silently
|
||||
ignored — the suite is the source of truth.
|
||||
Reference in New Issue
Block a user