Cryptographic Signing Explained: How Truthlocks Secures Every Attestation

Every attestation issued through Truthlocks carries a cryptographic signature that binds the content to the issuer and makes tampering detectable. This post explains the signing architecture in detail — from key generation through signature verification — so that security teams and developers can understand exactly how their data is protected.

Why Ed25519?

Truthlocks uses Ed25519, an elliptic curve digital signature algorithm defined in RFC 8032. We chose Ed25519 for several reasons:

• Performance: Ed25519 signature generation and verification are significantly faster than RSA or ECDSA with equivalent security levels. A single core can verify over 70,000 signatures per second.
• Small keys and signatures: Public keys are 32 bytes, signatures are 64 bytes. This keeps attestation payloads compact and reduces storage overhead.
• Deterministic signing: Ed25519 does not require a random nonce during signing, eliminating an entire class of implementation vulnerabilities (such as the Sony PS3 ECDSA nonce reuse attack).
• Resistance to side-channel attacks: The algorithm's design avoids secret-dependent branches and memory access patterns, making it more resilient against timing attacks.

Key Generation and Storage

Issuer key pairs are generated inside a FIPS 140-2 Level 3 hardware security module (HSM). The private key never leaves the HSM boundary — all signing operations are performed within the secure hardware. This means that even if the application server is fully compromised, the attacker cannot extract the signing key.

Each issuer in the trust registry has a unique key pair. When an issuer is onboarded, the platform provisions a new key in the HSM and publishes the corresponding public key to the trust registry. Key metadata — including creation timestamp, algorithm identifier, and the issuer's DID — is recorded as a trust registry event.

Key Rotation

Keys are rotated on a configurable schedule (default: annually) or on demand if a compromise is suspected. During rotation, a new key pair is generated, the old public key is marked as "rotated" with an effective end date, and the new public key is published. Attestations signed with the old key remain verifiable — the verification flow checks the key's validity window against the attestation's issuance timestamp.

The Signing Flow

When an issuer mints an attestation through the API, the following steps occur:

1. Canonicalization: The attestation payload is serialized into a canonical JSON form (RFC 8785 — JSON Canonicalization Scheme). This ensures that semantically identical payloads produce identical byte sequences regardless of key ordering or whitespace.
2. Hashing: The canonical payload is hashed with SHA-512 as part of the Ed25519 signing process (Ed25519 uses SHA-512 internally).
3. Signing: The hash is sent to the HSM, which performs the Ed25519 signature operation and returns the 64-byte signature.
4. Envelope construction: The signature, the issuer's public key reference (a key ID, not the raw key), and the attestation payload are assembled into a signed envelope. The envelope also includes a timestamp and the transparency log sequence number.
5. Log entry: The signed envelope is appended to the transparency log and assigned an inclusion proof.

Signature Verification Flow

When a verifier checks an attestation, the verification service performs these steps:

1. Resolve the public key: The key ID in the signed envelope is resolved against the trust registry to retrieve the issuer's public key and trust level.
2. Check key validity: The service confirms that the key was active at the time the attestation was issued (i.e., the issuance timestamp falls within the key's validity window).
3. Re-canonicalize the payload: The attestation payload is re-serialized using JCS to produce the canonical byte sequence.
4. Verify the signature: The Ed25519 verification algorithm is applied using the public key, the canonical payload bytes, and the signature. If the signature is valid, the payload has not been modified since signing.
5. Check revocation status: The service queries the revocation registry to confirm the attestation has not been revoked.
6. Verify transparency log inclusion: The inclusion proof is checked against the current signed tree head to confirm the attestation is recorded in the transparency log.

Only if all six checks pass does the verification service return a positive result.

Code Example

Here is a simplified illustration of verifying an attestation signature using our JavaScript SDK:

import { TruthlockClient } from '@truthlocks/sdk';

const client = new TruthlockClient({ apiKey: process.env.TRUTHLOCK_API_KEY });

const result = await client.attestations.verify({
  attestationId: 'att_8f3k2n4m5p6q',
});

console.log(result.valid);           // true
console.log(result.issuer.trustLevel); // "enhanced"
console.log(result.signature.algorithm); // "Ed25519"
console.log(result.transparency.included); // true

Defense in Depth

Cryptographic signing is one layer in a defense-in-depth strategy. It is complemented by TLS 1.3 for transport security, AES-256 encryption at rest, role-based access control, rate limiting, and the append-only transparency log. Together, these layers ensure that attestations are authentic, confidential, and auditable. For more details, see our security documentation.