Ed25519 Signatures
How Truestamp signs exactly three kinds of record with Ed25519 (block records, key handovers, proofs), strict verification, what a proof signature proves, the keyring at /.well-known/keyring.json and which keyring governs each verifier, and the signing key event a proof carries.
Overview
A digital signature is a small piece of data that proves a specific private key approved a specific message, and that the message was not altered afterward. Truestamp signs exactly three kinds of record with Ed25519, the elliptic-curve signature scheme of RFC 8032: its block records, the handover that passes signing from one key to the next, and every proof it issues. Nothing else is signed. What is signed is never the raw data: it is the 32-byte SHA-256 record hash of the object, computed under the domain prefix of its kind (see domain-separated hashing). A proof’s signature that verifies shows that the holder of the key the proof carries signed exactly that proof; it becomes Truestamp’s signature only when that key is also one of the keys in Truestamp’s keyring, which a verifier learns from outside the proof.
What Ed25519 signs at Truestamp
Each signature is pure Ed25519 over the 32 bytes of a record hash, H(p, R) = SHA-256(p || JCS(R)), never over the record’s own bytes and never over the hash’s hex text. The three signed kinds are:
- Block records. A block’s
block_hash, the hash under0x31of its seven-member record (height,id,leaf_count,merkle_root,metadata,previous_block_hashandsigning_key_id), is signed when the block is made: by the active key, or, for a rotation block, by the key the rotation introduces. The signature is Truestamp’s internal record, and no proof carries it. - Key handovers. When the signing key rotates, the outgoing key signs the hash under
0x62of the rotation event without itshandover_signature. That event holds the new key, the old key and theheightandprevious_block_hashof the block record that carries it, so a handover is valid only at the one place in the chain it was signed for. - Proofs. A proof’s
proof_hash, the hash under0x50of the JCS of the envelope’sproofmember (everything in the document but thesignatureobject), is signed by the active key when the proof is generated. See the proof bundle format.
Items, entropy observations, commitment rows and epochs are not signed. An item’s item_hash and an observation’s observation_hash are leaves of a block’s Merkle tree, so the signed block covers them; a commitment row holds only the inclusion proof that ties its subject into a tree; and an epoch’s epoch_hash is written to a public chain as it is.
The signer takes a kind and a record and computes the hash itself. It refuses every unsigned kind and never signs bytes a caller hands it, and every signed message is exactly 32 bytes. Because the three kinds hash under three different prefixes, a signature made for one kind never verifies for another.
Strict verification
Ed25519 verifiers disagree at the edges: on keys of small order, on encodings that are not canonical, and on whether the check multiplies by the cofactor. The Truestamp verification specification fixes one rule, so all conforming verifiers agree on every signature, and each signature binds one document and one key. A verifier:
- reads a key or a signature only from a string that matches its canonical class: 43 characters of unpadded base64url for a 32-byte key, 86 for a 64-byte signature, with the last character forcing the unused bits to zero;
- refuses a key whose y coordinate, read with the sign bit cleared, is 2^255 - 19 or more;
- refuses the ten encodings of points whose order divides 8, among them the identity key, under which one signature verifies for every message;
- refuses a key that does not decode as a point on the curve, and a signature whose
sis not below the group order L; - checks the cofactorless equation:
[s]B - [k]A, withk = SHA-512(R || A || message) mod L, must encode to exactly the signature’s first 32 bytes.
The checks of a key’s bytes (items 2 and 3) are also made on the key a proof carries before anything else, on every key of a keyring when it is loaded, and on every key a key event introduces. Common libraries, OpenSSL among them, do not make them, so a verifier built on one makes them itself before calling it. Truestamp signs with the Ed25519 of the Erlang runtime’s cryptographic library, which OpenSSL backs, and its own record verifiers refuse those keys before they call it. The verifier that checks proofs, truestamp-verify-ex, does its own RFC 8032 arithmetic and makes every step above.
What a signature proves to a verifier
Checking a signature answers one precise question: did the private key that pairs with this public key sign exactly these 32 bytes?
- If the check passes: the record is exactly the one signed. Any change to it changes its hash, and the old signature does not verify over the new hash.
- If the check fails: the record was altered, the signature was altered, or another key made it. The verifier cannot tell which, only that the signature does not hold.
A signature by itself proves who signed, not when. The submission window comes from the subject’s inclusion in a block whose hash is committed, by way of an epoch, to a public blockchain, and from the public records an item names as witnesses.
A proof carries its signer’s whole public key, as signature.public_key, and no key id. A verifier binds that key by comparing its 32 bytes with the keys of the keyring that governs the run, active or retired. The key id of the key, the hex of the first 4 bytes of SHA-256(0x60 || public_key), may serve as an index into the keyring, but only the full comparison binds. A verifier never reads a key id the proof carries, such as a block record’s signing_key_id or a key event’s key_id, to choose or to check the signer. Those ids are preimage inputs of the hashes they sit in: a block record’s signing_key_id names the key that signed that block when it was made, so after a rotation a genuine proof of an older item is signed by a newer key than its block names, and a verifier must not require the two to match.
The properties that make Ed25519 a good choice
Ed25519 gives Truestamp a set of properties that matter directly for long-lived, verifiable evidence:
- Deterministic. Signing one message with one key always gives the identical signature, byte for byte. There is no per-signature random nonce, so a whole class of catastrophic failures (where a weak or reused random value leaks the private key) cannot occur, and signatures are reproducible in tests.
- Fast. Signing and verifying are cheap, which keeps block and proof signing inexpensive and makes independent verification practical at scale.
- Small. A signature is 64 bytes and a public key is 32 bytes. Truestamp spells a signature as 86 characters of unpadded base64url and a public key as 43, and accepts no other spelling of either. Every signed message is 32 bytes whatever the proof’s size, so a hardware security module or a cloud key service can hold the key.
- 128-bit security level. Ed25519 targets roughly 128 bits of security, the conservative level used across modern cryptographic systems.
- Timing-attack resistant. Ed25519’s algorithm is designed to run in constant time, without secret-dependent branches or memory lookups. Truestamp reinforces this on its own side: whenever it compares stored signatures or key identifiers for equality, it uses a constant-time comparison that does not stop early at the first differing byte.
The keyring
Truestamp publishes the public keys it signs with at a stable endpoint that requires no authentication:
GET https://www.truestamp.com/.well-known/keyring.json
The response is a small JSON document with a keys list and a version of "1.0", sent as its canonical JSON (RFC 8785): no whitespace, and members in sorted order. Each entry carries exactly:
active:trueon the key currently signing new proofs;falseon every retired key.key_id: the 8 hex characters of the key’s id, the first 4 bytes ofSHA-256(0x60 || public_key).public_key: the 32-byte Ed25519 public key, as 43 characters of unpadded base64url (RFC 4648 section 5), the one spelling those bytes have.sequence: the key’s position in the rotation lineage. The original key is sequence 0, and each rotation adds one. The entries are in sequence order.
An illustrative response, spread over lines here for reading (values are examples, not real keys):
{
"keys": [
{"active": false, "key_id": "4ceefa4a", "public_key": "R3n...43 chars...", "sequence": 0},
{"active": true, "key_id": "b81f0c2e", "public_key": "mQz...43 chars...", "sequence": 1}
],
"version": "1.0"
}
The keyring lists every key Truestamp has used and not revoked. A key retired by a routine rotation stays, so the proofs it signed still bind. A revoked key, for example one that was stolen, leaves it, so every proof that key signed fails key binding wherever a current keyring governs, whenever it was signed.
The keyring is not a hand-edited list. Every key event, the original key and each rotation after it, is recorded in Truestamp’s own block ledger, and the endpoint serves the keys derived from those records, only while Truestamp’s own check of that key history has passed. Until it has passed, and whenever it fails, the endpoint answers 503 Service Unavailable with an empty body rather than publish keys it has not verified. A new key history replaces the old one in one step, so while a newly recorded key event is being checked the endpoint keeps serving the keys it last verified. The did:web document at /.well-known/did.json, derived from the same keys, follows the same rule. Both are served with cache-control: no-store, so no cache between Truestamp and a verifier keeps a key Truestamp has since revoked, and the keyring also with access-control-allow-origin: *, so a verifier running in a browser can read it.
Which keyring governs a run
Every verifier fixes, before it reads a proof, the one keyring that governs key binding for the run. Which one depends on the verifier’s role.
Truestamp’s own verifier, behind its web pages and APIs, binds against its key chain: the keys the key events in its own blocks introduce, less the revoked ones, verified from the genesis block’s key before it relies on any of them. It fails closed. While the key chain is not verified, key binding fails with keyring_unavailable for every proof, and a key that is not in the key chain fails with key_binding_failed. It has no keyless mode, accepts no keyring from a caller, and never falls back to a copy of the keyring.
An external verifier, Truestamp’s command-line client, the reference verifier, or one anyone else writes, uses one of these, chosen for the run:
| Keyring | Used | When the proof’s key is not in it |
|---|---|---|
the keyring read in this run from https://www.truestamp.com/.well-known/keyring.json |
by default, online | key_binding_failed; after a failed read, keyring_unavailable for every key |
| the compiled pin, the production keyring built into the verifier | by default, offline, and never online | key_binding_failed, with a message to update the verifier or run online |
| a supplied keyring: a file, a configured keyring, or one read from another origin | only on request | key_binding_failed; after a failed read from another origin, keyring_unavailable for every key |
| none: keyless mode | only on request | key binding is skip key_binding_not_performed |
- Online, the keyring read in the run replaces the compiled pin rather than adding to it, so a key revoked after the verifier was built stops binding at once. A read that does not give a keyring passing the load checks, for any reason, is a failed read: no key binds, and the verifier does not fall back to the pin. An answer from a cache is not a read in this run.
- Every keyring is checked when it is loaded. A keyring file or a configured keyring that fails its load checks stops the run as
configuration_error, with no verdict; a keyring read online that fails them is a failed read, as above. - Offline, the compiled pin shows only the keys that held when the verifier was built, and cannot see a revocation since.
- A supplied keyring attributes a proof to
keyring:<d>, d the SHA-256 of the keyring’s bytes, never to Truestamp, and its best label issupplied-keyring. - Keyless mode is never the default and never a fallback. The verifier still checks the signature under the key the proof carries, says in words that it checked it against no keyring, and labels a sound proof
unattributed: anyone could have made it. - Online, an external verifier trusts the keyring as www.truestamp.com serves it. A verifier that must not depend on that origin runs offline, where the pin governs, or supplies its own keyring.
A keyring that arrives with a proof, or from whoever handed over the proof, proves nothing, because that party can list its own key in it. Take it from Truestamp, or from a verifier built with Truestamp’s pin.
The signing key event a proof carries
A proof can also carry, as signing_key_event, the block whose key event introduced the key that signed it, with that block’s own commitments to Stellar and Bitcoin. It is present exactly when that block has a final commitment, and it is provenance only: it shows where the signing key entered Truestamp’s key chain, and it never binds the key. Binding is the keyring’s job alone.
The block’s key event is a genesis, rotation or emergency_rotation. A genesis event carries key_id, public_key, sequence (0), type and, optionally, prerotation_commitment; a rotation also carries handover_signature, height, previous_block_hash, previous_key_id, previous_public_key and reason. A verifier checks it offline with the rest of the proof:
- The block node: its
block_hashis recomputed under0x31from its record, and for the genesis block, its height is 0 and itsprevious_block_hashis the hash under0x30of the GENESIS object in its metadata, which names a Bitcoin block. - The key event: the key passes the checks of a key’s bytes, and its
key_idand the record’ssigning_key_idboth equal the key id of itspublic_key. For a rotation,previous_key_idis the key id ofprevious_public_key,heightandprevious_block_hashequal the record’s, andhandover_signatureverifies strictly underprevious_public_key. - The key it introduces: its 32 bytes must equal the proof’s own key, or the check fails with
key_event_mismatch. When the run attributes the proof to Truestamp, the row passes; otherwise it isinfo not_attributable. - The commitments: each entry’s epoch hash recomputes from its record, and its inclusion proof walks from the recomputed
block_hashto the epoch’s Merkle root. Online, each entry gets the same chain read as a top-level commitment, and so does the Bitcoin block a GENESIS object names; one more row, KEY_EVENT_COMMITMENT at/signing_key_event, sums them up at the end of the chain reads.
These commitments never give an edge of the submission window. After a rotation, the proof of an older item is signed by a newer key, and its window is unchanged.
Limitations
- A signature proves who and what, not when. The submission window comes from block inclusion, the epoch’s commitment to a public blockchain, and the item’s witnesses, read from their sources during verification.
- The keyring is the trust root. A proof’s signature means “Truestamp signed this” only when its key is in a keyring of Truestamp’s: the one Truestamp’s own verifier holds, the one an external verifier reads from www.truestamp.com in the run, or the pin built into it. Whoever can change what that origin serves can add a key for an online external verifier.
- Constant-time behavior is delegated to the platform. Ed25519 is constant-time by design, but the side-channel resistance of a specific build on specific hardware is a property of that platform, not something Truestamp asserts independently.
Citations
- RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA). Defines Ed25519, including its determinism, key and signature sizes, point decoding and verification equation.
- A Hybrid Approach to the Problems of Time-Stamping
- Byte-Prefix Registry
- Cryptographic Accelerators for Digital Signature Based on Ed25519
- Difference between X25519 and Ed25519 - Cryptography Stack Exchange
- Domain-Separated Hashing (SHA-256 Byte Prefixes)
- Ed25519 Deep Dive Addendum (r/crypto)
- Ed25519 signature
- Ed25519: high-speed high-security signatures
- EdDSA (Wikipedia)
- Offline verification
- OpenTimestamps
- Proof Bundle Wire Format
- Proof Claims by Availability
- Proving the Integrity of Digital Evidence with Time
- Ralph Merkle - Wikipedia
- RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA)
- Signing-key ID
- ssh-keygen: Wikipedia
- The Provable Security of Ed25519: Theory and Practice
- Things that use Ed25519 - IANIX
- Verify a Proof
- Why is implementation relevant to timing attacks?
- Witness