Process Flow

Step 1: Control Authority Establishment

Before signature verification can occur, the verifier must determine which key set was controlling an identifier at the time an event was issued. This process differs based on identifier type:

Non-Transferable Identifiers: For identifiers declared as non-transferable at inception, control establishment requires only a copy of the inception event. The public key can be extracted directly from the self-certifying identifier prefix.

Transferable Identifiers: For transferable identifiers, verifiers must obtain and verify a complete sequence of establishment events:

1. Retrieve the inception event
2. Obtain all subsequent rotation events
3. Verify the complete history up to the statement issuance time
4. Determine the authoritative key set at the relevant timestamp

This establishment phase is critical because KERI's pre-rotation mechanism means that the current authoritative keys may differ from the keys that were authoritative when a historical event was signed.

Step 2: Public Key Extraction

Once control authority is established, the verifier extracts the appropriate public key(s):

For Basic Signatures: Extract the single public key from the identifier or KEL that was authoritative at signing time.

For Indexed Signatures: In multi-sig scenarios, indexed signatures include an index value indicating which specific public key from the key set was used. The verifier:

1. Extracts the index from the qualified signature primitive
2. Retrieves the corresponding public key at that index position
3. Uses the identified public key for verification

Example indexed signature structure:

03.<binary signature>

The prefix 03 indicates the signature was created using the public key at index 3.

For Witness Signatures: Witnesses attach their signatures as indexed signatures to key event receipts. The controller determines which witness signed by examining the index against their configured witness list.

Step 3: Cryptographic Verification

The core verification algorithm processes the three inputs:

1. Message Preparation: The verifier serializes the message data in the exact format that was signed (typically CESR-encoded)

2. Algorithm Selection: Based on the derivation code in the qualified public key, select the appropriate signature algorithm:

   • Ed25519 for Edwards-curve signatures
   • ECDSA_secp256k1 for elliptic curve signatures
   • Other algorithms as specified by CESR codes

3. Signature Validation: Apply the verification algorithm:

   verify(message, public_key, signature) → {accept, reject}
   

4. Result Interpretation:

   • Accept: The signature is mathematically valid for the given message and public key
   • Reject: The signature is invalid, indicating either:
     • Message tampering
     • Wrong public key used
     • Signature corruption
     • Fraudulent signature attempt

Step 4: Threshold Validation (Multi-Signature)

For multi-signature identifiers, additional validation occurs:

1. Signature Collection: Gather all attached signatures for the event
2. Individual Verification: Verify each signature against its corresponding public key
3. Threshold Check: Confirm that the number of valid signatures meets or exceeds the signing threshold
4. Weight Calculation: For fractionally-weighted thresholds, sum the weights of valid signatures
5. Threshold Satisfaction: Accept the event only if threshold requirements are met

Example: A 2-of-3 multi-sig requires at least 2 valid signatures from the 3 authorized keys.

Step 5: State Changes

Successful verification triggers state changes:

KEL Updates: Verified establishment events update the identifier's key state:

• Current authoritative keys
• Next key digests (for pre-rotation)
• Witness configuration
• Signing thresholds

Receipt Recording: Verified witness receipts are recorded in the KERL (Key Event Receipt Log)

Credential Status: Verified ACDC presentations may trigger credential status checks against TEL (Transaction Event Log) registries

Step 6: Error Handling

Verification failures require specific handling:

Invalid Signature: Reject the event and do not update state. Log the failure for potential duplicity detection.

Missing Keys: If authoritative keys cannot be determined (incomplete KEL), place the event in escrow until the key state can be established.

Threshold Failure: For multi-sig events, if insufficient valid signatures are present, reject the event or escrow it pending additional signatures.

Duplicity Detection: If verification succeeds but conflicts with a previously verified event at the same sequence number, flag for duplicity investigation.

Technical Requirements

Cryptographic Requirements

Algorithm Support: Verifiers must support all cryptographic algorithms specified in the CESR code tables:

• Ed25519: Edwards-curve Digital Signature Algorithm
• ECDSA secp256k1: Elliptic Curve Digital Signature Algorithm
• ECDSA secp256r1: NIST P-256 curve
• Future algorithms as CESR evolves

Cryptographic Strength: All signature schemes must provide approximately 128 bits of cryptographic strength, as mandated by KERI security requirements.

Derivation Code Handling: Verifiers must correctly parse CESR derivation codes to:

