Type Classification

Seals are classified as cryptographic commitment primitives within KERI's architecture. They represent a specific application of hash functions to create tamper-evident bindings between events and data. Seals are not standalone primitives but rather structured data elements that appear within key events, encoded according to CESR conventions.

Cryptographic Properties

Underlying Algorithms

Seals leverage cryptographic hash functions that provide approximately 128 bits of cryptographic strength. The KERI specification supports multiple hash algorithms, with the specific algorithm indicated by a derivation code prepended to the digest:

• Blake3-256: Modern, high-performance hash function (default in many implementations)
• SHA-256: Widely supported standard hash function
• SHA3-256: NIST-standardized Keccak-based hash function

For Merkle tree roots, the seal represents the root hash of a tree structure where:

• Leaf nodes contain hashes of individual data items
• Internal nodes contain hashes of their child nodes
• The root hash cryptographically commits to all data in the tree

Security Properties

Seals inherit the security properties of their underlying hash functions:

Collision Resistance: It is computationally infeasible to find two different inputs that produce the same seal digest. This ensures that each unique data item has a unique seal.

Pre-image Resistance: Given a seal digest, it is computationally infeasible to determine the original data that was sealed. This provides privacy protection for sealed data until it is explicitly disclosed.

Second Pre-image Resistance: Given a data item and its seal, it is computationally infeasible to find a different data item that produces the same seal.

Binding Property: Once a seal is included in a signed event, the controller has made a non-repudiable cryptographic commitment to the sealed data. The seal cannot be changed without invalidating the event signature.

Immutability: The payload of a seal becomes immutable once the containing event is signed. Any modification to the sealed data will produce a different digest, breaking the cryptographic binding.

Key/Output Sizes

Seal digests are typically 256 bits (32 bytes) in their raw binary form, matching the output size of the underlying hash functions. When encoded in CESR text format, seals include:

• Derivation code: 1-2 characters indicating the hash algorithm
• Base64-encoded digest: 43-44 characters for 256-bit hashes
• Total CESR text length: Approximately 44-46 characters

For example, a Blake3-256 seal in CESR format:

ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM

Where:

• E is the derivation code for Blake3-256
• LvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM is the Base64-encoded digest

Data Format & Encoding

CESR Encoding Format

Seals are encoded as CESR primitives, which means they are self-framing and composable. The CESR encoding ensures that seals can be:

• Parsed unambiguously from concatenated streams
• Converted between text and binary domains without loss
• Verified independently without external schema information

Seal Structure in Events

Seals appear in key events as structured data elements, typically in one of two forms:

Event Source Seal (for anchoring to other KEL events):

{
  "s": "3",
  "d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM"
}

Where:

• s: Sequence number of the sealed event
• d: Digest (seal) of the sealed event

Data Seal (for anchoring arbitrary data):

{
  "d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM"
}

Where:

• d: Digest (seal) of the sealed data

Text and Binary Representations

Text Domain: Seals in the text domain use Base64 URL-safe encoding with prepended derivation codes. This format is human-readable and suitable for JSON serialization:

ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM

Binary Domain: Seals in the binary domain use raw bytes with binary-encoded derivation codes. This format is compact and efficient for transmission:

0x12 0x2e 0xb5 0x3a 0x67 ... (32 bytes total)

Raw Domain: The raw domain represents the seal as a tuple of derivation code and raw digest bytes, used internally for cryptographic operations:

("E", b"\x2e\xb5\x3a\x67...")

Derivation Codes

Common derivation codes for seals include:

• E: Blake3-256 digest (44 characters in Base64)
• F: Blake2b-256 digest (44 characters in Base64)
• G: Blake2s-256 digest (44 characters in Base64)
• H: SHA3-256 digest (44 characters in Base64)
• I: SHA2-256 digest (44 characters in Base64)

The derivation code is essential for:

• Identifying the hash algorithm used
• Enabling cryptographic agility (supporting multiple algorithms)
• Ensuring correct verification procedures

Usage in KERI/ACDC

In Establishment Events

Seals appear in establishment events (inception and rotation) to anchor critical data:

Delegated Inception: The delegator's rotation or interaction event includes a seal of the delegate's inception event:

{
  "v": "KERI10JSON00011c_",
  "t": "ixn",
  "d": "EZ-i0d8JZLvaU6JR2nmwyYAZAoTNZH3UfSVPzhzS6b5C",
  "i": "EaU6JR2nmwyYAZAoTNZH3UfSVPzhzS6b5CLvaU6Z-i0d8",
  "s": "3",
  "p": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "a": [
    {
      "i": "EJJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CLvaU6Z-i0d8",
      "s": "0",
      "d": "EoTNZH3UfSVPzhzS6b5CLvaU6Z-i0d8JJR2nmwyYAZA"
    }
  ]
}

