A cryptographic commitment to content achieved by digitally signing a digest (cryptographic hash) of that content, providing both content integrityverification and non-repudiable authentication of the signer.
Related Concepts
No related concepts available
Comprehensive Explanation
signed-digest
Technical Definition
A signed digest is a fundamental cryptographic primitive in KERI that represents a commitment to content through the combination of two core cryptographic operations:
Digest computation: Generating a cryptographic hash of content using a collision-resistant hash function
Digital signature: Applying a digital signature to that digest using a private key from an asymmetric key pair
Signed digests enable controllers to make verifiable commitments to data without requiring the full content to be transmitted, stored, or verified in every context. This provides:
Implementation Notes
Critical Implementation Guidance
Canonicalization Requirements
Before computing any digest, content MUST be canonicalized to ensure consistent hash values across implementations:
JSON serialization: Use consistent field ordering (typically alphabetical), no extraneous whitespace, consistent number formatting
CBOR/MessagePack: Use deterministic encoding modes specified in KERI specifications
String encoding: Always use UTF-8 encoding
Floating point: Avoid or use consistent precision/representation
Testing: Cross-validate digest computation with reference implementations (KERIpy, KERIox) to ensure canonicalization compatibility.
Signature Attachment Pattern
KERI uses attached signatures rather than embedded signatures:
Serialize the message body (event, ACDC, etc.)
Compute digest of the serialized body
Sign the digest with private key(s)
Encode signature(s) as CESR primitives
Append CESR-encoded signatures to the message
This pattern keeps message bodies clean and enables efficient signature verification without parsing embedded signatures.
Multi-Signature Handling
For multi-sig AIDs, implement proper threshold validation:
Parse all attached indexed signatures
Extract key indices from signature primitives
Retrieve corresponding public keys from current key state
Verify each signature independently
Count valid signatures and compare to threshold
For weighted thresholds, sum weights of valid signatures
Critical: Always validate that signing keys are authoritative at the specific KEL sequence number being verified.
Key State Validation
When verifying signed digests in KEL events:
Determine the sequence number of the event
Reconstruct key state at that sequence number
Verify signatures using keys authoritative at that point
For rotation events, validate new keys match previous next-key commitments
Update key state after successful verification
Never verify signatures using current key state when validating historical events.
Performance Optimization
Efficient verification: Verifiers can check signatures on compact digests rather than large content
Content integrity: Any modification to content produces a different digest, breaking the signature
Non-repudiation: The signature cryptographically binds the commitment to the signer's key pair
Privacy preservation: Content can remain confidential while its commitment is publicly verifiable
Type Classification
Signed digests are classified as cryptographic commitment primitives within KERI's architecture. They represent a specific pattern of combining:
Digital signature schemes (asymmetric cryptography for authentication)
This combination creates what KERI documentation refers to as "trust who said it not what was said" - establishing consistent attribution as the foundation for trust.
Cryptographic Properties
Underlying Algorithms
Signed digests in KERI leverage multiple cryptographic algorithm families:
Hash Functions
KERI supports various cryptographic hash functions through its derivation code system in CESR:
SHA-256: 256-bit output, widely deployed, NIST standard
BLAKE3: High-performance modern hash function with 256-bit output
BLAKE2b: 512-bit output variant
BLAKE2s: 256-bit output variant
All hash functions used must be collision-resistant, meaning it is computationally infeasible to find two different inputs that produce the same digest.
Signature Schemes
KERI's signed digests support multiple signature algorithms:
Ed25519: Edwards-curve Digital Signature Algorithm, 256-bit security
ECDSA (secp256k1): Elliptic Curve Digital Signature Algorithm used in Bitcoin
ECDSA (secp256r1): NIST P-256 curve variant
Ed448: Higher security Edwards-curve variant
The KERI whitepaper emphasizes that the protocol is designed to be cryptographically agile, allowing migration to new algorithms as cryptographic research advances or quantum computing threats materialize.
Security Properties
Signed digests provide multiple security guarantees:
Integrity Protection
The digest component ensures cryptographic integrity through collision resistance. For a hash function H and content C:
Computing D = H(C) produces a fixed-size digest
Any modification C' ≠ C produces D' = H(C') where D' ≠ D (with overwhelming probability)
An attacker cannot find C' such that H(C') = H(C) (collision resistance)
This property is fundamental to KERI's append-only event logs, where each event includes a digest of the previous event, creating an immutable chain.
Authentication and Non-Repudiation
The signature component provides cryptographic authentication:
Only the holder of the private key can generate valid signatures
Anyone with the public key can verify signatures
Signatures are non-repudiable: the signer cannot later deny having signed
In KERI's context, this enables end-verifiable statements where validators can cryptographically verify that a specific AID controller made a commitment without trusting intermediaries.
Forward Security Through Pre-Rotation
KERI's pre-rotation mechanism leverages signed digests of future keys. As documented in the KERI whitepaper:
Total size typically ranges from 97 to 182 bytes depending on algorithm choices.
Data Format & Encoding
CESR Encoding Format
Signed digests in KERI are encoded using CESR (Composable Event Streaming Representation), which provides dual text-binary encoding with composability properties.
Qualified Primitives
CESR represents cryptographic primitives as qualified primitives that include:
Derivation code: Prepended code indicating the cryptographic algorithm and encoding
Raw cryptographic material: The actual digest or signature bytes
This creates self-framing primitives where parsers can determine type and length without external context.
Derivation Codes for Digests
CESR uses specific derivation codes for different hash algorithms:
E: SHA-256 digest (32 bytes)
F: SHA-512 digest (64 bytes)
G: SHA3-256 digest (32 bytes)
H: SHA3-512 digest (64 bytes)
I: BLAKE3-256 digest (32 bytes)
0D: BLAKE2b-256 digest (32 bytes)
0E: BLAKE2s-256 digest (32 bytes)
Derivation Codes for Signatures
Signatures use different code families:
B: Ed25519 signature (64 bytes)
0B: ECDSA secp256k1 signature (64 bytes)
C: Ed448 signature (114 bytes)
For indexed signatures (used in multi-sig scenarios), additional codes indicate the signing key index.
Text and Binary Representations
CESR provides text-binary concatenation composability, meaning primitives can be converted between domains without loss:
Text Domain (Base64 URL-Safe)
In the text domain, signed digests are encoded as Base64 URL-safe strings:
One-time key use: Minimize key exposure through single-use patterns
Key separation: Use different keys for signing vs. rotation
Entropy quality: Use cryptographically strong random number generators
Algorithm agility: Design for future algorithm migration
Common Implementation Pitfalls
Pitfall 1: Inconsistent Canonicalization
Different implementations may canonicalize differently, causing verification failures. Solution: Use standardized serialization libraries and test cross-implementation compatibility.
Pitfall 2: Signature Malleability
Some signature schemes allow multiple valid signatures for the same message. Solution: Use non-malleable schemes (Ed25519) or canonical signature encoding.
Pitfall 3: Timing Attacks
Signature verification timing can leak information. Solution: Use constant-time comparison operations for cryptographic values.
Pitfall 4: Key State Confusion
Verifying signatures with wrong key state (e.g., rotated keys). Solution: Always validate key state at the specific KEL sequence number being verified.
Integration with KERI Infrastructure
Signed digests integrate with broader KERI components:
Witnesses: Verify and sign event digests to create receipts
Watchers: Monitor for duplicitous signed digests (duplicity detection)
Validators: Perform end-to-end verification of signed digest chains
Registries: Use signed digests to anchor credential state
Proper implementation requires understanding these interactions and maintaining consistency across the entire KERI stack.
Batch verification: When verifying multiple signatures, use batch verification algorithms if available (e.g., Ed25519 batch verification)
Caching: Cache verified key states to avoid recomputing KEL state for each verification
Parallel processing: Signature verification operations are independent and can be parallelized
Hardware acceleration: Use CPU crypto extensions (AES-NI, SHA extensions) when available
Security Considerations
Constant-Time Operations
Use constant-time comparison for all cryptographic values to prevent timing attacks:
# BAD - timing attack vulnerable
if computed_digest == expected_digest:
return True
# GOOD - constant-time comparison
import hmac
if hmac.compare_digest(computed_digest, expected_digest):
return True
Entropy Quality
For key generation and signing:
Use cryptographically secure random number generators (CSPRNG)
On Unix systems: /dev/urandom or getrandom() syscall
Never use rand(), random(), or predictable seeds
Ensure sufficient entropy before key generation
Algorithm Agility
Design implementations to support algorithm migration:
Parse derivation codes to determine algorithms dynamically
Support multiple hash and signature algorithms simultaneously
Implement algorithm negotiation for new key generation
Plan for post-quantum algorithm integration
Common Pitfalls
Pitfall 1: Signature Malleability
Some ECDSA implementations allow signature malleability (multiple valid signatures for same message). Solution: Use Ed25519 (non-malleable) or enforce canonical ECDSA encoding.
Pitfall 2: JSON Field Ordering
JavaScript objects and Python dicts may not preserve insertion order in older versions. Solution: Use ordered dictionaries or explicit field ordering during serialization.
Pitfall 3: Base64 Padding
CESR uses Base64 URL-safe encoding without padding characters. Solution: Ensure Base64 encoding/decoding strips = padding and uses URL-safe alphabet (-_ instead of +/).
Pitfall 4: Digest Algorithm Confusion
Mixing digest algorithms between commitment and verification. Solution: Always extract and respect derivation codes; never assume algorithm.
Integration Testing
Implementations should include:
Cross-implementation tests: Verify signed digests created by one implementation can be verified by others
Test vectors: Use official KERI test vectors for digest and signature verification
Fuzzing: Test parser robustness with malformed CESR primitives
Timing tests: Verify constant-time operations don't leak information