Comprehensive Explanation

derivation-code

Technical Definition

A derivation code is a prepended metadata indicator in KERI's Composable Event Streaming Representation (CESR) that encodes the cryptographic algorithm, key type, digest function, or signature scheme used to generate a cryptographic primitive. This code transforms raw cryptographic material into a qualified primitive that is self-describing and independently verifiable.

Formal Definition

Formally, a derivation code is a fixed-length character sequence (in text domain) or byte sequence (in binary domain) that:

1. Identifies the cryptographic suite: Specifies which algorithm family (Ed25519, ECDSA secp256k1, Blake3-256, etc.) was used
2. Determines primitive length: Implicitly defines the expected length of the following cryptographic material
3. Enables self-framing: Allows parsers to extract primitives atomically from concatenated streams
4. Preserves composability: Maintains 24-bit boundary alignment for lossless text-binary domain conversion

Purpose in KERI/ACDC

Derivation codes solve a fundamental problem in cryptographic systems: how to know which algorithm was used to generate a piece of cryptographic material. When a verifier receives a public key, signature, or digest, they must know:

• Which cryptographic algorithm to apply for verification
• What key size or output length to expect
• How to interpret the raw bytes

Traditional systems solve this through:

• External schemas (requiring out-of-band coordination)
• Protocol negotiation (adding complexity and round-trips)
• Fixed algorithm assumptions (preventing cryptographic agility)

KERI's derivation codes embed this information directly in the identifier or primitive itself, creating truly portable, self-contained cryptographic objects.

Type Classification

Derivation codes are classified into three primary categories in CESR:

1. Basic Material Primitives: Fixed-size cryptographic material (keys, digests, salts)
2. Indexed Signature Primitives: Signatures with index information for multi-sig scenarios
3. Count/Group Codes: Framing codes that indicate groups of primitives for pipelining

Cryptographic Properties

Algorithm Specification

Derivation codes do not perform cryptographic operations themselves—they are metadata indicators that specify which algorithms were used. Common derivation codes include:

Public Key Algorithms:

• B: Ed25519 non-transferable prefix public verification key (44 characters)
• D: Ed25519 public verification key (44 characters)
• 1AAA: ECDSA secp256k1 non-transferable prefix (48 characters)
• 1AAC: Ed448 non-transferable prefix (80 characters)

Digest Algorithms:

• E: Blake3-256 digest (44 characters)
• F: Blake2b-256 digest (44 characters)
• H: SHA3-256 digest (44 characters)
• I: SHA2-256 digest (44 characters)
• 0D: Blake3-512 digest (88 characters)
• 0F: SHA3-512 digest (88 characters)

Signature Algorithms:

• 0B: Ed25519 signature (88 characters)
• 0C: ECDSA secp256k1 signature (88 characters)
• 1AAE: Ed448 signature (152 characters)

Security Properties

Derivation codes themselves provide no cryptographic security—they are plaintext metadata. However, they enable critical security properties:

Cryptographic Agility: Systems can support multiple algorithms simultaneously without breaking changes. New algorithms can be added by defining new derivation codes.

Algorithm Binding: The derivation code creates an immutable binding between the algorithm specification and the cryptographic material. Changing the code invalidates the primitive.

Verification Determinism: Verifiers can deterministically select the correct algorithm without ambiguity or negotiation.

Post-Quantum Readiness: New post-quantum algorithms can be integrated by defining new derivation codes without protocol changes.

Key/Output Sizes

Derivation codes implicitly encode the expected size of cryptographic material:

Single-character codes (e.g., B, E, F):

• Text domain: 44 characters total (1 code + 43 Base64 characters)
• Binary domain: 33 bytes total (1 code byte + 32 raw bytes)
• Pad size: 1 (one lead byte prepended before Base64 encoding)

Two-character codes (e.g., 0B, 0D, 0F):

• Text domain: 88 characters total (2 code + 86 Base64 characters)
• Binary domain: 66 bytes total (2 code bytes + 64 raw bytes)
• Pad size: 2 (two lead bytes prepended)

