Cryptographic Strength Requirements

KERI primitives must provide approximately 128 bits of cryptographic strength or entropy (nominally). This security threshold ensures:

• Resistance to brute-force attacks
• Collision resistance for hash functions
• Sufficient entropy for key generation
• Post-quantum security considerations through pre-rotation mechanisms

Supported Cryptographic Algorithms

KERI supports multiple cryptographic suites through its primitive system:

Key Material:

• Ed25519: Elliptic curve signing (32-byte keys)
• ECDSA secp256k1: Bitcoin-compatible signing
• Ed448: Higher-security elliptic curve
• X25519: Elliptic curve encryption

Digest Algorithms:

• Blake3-256/512: Modern high-performance hashing
• Blake2b-256/512: Predecessor to Blake3
• Blake2s-256: Optimized for smaller architectures
• SHA3-256/512: NIST-standardized Keccak
• SHA2-256/512: Traditional SHA-2 family

Signature Schemes:

• Ed25519 signatures: 64-byte signatures
• ECDSA secp256k1 signatures: Variable-length
• Ed448 signatures: Higher-security variant

Data Format & Encoding

CESR Encoding Structure

Primitives in CESR follow a strict encoding structure that enables self-framing - each primitive contains sufficient information to determine its own boundaries within a stream. The encoding consists of:

1. Derivation Code: Prepended type indicator (1-4 characters in text domain)
2. Raw Value: The actual cryptographic material
3. Alignment Padding: Pre-padding or post-padding to achieve 24-bit boundary alignment

Text Domain Representation

In the text domain, primitives are encoded using Base64 URL-safe characters (A-Z, a-z, 0-9, -, _). The encoding ensures:

• Human readability: Text can be inspected and debugged
• URL safety: Can be transmitted in URLs without escaping
• Fixed-length encoding: Primitives align on 4-character boundaries (24 bits)

Example text domain primitive:

BF5pxRJP6THrUtlDdhh07hJEDKrJxkcR9m5u1xs33bhp

Where B is the derivation code for Ed25519 non-transferable prefix public verification key.

Binary Domain Representation

In the binary domain, primitives are encoded as raw bytes with:

• Compact representation: Minimal overhead for transmission
• 3-byte alignment: Primitives align on 24-bit boundaries
• Efficient parsing: Self-framing enables stream processing

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 encoding)
• 8 bits (byte encoding)

This alignment ensures that conversion between text and binary domains does not create bit-level dependencies between adjacent primitives, maintaining separability.

Pre-Padding vs. Post-Padding

CESR uses pre-padding (leading pad bytes) rather than trailing = pad characters:

• Pre-padding: Adds leading zero bytes to raw binary before Base64 conversion
• Advantage: Eliminates trailing = characters, enabling cleaner concatenation
• Calculation: ps = (3 - (N mod 3)) mod 3 where N is raw binary length

Derivation Codes

Derivation codes serve as compact type indicators:

• Single character codes: Most common primitives (e.g., B for Ed25519 public key)
• Multi-character codes: Extended primitive types (e.g., 1AAA for ECDSA secp256k1)
• Self-describing: Code indicates algorithm, key size, and usage

Usage in KERI/ACDC

Key Event Log (KEL) Construction

Primitives are the fundamental building blocks of KELs:

• AID prefixes: Self-certifying identifier prefixes are primitives
• Public keys: Current and next key sets are primitive arrays
• Signatures: Event signatures are attached as primitives
• Digests: Event chaining uses digest primitives
• Seals: Data anchoring uses digest primitives as seals

Establishment Events

In inception events and rotation events:

• Current keys (k field): Array of public key primitives
• Next key digests (n field): Array of digest primitives (ndigs)
• Signatures: Attached as indexed signature primitives (sigers)
• Witness identifiers: Array of AID primitives

Interaction Events

In interaction events:

• Seal digests: Primitives anchoring external data
• Signatures: Proving controller authorization

ACDC Credentials

In ACDCs:

• SAIDs: Self-addressing identifiers as digest primitives
• Issuer AID: Primitive identifying credential issuer
• Signatures: CESR proof signatures as primitive attachments
• Schema SAIDs: Digest primitives referencing schemas

Witness Receipts

Witness receipts use primitives for:

• Witness signatures: Indexed signature primitives
• Event references: Digest primitives pointing to witnessed events
• Witness AIDs: Identifier primitives for witness identity

OOBI Discovery

Out-Of-Band Introductions transmit primitives:

• AID primitives: Identifier being introduced
• Endpoint URLs: Encoded as variable-length text primitives
• Witness AIDs: Primitives identifying witnesses

Related Primitives

Primitive Type Hierarchy

