Comprehensive Explanation

framing-code

Technical Definition

A framing code (also called frame-code, FRAME-CODE, derivation code, or count code) is a fundamental component of CESR (Composable Event Streaming Representation) that provides self-describing type and length information for cryptographic primitives and data structures in KERI streams. Framing codes enable self-framing - the property where each encoded element contains sufficient metadata to determine its own boundaries without requiring external schemas, delimiters, or context.

Formally, a framing code is a prefix attached to encoded data that specifies:

1. Type information: What kind of primitive or structure follows (e.g., Ed25519 public key, Blake3-256 digest, signature, count of grouped primitives)
2. Size information: The exact length of the value portion in the current domain (text or binary)
3. Encoding metadata: Implicitly, the pad size needed for 24-bit boundary alignment

Framing codes are the mechanism that makes CESR streams composable - enabling lossless round-trip conversion between text and binary domains while maintaining the ability to parse individual primitives from concatenated streams.

Purpose in KERI/ACDC

Framing codes serve multiple critical functions in the KERI ecosystem:

Stream Parsing: Enable parsers to process CESR streams without prior knowledge of content structure. By reading the framing code, a parser immediately knows the primitive type and can extract exactly the right number of characters/bytes.

Composability: Support the fundamental CESR property that T(cat(b[k])) = cat(T(b[k])) - the transformation of concatenated primitives equals the concatenation of individually transformed primitives. This requires that primitive boundaries align on 24-bit boundaries, which framing codes ensure.

Self-Description: Make cryptographic material self-describing by embedding algorithm information directly in the encoding. A verifier receiving a CESR-encoded signature knows which algorithm to use for verification without external configuration.

Pipelining: Enable efficient stream processing where multiple primitives can be multiplexed into complex streams and de-multiplexed back without ambiguity, supporting high-bandwidth applications.

Type Classification

Framing codes fall into several categories:

Basic Primitive Codes: Single-character or multi-character codes for fixed-size cryptographic primitives (keys, digests, signatures). Example: B indicates an Ed25519 non-transferable prefix public key (44 characters in text domain).

Variable-Length Codes: Codes that include explicit length information for variable-size data. Example: 4B## where ## represents two Base64 characters encoding the length in quadlets.

Count Codes (also called group framing codes): Special codes that specify the number of primitives in a group, enabling hierarchical composition. Example: -AAB indicates an event source seal triple attachment.

Version Codes: Special count codes that specify which CESR code table version is active for a stream section.

Cryptographic Properties

Framing codes themselves are not cryptographic primitives - they are metadata that describes cryptographic primitives. However, they have critical security properties:

Algorithm Specification

Framing codes cryptographically bind the algorithm specification to the encoded material. When a primitive is encoded with derivation code E, this creates an immutable association with the Blake3-256 algorithm. Any attempt to interpret the material with a different algorithm will fail verification.

Integrity Through Self-Description

The self-describing nature of framing codes prevents certain classes of attacks:

Algorithm Substitution: An attacker cannot substitute a weaker algorithm because the framing code explicitly specifies which algorithm was used.

Length Manipulation: The framing code's length specification prevents buffer overflow attacks or truncation attacks by precisely defining boundaries.

Type Confusion: Different primitive types have distinct framing codes, preventing type confusion vulnerabilities where one primitive type is misinterpreted as another.

No Direct Cryptographic Operations

Framing codes do not perform cryptographic operations themselves - they describe the operations that were performed. The actual cryptographic strength comes from the algorithms they reference (Ed25519, Blake3-256, etc.) and the key material they frame.

Data Format & Encoding

CESR Encoding Structure

A CESR-encoded primitive with framing code follows this structure:

[Framing Code][Value]

Where:

• Framing Code: 1-4 characters in text domain, variable bytes in binary domain
• Value: Base64-encoded (text) or raw bytes (binary) of the cryptographic material

Text Domain Representation

In the text domain, framing codes use Base64 URL-safe characters (A-Z, a-z, 0-9, -, _). The code length varies:

1-character codes: For small fixed-size primitives with pad size 1

• Example: B for Ed25519 public key
• Total length: 44 characters (1 code + 43 value)

2-character codes: For primitives with pad size 0 or 2, or for special purposes

• Example: 0B for Ed25519 signature
• Total length: 88 characters (2 code + 86 value)

4-character codes: For large fixed-size primitives

• Example: 1AAA for ECDSA secp256k1 public key
• Total length: 48 characters (4 code + 44 value)

Variable-length codes: Include length information

• Example: 4BAA for a 0-length byte string (code indicates lead size 0)
• Example: 5AABAA-A for a 2-character string with lead size 1

Binary Domain Representation

In the binary domain, framing codes are more compact:

1-byte codes: Most common primitives

• First 2 bits: Selector (00, 01, 10, 11)
• Remaining 6 bits: Type within selector

2-byte codes: Extended primitive set

• First byte: Selector indicating 2-byte code
• Second byte: Type specification

Multi-byte codes: For count codes and variable-length primitives

• Include explicit length fields encoded in binary

24-bit Alignment Constraint

All CESR primitives must align on 24-bit boundaries because:

• Base64 encodes 6 bits per character (4 characters = 24 bits)
• Binary bytes encode 8 bits each (3 bytes = 24 bits)
• 24 is the least common multiple of 6 and 8

Framing codes achieve this through pre-padding (lead bytes) before Base64 conversion. The pad size calculation is:

ps = (3 - (N mod 3)) mod 3

Where ps is pad size and N is raw binary length in bytes.

Derivation Code Examples

Common framing codes in KERI:

Keys:

• B: Ed25519 non-transferable prefix (44 chars)
• D: Ed25519 public key (44 chars)
• 1AAA: ECDSA secp256k1 non-transferable prefix (48 chars)

Digests:

• E: Blake3-256 (44 chars)
• F: Blake2b-256 (44 chars)
• H: SHA3-256 (44 chars)
• 0D: Blake3-512 (88 chars)

Signatures:

• 0B: Ed25519 signature (88 chars)
• 0C: ECDSA secp256k1 signature (88 chars)

Count Codes:

• -AAB: Event source seal triple
• -CAB: Witness signature couple
• 5AAA: Version string count code

Usage in KERI/ACDC

In Key Event Logs (KELs)

Framing codes appear throughout KEL structures:

Inception Events: The i field contains an AID with a framing code indicating the key type. Example: BHt9Kw8oUgfB2kiyoj65B2VE5fZLr87S5MJP3l4JeRwC uses code B for Ed25519.

Rotation Events: The k field (current keys) and n field (next key digests) use framing codes. The n field typically uses digest codes like E for Blake3-256 digests of pre-rotated keys.

Signatures: All event signatures are attached with framing codes. The -AAB count code indicates a signature attachment follows, with the actual signature using code 0B for Ed25519.

Event Digests: The d field (SAID) uses digest framing codes to indicate the hash algorithm used for the event's self-addressing identifier.

In ACDC Credentials

Framing codes enable ACDC features:

Compact Disclosure: ACDCs can be compacted by replacing field values with their SAIDs. The SAID's framing code indicates the digest algorithm, enabling verification when the full value is later disclosed.

Issuer Identification: The i field (issuer AID) uses framing codes to specify the issuer's key type.

Schema References: The s field can contain a SAID with framing code indicating the schema's digest algorithm.

Chaining: The e field (edges) contains SAIDs of other ACDCs, with framing codes enabling verification of the chain.

In CESR Streams

Framing codes enable stream processing:

Cold Start Parsing: When a parser encounters a CESR stream after reboot, it reads the first framing code to determine how to parse the first primitive, then continues sequentially.

Interleaved Serialization: Special count codes mark boundaries between CESR and other formats (JSON, CBOR, MGPK), enabling mixed-format streams.

Hierarchical Composition: Group framing codes enable nested structures where groups of primitives are treated as higher-level primitives.

Verification Procedures