Four-character codes (e.g., 1AAA, 1AAC):

• Text domain: 48-152 characters depending on algorithm
• Binary domain: 36-114 bytes depending on algorithm
• Pad size: 0 (no padding needed, already 24-bit aligned)

The 24-bit alignment constraint is fundamental: all CESR primitives must be integer multiples of 4 Base64 characters (24 bits) in text domain and 3 bytes (24 bits) in binary domain. This ensures composability—the ability to convert concatenated primitives between domains without losing structure.

Data Format & Encoding

CESR Encoding Format

CESR encoding transforms raw cryptographic material into qualified primitives through a precise process:

Step 1: Determine Pad Size

Given raw material of N bytes, calculate pad size:

ps = (3 - (N mod 3)) mod 3

For a 32-byte Ed25519 public key:

ps = (3 - (32 mod 3)) mod 3 = (3 - 2) mod 3 = 1

Step 2: Prepend Lead Bytes

Prepend ps zero bytes to the raw material:

padded = [0x00] * ps + raw_bytes

For 32-byte key with ps=1:

padded = [0x00] + [32 bytes of key material] = 33 bytes

Step 3: Base64 Encode

Encode the padded bytes using Base64 URL-safe encoding:

encoded = base64_url_safe_encode(padded)

This produces 44 characters (33 bytes * 8 bits / 6 bits per Base64 char = 44).

Step 4: Replace Lead Characters with Derivation Code

The first ps Base64 characters result from the lead bytes and contain no information from the raw material. Replace these with the derivation code:

qualified = derivation_code + encoded[ps:]

For Ed25519 with code B:

qualified = 'B' + encoded[1:] = 'BF5pxRJP6THrUtlDdhh07hJEDKrJxkcR9m5u1xs33bhp'

Text and Binary Representations

Text Domain (T):

• Uses Base64 URL-safe characters: [A-Z, a-z, 0-9, -, _]
• Human-readable and debuggable
• Suitable for JSON, logs, QR codes, URLs
• Example: BF5pxRJP6THrUtlDdhh07hJEDKrJxkcR9m5u1xs33bhp

Binary Domain (B):

• Compact byte representation
• Efficient for network transmission and storage
• Derivation code encoded in first 1-2 bytes
• Example: [0x04, 0x17, 0xa7, ...] (33 bytes total)

Raw Domain (R):

• Unencoded cryptographic material
• Used by cryptographic libraries for operations
• Represented as tuple: (derivation_code, raw_bytes)
• Example: ('B', [0x17, 0xa7, 0x1c, ...]) (32 raw bytes)

Derivation Code Structure

Derivation codes follow specific structural patterns:

Single-character codes (most common):

• First character from Base64 alphabet
• Indicates algorithm and implies 44-character total length
• Examples: B, D, E, F, H, I

Two-character codes (larger primitives):

• First character is 0 (zero)
• Second character specifies algorithm
• Indicates 88-character total length
• Examples: 0B, 0D, 0E, 0F, 0G

Four-character codes (specialized algorithms):

• First character is 1 (one)
• Remaining three characters specify algorithm
• Variable total length depending on algorithm
• Examples: 1AAA, 1AAB, 1AAC, 1AAD, 1AAE

Usage in KERI/ACDC

In Event Types

Inception Events (icp):

Derivation codes appear in multiple fields:

{
  "v": "KERI10JSON000188_",
  "t": "icp",
  "d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "i": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "s": "0",
  "kt": "1",
  "k": ["DKrJxkcR9m5u1xs33F5pxRJP6T7hJEbhpHrUtlDdhh0"],
  "n": ["ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM"]
}

• d field: SAID with E derivation code (Blake3-256 digest)
• i field: AID prefix with E code (self-addressing identifier)
• k array: Current signing key with D code (Ed25519 public key)
• n array: Next key digest with E code (Blake3-256 of pre-rotated key)

Rotation Events (rot):

Similar structure with updated keys:

{
  "v": "KERI10JSON000190_",
  "t": "rot",
  "d": "EY6jnekRK0M3GzKd7N0xH6fMJk2EqPjLkEcvXqhJRkqw",
  "i": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "s": "1",
  "p": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "kt": "1",
  "k": ["DNewKeyMaterialAfterRotation123456789012345678"],
  "n": ["ENextKeyDigestForSubsequentRotation1234567890"]
}

• p field: Prior event digest with E code
• New k and n values with appropriate derivation codes

Interaction Events (ixn):

Minimal structure for anchoring:

{
  "v": "KERI10JSON000138_",
  "t": "ixn",
  "d": "EAnchoredDataDigest123456789012345678901234",
  "i": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
  "s": "2",
  "p": "EY6jnekRK0M3GzKd7N0xH6fMJk2EqPjLkEcvXqhJRkqw",
  "a": ["ESealedDataDigest1234567890123456789012345"]
}

• a array: Anchored data seals with E codes

Common Usage Patterns

Self-Certifying Identifiers:

The most fundamental usage is in AID prefixes:

BF5pxRJP6THrUtlDdhh07hJEDKrJxkcR9m5u1xs33bhp

Breakdown:

• B: Derivation code indicating Ed25519 non-transferable
• F5pxRJP6THrUtlDdhh07hJEDKrJxkcR9m5u1xs33bhp: Base64-encoded public key

Verification process:

1. Extract derivation code B
2. Determine algorithm: Ed25519
3. Extract remaining 43 characters as Base64-encoded key
4. Decode to recover 32-byte public key
5. Use Ed25519 verification algorithm for signatures

Self-Addressing Identifiers:

For self-addressing AIDs:

ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM

Breakdown:

• E: Derivation code indicating Blake3-256 digest
• LvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM: Base64-encoded digest

Verification process:

1. Extract derivation code E
2. Determine algorithm: Blake3-256
3. Extract inception event data
4. Replace i field with dummy characters
5. Compute Blake3-256 digest
6. Compare with identifier—must match

Witness Receipts:

Witness signatures use indexed signature codes:

-CAB
0BAAAAAAAAAAAAAAAAAAAAAA
BJq7UABlttINuWJh1Xl2lkqZG4NTdUdqnbFJDa6ZyxCC
0BSignatureBytes1234567890123456789012345678901234567890123456789012345678901234

Breakdown:

• -CAB: Count code indicating 2 indexed signatures follow
• 0B: Indexed signature derivation code (Ed25519)
• Index and signature data follow

Verification Procedures

Public Key Verification:

1. Extract derivation code: Read first 1-4 characters
2. Determine algorithm: Look up code in CESR table
3. Extract key material: Read remaining characters based on code
4. Decode Base64: Convert to raw bytes
5. Remove padding: Strip lead bytes if present
6. Verify signature: Use algorithm-specific verification

Digest Verification:

1. Extract derivation code: Identify hash algorithm
2. Prepare data: Serialize data structure canonically
3. Compute digest: Apply hash algorithm
4. Encode result: Apply CESR encoding with same code
5. Compare: Verify encoded digest matches original

SAID Verification:

1. Extract SAID: Read self-addressing field value
2. Replace with dummy: Substitute SAID with # characters
3. Serialize: Create canonical serialization
4. Compute digest: Apply algorithm from SAID's derivation code
5. Encode: Apply CESR encoding
6. Compare: Verify computed SAID matches original

Related Primitives

Cryptographic Material Primitives

Derivation codes qualify various types of cryptographic material:

Keys: Public keys (B, D, 1AAA), private keys (A, J), encryption keys (C, O)

Digests: Hash outputs (E, F, G, H, I, 0D, 0E, 0F, 0G)

Signatures: Signature values (0B, 0C, 1AAE)

Salts/Seeds: Random values (0A, A)

Indexed Signatures

For multi-signature scenarios, derivation codes include index information:

Siger (indexed signature): Combines signature with index indicating which key signed

Cigar (un-indexed signature): Signature without index for single-sig scenarios

Both use the same underlying derivation codes but with different framing.

