A prefix is a qualified cryptographic primitive in CESR format that combines a derivation code with an encoded public key or digest, serving as the self-certifying identifier for an AID in KERI. The prefix cryptographically binds the identifier to its controlling key material through one-way functions, enabling self-certification without external trust.
Related Concepts
No related concepts available
Comprehensive Explanation
prefix
Structure Definition
A prefix in KERI is a composite data structure that serves as the fundamental identifier for an Autonomic Identifier (AID). The prefix combines two essential components into a single self-describing string:
Derivation Code: A leading character or character sequence that specifies the cryptographic algorithm suite used to derive the identifier
Encoded Key Material: A Base64 URL-safe encoding of the public key or cryptographic digest
The canonical example from the source documents illustrates this structure:
BDKrJxkcR9m5u1xs33F5pxRJP6T7hJEbhpHrUtlDdhh0
In this 44-character prefix:
First character (B): Single-character derivation code indicating Ed25519 non-transferable prefix
Remaining 43 characters: Base64 encoding of a 32-byte Ed25519 public key
The prefix structure implements KERI's principle of self-certification - the identifier itself contains sufficient information to cryptographically verify control authority without requiring external lookups or trusted third parties. This design eliminates the need for certificate authorities or centralized registries that plague traditional PKI systems.
Cryptographic Binding Mechanism
The derivation code serves multiple critical functions:
Algorithm Specification: Identifies which cryptographic suite (key type, signature algorithm, hashing algorithm) was used
Length Indication: Implicitly specifies the expected length of the encoded key material
Type Discrimination: Enables parsers to distinguish between different identifier types (basic, self-addressing, delegated, etc.)
Composability: Supports CESR's text-binary composability by providing self-framing information
Implementation Notes
Critical Implementation Considerations
Derivation Code Selection
Choosing the appropriate derivation code is critical:
Non-transferable vs. Transferable: Use basic codes (e.g., 'B') for ephemeral identifiers that don't need key rotation. Use self-addressing codes (e.g., 'E') for persistent identifiers requiring rotation capability.
Algorithm Selection: Ed25519 ('B', 'D') provides excellent performance and security for most use cases. ECDSA secp256k1 ('1AAA', '1AAB') may be required for blockchain interoperability. Ed448 ('1AAC', '1AAD') offers higher security margins.
Multi-sig Requirements: Self-addressing prefixes ('E', 'F', etc.) are required for multi-signature configurations, as the prefix must be derived from a digest that includes all participant keys and thresholds.
Entropy Management
The source documents emphasize that the bran (seed) is the root secret:
Generate using cryptographically secure random number generators
Minimum 128 bits of entropy (256 bits recommended)
Store encrypted with strong passcode
Backup securely - loss of bran means loss of identifier control
Never transmit bran over networks
Keystore Architecture
Implementations should follow the KERIpy pattern:
Separate keystores per AID: Each identifier has isolated encrypted storage
Deterministic derivation: Same bran + aeid always produces same keys
Hierarchical organization: Use Habery to manage multiple Habs (keystores)
Encrypted at rest: All private key material encrypted with passcode
Witness Configuration
When creating prefixes with witnesses:
Minimum 3 witnesses recommended for production
TOAD = N - F where N is total witnesses and F is maximum tolerable faults
Geographic distribution: Spread witnesses across jurisdictions/providers
Witness rotation: Plan for witness changes through establishment events
Prefix Validation
Implement comprehensive validation:
def validate_prefix(prefix: str) -> bool:
# Check length is multiple of 4 (24-bit alignment)
if len(prefix) % 4 != 0:
return False
# Validate Base64 URL-safe character set
valid_chars = set('ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_')
if not all(c in valid_chars for c in prefix):
return False
# Parse derivation code and verify length
code = prefix[0] # Simplified - may be multi-char
expected_length = DERIVATION_CODE_LENGTHS.get(code)
if expected_length and len(prefix) != expected_length:
return False
return True
The binding between derivation code and key material is immutable - any modification to either component produces a completely different prefix, making tampering immediately evident.
Prefix Types and Derivation Patterns
KERI supports multiple prefix derivation patterns, each serving different use cases:
Basic Self-Certifying Prefix: Directly encodes the public key with a derivation code. The identifier is literally the encoded public key, making verification straightforward - extract the key from the prefix and verify signatures.
Self-Addressing Prefix: Uses a cryptographic digest of the inception event data rather than the raw public key. This approach:
Binds the identifier to the complete inception configuration (keys, thresholds, witnesses)
Enables more complex identifier types (multi-sig, delegated)
Provides stronger integrity guarantees through content-addressing
Multi-Sig Self-Addressing Prefix: Derives from a digest that includes multiple public keys and threshold specifications, enabling group control.
Delegated Self-Addressing Prefix: Includes cryptographic commitment to a delegating identifier, creating hierarchical trust structures.
Data Format
Encoding Specifications
Prefixes use Base64 URL-safe encoding (RFC 4648) exclusively, which provides:
Character set: [A-Z, a-z, 0-9, -, _] (64 characters)
URL compatibility: No special characters requiring escaping
Filename safety: Can be used in filesystem paths
6-bit encoding: Each character represents 6 bits of information
Critical constraint: CESR requires 24-bit alignment for composability. All prefixes must be integer multiples of 4 Base64 characters (24 bits = 4 × 6 bits). This alignment enables lossless round-trip conversion between text and binary domains.
Derivation Code Tables
The derivation code determines the prefix structure. From the CESR specification, common codes include:
Multi-character codes (for larger key sizes or specialized types):
1AAA: ECDSA secp256k1 non-transferable prefix
1AAC: Ed448 non-transferable prefix
Each code specifies:
Raw size: Byte length of the underlying cryptographic material
Pad size: Number of leading pad bytes needed for 24-bit alignment
Total length: Final character count in text domain
Field Constraints
Prefixes must satisfy multiple constraints:
Length determinism: Given a derivation code, the total length is fixed and predictable
Character validity: All characters must be in the Base64 URL-safe alphabet
Alignment: Total length must be divisible by 4 (24-bit boundary)
Uniqueness: Collision resistance of underlying cryptographic functions ensures global uniqueness
Immutability: Once generated, a prefix never changes (though control can be rotated)
Operations
Creation and Initialization
Prefix generation follows a deterministic process:
Step 1: Entropy Generation
Generate high-entropy random seed (typically 128+ bits)
Use cryptographically secure random number generator (CSPRNG)
Seed serves as root secret for key derivation
Step 2: Key Pair Derivation
Apply key derivation function to seed
Generate public-private key pair using specified algorithm
For hierarchical deterministic keys, use derivation paths
Step 3: Prefix Construction
Select appropriate derivation code for identifier type
For basic prefixes: Encode public key in Base64
For self-addressing prefixes: Construct inception event, compute digest, encode digest
Prepend derivation code to encoded material
Step 4: Validation
Verify total length matches expected value for derivation code
Confirm 24-bit alignment
Validate Base64 character set compliance
The source documents emphasize that the bran (seed) combined with the keystore's aeid (authentication encryption identifier) deterministically generates all key-pairs. This means identical inputs always produce identical prefixes, enabling key recovery from seed backup.
Verification and Validation
Prefix verification involves multiple layers:
Structural Validation:
Parse derivation code from first character(s)
Verify total length matches code specification
Validate Base64 character set
Confirm 24-bit alignment
Cryptographic Validation:
Extract key material by decoding Base64
For basic prefixes: Use extracted public key directly
For self-addressing prefixes: Recompute digest from inception event and compare
Verify signatures using extracted/derived public key
Check for duplicity by comparing with witness receipts
The source documents note that for self-addressing identifiers, both the d (SAID) and i (identifier) fields in the inception event must contain identical values after derivation, creating a self-referential integrity check.
Updates and Modifications
Critical principle: Prefixes are immutable identifiers. They never change once created. However, the control authority over a prefix can change through key rotation.
Key Rotation Process:
Controller signs rotation event with current authoritative keys
Rotation event includes digest of new public keys (pre-rotation)
Event is appended to KEL
Prefix remains unchanged; key state updates
Subsequent operations use new keys
This separation between identifier (prefix) and key state is fundamental to KERI's architecture. The prefix provides stable identity while keys can be rotated for security.
Delegation Operations:
Delegated prefixes include cryptographic commitment to delegator
Delegation can be revoked by delegator through interaction events
Prefix itself remains constant; delegation status changes
Usage Context
Protocol Integration
Prefixes appear throughout KERI protocol messages:
In Key Events:
i field: Identifier prefix of the AID
di field: Delegator prefix (for delegated identifiers)
CESR composability enables streaming without framing overhead
Implementation Patterns
Source documents reveal several implementation patterns:
Keystore Organization:
Each AID has dedicated keystore ("Hab" in KERIpy)
Keystore encrypted with passcode
Salt + aeid deterministically generates keys
Multiple AIDs managed by "Habery"
Witness Configuration:
Prefixes include witness list in inception
Witnesses identified by their prefixes
TOAD (Threshold of Accountable Duplicity) specifies minimum witnesses
Witness rotation supported through establishment events
Multi-Signature Groups:
Group prefix derived from all participant prefixes
Threshold specified in inception (e.g., "2-of-3")
Each participant signs with their individual keys
Indexed signatures identify which participant signed
Delegation Hierarchies:
Root prefix has no delegator
Delegated prefix includes di field
Recursive delegation creates trees
Each level maintains independent KEL
The source documents emphasize that prefixes are the atomic unit of identity in KERI - all other structures (KELs, credentials, registries) reference and depend on prefixes as their foundation.
Performance Optimization
Cache key state: Avoid replaying KEL for every verification
Batch signature verification: Verify multiple signatures together when possible