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 self-describing - they carry their own type information, eliminating the need for external schemas or configuration to interpret the cryptographic material.

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.