A primitive in KERI is the serialization of a unitary cryptographic value (digest, salt, seed, private key, public key, or signature) that MUST be expressed in CESR (Composable Event Streaming Representation) format, serving as the atomic building block for all KERI cryptographic operations and data structures.
Related Concepts
No related concepts available
Comprehensive Explanation
primitive
Technical Definition
A primitive in the KERI/ACDC ecosystem represents the fundamental atomic unit of cryptographic data representation. Formally, a primitive is defined as the serialization of a unitary value associated with a cryptographic operation. This encompasses all cryptographic material including:
Digests (hashes): Cryptographic fingerprints of data
Salts: Random values for cryptographic operations
Seeds: Entropy sources for key generation (also called 'bran' in KERI)
Private keys: Secret cryptographic keys for signing
Public keys: Corresponding verification keys
Signatures: Digital signatures proving authenticity
The critical architectural requirement is that all primitives in KERI MUST be expressed in CESR (Composable Event Streaming Representation). This mandatory encoding ensures composability, self-framing properties, and interoperability across the KERI ecosystem.
Primitives serve as the smallest processing unit accessible to KERI protocol implementers, representing indivisible units of cryptographic data that cannot be further decomposed while maintaining their semantic meaning.
Cryptographic Properties
Qualified Representation
All KERI primitives are qualified, meaning they include a prepended derivation code (also called a proem) that indicates:
The cryptographic algorithm used for derivation
The cryptographic suite employed
The encoding format and domain (text or binary)
This qualification makes primitives - they carry their own type information, eliminating the need for external schemas or configuration to interpret the cryptographic material.
Implementation Notes
Implementation Guidance
Primitive Parsing
Implementations must support parsing primitives from CESR streams:
Read derivation code: Extract 1-4 characters to determine primitive type
Determine length: Use code table to calculate primitive length
Extract raw value: Read specified number of characters/bytes
Validation: Verify round-trip conversion produces identical result
Batch processing: Convert groups of primitives en masse for efficiency
Security Best Practices
Private Key Primitives:
Never log or transmit unencrypted private key primitives
Use secure memory (locked pages, zeroing on free)
Implement proper key lifecycle management
Support hardware security modules (HSMs) for key storage
Entropy Generation:
Use cryptographically secure random number generators
Validate entropy sources meet 128-bit minimum
Implement proper seed/salt generation for key derivation
Protect against entropy exhaustion attacks
Signature Verification:
Always verify derivation codes match expected algorithms
Validate signature lengths against algorithm specifications
Implement replay attack protection through event sequencing
Support threshold signature schemes for multi-sig scenarios
Performance Optimization
:
self-describing
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:
Derivation Code: Prepended type indicator (1-4 characters in text domain)
Raw Value: The actual cryptographic material
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
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