• Simplifies the representation by embedding algorithm information directly
• Compactifies essential information needed to use the primitive
• Eliminates ambiguity about which cryptographic operations were applied

Qualification is described as an essential property of CESR, making it foundational to KERI's encoding scheme.

Cryptographic Properties

Algorithm Agility

CESR's derivation code system provides cryptographic agility by supporting multiple algorithm families through standardized prefixes. Document 4 details how CESR code tables organize primitives by:

• Algorithm type (Ed25519, ECDSA secp256k1, Ed448, Blake3, SHA3, etc.)
• Key material type (signing keys, encryption keys, seeds)
• Digest algorithm (Blake3-256, Blake2b-256, SHA3-256, SHA2-256, etc.)
• Signature type (Ed25519, ECDSA, Ed448)

Security Properties

According to Document 2, cryptographic primitives in KERI must exhibit cryptographic strength - greater resistance to attack compared to weaker alternatives. The ACDC specification (Document 68) mandates that cryptographic operations MUST provide approximately 128 bits of cryptographic strength or entropy (nominally).

Document 22 establishes that hash functions with 128 bits of cryptographic strength remain quantum-resistant:

• Blake2-256 or greater
• Blake3-256 or greater
• SHA3-256 or greater
• SHA2-512

These hash functions maintain their security properties even in a post-quantum computing environment because quantum computers provide no advantage for collision search operations.

Key and Output Sizes

CESR primitives are organized by raw binary size in code tables (Document 9):

Small Fixed Raw Size (common primitives):

• 32-byte keys (Ed25519 public keys, X25519 keys)
• 32-byte digests (Blake3-256, SHA3-256)
• 64-byte signatures (Ed25519)

Large Fixed Raw Size (extended primitives):

• 48-byte keys (Ed448)
• 64-byte digests (Blake3-512, SHA3-512)
• 114-byte signatures (Ed448)

Variable Size (for arbitrary-length data):

• Encoded with count codes indicating length
• Support for extensible cryptographic material

Data Format & Encoding

CESR Encoding Architecture

CESR provides a dual text-binary encoding format (Document 5) that operates across three domains:

1. Text (T) Domain: Uses URL-safe Base64 characters [A-Z, a-z, 0-9, -, _] encoding 6 bits per character
2. Binary (B) Domain: Raw bytes (8 bits each) for compact transmission
3. Raw (R) Domain: Represented as tuple (code, raw) where cryptographic operations occur

24-Bit Alignment Constraint

The composability property requires all primitives to align on 24-bit boundaries - the least common multiple of 6 bits (Base64 character) and 8 bits (byte). This constraint means:

• Text domain primitives must be integer multiples of 4 Base64 characters (24 bits)
• Binary domain primitives must be integer multiples of 3 bytes (24 bits)
• This alignment ensures no bits from adjacent primitives share the same character/byte after domain conversion

Derivation Codes

As explained in Document 27, a derivation code is prepended to the Base-64 encoding of cryptographic material. For example:

• Original Base64 key: F5pxRJP6THrUtlDdhh07hJEDKrJxkcR9m5u1xs33bhp=
• With derivation code B: BF5pxRJP6THrUtlDdhh07hJEDKrJxkcR9m5u1xs33bhp

The derivation code replaces the pad character, embedding crucial cryptographic context directly into the identifier.

Pre-Padding Approach

Unlike naive Base64 that uses trailing = pad characters, CESR uses leading pad bytes ("lead bytes") prepended to raw binary values before Base64 conversion (Document 9). The pad size calculation is:

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

Where ps is pad size and N is the raw binary length in bytes. This pre-padding ensures 24-bit alignment without requiring trailing pad characters in the text representation.

Self-Framing Property

CESR primitives are self-framing (Document 29), meaning they include type, size, and value information in a single atomic encoding. This enables:

• Delimiter-free parsing: No special characters needed to separate primitives
• Stream composability: Multiple primitive types can be mixed in a single stream
• Efficient processing: Parsers know exactly how many characters to read for each primitive

Usage in KERI/ACDC

Key Event Logs (KELs)

Cryptographic primitives are fundamental to KEL structure (Document 3):

Inception Events use primitives for:

• AID prefix: Self-certifying identifier derived from initial public key(s)
• Current signing keys: Public keys in the k field
• Next key digests: Pre-rotated key commitments in the n field
• Witness identifiers: AIDs of designated witnesses

Rotation Events use primitives for:

