Type Classification

Content-addressable hashing is classified as a cryptographic primitive within the CESR (Composable Event Streaming Representation) framework. It represents a fundamental building block for more complex constructs like SAIDs, seals, and digests used throughout KERI event logs and ACDC credential structures.

Cryptographic Properties

Underlying Algorithms

KERI supports multiple cryptographic hash algorithms through its derivation code system, with Blake3-256 being the preferred default for new implementations due to its performance and security characteristics. The specification also supports:

• Blake3-256: 256-bit output, high performance, modern design (recommended)
• Blake2b-256: 256-bit output, widely deployed, proven security
• Blake2s-256: 256-bit output, optimized for 32-bit platforms
• SHA-256: 256-bit output, NIST standard, broad compatibility
• SHA3-256: 256-bit output, Keccak-based, quantum-resistant properties

The choice of algorithm is encoded in the CESR derivation code that prepends the hash output, enabling cryptographic agility—the ability to support multiple algorithms and migrate to stronger ones as needed without breaking existing systems.

Security Properties

Content-addressable hashes in KERI must satisfy three critical security properties:

Collision Resistance: It must be computationally infeasible to find two different inputs that produce the same hash output. This property ensures that each unique piece of content has a unique identifier. For 256-bit hash functions, the collision resistance provides approximately 128 bits of security against birthday attacks.

Preimage Resistance (One-Way Property): Given a hash output, it must be computationally infeasible to find any input that produces that hash. This property ensures that the hash cannot be reversed to reveal the original content, which is critical for privacy-preserving applications where hashes serve as commitments to undisclosed data.

Second Preimage Resistance: Given an input and its hash, it must be computationally infeasible to find a different input that produces the same hash. This property prevents attackers from substituting malicious content while maintaining the same identifier.

These properties collectively ensure that content-addressable hashes provide tamper-evidence—any modification to content produces a different hash, making tampering immediately detectable through identifier mismatch.

Key/Output Sizes

KERI standardizes on 256-bit (32-byte) hash outputs for content-addressable identifiers, providing:

