Type Classification

SADs represent a specific class of self-referential cryptographic data structures that extend traditional content-addressable storage with self-containment properties. Unlike simple content-addressed data (where identifiers are external), SADs embed their identifiers within the data itself, creating a self-proving structure.

Cryptographic Properties

SAID Generation Algorithm

The SAID derivation follows a precise four-step protocol:

1. Populate Data: Create the complete data structure with a placeholder for the SAID field (typically a string of # characters matching the target SAID length)
2. Canonicalize: Transform the data into a canonical serialization form (the identifiable basis) ensuring consistent byte representation
3. Hash: Apply a cryptographic hash function to the identifiable basis to generate the SAID value
4. Embed: Replace the placeholder with the computed SAID, creating the final saidified data

Verification reverses this process: extract the SAID, replace with placeholder, recompute hash, and compare.

Underlying Algorithms

KERI's SAID implementation primarily uses Blake3-256 as the default hash algorithm, though the architecture supports cryptographic agility through CESR derivation codes. Blake3-256 provides:

• 256-bit output: Sufficient collision resistance for identifier uniqueness
• High performance: Optimized for modern CPU architectures with SIMD support
• Parallelizable: Merkle tree structure enables efficient processing
• Verified streaming: Supports incremental hashing for large data structures

Alternative algorithms supported include Blake2b-256, Blake2s-256, SHA3-256, and SHA2-256, each identified by specific CESR derivation codes.

Security Properties

SADs provide several critical security guarantees:

Collision Resistance: The cryptographic hash function ensures that finding two different data structures with the same SAID is computationally infeasible (approximately 2^128 operations for 256-bit hashes).

Pre-image Resistance: Given a SAID, it is computationally infeasible to construct data that produces that SAID without knowing the original content.

Tamper Evidence: Any modification to the data content invalidates the SAID, making tampering immediately detectable through verification.

Binding Strength: The cryptographic binding between SAID and content provides approximately 128 bits of security strength, meeting KERI's security requirements.

Key/Output Sizes

For Blake3-256 (the default):

• Raw hash output: 32 bytes (256 bits)
• CESR text encoding: 44 characters (including 1-character derivation code)
• CESR binary encoding: 33 bytes (including 1-byte derivation code)
• Derivation code: E (text) or 0x0c (binary) for Blake3-256

The CESR encoding ensures that SAIDs are self-describing, with the derivation code indicating which hash algorithm was used, enabling cryptographic agility and future algorithm transitions.

Data Format & Encoding

CESR Encoding Format

SAIDs are encoded using Composable Event Streaming Representation (CESR), which provides dual text/binary encoding with composability properties. The encoding structure consists of:

1. Derivation Code: Prepended code indicating the hash algorithm
2. Hash Value: Base64 URL-safe encoding (text) or raw bytes (binary)

Example SAID in text domain:

ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM

Breakdown:

• E: Derivation code for Blake3-256
• LvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM: Base64 URL-safe encoded hash

Text and Binary Representations

Text Domain (T): Uses Base64 URL-safe character set [A-Z, a-z, 0-9, -, _] for human readability and debugging. Text SAIDs are 44 characters for 256-bit hashes.

Binary Domain (B): Uses raw bytes for compact transmission and storage. Binary SAIDs are 33 bytes for 256-bit hashes.

Composability: CESR ensures that concatenated SAIDs can be converted between text and binary domains without loss, maintaining separability of individual primitives.

Derivation Codes

CESR derivation codes for common SAID algorithms:

• E (text) / 0x0c (binary): Blake3-256 (44 characters / 33 bytes)
• F (text) / 0x0d (binary): Blake2b-256
• G (text) / 0x0e (binary): Blake2s-256
• H (text) / 0x0f (binary): SHA3-256
• I (text) / 0x10 (binary): SHA2-256

For 512-bit variants:

• 0D (text) / 0x1c1d (binary): Blake3-512 (88 characters / 66 bytes)
• 0E (text) / 0x1c1e (binary): Blake2b-512

The derivation code enables cryptographic agility, allowing systems to transition to new hash algorithms while maintaining backward compatibility.

Usage in KERI/ACDC

In Which Event Types

SADs and SAIDs appear throughout KERI and ACDC structures:

KERI Key Events:

• Inception Events: The event digest (d field) is a SAID of the inception event data
• Rotation Events: Event digest (d field) and prior event digest (p field) are SAIDs
• Interaction Events: Event digest (d field) is a SAID
• Delegated Events: Delegation seals reference SAIDs of delegating events

ACDC Credentials:

• Credential SAID: Top-level d field is the SAID of the entire credential
• Schema SAID: s field references the schema by its SAID
• Attribute Block SAID: a field can be a SAID in compact form
• Edge Block SAID: e field can be a SAID referencing linked credentials
• Rule Block SAID: r field can be a SAID for Ricardian contracts
• Nested SAIDs: Attribute sections, edge sections, and rule sections each have their own SAIDs

Transaction Event Logs (TELs):

• Registry identifiers are SAIDs
• Credential status events reference credential SAIDs

Common Usage Patterns

Compact Disclosure: ACDCs use SAIDs to represent undisclosed sections, enabling graduated disclosure:

{
  "v": "ACDC10JSON00011c_",
  "d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "i": "EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM",
  "s": "E46jrVPTzlSkUPqGGeIZ8a8FWS7a6s4reAXRZOkogZ2A",
  "a": "EEveY4-9XgOcLxUderzwLIr9Bf7V_NHwY1lkFrn9y2PY"
}

Here, the a field contains only the SAID of the attributes block, not the full attributes. The holder can later reveal the full attributes while proving they match the committed SAID.

Schema References: Credentials reference schemas by SAID rather than URL, ensuring schema immutability:

{
  "s": "E46jrVPTzlSkUPqGGeIZ8a8FWS7a6s4reAXRZOkogZ2A"
}

Any party can verify that a retrieved schema matches the committed SAID, preventing schema tampering.

Credential Chaining: ACDCs use SAIDs in edge sections to create verifiable credential graphs:

{
  "e": {
    "d": "EFH3dCdoFOLe71iheqcywJcnjtJtQIYPvAu6DZIl3MOA",
    "qvi": {
      "n": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
      "s": "EBfdlu8R27Fbx-ehrqwImnK-8Cm79sqbAQ4MmvEAYqao"
    }
  }
}

The n field contains the SAID of a prerequisite credential, creating a cryptographically verifiable dependency chain.

Verification Procedures

Verifying a SAD involves:

1. Extract SAID: Retrieve the SAID value from the designated field (typically d)
2. Canonicalize: Serialize the data structure in canonical form
3. Replace SAID: Substitute the SAID field with the original placeholder (matching length)
4. Recompute Hash: Apply the hash algorithm indicated by the derivation code
5. Compare: Verify the computed hash matches the extracted SAID

For nested SADs (like ACDC sections), verification proceeds recursively from innermost to outermost SAIDs.

Verification Failure Modes:

• SAID Mismatch: Computed hash doesn't match embedded SAID (data tampered)
• Invalid Derivation Code: SAID uses unsupported hash algorithm
• Malformed Structure: Data cannot be canonicalized or SAID field missing
• Length Mismatch: SAID length doesn't match expected length for algorithm

Related Primitives

SAID (Self-Addressing Identifier)

The SAID is the identifier component of a SAD. While SADs are the data structures, SAIDs are the identifiers derived from and embedded within those structures. Every SAD contains exactly one SAID at its top level, though it may contain nested SADs with their own SAIDs.

Diger (Digest Primitive)

Digers are CESR primitives representing cryptographic digests. SAIDs are a specialized form of Diger with the additional property of self-referentiality. While a Diger can represent any hash value, a SAID specifically represents a hash that is embedded within the data it hashes.

ACDC (Authentic Chained Data Container)

ACDCs are the primary application of SADs in the KERI ecosystem. Every ACDC is a SAD, with its top-level d field containing the credential's SAID. ACDCs leverage SADs' properties to enable:

• Compact credential representations
• Graduated disclosure of attributes
• Verifiable credential chaining
• Schema immutability guarantees

Composition Patterns

Nested SADs: ACDCs contain multiple nested SADs:

• Top-level credential SAD
• Attribute section SAD
• Edge section SAD
• Rule section SAD

Each nested SAD has its own SAID, and the parent SAD's SAID is computed over the serialization that includes the child SAIDs. This creates a Merkle tree-like structure where the root SAID commits to all nested content.

SAID References: SADs can reference other SADs by including their SAIDs as field values. This creates directed acyclic graphs (DAGs) of verifiable data, where each node is a SAD and edges are SAID references.

Compact/Full Variants: The same logical SAD can be represented in multiple forms:

• Fully Compact: All nested sections represented by SAIDs only
• Partially Expanded: Some sections expanded, others as SAIDs
• Fully Expanded: All sections expanded with full content

All variants have the same top-level SAID, enabling cryptographic equivalence across representations.

Implementation Considerations

Canonicalization Requirements

SAD implementations must ensure deterministic serialization:

Field Ordering: JSON objects must maintain insertion order, not lexicographic order. Modern JSON libraries (Python 3.7+, JavaScript ES2015+) preserve insertion order by default.

Whitespace: Canonical form uses compact JSON with no unnecessary whitespace. Pretty-printed JSON for human readability must be compacted before SAID computation.

Unicode Normalization: String values should use consistent Unicode normalization (typically NFC) to prevent equivalent strings from producing different hashes.

Numeric Representation: Numbers should use consistent precision and formatting (no trailing zeros, consistent exponential notation).

Placeholder Mechanics

The placeholder string must:

• Match the exact length of the final SAID (44 characters for Blake3-256 text encoding)
• Use a character that doesn't appear in Base64 URL-safe encoding (typically #)
• Occupy the same field position as the final SAID

Example placeholder for Blake3-256:

{
  "d": "############################################"
}

Performance Optimization

Incremental Hashing: For large data structures, use streaming hash APIs to avoid loading entire structures into memory.

Caching: Cache computed SAIDs to avoid redundant computation, especially for frequently accessed credentials or schemas.

Parallel Verification: When verifying multiple SADs (e.g., a credential chain), parallelize verification operations since each SAD can be verified independently.

Security Considerations

Hash Algorithm Selection: Use Blake3-256 as default for new implementations. Support multiple algorithms for backward compatibility and future transitions.

SAID Length Validation: Always validate that SAID length matches the expected length for the indicated algorithm to prevent truncation attacks.

Derivation Code Verification: Verify the derivation code is supported before attempting verification to prevent processing with incorrect algorithms.

Replay Protection: SAIDs alone don't prevent replay attacks. Combine with timestamps, nonces, or sequence numbers in higher-level protocols.

Interoperability

CESR Compliance: Ensure SAID encoding follows CESR specifications exactly, including correct derivation codes and Base64 URL-safe encoding.

Schema Validation: When implementing ACDC SADs, validate against JSON Schema to ensure structural correctness before SAID computation.

Cross-Implementation Testing: Test SAID computation and verification across different implementations (Python, Rust, TypeScript) to ensure consistent canonicalization.

Advanced Topics

SAD Path Language

KERI defines a SAD Path Language for referencing nested SADs within larger structures. Paths use - as separator and support both field labels and integer indices:

• - : Root SAD
• -a : Attribute section
• -a-personal : Personal subsection within attributes
• -e-qvi-n : SAID reference in edge section

This enables precise references to nested SADs for selective disclosure and verification.

Transposable Signatures

CESR Proof Signatures can be attached to SADs and transposed across envelope boundaries. The signature remains valid because it's computed over the SAD's canonical form, which is invariant regardless of how the SAD is embedded or transmitted.

Blinded SADs

Private ACDCs use UUIDs (high-entropy nonces) as "salty nonces" to prevent rainbow table attacks on compact SAIDs. The UUID is included in SAID computation, making it computationally infeasible to determine the content of a compact ACDC from its SAID alone.

SAID-Based Merkle Trees

ACDCs form Merkle tree-like structures where:

• Leaf nodes are primitive values
• Internal nodes are nested SADs
• Root is the top-level credential SAID

This enables efficient proof-of-inclusion for specific attributes without revealing the entire credential structure.

Streaming Hashing: For large data structures, use streaming hash APIs (e.g., hashlib incremental hashing in Python) to avoid memory overhead.

Parallel Verification: When verifying credential chains or multiple credentials, parallelize verification since each SAD is independent.

Security Considerations

Length Validation: Always validate SAID length matches expected length for the algorithm (44 chars for 256-bit, 88 chars for 512-bit in text domain).

Truncation Prevention: Reject SAIDs that are shorter than expected length to prevent truncation attacks.

Algorithm Deprecation: Plan for algorithm transitions. Support multiple algorithms but mark deprecated algorithms in documentation.

Common Pitfalls

Lexicographic Sorting: Do NOT sort JSON object keys alphabetically. This breaks SAID verification.

Pretty Printing: Do NOT compute SAIDs over pretty-printed JSON. Always compact before hashing.

String Encoding: Ensure consistent UTF-8 encoding. Avoid platform-specific encodings (e.g., UTF-16 on Windows).

Floating Point: Use consistent numeric precision. Avoid floating-point representation issues by using integer or string representations for precise values.

Testing Requirements

Cross-Implementation Testing: Test SAID computation and verification across different language implementations to ensure consistent canonicalization.

Round-Trip Testing: Verify that SADs can be serialized, deserialized, and re-verified without SAID changes.

Edge Cases: Test with empty objects, deeply nested structures, Unicode characters, large numbers, and special characters.

Library Recommendations

Python: Use keripy library which provides Saider class for SAID operations. Alternatively, use blake3 library directly with json module.

Rust: Use cesrox library which provides SAID primitives with CESR encoding support.

TypeScript/JavaScript: Use signify-ts library which provides SAID generation and verification utilities.

Interoperability

CESR Compliance: Ensure SAID encoding strictly follows CESR specifications. Use official CESR libraries when possible.

Schema Validation: Validate data structures against JSON Schema before SAID computation to catch structural errors early.

Version Compatibility: Support multiple CESR versions and SAID algorithms to maintain backward compatibility with existing credentials and events.