The seal in the a (anchors) field commits the delegator to the delegate's inception event.

In Interaction Events

Seals are the primary payload of interaction events, which exist specifically to anchor data without changing key state:

Service Endpoint Anchoring:

{
  "v": "KERI10JSON00011c_",
  "t": "ixn",
  "d": "EZ-i0d8JZLvaU6JR2nmwyYAZAoTNZH3UfSVPzhzS6b5C",
  "i": "EaU6JR2nmwyYAZAoTNZH3UfSVPzhzS6b5CLvaU6Z-i0d8",
  "s": "4",
  "p": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "a": [
    {
      "d": "EJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CLvaU6Z-i0d8J"
    }
  ]
}

The seal in the a field commits to a service endpoint configuration document stored externally.

In TEL Events

Transaction Event Logs use seals to anchor back to their controlling KEL:

TEL Inception with KEL Anchor:

{
  "v": "KERI10JSON00011c_",
  "t": "vcp",
  "d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "i": "EaU6JR2nmwyYAZAoTNZH3UfSVPzhzS6b5CLvaU6Z-i0d8",
  "s": "0",
  "bt": "0",
  "b": ["BaU6JR2nmwyYAZAoTNZH3UfSVPzhzS6b5CLvaU6Z-i0d8"],
  "c": ["NB"]
}

The TEL event is anchored to the KEL through a seal in a KEL interaction event, creating a cryptographic link between the secondary root-of-trust (TEL) and primary root-of-trust (KEL).

In ACDC Credentials

ACDCs use seals extensively for credential issuance and chaining:

Credential Issuance Seal: The issuer's KEL includes an interaction event with a seal of the credential's SAID:

{
  "v": "KERI10JSON00011c_",
  "t": "ixn",
  "d": "EZ-i0d8JZLvaU6JR2nmwyYAZAoTNZH3UfSVPzhzS6b5C",
  "i": "EaU6JR2nmwyYAZAoTNZH3UfSVPzhzS6b5CLvaU6Z-i0d8",
  "s": "5",
  "p": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "a": [
    {
      "d": "EBkPreYpZfFk66jpf3uFv7vklXKhzBrAqjsKAn2EDIPM"
    }
  ]
}

This seal commits the issuer to the credential, enabling verification that the credential was issued by the claimed issuer at a specific point in the KEL.

Credential Chaining: ACDCs can reference other ACDCs through seals in their edge section:

{
  "v": "ACDC10JSON00011c_",
  "d": "EBkPreYpZfFk66jpf3uFv7vklXKhzBrAqjsKAn2EDIPM",
  "i": "EaU6JR2nmwyYAZAoTNZH3UfSVPzhzS6b5CLvaU6Z-i0d8",
  "s": "ED6jrVPTzlSkUPqGGeIZ8a8FWS7a6s4reAXRZOkogZ2A",
  "a": {...},
  "e": {
    "d": "EFH3dCdoFOLe71iheqcywJcnjtJtQIYPvAu6DZIl3MOA",
    "parent": {
      "n": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM"
    }
  }
}

The seal in the edge section (n field) references the parent credential's SAID, creating a verifiable chain of credentials.

Common Usage Patterns

Pattern 1: Data Anchoring

1. Controller creates or receives data to be anchored
2. Controller computes digest of the data
3. Controller creates interaction event with seal of the digest
4. Controller signs and publishes the event
5. Verifiers can later verify the data matches the seal

Pattern 2: Delegation Authorization

1. Delegate creates inception event
2. Delegator computes digest of delegate's inception event
3. Delegator creates interaction/rotation event with seal
4. Delegator signs and publishes the event
5. Verifiers can verify the delegation relationship

Pattern 3: Credential Issuance

1. Issuer creates ACDC credential
2. Issuer computes SAID of the credential
3. Issuer creates interaction event with seal of the SAID
4. Issuer signs and publishes the event
5. Issuer provides credential to holder
6. Verifiers can verify credential issuance through the seal

Verification Procedures

Verifying a seal involves several steps:

Step 1: Extract the Seal Parse the event to extract the seal structure, including the derivation code and digest.

Step 2: Obtain the Sealed Data Retrieve the data that was allegedly sealed. This may come from:

• The event itself (for self-referential seals)
• External storage (for data anchoring)
• Another event stream (for event source seals)

Step 3: Compute the Digest Using the hash algorithm indicated by the derivation code, compute the digest of the sealed data.

Step 4: Compare Digests Compare the computed digest with the seal digest. If they match, the seal is valid.