• Previous event digest: Hash linking to prior event in the p field
• New signing keys: Rotated public keys in the k field
• Next key digests: New pre-rotation commitments in the n field
• Event signatures: Attached as CESR-encoded signature primitives

Interaction Events use primitives for:

• Seal digests: Cryptographic commitments to external data
• Event signatures: Non-establishment event signatures

ACDC Credentials

Document 68 describes how ACDCs use cryptographic primitives:

SAIDs (Self-Addressing Identifiers):

• The d field contains a CESR-encoded digest primitive
• Computed over the entire ACDC structure
• Provides content-addressable integrity

Issuer AIDs:

• The i field contains a CESR-encoded AID primitive
• Identifies the credential issuer
• Enables verification against the issuer's KEL

Signatures:

• Attached as CESR-encoded signature primitives
• May be indexed (for multi-sig) or non-indexed
• Cryptographically bind the issuer to the credential content

Witness Receipts

Witnesses provide signed receipts using cryptographic primitives (Document 71):

• Receipt messages (rct) reference the event digest
• Witness signatures are attached as CESR primitives with -CAB prefix
• Dual signatures from multiple witnesses provide redundant validation

Verification Procedures

Verification of cryptographic primitives follows a standard pattern:

1. Extract the derivation code from the qualified primitive
2. Identify the algorithm from CESR code tables
3. Parse the raw cryptographic material according to the code's length specification
4. Apply the appropriate verification algorithm (signature verification, hash comparison, etc.)
5. Validate against the current key state (for signatures) or expected digest (for hashes)

Related Primitives

Cesride Primitive Classes

The cesride implementation (Document 23) defines six core primitive classes:

Diger (Document 172):

• Represents a cryptographic digest
• Has the ability to verify that input hashes to its raw value
• Used for content addressing and integrity verification

Verfer (Document 175):

• Represents a public key
• Has the ability to verify signatures on data
• Used for signature verification in KELs and ACDCs

Signer (Document 176):

• Represents a private key
• Has the ability to create Sigers (indexed signatures) and Cigars (non-indexed signatures)
• Used for signing key events and credentials

Siger (Document 47):

• Represents an indexed signature
• Includes index information for multi-signature scenarios
• Used when signing with multi-key AIDs

Cigar (Document 48):

• Represents an un-indexed signature
• Used for single-signature scenarios
• Simpler structure than indexed signatures

Salter (Document 174):

• Represents a seed
• Has the ability to generate new Signers
• Used for deterministic key derivation

Common Method Interface

All cesride primitives share a common method interface (Document 118):

• .qb64(): Qualified base-64 representation as a string
• .qb64b(): Qualified base-64 representation as bytes
• .qb2(): Qualified base-2 representation as bytes
• .code(): Derivation code indicating cryptographic type
• .raw(): Raw cryptographic material without qualification

Composition Patterns

Cryptographic primitives compose in several ways:

Concatenation (Document 145):

• Multiple primitives can be concatenated in streams
• Self-framing enables de-concatenation without delimiters
• Composability ensures lossless domain conversion

Group Codes (Document 154):

• Special framing codes support groups of primitives
• Enable pipelining for efficient stream processing
• Support hierarchical compositions

Indexed Signatures (Document 149):

• Combine signature primitive with index value
• Enable multi-signature verification
• Support threshold signature schemes

• Recommended digests: Blake3-256, Blake2b-256, SHA3-256
• Recommended signatures: Ed25519, Ed448
• Avoid: MD5, SHA1, weak RSA key sizes

Post-quantum considerations favor hash-based commitments over signature schemes vulnerable to Shor's algorithm.

Error Handling

Implementations must handle:

• Unknown derivation codes: Reject or skip primitives with unrecognized codes
• Length mismatches: Verify extracted length matches code table specification
• Alignment violations: Detect and reject primitives not on 24-bit boundaries
• Cryptographic failures: Properly propagate signature verification failures

Performance Considerations

CESR's design enables efficient stream processing:

• Pipelining: Group codes enable parallel processing of primitive groups
• Zero-copy parsing: Self-framing allows in-place parsing without buffering
• Domain selection: Use binary domain for transmission, text domain for debugging

Interoperability Testing

Implementations should verify:

• Round-trip conversion between text and binary domains
• Compatibility with reference implementations (KERIpy, KERIox)
• Correct handling of all supported primitive types
• Proper concatenation and de-concatenation of primitive streams