Supported Hash Algorithms

KERI implementations support multiple cryptographic hash algorithms, each with specific properties:

Blake3-256: A modern, high-performance hash function producing 256-bit (32-byte) digests. Blake3 is the preferred algorithm for new KERI implementations due to its speed and security properties. CESR derivation code: E

Blake2b-256: Produces 256-bit digests with excellent performance characteristics. CESR derivation code: F

Blake2s-256: A variant optimized for 8- to 32-bit platforms, producing 256-bit digests. CESR derivation code: G

SHA3-256: Part of the SHA-3 family, producing 256-bit digests based on the Keccak algorithm. CESR derivation code: H

SHA2-256: The widely-deployed SHA-256 algorithm producing 256-bit digests. CESR derivation code: I

Blake3-512: Extended Blake3 variant producing 512-bit (64-byte) digests for applications requiring higher security margins. CESR derivation code: 0D

Blake2b-512: 512-bit variant of Blake2b. CESR derivation code: 0E

SHA3-512: 512-bit variant of SHA3. CESR derivation code: 0F

SHA2-512: 512-bit variant of SHA-256. CESR derivation code: 0G

All these algorithms provide collision resistance suitable for KERI's security requirements, with 256-bit variants offering approximately 128 bits of security and 512-bit variants offering approximately 256 bits of security.

Cryptographic Equivalence Property

A critical property leveraged by ACDCs is that a verifiable cryptographic commitment (such as a digital signature) to the digest of data is cryptographically equivalent to a commitment to the data itself. This equivalence enables:

• Compact chains: ACDCs can reference large data sets through fixed-size digests
• Equivalent authentication: Data represented by its digest receives the same cryptographic guarantees as the full data
• Privacy preservation: Digests can serve as commitments without revealing underlying data

Data Format & Encoding

CESR Encoding

Digests in KERI are encoded as qualified CESR primitives consisting of:

1. Derivation code: A prefix indicating the hash algorithm used
2. Base64 URL-safe encoded digest: The hash output encoded for text transmission

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

ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM

Breakdown:

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

Text and Binary Representations

CESR supports dual encoding domains:

Text Domain (T): Uses Base64 URL-safe characters for human readability and debugging. Digests are represented as strings with prepended derivation codes.

Binary Domain (B): Compact binary representation for efficient transmission. The derivation code is encoded as binary prefix bytes, followed by the raw digest bytes.

Raw Domain (R): The actual digest bytes as produced by the hash function, without encoding. This is the form used by cryptographic libraries.

The CESR composability property ensures lossless round-trip conversion between text and binary domains for concatenated primitives.

Derivation Codes

Derivation codes serve multiple purposes:

• Algorithm identification: Indicates which hash function produced the digest
• Cryptographic agility: Enables protocol evolution to new algorithms
• Self-describing: Digests carry their own type information
• Verification guidance: Tells verifiers which algorithm to use for recomputation

The code table structure ensures that derivation codes preserve 24-bit alignment boundaries required for CESR composability.

Usage in KERI/ACDC

Key Event Logs (KELs)

Digests are fundamental to KEL integrity:

Event Chaining: Each key event includes the digest of the previous event in its p (prior) field, creating a hash-chained data structure. This backward chaining makes the KEL tamper-evident—any modification to a past event breaks the chain.

Self-Addressing Events: The d field in each event contains the event's own SAID (Self-Addressing Identifier), which is the digest of the event content with the d field replaced by a placeholder during computation. This creates a self-referential integrity mechanism.

Pre-Rotation Commitments: The n (next) field contains digests of pre-rotated public keys, enabling KERI's post-quantum secure key rotation mechanism. The digest hides the actual next keys until rotation, preventing attackers from compromising future keys.

Authentic Chained Data Containers (ACDCs)

ACDCs extensively use digests for multiple purposes:

SAID Protocol: Every ACDC has a d field containing its SAID—the digest of the entire credential structure. This makes the credential self-addressing and tamper-evident.

Compact Disclosure: ACDCs support graduated disclosure where field maps can be represented by their SAIDs (digests) rather than full content. For example:

{
  "v": "ACDC10JSON00011c_",
  "d": "EAdXt3gIXOf2BBWNHdSXCJnFJL5OuQPyM5K0neuniccM",
  "i": "did:keri:EBkPreYpZfFk66jpf3uFv7vklXKhzBrAqjsKAn2EDIPM",
  "s": "ED6jrVPTzlSkUPqGGeIZ8a8FWS7a6s4reAXRZOkogZ2A",
  "a": "EEveY4-9XgOcLxUderzwLIr9Bf7V_NHwY1lkFrn9y2PY"
}

Here, the a (attributes) field contains only the digest of the attributes block, not the full attributes. This enables privacy-preserving credential presentation.

Schema Identification: The s field contains the SAID of the JSON Schema defining the credential structure, ensuring schema integrity and preventing schema tampering.

Edge Chaining: The e (edges) field uses digests to link ACDCs together, forming directed acyclic graphs (DAGs) of verifiable credentials.

Transaction Event Logs (TELs)

TELs anchor to KELs through digests:

Event Source Seals: TEL events are anchored to KEL events using seals containing the digest of the TEL event. This cryptographic anchoring binds the TEL state to the KEL's security properties.

Registry State: Credential registries use digests to track issuance and revocation state, with each state change anchored via digest to the controlling KEL.

Verification Procedures

Digest verification follows a standard process:

1. Extract the digest from the data structure (e.g., from the d field)
2. Identify the algorithm from the derivation code prefix
3. Reconstruct the digestible content by replacing the digest field with the appropriate placeholder
4. Recompute the digest using the identified algorithm
5. Compare the computed digest to the extracted digest
6. Verify match: Equality proves the data has not been tampered with

For SAIDs specifically, the placeholder is typically a string of # characters matching the expected digest length.

Related Primitives

Diger

A diger is a CESR primitive class that represents a digest. It provides methods to:

• Verify that input data hashes to its stored raw value
• Convert between raw, text, and binary representations
• Extract derivation codes and raw digest bytes

Digers are the implementation abstraction for working with digests in KERI code.

SAID (Self-Addressing Identifier)

SAIDs are a specialized application of digests where the digest is embedded within the data it identifies. The SAID generation process:

1. Populate data with placeholder for SAID field
2. Compute digest of the data
3. Replace placeholder with the computed digest

This creates a self-referential structure where the identifier is the digest of content that includes the identifier itself.

Signed Digests

A signed digest combines two operations:

1. Computing a cryptographic digest of content
2. Applying a digital signature to that digest

This provides both integrity (via the digest) and non-repudiable commitment (via the signature). In KERI, controllers sign digests of events rather than the full event content, leveraging the cryptographic equivalence property.

Seals

A seal is a cryptographic commitment in the form of a digest or Merkle root that anchors data to a key event. Seals enable:

• Anchoring external data to KELs
• Binding TELs to KELs
• Creating verifiable timestamps for arbitrary data

Seals use digests as the commitment mechanism, ensuring tamper-evidence of the sealed data.

Implementation Considerations

Algorithm Selection

For new implementations, Blake3-256 is recommended due to:

• Superior performance characteristics
• Modern cryptographic design
• Parallelization support
• Cryptographic strength equivalent to SHA-256

However, implementations must support multiple algorithms for interoperability with existing KERI deployments.

Digest Computation

When computing digests for SAIDs:

1. Ensure canonical serialization of the data structure
2. Use insertion-ordered field maps to maintain deterministic ordering
3. Replace the SAID field with the correct placeholder (typically # characters)
4. Apply the hash function to the serialized bytes
5. Encode the result according to CESR rules

Performance Optimization

Digest computation can be a performance bottleneck in high-throughput scenarios:

• Caching: Store computed digests to avoid recomputation
• Streaming: Use streaming hash APIs for large data
• Parallelization: Blake3 supports parallel hashing for multi-core systems
• Hardware acceleration: Leverage CPU instructions (e.g., SHA-NI) when available

Security Considerations

Collision Resistance: Always use hash functions with at least 256-bit output for production systems. 128-bit digests are insufficient for collision resistance.

Algorithm Agility: Design systems to support algorithm migration. The CESR derivation code system enables this by making the algorithm explicit in every digest.

Quantum Resistance: Current hash functions (SHA-256, Blake3) are believed to be quantum-resistant for collision resistance, though Grover's algorithm reduces pre-image resistance. 256-bit hashes provide approximately 128 bits of quantum security.

Timing Attacks: Use constant-time comparison functions when verifying digests to prevent timing side-channels.

Testing

Digest implementations should be tested for:

• Correctness: Verify against known test vectors for each algorithm
• Encoding: Ensure CESR encoding/decoding round-trips correctly
• Edge cases: Test with empty input, maximum-size input, and boundary conditions
• Interoperability: Verify compatibility with other KERI implementations

Performance Optimization

Streaming for Large Data: When hashing large data structures, use streaming hash APIs to avoid loading entire content into memory.

Caching Strategy: Cache computed digests with cache invalidation on data modification. Use the digest itself as a cache key for content-addressed storage.

Parallel Hashing: Blake3 supports parallel hashing. For multi-core systems processing multiple digests, parallelize across items rather than within a single digest.

Security Best Practices

Constant-Time Comparison: When verifying digests, use constant-time comparison functions to prevent timing attacks:

import hmac
hmac.compare_digest(computed_digest, expected_digest)

Algorithm Deprecation: Monitor NIST and cryptographic community guidance for algorithm deprecation. The CESR derivation code system enables graceful migration to new algorithms.

Collision Resistance: For production systems, use at least 256-bit digests. 128-bit digests do not provide adequate collision resistance (birthday attack complexity of 2^64).

Testing Requirements

Test Vectors: Verify implementation correctness against known test vectors for each supported algorithm.

Round-Trip Testing: Ensure CESR encoding/decoding preserves digest values across text/binary conversions.

Interoperability Testing: Verify digest computation matches other KERI implementations by comparing digests of identical data structures.

Edge Case Testing: Test with empty input, maximum-size input, and boundary conditions for each algorithm.