Skip to content
You are reading the Ratify Protocol v2 beta documentation. Protocol v1 remains available at the site root.

Typed signing and key IDs

Every signed v2 object has a permanent object type code (delegation certificate 0x0001, challenge presentation 0x0002, revocation list 0x0003, and so on). Both signature components sign the same 77-byte message:

d = SHA-384(signable_bytes)
M = "ratify-protocol-signature" || 0x00 || 0x02 || uint16_be(object_type_code) || d

Ed25519 signs M. ML-DSA-65 (FIPS 204, pure mode) signs M under the fixed context ratify-protocol/2/<code>, for example ratify-protocol/2/0001. The verifier derives the code from the schema it is verifying, so an object signed under one code never verifies as another. Both components must verify; a partial, swapped, or stripped signature fails.

Details: SPEC-v2 §3 and the registry in §4.

Every Ratify signature pairs Ed25519 with ML-DSA-65 (NIST FIPS 204), and it verifies only when both verify, so a forger must break both, including with a future quantum computer.

flowchart LR
O["Ratify object<br/>(delegation, proof, receipt...)"] --> M["Typed signing message<br/>binds object type and protocol version"]
M --> E["Ed25519 signature"]
M --> L["ML-DSA-65 signature<br/>(NIST FIPS 204)"]
E --> P["Hybrid signature pair"]
L --> P
P --> VE{"Ed25519<br/>valid?"}
P --> VL{"ML-DSA-65<br/>valid?"}
VE --> A{"Both valid?"}
VL --> A
A -->|yes| OK["Accept"]
A -->|no| NO["Reject"]

A large enough quantum computer is expected to break Ed25519, and ML-DSA-65 is designed to resist one. An undiscovered weakness in the younger ML-DSA standard is covered by Ed25519. Either way, a forgery fails:

flowchart TB
subgraph Q["Attacker with a quantum computer"]
Q1["Breaks Ed25519"] --> Q2["Cannot produce a valid ML-DSA-65 signature"] --> Q3["Forgery rejected"]
end
subgraph W["Attacker with an unknown ML-DSA weakness"]
W1["Breaks ML-DSA-65"] --> W2["Cannot produce a valid Ed25519 signature"] --> W3["Forgery rejected"]
end
subgraph B["A forgery that verifies"]
B1["Requires breaking Ed25519 AND ML-DSA-65"]
end

Post-quantum signatures protect the authenticity of Ratify objects. They do not protect a leaked private key, and Ratify does not encrypt traffic, so transport security remains the deployment’s concern. The full explanation, including what this does and does not cover, is in Post-quantum hybrid signatures.

Every SDK signs through one typed function per object. A typed signer validates the object against its schema and limits, applies the issuer duties (for a delegation: finite lifetime, valid scopes, satisfiable resource_path constraints), and computes M and the context itself.

  • No SDK exports a function that signs caller-selected bytes, codes, contexts, or prehash modes.
  • No SDK exports a local signer object. An in-process private key is accepted only by the typed signing functions and by constructors that sign through them, such as the status publisher.

Keys can live in software, a hardware security module, or a cloud key service. Every SDK accepts an external signer through one interface:

  1. Key binding. The signer reports its complete hybrid public key. The SDK recomputes the key ID and requires the key to match the role. A provider label or alias is never identity.
  2. Inputs. Ed25519 receives M. ML-DSA receives either M and the context, or the 64-byte external mu that the SDK computes. The provider never receives the object or a code.
  3. Verify before use. The SDK verifies every returned component and discards both on any failure.
  4. Hedged signatures. A retry may return different valid bytes, so deduplication compares the signed body digest, never signature bytes.

Each SDK reference page renders an external-signer example.

key_id_v2 = lowercase_hex(SHA-256("ratify-key-id-v2" || 0x00 || ed25519_pub (32 bytes) || ml_dsa_65_pub (1952 bytes)))

A v2 key ID is the full 256-bit digest, 64 hexadecimal characters. A 128-bit v1 ID is rejected wherever a v2 ID is required.

IDs are lookup indexes, not trust. A verifier recomputes every ID from the complete key and rejects a mismatch. After a lookup, the complete public key must match, and zero or several matching records fail closed. Trust anchors are pinned as complete keys; pinning only an ID lets a different key that claims the same label slip through.

Details: SPEC-v2 §2.3, §3.2.