Composability: The qualification property is essential for CESR's composability guarantee—the ability to convert concatenated primitives between text and binary domains without losing separability.

Algorithm Agility: By embedding algorithm identifiers, qualified primitives support multiple cryptographic suites coexisting in the same system, enabling gradual migration to post-quantum algorithms.

Interoperability: Systems can exchange qualified primitives without pre-negotiating cryptographic parameters, as each primitive declares its own derivation method.

Type Classification

Qualified primitives in KERI/CESR fall into several categories:

Basic Primitives: Single cryptographic values with derivation codes

• Public keys (e.g., Ed25519, ECDSA secp256k1)
• Private keys (for secure storage contexts)
• Cryptographic digests (Blake3-256, SHA-256, SHA3-256)
• Signatures (indexed and non-indexed variants)

Composed Primitives: Aggregations of qualified primitives

• Multi-signature groups
• Threshold signature sets
• Witness receipt collections

Variable-Length Primitives: Qualified text or binary data

• Bexter (Base64 text strings)
• Variable-length byte strings

Cryptographic Properties

Derivation Code Structure

The derivation code (proem) that qualifies a primitive consists of:

Code Characters: 1-4 characters in Base64 URL-safe encoding that specify:

• Cryptographic algorithm family (e.g., Ed25519, ECDSA)
• Hash function (e.g., Blake3, SHA-256)
• Key length or digest size
• Special properties (transferability, delegation)

Length Information: Implicit or explicit encoding of the primitive's length:

• Fixed-length primitives: Length determined by derivation code
• Variable-length primitives: Length encoded in additional characters

Security Properties

Qualification provides several security benefits:

Algorithm Binding: The derivation code cryptographically commits to the algorithm used, preventing algorithm substitution attacks where an attacker might attempt to reinterpret a primitive under a weaker algorithm.

Type Safety: Parsers can verify that primitives are used in appropriate contexts (e.g., ensuring a signature primitive is not misinterpreted as a public key).

Version Control: Different versions of the same algorithm can be distinguished through distinct derivation codes, enabling security updates without breaking existing systems.

Cryptographic Strength

KERI mandates minimum cryptographic strength requirements:

128-bit Security: All qualified primitives must provide approximately 128 bits of cryptographic strength, ensuring resistance to brute-force attacks and providing a security margin against future computational advances.

Post-Quantum Considerations: The qualification mechanism supports post-quantum algorithms through:

• Pre-rotation with hidden next keys (quantum-safe key rotation)
• Support for hash-based signatures and lattice-based cryptography
• Algorithm agility enabling migration to quantum-resistant primitives

Data Format & Encoding

CESR Encoding Format

Qualified primitives in CESR exist in three domains:

Text Domain (T): Base64 URL-safe encoding

• Uses character set: [A-Z, a-z, 0-9, -, _]
• Derivation code prepended as readable characters
• Example: BF5pxRJP6THrUtlDdhh07hJEDKrJxkcR9m5u1xs33bhp
  • B = derivation code for Ed25519 public key
  • Remaining 43 characters = Base64-encoded key material

Binary Domain (B): Compact binary representation

• Derivation code encoded as binary prefix
• Raw cryptographic material follows
• Optimized for transmission and storage efficiency

Raw Domain (R): Unqualified cryptographic material

• Represented as tuple: (derivation_code, raw_bytes)
• Used internally by cryptographic libraries
• Not directly serialized in KERI messages

Text and Binary Representations

The qualification mechanism ensures round-trip composability between text and binary domains:

Text Representation:

Derivation_Code + Base64(Raw_Material)

Binary Representation:

Binary_Derivation_Code + Raw_Material_Bytes

24-bit Alignment: All qualified primitives align on 24-bit boundaries (the least common multiple of 6-bit Base64 characters and 8-bit bytes), ensuring clean conversion between domains without bit-level dependencies between adjacent primitives.

Derivation Codes

CESR defines extensive code tables for different primitive types:

Single-Character Codes: Most common primitives

• A: Ed25519 non-transferable prefix (basic derivation)
• B: Ed25519 transferable prefix (self-addressing derivation)
• C: X25519 public encryption key
• D: Ed25519 public signing key
• E: Blake3-256 digest
• F: Blake2b-256 digest
• G: Blake2s-256 digest
• H: SHA3-256 digest
• I: SHA2-256 digest

Multi-Character Codes: Specialized or less common primitives

• 0B: Ed25519 signature (indexed)
• 0C: ECDSA secp256k1 signature
• 1AAA: Large frame count code
• 4B##: Variable-length byte string (small)

Count Codes: For grouping primitives

• -A##: Attachment group counter
• -B##: Message group counter
• -C##: Material group counter

Usage in KERI/ACDC

In Key Event Messages

Qualified primitives appear throughout KERI key events:

Inception Events:

