Time-Based One-Time Passwords (TOTP) for M2M Authentication
Status: This directory is the normative home of the Open Charging Technology TOTP token format — a machine-to-machine Time-based One-Time Password format — and of its HTTP authentication binding. The token format (v1.0) is final: it is frozen by deployed verifiers, and the specification describes it exactly as implemented. The HTTP binding (v1.0) is a draft. The documents moved here from OpenChargingCloud/TOTPConformanceTests, which remains the cross-implementation conformance suite executing the vector annex.
Point of contact: Achim Friedland <achim.friedland@graphdefined.com>, GraphDefined GmbH
| Document | Content |
|---|---|
| totp-token-format.md | The token format (v1.0, final): token derivation (HMAC over the big-endian 64-bit time slot, arbitrary alphabets, 4–255 characters), parameters and validation rules, the previous/current/next acceptance window, the TLS v1.3 channel binding extension, security considerations. |
| totp-http-authentication.md | The HTTP bindings (v1.0, draft): TOTP over HTTP Basic Auth (the token in the password field — zero new wire code, the migration path), the native Authorization: TOTP scheme (RFC 9110 auth-params: login, totp, tlscb with its secure default true) and the TOTP request header, verification procedure, WebSocket handshakes, caching, error handling. |
| test-vectors/ | The normative annex: machine-readable conformance test vectors — generation vectors, invalid-input vectors, and the Authorization: TOTP header vectors. GENERATED by the tool below, never hand-edited. |
| tools/ | The vector generator: an independent third implementation of the specification (pure Python stdlib), which re-derives the hand-cross-validated anchor values before writing anything. |
Implementations and conformance
Two independent implementations derive byte-identical tokens:
- Vanaheimr Hermod —
TOTPGenerator, C#/.NET (including the TLS channel binding and the HTTP bindings) - TOTP.ts —
@open-charging-cloud/totp, TypeScript/Node
The conformance suite
OpenChargingCloud/TOTPConformanceTests
consumes this repository as its libs/specification submodule and runs both
implementations against the annex — on every push against pinned submodule
states, and nightly against the upstream HEADs. Both implementation
repositories additionally run their own test suites against vendored copies
of the annex (see test-vectors/README.md).
Relationship to OCPP — and to the whitepapers around this directory
The format was originally developed for OCPP v2.1: use case C25 "Ad hoc payment via a QR code" normatively defines "TOTP algorithm, version 1", which is exactly the sha256/Base62 profile of this specification (token format section 1.2). Related whitepapers in this repository tell the why around this normative what:
- HTTP Basic Authentication with Time-Based One-Time Passwords — the migration story behind the Basic binding (HTTP binding section 4)
- Alternative HTTP Authentication Methods for OCPP
— how peers negotiate authentication schemes, including
TOTP - Secure Time Synchronization for OCPP v1.6 and v2.x — the authenticated time source this format's security depends on
- upcoming: Time-Based One-Time Passwords as 2nd Factor Authentication for OCPI