KERI defines several specialized primitive types:

Diger: Represents a digest with verification capability

• Can verify that input hashes to its raw value
• Used for content addressing and integrity checking

Verfer: Represents a public key

• Can verify signatures on data
• Used for signature verification operations

Signer: Represents a private key

• Can create Sigers (indexed signatures)
• Can create Cigars (non-indexed signatures)

Siger: Indexed signature primitive

• Includes index indicating which key signed
• Used in multi-signature scenarios

Cigar: Non-indexed signature primitive

• Simple signature without index
• Used in single-signature scenarios

Salter: Represents a seed

• Can generate new Signers
• Used for hierarchical key derivation

Composition Patterns

Primitives can be composed through:

Concatenation: Joining primitives end-to-end

• Maintains separability through self-framing
• Enables stream processing

Group Codes: Framing multiple primitives

• Count codes specify number of primitives in group
• Enables hierarchical composition

Hierarchical Composition: Nested primitive structures

• Groups can contain other groups
• Enables complex data structures

Cryptonym Relationship

A cryptonym is a specialized type of primitive:

• Cryptographically derived from random/pseudo-random seed or salt
• Uses one-way cryptographic function
• Provides 128+ bits of cryptographic strength
• Functions as universally unique identifier
• Only controller of secret can prove control

Implementation Considerations

Parsing Requirements

Implementers must handle:

• Self-framing detection: Reading derivation codes to determine primitive boundaries
• Domain conversion: Transforming between text and binary representations
• Alignment validation: Ensuring 24-bit boundary compliance
• Code table management: Supporting multiple CESR code table versions

Stream Processing

Primitives enable efficient stream processing:

• Pipelining: Parallel processing of primitive streams
• Multiplexing: Combining multiple primitive streams
• Cold start parsing: Beginning stream processing without prior context

Composability Guarantees

Implementations must preserve:

• Round-trip conversion: Text → Binary → Text produces identical result
• Primitive separability: Individual primitives remain extractable after group conversion
• Lossless transformation: No information loss during domain conversion

Security Considerations

Key Management: Primitives representing private keys require:

• Secure storage (encrypted at rest)
• Protected memory handling
• Secure deletion (crypto-shredding)

Entropy Requirements: Seed and salt primitives need:

• Cryptographically secure random number generation (CSPRNG)
• Sufficient entropy (128+ bits)
• Protection against rainbow table attacks

Signature Verification: Signature primitives require:

• Correct public key association
• Proper algorithm selection based on derivation code
• Replay attack protection through event sequencing

Performance Optimization

Primitive processing can be optimized through:

• Batch conversion: Converting groups of primitives en masse
• Parallel verification: Verifying multiple signatures concurrently
• Caching: Storing parsed primitives to avoid re-parsing
• Stream buffering: Efficient I/O for primitive streams

Extensibility

The primitive system supports future extensions:

• New cryptographic algorithms: Adding derivation codes for new algorithms
• Variable-length primitives: Supporting primitives of arbitrary size
• Custom primitive types: Domain-specific primitive definitions
• Backward compatibility: New primitives coexist with existing ones

This extensibility ensures KERI can adapt to evolving cryptographic standards while maintaining compatibility with existing implementations.

• Implement buffered I/O for primitive streams
• Use parallel processing for signature verification
• Cache parsed primitives to avoid redundant parsing
• Optimize Base64 encoding/decoding with SIMD instructions

Memory Management:

• Pre-allocate buffers for known primitive sizes
• Reuse buffers for repeated conversions
• Implement zero-copy parsing where possible
• Use memory pools for frequent allocations

Testing Requirements

Implementations should include tests for:

• Round-trip conversion: Text → Binary → Text identity
• Alignment validation: 24-bit boundary compliance
• Code table coverage: All supported primitive types
• Edge cases: Zero-length, maximum-length primitives
• Interoperability: Cross-implementation compatibility
• Security: Proper handling of malformed primitives

Library Integration

When integrating CESR primitive libraries:

• Use official implementations (keripy, cesrox, cesride) as reference
• Validate interoperability with other KERI implementations
• Support all mandatory primitive types from CESR specification
• Implement optional primitive types based on use case requirements
• Maintain backward compatibility with older CESR versions

Error Handling

Implementations must handle:

• Invalid derivation codes: Unknown or malformed codes
• Alignment errors: Primitives not on 24-bit boundaries
• Length mismatches: Declared vs. actual primitive length
• Encoding errors: Invalid Base64 characters
• Cryptographic failures: Signature verification failures, hash mismatches

Provide clear error messages indicating:

• Primitive type and position in stream
• Expected vs. actual values
• Suggested remediation steps