{
  "v": "KERI10JSON00011c_",
  "t": "icp",
  "d": "EAdXt3gIXOf2BBWNHdSXCJnFJL5OuQPyM5K0neuniccM",
  "i": "EAdXt3gIXOf2BBWNHdSXCJnFJL5OuQPyM5K0neuniccM",
  "s": "0",
  "kt": "1",
  "k": ["DKxy2sgzfplyr-tgwIxS19f2OchFHtLwPWD3v4oYimBx"],
  "n": ["EQb3h7P3fmKJNRqZbzxI7JZ6JjLQCXq0JzLZqFZvDxkQ"],
  "bt": "2",
  "b": ["BGKVzj4ve0VSd8z_AmvhLg4lqcC_9WYX90k03q-R_Ydo"],
  "c": [],
  "a": []
}

Qualified primitives in this event:

• d: Qualified SAID (self-addressing identifier) with E derivation code
• i: Qualified AID (autonomic identifier) with E derivation code
• k: Qualified public key with D derivation code
• n: Qualified next key digest with E derivation code
• b: Qualified witness AID with B derivation code

Rotation Events: Similar structure with qualified primitives for rotated keys and next key commitments.

Interaction Events: Include qualified seals (digests) anchoring external data.

In ACDC Credentials

ACDCs extensively use qualified primitives:

SAIDs (Self-Addressing Identifiers):

• Every ACDC section (attributes, edges, rules) has a qualified SAID
• Example: ELqriXX1-lbV9zgXP4BXxqJlpZTgFchll3cyja (Blake3-256 digest)

Issuer AIDs:

• The i field contains a qualified AID of the credential issuer
• Enables cryptographic verification of issuer authority

Schema SAIDs:

• The s field references schemas via qualified SAIDs
• Ensures schema integrity and immutability

Common Usage Patterns

Identifier Derivation:

1. Generate cryptographic key pair
2. Compute digest of inception data
3. Prepend appropriate derivation code
4. Result is a qualified self-certifying identifier

Signature Attachment:

1. Sign event message with private key
2. Encode signature with indexed signature derivation code
3. Attach qualified signature to message
4. Verifier uses derivation code to select verification algorithm

Digest Computation:

1. Serialize data structure canonically
2. Compute cryptographic hash
3. Prepend digest derivation code
4. Use qualified digest as content identifier

Verification Procedures

Verifying qualified primitives follows a standard pattern:

Step 1: Parse Derivation Code

• Extract leading characters according to code table
• Determine primitive type, algorithm, and length

Step 2: Extract Raw Material

• Based on derivation code, extract appropriate number of characters/bytes
• Decode from Base64 (text domain) or use directly (binary domain)

Step 3: Perform Cryptographic Operation

• For signatures: Verify using indicated algorithm and extracted public key
• For digests: Recompute hash and compare
• For keys: Use in appropriate cryptographic operations

Step 4: Validate Context

• Ensure primitive type matches expected usage
• Verify cryptographic strength meets requirements
• Check for algorithm deprecation or security advisories

Related Primitives

Qualification is a property that applies to all CESR primitives:

Diger: Qualified digest primitive

• Represents cryptographic hash with algorithm indicator
• Used for SAIDs, content addressing, and integrity verification

Verfer: Qualified public key primitive

• Represents verification key with algorithm indicator
• Used for signature verification and identifier derivation

Signer: Qualified private key primitive

• Represents signing key (in secure contexts only)
• Used for signature generation

Siger: Qualified indexed signature primitive

• Includes signature and index for multi-sig scenarios
• Used in witness receipts and multi-signature events

Cigar: Qualified non-indexed signature primitive

• Signature without index information
• Used in single-signature contexts

Salter: Qualified seed/salt primitive

• Represents entropy source for key derivation
• Used in hierarchical deterministic key generation

Composition Patterns

Qualified primitives compose into higher-level structures:

Multi-Signature Groups: Collection of qualified indexed signatures

• Each signature is individually qualified
• Group has its own count code
• Enables threshold signature verification

Witness Receipt Logs: Sequences of qualified receipts

• Each receipt contains qualified signatures from witnesses
• Enables duplicity detection and consensus verification

ACDC Chains: Linked credentials via qualified SAIDs

• Each ACDC references others through qualified identifiers
• Creates verifiable provenance chains

Implementation Considerations

Qualification is not optional in KERI/CESR—all cryptographic primitives MUST be qualified. This requirement ensures:

Universal Parseability: Any CESR stream can be parsed without external schema

Algorithm Agility: Systems can evolve cryptographic algorithms without breaking changes

Interoperability: Different implementations can exchange primitives reliably

Security: Algorithm binding prevents substitution attacks

The qualification mechanism is described as an essential property of CESR, making it a foundational concept for understanding KERI's encoding scheme and cryptographic architecture.

Testing Requirements

1. Round-Trip Tests: Verify text ↔ binary conversion preserves primitives
2. Code Coverage: Test all supported derivation codes
3. Boundary Conditions: Test variable-length primitives at size boundaries
4. Interoperability: Test against other KERI implementations