• Identify the signature algorithm
• Determine key length
• Select appropriate verification procedures

Qualified Primitives: All cryptographic material must be processed as qualified primitives with derivation codes, not as raw binary data.

Timing Considerations

Historical Verification: When verifying historical events, verifiers must use the key state that was authoritative at the time of signing, not the current key state. This requires:

• Maintaining complete KEL history
• Timestamp-based key state reconstruction
• Proper handling of key rotations

Witness Receipt Timing: Witness receipts must be verified using the witness keys that were configured at the time the event was issued, even if witness configuration has since changed.

Escrow Timeout: Events placed in escrow due to missing key state information should have configurable timeout periods before being rejected.

First-Seen Policy: KERI's first-seen policy means that once an event is verified and accepted, any conflicting event at the same sequence number is automatically rejected as duplicitous.

Error Handling

Graceful Degradation: Verification failures should not crash the verifier. Instead:

• Log the failure with sufficient detail for debugging
• Return clear error codes indicating failure type
• Maintain system stability

Escrow Management: Events that cannot be immediately verified due to missing dependencies should be:

• Stored in escrow with metadata
• Periodically re-evaluated as new information arrives
• Eventually timed out if dependencies never arrive

Duplicity Reporting: When verification reveals duplicity:

• Record both conflicting events in the DEL (Duplicitous Event Log)
• Alert the controller and relevant parties
• Maintain evidence for potential dispute resolution

Partial Verification: In multi-signature scenarios:

• Track which signatures have been verified
• Support incremental verification as signatures arrive
• Provide clear status on threshold satisfaction progress

Usage Patterns

Typical Scenarios

Scenario 1: KEL Validation

When a verifier receives a KEL for an identifier:

1. Start with the inception event
2. Verify the inception signature using the public key embedded in the identifier prefix
3. Extract the next key digest for pre-rotation validation
4. Process each subsequent event in sequence:
   • Verify signatures using current authoritative keys
   • Validate next key digest matches the actual next rotation
   • Update key state after each verified establishment event
5. Confirm the final key state matches expectations

This pattern ensures the entire KEL is cryptographically valid and internally consistent.

Scenario 2: ACDC Credential Verification

When verifying an ACDC credential presentation:

1. Extract the issuer AID from the credential
2. Retrieve the issuer's KEL to establish current key state
3. Verify the credential signature using the issuer's authoritative keys
4. Check the credential's SAID matches its content
5. Validate any chained credentials in the DAG
6. Query the TEL registry for revocation status
7. Apply business logic validation (schema compliance, attribute checks)

This pattern combines cryptographic verification with policy-based validation.

Scenario 3: Witness Receipt Validation

When processing witness receipts:

1. Receive a key event with attached witness receipts
2. For each receipt:
   • Extract the witness index from the indexed signature
   • Look up the witness AID in the controller's witness list
   • Retrieve the witness's KEL to determine authoritative keys
   • Verify the witness signature on the event
3. Count valid witness receipts
4. Check if the count meets the TOAD (Threshold of Accountable Duplicity)
5. Accept the event only if threshold is satisfied

This pattern implements KERI's distributed consensus mechanism.

Scenario 4: Multi-Signature Group Validation

For multi-sig group identifiers:

1. Receive an event signed by multiple group members
2. Extract all indexed signatures
3. For each signature:
   • Identify the signer via the index
   • Retrieve the corresponding public key
   • Verify the signature
   • Track the signer's weight (if using fractional thresholds)
4. Sum the weights of valid signatures
5. Compare against the signing threshold
6. Accept only if threshold is satisfied

This pattern enables cooperative multi-party control.

Best Practices

Always Verify Complete Chains: Never verify a single event in isolation. Always verify the complete chain from inception to the event in question to ensure proper key state.

Cache Key State Carefully: While caching key state improves performance, ensure caches are invalidated appropriately when new rotations occur. Stale key state leads to verification failures.

Implement Escrow Properly: Events that arrive out-of-order should be escrowed, not rejected. KERI's asynchronous nature means events may arrive in non-sequential order.

Use First-Seen Consistently: Once an event is verified and accepted, maintain the first-seen policy strictly. This is critical for duplicity detection.

Validate Derivation Codes: Always validate that derivation codes are recognized and supported before attempting verification. Unknown codes should trigger graceful failures.

Log Verification Failures: Maintain detailed logs of verification failures, including:

• Event identifiers
• Failure reasons
• Key state at time of verification
• Timestamp of verification attempt