Verifying CESR-encoded primitives:

1. Extract framing code: Read the first 1-4 characters/bytes
2. Lookup code table: Determine primitive type and length
3. Extract value: Read the specified number of characters/bytes
4. Decode: Convert from Base64 (text) or use raw bytes (binary)
5. Verify: Apply the algorithm specified by the framing code

For signatures:

1. Extract signature with framing code (e.g., 0B for Ed25519)
2. Extract public key with framing code (e.g., D for Ed25519 key)
3. Verify signature matches algorithm specified by both codes
4. Confirm signature validates the message

Related Primitives

Count Codes (Group Framing Codes)

Count codes are specialized framing codes that specify the number of primitives in a group rather than framing a single primitive. They enable:

• Pipelining: Multiplexing multiple primitives into streams
• Hierarchical composition: Nesting groups within groups
• Efficient parsing: Knowing how many primitives to expect

Example: -AAB indicates a couple (2 primitives) follows, specifically an event source seal triple format.

Derivation Codes

The term derivation code is often used interchangeably with framing code, particularly when referring to codes that specify cryptographic algorithms. The "derivation" refers to how the primitive was derived (which algorithm was used).

Version Codes

Version codes are special count codes that specify which CESR code table version is active. They enable:

• Protocol evolution: Supporting multiple CESR versions
• Backward compatibility: Parsers can switch tables based on version
• Forward compatibility: New codes can be added without breaking old parsers

Qualified Primitives

All CESR primitives are qualified by definition - they include a framing code (proem) that qualifies the primitive with algorithm information. This qualification is what makes CESR primitives self-describing.

Implementation Considerations

Code Table Management

Implementations must maintain code tables mapping framing codes to:

• Primitive types
• Lengths in text and binary domains
• Pad sizes for alignment
• Cryptographic algorithms

The CESR specification defines multiple code tables:

• Small fixed raw size table
• Large fixed raw size table
• Variable length table
• Count code table

Parsing Strategy

Efficient CESR parsing:

1. Read first character: Determines which code table to use
2. Read full code: May be 1-4 characters depending on first character
3. Lookup length: Determine how many characters/bytes to extract
4. Extract value: Read the specified length
5. Continue: Move to next primitive

This enables streaming parsing where primitives are processed as they arrive without buffering entire messages.

Error Handling

Framing codes enable robust error detection:

Unknown codes: If a code is not in the table, the primitive is invalid Length mismatches: If the stream ends before the specified length, it's truncated Alignment errors: If primitives don't align on 24-bit boundaries, the encoding is invalid

Performance Optimization

Framing codes enable optimizations:

Zero-copy parsing: In binary domain, primitives can be referenced in place without copying Parallel processing: Independent primitives can be processed concurrently Incremental verification: Signatures can be verified as they arrive without buffering

Advanced Topics

Composability Property

Framing codes are essential to CESR's composability property. The formal requirement:

T(cat(b[k])) = cat(T(b[k])) for all k
B(cat(t[k])) = cat(B(t[k])) for all k

This means:

• Converting concatenated binary primitives to text produces the same result as converting each individually then concatenating
• The same holds for text to binary conversion

Framing codes enable this by ensuring primitive boundaries align on 24-bit boundaries, preventing bit-level dependencies between adjacent primitives.

Self-Framing vs. External Framing

Traditional encodings use external framing:

• JSON uses {} and , delimiters
• Protocol Buffers use length prefixes
• XML uses opening/closing tags

CESR uses self-framing via framing codes:

• No external delimiters needed
• Each primitive is independently parseable
• Concatenation preserves parseability

This enables CESR's unique combination of human-readable text encoding and efficient binary encoding with full round-trip composability.

Sniffable Streams

Framing codes make CESR streams sniffable - a parser can automatically detect:

• Whether the stream is text or binary domain
• Which CESR version is in use
• Where CESR ends and other formats (JSON, CBOR) begin

This is achieved through careful code design where the first few bits/characters unambiguously identify the format and version.