Typed signing and key IDs
One message per object type
Section titled “One message per object type”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) || dEd25519 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.
Post-quantum hybrid signatures
Section titled “Post-quantum hybrid signatures”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"] endPost-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.
Typed signers only
Section titled “Typed signers only”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.
External signers
Section titled “External signers”Keys can live in software, a hardware security module, or a cloud key service. Every SDK accepts an external signer through one interface:
- 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.
- Inputs. Ed25519 receives
M. ML-DSA receives eitherMand the context, or the 64-byte externalmuthat the SDK computes. The provider never receives the object or a code. - Verify before use. The SDK verifies every returned component and discards both on any failure.
- 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 IDs
Section titled “Key IDs”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.
