Comprehensive Explanation

key

Technical Definition

Within the KERI (Key Event Receipt Infrastructure) protocol and broader cryptographic identity systems, a key refers to cryptographic material that serves as the foundation for establishing and maintaining control authority over autonomic identifiers (AIDs). Keys exist in two complementary forms:

• Private keys: Secret cryptographic material held exclusively by the controller, used to generate digital signatures that prove control authority
• Public keys: Corresponding verification material that can be openly shared, used to verify signatures created by the associated private key

In KERI's architecture, keys are not merely cryptographic primitives but are qualified cryptographic primitives - meaning they are always encoded with metadata (derivation codes) that specify the cryptographic algorithm, key type, and derivation method. This qualification is essential for KERI's composability and interoperability properties.

Keys serve multiple critical functions in KERI:

1. Control Authority Establishment: Keys cryptographically bind controllers to their AIDs through self-certifying identifier derivation
2. Event Signing: Private keys sign key events (inception, rotation, interaction) to create non-repudiable commitments
3. Verification: Public keys enable validators to verify the authenticity of signed events
4. Pre-rotation Security: Cryptographic digests of next keys provide forward security through pre-rotation commitments

Cryptographic Properties

Asymmetric Key Pair Foundation

KERI keys are based on asymmetric cryptography (public-key cryptography), where key pairs are generated through one-way mathematical functions:

Seed → Private Key → One-Way Function → Public Key

The security model relies on the computational infeasibility of deriving the private key from the public key, even though the public key is mathematically derived from the private key.

Supported Cryptographic Algorithms

KERI supports multiple cryptographic suites to enable cryptographic agility:

Ed25519 (Edwards-curve Digital Signature Algorithm):

• Key size: 32 bytes (256 bits) for both private and public keys
• Signature size: 64 bytes (512 bits)
• Security level: ~128 bits of security
• Properties: Fast signature generation and verification, deterministic signatures
• CESR derivation codes: B (non-transferable prefix), D (public verification key)

ECDSA secp256k1 (Elliptic Curve Digital Signature Algorithm):

• Key size: 32 bytes private key, 33 bytes compressed public key
• Signature size: Variable (typically 64-72 bytes)
• Security level: ~128 bits of security
• Properties: Bitcoin-compatible, widely supported
• CESR derivation codes: 1AAA (non-transferable prefix), 1AAB (public key)

Ed448 (Edwards-curve with 448-bit keys):

• Key size: 57 bytes for both private and public keys
• Signature size: 114 bytes
• Security level: ~224 bits of security
• Properties: Higher security margin, post-quantum resistant properties
• CESR derivation codes: 1AAC (non-transferable prefix), 1AAD (public key)

X25519 (Curve25519 for key exchange):

• Key size: 32 bytes
• Purpose: Encryption and key agreement (not signing)
• CESR derivation code: C (public encryption key), O (private decryption key)

Cryptographic Strength Requirements

The GLEIF vLEI Ecosystem Governance Framework establishes that all key pairs MUST provide approximately 128 bits of cryptographic strength. This requirement ensures:

• Resistance to brute-force attacks with current computational capabilities
• Sufficient security margin for long-lived identifiers
• Compliance with industry-standard security recommendations

Key Generation Process

KERI key generation follows a deterministic, entropy-based process:

1. Entropy Collection: High-quality random entropy is collected (minimum 128 bits)
2. Seed Derivation: Entropy is processed into a cryptographic seed (called bran in KERI)
3. Key Stretching: The seed undergoes key stretching (e.g., Argon2) to derive private keys
4. Hierarchical Derivation: Multiple keys can be derived from a single seed using hierarchical deterministic algorithms
5. Public Key Derivation: Public keys are mathematically derived from private keys

Data Format & Encoding

CESR Encoding

All keys in KERI MUST be encoded using CESR (Composable Event Streaming Representation), which provides:

• Self-describing format: Each key includes metadata about its type and algorithm
• Domain flexibility: Keys can be represented in both text (Base64) and binary domains
• Composability: Keys can be concatenated and parsed without external schema

Qualified Base64 Representation

KERI keys use qualified Base64 encoding where the key is prepended with a derivation code:

<derivation_code><base64_encoded_key>

Example Ed25519 public key:

DKxy2sgzfplyr-tgwIxS19f2OchFHtLwPWD3v4oYimBx

Breakdown:

• D: Derivation code indicating Ed25519 public verification key
• Kxy2sgzfplyr-tgwIxS19f2OchFHtLwPWD3v4oYimBx: Base64-encoded 32-byte public key

Derivation Codes

Derivation codes are compact indicators (1-4 characters) that specify:

• Cryptographic algorithm: Which signature scheme (Ed25519, ECDSA, etc.)
• Key type: Public key, private key, seed, etc.
• Key purpose: Signing, encryption, rotation, etc.

Common derivation codes for keys:

• A: Ed25519 seed (private key seed)
• B: Ed25519 non-transferable prefix (public key)
• C: X25519 public encryption key
• D: Ed25519 public verification key
• J: ECDSA secp256k1 seed
• O: X25519 private decryption key
• 1AAA: ECDSA secp256k1 non-transferable prefix
• 1AAB: ECDSA secp256k1 public key
• 1AAC: Ed448 non-transferable prefix
• 1AAD: Ed448 public key

Binary Encoding

In binary domain, CESR uses compact binary codes:

• Derivation code is encoded as binary prefix
• Key material follows in raw binary format
• Total size is optimized for streaming efficiency

Key State Representation

In KERI events, keys appear in specific fields:

Current Keys (k field):

"k": [
  "DKxy2sgzfplyr-tgwIxS19f2OchFHtLwPWD3v4oYimBx",
  "DFBTlnGd2gwTwMZTHIHUMmPxydvvXyXTOICWncIVS0oL"
]

Next Key Digests (n field - pre-rotated keys):

"n": [
  "EIFG_uqfr1yN560LoHYHfvPAhxQ5sN6xZZT_E3h7d2tL"
]

Note that next keys are represented as cryptographic digests (Blake3-256 hashes) rather than the actual public keys, providing forward security.

Usage in KERI/ACDC

Inception Events

Keys are first introduced in inception events that create an AID:

• Current signing keys (k field): Public keys authorized to sign events
• Next key digests (n field): Cryptographic commitments to pre-rotated keys
• Signing threshold (kt field): Number of signatures required from current keys
• Next threshold (nt field): Threshold for next key set

The inception event establishes the initial key state and is signed by the current private key(s).

Rotation Events

Keys change through rotation events:

• Expose pre-rotated keys: Next keys from previous event become current keys
• Commit to new next keys: New pre-rotated key digests are specified
• Dual threshold validation: Event must satisfy both prior next threshold and current threshold
• Partial rotation support: Subset of pre-rotated keys can be exposed while keeping others in reserve

Interaction Events

Keys are used to sign interaction events (non-establishment events):

• Events are signed by current authoritative keys
• No key state changes occur
• Signatures prove controller authorization of the event

Multi-Signature Scenarios

For multi-sig AIDs:

• Multiple keys are listed in the k field
• Threshold (kt) specifies minimum signatures required
• Indexed signatures associate each signature with its corresponding key
• Weighted thresholds enable fractional signing requirements

Witness Signatures

Witnesses use their own keys to sign receipts:

• Witness keys are separate from controller keys
• Witness signatures are indexed to identify which witness signed
• Witness key state is managed through their own KELs

Custodial Key Management

KERI supports split key authority:

• Signing authority: Custodial agent holds keys for day-to-day signing
• Rotation authority: Original controller retains keys for rotation
• Implemented through partial rotation and threshold configuration

Key Compromise Recovery

KERI's pre-rotation mechanism enables recovery:

1. Detection: Duplicity detection identifies compromised key usage
2. Rotation: Controller rotates to pre-committed next keys
3. Recovery: New key state supersedes compromised state
4. Verification: Validators can verify the recovery through KEL

Related Primitives

Key Pairs

Keys exist as asymmetric key pairs:

• Private key and public key are mathematically related
• Generated together through cryptographic algorithms
• Private key must be kept secret; public key can be shared

Seeds and Salts

Seeds (also called bran in KERI):

• High-entropy input for key generation
• Enables deterministic key derivation
• Must be protected with same security as private keys

Salts:

• Random values used in key derivation
• Prevent rainbow table attacks
• Used in key stretching algorithms

Digests

Keys are often represented as cryptographic digests:

• Next key digests: Blake3-256 hashes of pre-rotated public keys
• Provide forward security through cryptographic hiding
• Enable pre-rotation without exposing future keys

Signatures

Keys are used to create and verify digital signatures:

• Private keys generate signatures
• Public keys verify signatures
• Signatures prove control authority and non-repudiation

Verfers and Signers

In KERI implementations:

• Verfer: Primitive representing a public key with verification capability
• Signer: Primitive representing a private key with signing capability
• Salter: Primitive representing a seed for key generation

Key Management Best Practices

One-Time Use Principle

KERI advocates for "one-time, one-place, one-way" key usage:

• Minimize key exposure through limited use
• Rotate keys proactively rather than reactively
• Use different keys for different purposes when possible

Key Storage Security

Private keys should be protected through:

• Hardware Security Modules (HSMs): Dedicated cryptographic hardware
• Trusted Execution Environments (TEEs): Secure processor enclaves
• Encrypted keystores: Software-based encrypted storage
• Multi-factor authentication: Additional protection layers

Key Rotation Strategies

Proactive rotation:

• Regular scheduled rotations reduce exposure windows
• Pre-rotation enables quantum-resistant key management
• Rotation frequency can adapt to threat landscape

Reactive rotation:

• Immediate rotation upon suspected compromise
• Recovery through pre-committed next keys
• Duplicity detection enables compromise identification

Hierarchical Key Management

KERI supports multi-valent key management:

• Root keys with highest security
• Delegated keys for operational use
• Nested delegation trees for organizational structures
• Each level can have different security/performance trade-offs

Security Considerations

Key Compromise Scenarios

Live attack (current key compromise):

• Attacker gains access to current signing keys
• Can sign malicious events until rotation occurs
• Pre-rotation enables recovery without cooperation

Dead attack (past key compromise):

• Attacker gains access to previously rotated keys
• Cannot affect current key state due to pre-rotation
• Historical events remain valid and verifiable

Post-Quantum Security

KERI's pre-rotation provides post-quantum resistance:

• Next keys are hidden through one-way hash functions
• Even quantum computers cannot reverse hash functions efficiently
• Rotation frequency can adapt to quantum computing advances

Key Exposure Minimization

Strategies to minimize key exposure:

• Edge signing: Keep private keys on client devices, not cloud servers
• Custodial rotation: Separate signing authority from rotation authority
• Witness isolation: Witnesses use separate keys from controllers
• Ephemeral keys: Use [non-transferable](/concept/non-transferable "A property indicating that control authority over a digital identifier or asset ...") identifiers for temporary purposes