Count Codes

Special derivation codes indicate groups of primitives:

-CAB: Count code for 2 indexed signatures -CAC: Count code for 3 indexed signatures -GAB: Group code for event source seals

These enable pipelined streaming where multiple primitives are processed as a unit.

Composition Patterns

Concatenated Streams:

Multiple qualified primitives can be concatenated:

BKey1234567890123456789012345678901234567890EDigest1234567890123456789012345678901234560BSignature123456789012345678901234567890123456789012345678901234567890123456789012

Parsing:

1. Read B → 44-character Ed25519 key follows
2. Read E → 44-character Blake3-256 digest follows
3. Read 0B → 88-character Ed25519 signature follows

Nested Structures:

ACDC credentials contain multiple qualified primitives:

{
  "v": "ACDC10JSON000197_",
  "d": "ECredentialSAID1234567890123456789012345",
  "i": "EIssuerAID123456789012345678901234567890",
  "s": "ESchemaID1234567890123456789012345678901",
  "a": {
    "d": "EAttributeBlockSAID123456789012345678901",
    "name": "Alice"
  }
}

Each d, i, s field contains a qualified primitive with derivation code.

Implementation Considerations

Code Table Management

Implementations must maintain code tables mapping derivation codes to:

• Algorithm specifications
• Expected primitive lengths
• Padding requirements
• Verification procedures

The CESR specification defines multiple code tables:

Small Fixed Raw Size Table: Single-character codes for 32-byte primitives Large Fixed Raw Size Table: Two-character codes for 64-byte primitives Variable Raw Size Tables: Four-character codes for variable-length primitives

Parsing Strategies

Cold Start Parsing:

When beginning to parse a CESR stream:

1. Read first character
2. Determine if it's a code table selector or primitive code
3. Look up code in appropriate table
4. Extract primitive of specified length
5. Continue with next primitive

Stream Processing:

For continuous streams:

1. Maintain parser state
2. Buffer incomplete primitives
3. Process complete primitives as they arrive
4. Handle group codes for batched processing

Error Handling

Unknown Codes:

If a derivation code is not recognized:

• Reject the primitive
• Do not attempt to parse further
• Return error indicating unknown code

Length Mismatches:

If primitive length doesn't match code specification:

• Reject the primitive
• Indicate truncation or corruption
• Do not attempt recovery

Invalid Base64:

If Base64 decoding fails:

• Reject the primitive
• Indicate encoding error
• Check for transmission corruption

Performance Optimization

Code Lookup:

Use hash tables or switch statements for O(1) code lookup:

CODE_TABLE = {
    'B': {'algorithm': 'Ed25519', 'length': 44, 'pad': 1},
    'E': {'algorithm': 'Blake3-256', 'length': 44, 'pad': 1},
    '0B': {'algorithm': 'Ed25519-Sig', 'length': 88, 'pad': 2},
    # ...
}

Batch Processing:

Process groups of primitives together when count codes indicate batches:

if code == '-CAB':  # 2 indexed signatures
    signatures = parse_batch(stream, count=2, type='indexed_sig')
    verify_batch(signatures)

Zero-Copy Parsing:

Where possible, avoid copying data:

# Instead of:
key_bytes = stream[1:44].decode('base64')

# Use views:
key_view = memoryview(stream)[1:44]

Cryptographic Agility

Derivation codes enable seamless algorithm upgrades:

Adding New Algorithms:

1. Define new derivation code
2. Specify primitive length and padding
3. Update code tables
4. Implement algorithm-specific operations
5. Deploy without breaking existing code

Deprecating Algorithms:

1. Mark code as deprecated in documentation
2. Continue supporting for verification
3. Prevent new issuance with deprecated codes
4. Eventually remove from code tables

Post-Quantum Transition:

When quantum computers threaten current algorithms:

1. Define new post-quantum derivation codes
2. Implement post-quantum algorithms
3. Rotate to new codes via KERI rotation events
4. Maintain backward compatibility for verification

This approach ensures KERI remains secure even as cryptographic landscape evolves.