These logs are invaluable for debugging and duplicity investigation.

Handle Witness Receipts Asynchronously: Don't block on witness receipt collection. Accept events into escrow and verify receipts as they arrive.

Implement Timeout Policies: Define clear timeout policies for:

• Escrow retention
• Witness receipt collection
• Key state resolution

Integration Considerations

KEL Storage: Verifiers need access to complete KELs. Integration with KEL storage systems (databases, distributed storage) is essential.

Witness Network: For indirect mode operation, verifiers must integrate with witness networks to retrieve receipts and validate events.

Watcher Networks: Integration with watcher networks provides additional duplicity detection capabilities beyond local verification.

TEL Registries: For credential verification, integration with TEL registries enables revocation checking and status validation.

OOBI Resolution: Verifiers must support OOBI (Out-of-Band Introduction) resolution to discover witness endpoints and retrieve KELs.

CESR Parsing: Robust CESR parsing is mandatory. Verifiers must handle:

• Text domain CESR
• Binary domain CESR
• Mixed streams with multiple primitive types
• Group codes and count codes

Cryptographic Libraries: Integration with cryptographic libraries must support:

• Multiple signature algorithms
• Constant-time operations (to prevent timing attacks)
• Secure random number generation
• Key derivation functions

Performance Optimization: For high-throughput scenarios:

• Batch verification of multiple signatures
• Parallel verification of independent events
• Caching of frequently accessed KELs
• Efficient escrow data structures

Implementation Examples

The KERI ecosystem provides multiple reference implementations demonstrating signature verification:

KERIpy (Python): The reference implementation includes comprehensive verification logic in the keri.core.eventing module, with the Kever class handling key event verification.

KERI-Ox (Rust): The Rust implementation provides high-performance verification with strong type safety.

SignifyTS (TypeScript): The TypeScript client library includes verification capabilities for browser and Node.js environments.

All implementations follow the same verification algorithm while optimizing for their respective language ecosystems and use cases.

Performance Optimization

• Batch Verification: Some cryptographic libraries support batch verification of multiple signatures, providing significant performance improvements
• Parallel Processing: Independent events can be verified in parallel
• Signature Caching: Cache verification results for frequently accessed events
• KEL Caching: Cache parsed KELs to avoid repeated parsing

Security Considerations

• Constant-Time Operations: Use constant-time comparison functions to prevent timing attacks
• Input Validation: Validate all inputs (message length, signature length, key length) before verification
• Error Handling: Never expose detailed error information that could aid attackers
• Resource Limits: Implement limits on verification operations to prevent DoS attacks
• Cryptographic Library Selection: Use well-audited cryptographic libraries (libsodium, OpenSSL)

Testing Requirements

• Test Vectors: Use KERI test vectors to validate implementation correctness
• Edge Cases: Test boundary conditions (empty messages, maximum length messages, invalid signatures)
• Interoperability: Verify compatibility with other KERI implementations
• Performance Testing: Benchmark verification throughput for expected workloads
• Failure Scenarios: Test all failure modes (invalid signatures, wrong keys, corrupted data)

Integration Patterns

• KEL Storage: Integrate with persistent storage for KEL data
• Witness Communication: Implement protocols for retrieving witness receipts
• OOBI Resolution: Support OOBI discovery for finding witness endpoints
• TEL Integration: For credential verification, integrate with TEL registries
• Event Streaming: Handle CESR event streams efficiently

Common Pitfalls

• Using Current Keys for Historical Events: Always use the key state that was authoritative when the event was signed
• Ignoring Escrow: Rejecting out-of-order events instead of escrowing them breaks KERI's asynchronous model
• Incomplete KEL Validation: Verifying individual events without validating the complete chain from inception
• Threshold Miscalculation: Incorrectly implementing fractional weight thresholds
• First-Seen Violations: Accepting a second version of an event after the first has been verified
• Derivation Code Mishandling: Failing to check derivation codes before attempting verification

Debugging Strategies

• Detailed Logging: Log all verification attempts with sufficient detail for post-mortem analysis
• Event Inspection: Provide tools to inspect event structure, signatures, and key state
• KEL Visualization: Visualize KEL structure to identify chain breaks or inconsistencies
• Signature Debugging: Provide detailed failure reasons (wrong key, invalid signature, corrupted data)
• Escrow Monitoring: Monitor escrow state to identify stuck events or missing dependencies