• 128 bits of collision resistance (birthday bound)
• 256 bits of preimage resistance
• Sufficient security margin against quantum computing threats (Grover's algorithm reduces effective security to 128 bits)

When encoded in CESR text format using Base64 URL-safe encoding, a 256-bit hash with its derivation code occupies 44 characters. In binary format, the same hash with derivation code occupies 33 bytes (1-byte code + 32-byte hash).

Data Format & Encoding

CESR Encoding Format

Content-addressable hashes in KERI are encoded using CESR (Composable Event Streaming Representation), which provides dual text-binary encoding with composability properties. The encoding structure consists of:

1. Derivation Code: A prefix indicating the hash algorithm used
2. Hash Output: The raw cryptographic digest bytes

For example, a Blake3-256 hash in CESR text format:

ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM

Breaking down this encoding:

• E: Derivation code for Blake3-256 digest
• LvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM: Base64 URL-safe encoding of the 32-byte hash

Text and Binary Representations

Text Domain (Base64 URL-safe):

• Used in JSON serializations and human-readable formats
• 44 characters total (1 char code + 43 chars hash)
• URL-safe character set: A-Z, a-z, 0-9, -, _
• No padding characters (=) due to CESR's alignment properties

Binary Domain:

• Used in compact binary serializations (CBOR, MessagePack)
• 33 bytes total (1 byte code + 32 bytes hash)
• Direct byte representation without encoding overhead
• Maintains text-binary concatenation composability

CESR's design ensures that any set of concatenated primitives in text domain can be converted to binary domain and back without loss, enabling efficient streaming and storage while maintaining human readability when needed.

Derivation Codes

KERI uses single-character derivation codes in text domain to indicate hash algorithms:

• E: Blake3-256 (recommended default)
• F: Blake2b-256
• G: Blake2s-256
• H: SHA3-256
• I: SHA2-256

These codes are part of the CESR code table, which defines the complete set of cryptographic primitives supported by KERI. The derivation code system enables algorithm agility—systems can support multiple hash functions simultaneously and migrate to stronger algorithms as cryptographic research advances.

Usage in KERI/ACDC

In Which Event Types

Content-addressable hashes appear throughout KERI and ACDC data structures:

Key Event Logs (KELs):

• Previous Event Digest: Each key event includes a hash of the prior event, creating backward chaining
• Next Key Digest: Pre-rotation commits to future keys via hash digests
• Seal Digests: Seals anchor external data to events through content hashes

Authentic Chained Data Containers (ACDCs):

• SAID Fields: The d field in every ACDC contains a self-addressing identifier computed as a hash of the entire structure
• Schema References: The s field may contain a hash reference to a JSON Schema
• Attribute Commitments: The a field may contain a hash of attribute blocks for compact disclosure
• Edge References: The e field uses hashes to link ACDCs in directed acyclic graphs

Transaction Event Logs (TELs):

• Registry Anchoring: TEL events are anchored to KELs via hash digests in event source seals
• Credential State: Issuance and revocation events reference credentials by content hash

Common Usage Patterns

Self-Referential Identifiers (SAIDs):

The most sophisticated use of content-addressable hashing in KERI is the SAID protocol, which creates identifiers that are embedded within the content they identify. The generation process:

1. Populate data structure with placeholder where SAID will reside (typically # characters)
2. Serialize to canonical form
3. Compute hash of serialization containing placeholder
4. Encode hash with CESR derivation code
5. Replace placeholder with computed SAID

This creates a self-referential identifier that is simultaneously part of the data and a cryptographic commitment to it.

Compact Disclosure:

ACDCs use content-addressable hashes to enable graduated disclosure mechanisms:

• Full Disclosure: Complete data structure with all fields expanded
• Compact Disclosure: Replace field values with their SAIDs
• Selective Disclosure: Reveal only specific fields while maintaining cryptographic commitments to undisclosed fields

This pattern allows credential holders to progressively reveal information while maintaining verifiable commitments to the complete credential structure.

Merkle Tree Commitments:

While not explicitly detailed in the provided sources, content-addressable hashing enables Merkle tree structures for efficient verification of large data sets. The ACDC specification mentions support for Merkle proofs in selective disclosure scenarios.

Verification Procedures

Verifying content-addressable hashes follows a standard protocol:

Basic Hash Verification:

1. Extract the hash value and derivation code from the identifier
2. Identify the hash algorithm from the derivation code
3. Recompute the hash of the claimed content using the same algorithm
4. Compare the computed hash with the extracted hash
5. Accept if hashes match; reject if they differ

SAID Verification:

1. Extract the SAID value from the data structure
2. Replace the SAID field with the original placeholder (typically # characters of same length)
3. Serialize to canonical form (same serialization used during generation)
4. Compute hash of the serialization with placeholder
5. Encode with appropriate CESR derivation code
6. Compare computed SAID with extracted SAID
7. Accept if SAIDs match; reject if they differ

Chain Verification:

For chained structures like KELs:

1. Verify each event's signature using the controller's public key
2. Verify each event's previous event digest matches the hash of the prior event
3. Verify any seal digests match the hashed content they reference
4. Ensure the chain is unbroken from inception to current state

Any mismatch in hash verification indicates either data corruption or malicious tampering, triggering rejection of the invalid data.

Related Primitives

Digest Primitives

Content-addressable hashes are closely related to digest primitives in CESR, which represent the raw cryptographic hash output with its derivation code. The distinction:

• Content-addressable hash: The concept and usage pattern
• Digest primitive: The CESR-encoded representation

Digests appear in multiple contexts:

• Event digests: Hashes of serialized key events
• Seal digests: Hashes of anchored external data
• Key digests: Hashes of public keys (used in pre-rotation)

Self-Addressing Identifiers (SAIDs)

SAIDs represent the most sophisticated application of content-addressable hashing, where the hash is embedded within the content it identifies. This creates a self-referential identifier that provides:

• Content binding: Identifier cryptographically bound to content
• Self-containment: No external registry needed for verification
• Immutability: Any content change produces a different SAID

SAIDs are used extensively in ACDCs for the d (identifier), s (schema), a (attributes), and e (edges) fields.

Seals

Seals use content-addressable hashes to anchor external data to key events. A seal consists of:

• Digest: Content-addressable hash of the anchored data
• Event reference: Link to the anchoring key event

Seals enable KERI to make cryptographically verifiable commitments to arbitrary data (credentials, documents, transactions) without embedding the full data in the KEL.

Composition Patterns

Content-addressable hashes compose with other CESR primitives to create complex verifiable structures:

Hash Chains: Sequential events linked by digests of prior events

Merkle Trees: Hierarchical hash structures for efficient verification

Commitment Schemes: Hashes serve as cryptographic commitments to undisclosed data

Authenticated Data Structures: Combining hashes with signatures creates non-repudiable commitments

These composition patterns enable KERI's architecture of verifiable data structures that provide end-to-end verifiability without requiring trusted intermediaries.

• Use high-entropy content (e.g., include UUIDs as salts)
• Avoid hashing predictable or low-entropy data
• Consider rainbow table attacks for publicly known content

Side-Channel Attacks: Implementations should:

• Use constant-time comparison for hash verification
• Avoid timing leaks in hash computation
• Protect hash inputs from unauthorized access

CESR Integration

When implementing content-addressable hashing with CESR:

• Derivation code handling: Correctly parse and validate derivation codes
• Text-binary conversion: Maintain composability during domain conversion
• Stream processing: Support cold-start parsing of concatenated primitives
• Error handling: Gracefully handle unknown derivation codes for forward compatibility

Testing and Validation

Comprehensive testing should include:

• Test vectors: Validate against known hash outputs for standard inputs
• Round-trip verification: Ensure serialization-hash-verification cycles succeed
• Collision testing: Verify different inputs produce different hashes
• Tamper detection: Confirm modified content produces different hashes
• Interoperability: Test with other KERI implementations

Common Pitfalls

Non-deterministic serialization: Ensure JSON serialization maintains field order and produces identical output for identical input.

Incorrect placeholder handling: SAID generation requires exact placeholder length matching the final SAID length.

Algorithm mismatch: Verify the derivation code matches the actual hash algorithm used.

Encoding errors: Ensure proper Base64 URL-safe encoding without padding characters.

Premature optimization: Prioritize correctness over performance in initial implementations; optimize only after profiling identifies bottlenecks.