Step 5: Verify Event Signature Verify that the event containing the seal is properly signed by the controller's authoritative keys at the time of the event.

Step 6: Verify Event Ordering Verify that the event is properly ordered in the KEL and that all prior events are valid.

Only when all steps succeed can the seal be considered verified, establishing that:

• The controller committed to the sealed data
• The commitment was made at a specific point in the KEL
• The sealed data has not been tampered with

Related Primitives

SAID (Self-Addressing Identifier)

Seals and SAIDs are closely related:

• Both use cryptographic digests for content commitment
• SAIDs are self-referential (the digest includes itself)
• Seals reference external data (the digest is separate from the data)
• SAIDs are used for ACDC identifiers; seals anchor ACDCs to KELs

Digest Primitives

Seals are a specific application of general digest primitives:

• Seals always appear in the context of key events
• Digests may appear in other contexts (e.g., next key digests in pre-rotation)
• Seals create commitments; digests may serve other purposes

Event Source Seals vs. Data Seals

Event Source Seals reference other events:

• Include sequence number and digest
• Used for delegation and TEL anchoring
• Enable verification of event relationships

Data Seals reference arbitrary data:

• Include only the digest
• Used for service endpoints, credentials, and general data anchoring
• Enable verification of data authenticity

Composition Patterns

Seal Arrays: Events can contain multiple seals in an array:

"a": [
  {"d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM"},
  {"d": "EJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CLvaU6Z-i0d8J"},
  {"d": "EoTNZH3UfSVPzhzS6b5CLvaU6Z-i0d8JJR2nmwyYAZA"}
]

This enables a single event to commit to multiple data items simultaneously.

Nested Seals: Seals can reference data that itself contains seals, creating hierarchical commitment structures. This is fundamental to ACDC chaining and delegation trees.

Merkle Tree Seals: When sealing a large dataset, a Merkle tree can be constructed with the root hash serving as the seal. This enables efficient verification of individual items within the dataset without revealing the entire dataset.

Implementation Considerations

Performance

Seal computation is computationally efficient:

• Blake3-256 hashing: ~3 GB/s on modern CPUs
• SHA-256 hashing: ~500 MB/s on modern CPUs
• Verification overhead is minimal compared to signature verification

Storage

Seals are compact:

• 32 bytes in binary format
• ~44 characters in CESR text format
• Minimal storage overhead for anchoring large datasets

Privacy

Seals provide privacy protection:

• Sealed data is not revealed until explicitly disclosed
• Pre-image resistance prevents data recovery from seals
• Selective disclosure is enabled by sealing individual attributes

Interoperability

Seals support multiple hash algorithms:

• Implementations must support algorithm indicated by derivation code
• Cryptographic agility enables algorithm upgrades
• CESR encoding ensures cross-platform compatibility

Error Handling

Implementations must handle:

• Invalid derivation codes
• Mismatched digest lengths
• Missing sealed data
• Hash algorithm unavailability

Security Considerations

Hash Algorithm Selection: Use algorithms with at least 128 bits of security strength. Blake3-256 and SHA-256 are recommended.

Seal Verification: Always verify seals before trusting sealed data. Never assume a seal is valid without verification.

Data Availability: Ensure sealed data is available when needed for verification. Seals are useless if the sealed data cannot be retrieved.

Timing Attacks: Be aware that seal verification timing may leak information about the sealed data. Use constant-time comparison when necessary.

Collision Attacks: While collision attacks on modern hash functions are impractical, implementations should monitor for advances in cryptanalysis and be prepared to migrate to stronger algorithms if needed.

Cryptographic Agility

Support multiple hash algorithms:

• Algorithm Registry: Maintain a registry of supported hash algorithms and their derivation codes.
• Algorithm Selection: Allow configuration of preferred hash algorithm for seal creation.
• Algorithm Verification: Support verification of seals using any registered algorithm.
• Algorithm Migration: Plan for migration to stronger algorithms if current algorithms are weakened.

Performance Optimization

• Batch Hashing: When creating multiple seals, batch hash operations for efficiency.
• Caching: Cache computed digests to avoid redundant computation during verification.
• Parallel Verification: Verify multiple seals in parallel when possible.
• Hardware Acceleration: Use hardware-accelerated hash functions when available (e.g., SHA-NI for SHA-256).

Testing

• Test Vector Validation: Verify implementation against known test vectors for each supported hash algorithm.
• Cross-Implementation Testing: Test seal creation and verification across different KERI implementations.
• Edge Case Testing: Test handling of invalid derivation codes, mismatched digest lengths, and missing data.
• Performance Testing: Measure seal creation and verification performance under realistic workloads.