OCRA (RFC 6287) JavaScript Implementation

An implementation of the OATH Challenge-Response Algorithm (OCRA) as specified in RFC 6287.

RFC 6287 Compliance

This implementation fully complies with RFC 6287 and passes all official test vectors:

Features

RFC Conformance Test

Running RFC conformance Test Vectors her

Quick Start

Browser Usage

<!-- Include a crypto library -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.2.0/crypto-js.min.js"></script>

<!-- Include OCRA -->
<script src="ocra.js"></script>

<script>
async function generateCode() {
  const code = await OCRA.generate(
    "OCRA-1:HOTP-SHA1-6:QN08",  // Suite
    "12345678901234567890",      // Secret key
    "12345678"                   // Challenge
  );
  console.log("OCRA Code:", code);
}
</script>

API Reference

OCRA.generate(suite, key, challenge, [counter], [password], [sessionInfo], [timestamp])

Generates an OCRA code according to the specified suite.

Parameters

Parameter Type Required Description
suite string ✅ OCRA suite specification (e.g., “OCRA-1:HOTP-SHA1-6:QN08”)
key Hex Encoded string ✅ Secret key (HEX encoded)
challenge Hex Encoded string ✅ Challenge/question string (HEX encoded, type to encode depend on suite QNxx/QAxx/QHxx, QN = BigInt hexx String encoded, QA = String Hex Encoded, QH = Raw Hex String, max 128 bytes)
counter Big Int Hex Encoded String ❌ Counter value (for suites with ‘C’) (BigInt HEX encoded, max 16 bytes)
password Hex Encoded string ❌ Password (for suites with ‘P’) (HEX encoded, max 20 bytes)
sessionInfo Hex Encoded string ❌ Session information (for suites with ‘S’) (HEX encoded, max bytes depend on the Ocra Suite : 64, 128, 512)
timestamp Big Int Hex Encoded ❌ Timestamp (for suites with ‘T’) (BigInt Hex Encoded, the signification of the depend on the Time Step Granularity of the Ocra Suite)

Returns

Ocra Suite Format Structure

An OCRASuite value follows this general format:

<Algorithm>:<CryptoFunction>:<DataInput>

The OCRASuite is composed of three main components separated by colons (:):

  1. Algorithm - Specifies the OCRA version
  2. CryptoFunction - Defines the cryptographic function used
  3. DataInput - Describes the input parameters for computation

Component Specifications

1. Algorithm Component

Format: OCRA-v

2. CryptoFunction Component

Format: HOTP-H-t

Supported Values:

Function Name HMAC Function Truncation Size
HOTP-SHA1-t HMAC-SHA1 0, 4-10
HOTP-SHA256-t HMAC-SHA256 0, 4-10
HOTP-SHA512-t HMAC-SHA512 0, 4-10

Common Examples:

3. DataInput Component

Format: [C][|QFxx][|PH][|Snnn][|TG]

The DataInput component specifies which input parameters are used in the computation. Components are separated by hyphens (-) and include:

Counter (C) - Optional

Challenge Question (Q) - Mandatory for most modes

Format Specifiers:

Format (F) Type Length Range
A Alphanumeric 04-64
N Numeric 04-64
H Hexadecimal 04-64

Default: QN08 (Numeric, up to 8 digits)

Examples:

PIN/Password (P) - Optional

Supported Hash Functions:

Session Information (S) - Optional

Common Lengths:

Timestamp (T) - Optional

Time-Step Granularity:

Granularity (G) Description Examples
[1-59]S Seconds 20S
[1-59]M Minutes 5M
[0-48]H Hours 24H

Default: T1M (1-minute time steps)

Usage Patterns

Challenge-Response Computation

Format: [C]|QFxx|[PH|Snnn|TG]

Examples:

Plain Signature Computation

Format: [C]|QFxx|[PH|TG]

Examples:

OCRA Suite Examples

Basic Challenge-Response

OCRA-1:HOTP-SHA1-6:QN08

Advanced Authentication

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

Timestamped Challenge

OCRA-1:HOTP-SHA256-6:QA10-T1M

Session-Based Signature

OCRA-1:HOTP-SHA1-4:QH8-S512

Notes

  1. Key Agreement: Client and server must agree on OCRASuite values during provisioning or negotiation
  2. Mutual Authentication: Requires two OCRASuite values (one for server, one for client computation)
  3. Default Values: When optional parameters are omitted, defaults apply (QN08, PSHA1, S064, T1M)
  4. Padding: Challenge/questions less than 128 bytes are padded with zeros to the right
  5. Encoding: Session information uses UTF-8 encoding
  6. Epoch Time: Timestamps based on Unix epoch (January 1, 1970, midnight UTC)

Examples

Basic OCRA Generation

const suite = "OCRA-1:HOTP-SHA1-6:QN08";
const key = "12345678901234567890";
const challenge = "12345678";

const code = await OCRA.generate(suite, key, challenge);
console.log(code); // e.g., "123456"

Using Hex Keys

const key = "3132333435363738393031323334353637383930";  // hex encoded seed key

const code = await OCRA.generate(
  "OCRA-1:HOTP-SHA1-6:QN08", 
  key,
  ORCA.bigIntToHex("00000000") // QN = numeric challenge
);

Counter-Based OCRA

const code = await OCRA.generate(
  "OCRA-1:HOTP-SHA1-6:C-QN08",
  key,
  ORCA.bigIntToHex("12345678"), // QN = numeric challenge
  ORCA.bigIntToHex("123")  // counter
);

Password-Protected OCRA

const code = await OCRA.generate(
  "OCRA-1:HOTP-SHA256-8:QN08-PSHA1",
  key, 
  ORCA.bigIntToHex("12345678"), // QN = numeric challenge
  undefined,                    // no counter
  OCRA.stringToHex("1234")      // PSHA1 = SHA1 password
);

Time-Based OCRA

const timestampMinutes = Math.floor(Date.now() / 60000); // Actual nulber of minute from epoch because set T1M in ocra suite

const code = await OCRA.generate(
  "OCRA-1:HOTP-SHA512-8:QN08-T1M",
  key,
  ORCA.bigIntToHex("12345678"),  // QN = numeric challenge
  undefined, // no counter
  undefined, // no password
  undefined, // no session
  ORCA.bigIntToHex(timestampMinutes)
);

Crypto Library Support

The implementation automatically detects and uses available crypto libraries in this order:

  1. WebCrypto API (default)
  2. CryptoJS (alternative)
  3. jsSHA (alternative)

Automatique detection :

const cryptoInfo = OCRA.getCryptoInfo();
console.log('Libraries available:', cryptoInfo.available);
console.log('Primary library:', cryptoInfo.primary);

CryptoJS Setup

<!-- Browser -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/crypto-js/4.2.0/crypto-js.min.js"></script>

jsSHA Setup

<!-- Browser -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/jsSHA/3.3.1/sha.js"></script>

Error Handling

try {
  const code = await OCRA.generate(suite, key, challenge);
  console.log("Success:", code);
} catch (error) {
  console.error("OCRA Error:", error.message);
}

Common Errors

License

GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later)

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.