KEL Verification Sequence

The verification of a Key Event Log follows a precise sequence:

Step 1: Inception Event Verification

• Extract the AID prefix from the inception event
• Verify the prefix is correctly derived from the initial public key(s)
• For self-addressing identifiers, compute the digest of the inception event and confirm it matches the prefix
• Validate the inception event signature(s) using the public key(s) embedded in or derived from the prefix

Step 2: Establishment Event Chain Verification

• Process each rotation event in sequence
• Verify the previous event digest matches the computed digest of the prior event (backward chaining)
• Verify the pre-rotated key commitment from the previous event matches the digest of the current rotation keys (forward chaining)
• Validate signatures on the rotation event using the current authoritative keys
• Update the key state to reflect the new authoritative keys and next key commitments

Step 3: Interaction Event Verification

• Verify interaction events are signed by keys that were authoritative at the time of signing
• Validate the previous event digest chain
• Confirm sequence numbers are monotonically increasing
• Verify any seals (anchored data commitments) are properly formatted

Step 4: Witness Receipt Verification

• For each key event, verify witness receipts if operating in indirect mode
• Confirm witness signatures using witness AIDs and their KELs
• Validate that the threshold of accountable duplicity (TOAD) is satisfied
• Check for duplicity by comparing receipts from multiple witnesses

ACDC Credential Verification Sequence

Step 1: Structural Validation

• Parse the ACDC according to its version string
• Validate the ACDC conforms to its declared schema
• Verify all required fields are present
• Confirm field ordering matches the schema specification

Step 2: SAID Integrity Verification

• Extract the SAID from the credential's d field
• Replace the SAID with placeholder characters (typically #)
• Compute the cryptographic digest of the modified credential
• Verify the computed digest matches the extracted SAID
• Repeat for nested SAIDs in attribute, edge, and rule sections

Step 3: Issuer KEL Verification

• Extract the issuer AID from the credential's i field
• Retrieve the issuer's KEL (via OOBI or cached copy)
• Verify the issuer's KEL from inception through current state
• Determine the key state that was authoritative when the credential was issued

Step 4: Signature Verification

• Locate the CESR Proof Signature attachments
• Extract the signature(s) and signing key indices
• Retrieve the public keys that were authoritative at issuance time
• Verify the signature(s) over the credential using the authoritative public keys
• For multi-sig credentials, verify the threshold is satisfied

Step 5: Registry State Verification (if applicable)

• If the credential includes a registry identifier (ri field), retrieve the TEL
• Verify the TEL is properly anchored to the issuer's KEL
• Check the credential's issuance and revocation state
• Confirm the credential has not been revoked

Step 6: Chain Verification (for chained credentials)

• If the credential includes edges to other ACDCs, recursively verify the referenced credentials
• Validate edge operators (I2I, DI2I, NI2I) are satisfied
• Confirm the credential chain forms a valid directed acyclic graph

State Changes During Verification

Verification processes involve several state transitions:

Initial State: Unverified data received from an untrusted source

Parsing State: Data structure is parsed and basic format validation occurs

• Transition condition: Valid serialization format
• Failure: Malformed data rejection

Cryptographic Validation State: Signatures and digests are verified

• Transition condition: Valid cryptographic proofs
• Failure: Authentication failure

Policy Evaluation State: Business logic and trust policies are applied

• Transition condition: Policy requirements satisfied
• Failure: Authorization failure

Verified State: Data is confirmed authentic and authorized

• Result: Trust decision can be made

Decision Points

Verification processes include critical decision points:

Signature Validity Decision:

• If signature verification fails → Reject immediately
• If signature verification succeeds → Continue to next check

Key State Currency Decision:

• If keys have been rotated since signing → Verify using historical key state
• If keys are current → Use current key state
• If keys are compromised/revoked → Reject

Duplicity Detection Decision:

• If multiple inconsistent versions of KEL exist → Flag duplicity
• If KEL is consistent across all sources → Accept
• If insufficient witnesses confirm → Defer or reject based on policy

Revocation Status Decision:

• If credential is revoked → Reject
• If credential is issued but not revoked → Accept
• If registry is unavailable → Apply policy (fail-open vs fail-closed)

Technical Requirements

Cryptographic Requirements

Signature Algorithms:

• KERI primarily uses Ed25519 signatures for their security and performance
• Signatures must be verified using the exact public key that was authoritative at signing time
• Multi-signature verification requires satisfying the threshold specified in the key state

Hash Functions:

• Blake3-256 is the preferred hash function for SAIDs and digests
• Blake2-256 and SHA3-256 are also supported
• Hash functions must provide at least 128 bits of cryptographic strength
• Digest verification requires exact byte-for-byte reproduction of the input

Key Derivation:

• Public keys must be derived according to the derivation code specified in the AID prefix
• CESR encoding must be properly decoded to extract raw key material
• Key indices in indexed signatures must correctly map to the key list

CESR Encoding:

• All cryptographic primitives must be properly CESR-encoded
• Derivation codes must be validated against the CESR code tables
• Primitive boundaries must be correctly identified for stream parsing

Timing Considerations

Temporal Validity Windows:

• Credentials may include issuance dates and expiration dates that must be checked
• Key states are time-dependent; verification must use the key state that was current at signing time
• Witness receipts have temporal ordering that must be respected

Replay Attack Protection:

• Interaction events include sequence numbers that must be monotonically increasing
• Timestamps in KRAM (KERI Request Authentication Method) must fall within acceptable windows
• Nonces in challenge-response protocols must be fresh and not reused

Asynchronous Operations:

• KEL retrieval may require network operations with variable latency
• Witness queries may timeout, requiring retry logic
• Registry state checks may be eventually consistent

Caching Strategies:

• Verified KELs can be cached to avoid repeated verification
• Cache invalidation must occur when new events are discovered
• Stale cache entries can lead to verification failures

Error Handling

Cryptographic Failures:

• Invalid Signature: Immediate rejection, log security event
• Digest Mismatch: Data tampering detected, reject and alert
• Unknown Derivation Code: Unsupported cryptographic algorithm, reject

Structural Failures:

• Malformed CESR: Parsing error, reject with diagnostic information
• Schema Violation: Credential doesn't match declared schema, reject
• Missing Required Fields: Incomplete credential, reject

State Failures:

• Revoked Credential: Credential no longer valid, reject with revocation reason
• Expired Credential: Temporal validity exceeded, reject
• Insufficient Witnesses: TOAD threshold not met, defer or reject based on policy

Network Failures:

• OOBI Resolution Failure: Cannot retrieve KEL, retry or fail based on policy
• Witness Timeout: Cannot confirm event, use cached state or reject
• Registry Unavailable: Cannot check revocation status, apply fail-open or fail-closed policy

Duplicity Detection:

• Inconsistent KEL Versions: Multiple conflicting versions detected, flag for investigation
• Conflicting Witness Receipts: Witnesses disagree on event content, potential attack
• Fork Detection: KEL has branched, identify malicious controller

Usage Patterns

Credential Presentation Verification

The most common verification pattern involves a holder presenting a credential to a verifier:

Scenario: An employee presents their OOR (Official Organizational Role) vLEI credential to access a corporate system.

Verification Steps:

1. Receive the ACDC credential and CESR Proof Signature attachments
2. Verify the credential's SAID integrity
3. Retrieve and verify the issuer's (QVI) KEL
4. Verify the credential signature using the QVI's authoritative keys
5. Check the credential's registry state for revocation
6. Verify the credential chain back to the Legal Entity vLEI credential
7. Verify the Legal Entity credential chains to the QVI credential
8. Verify the QVI credential chains to the GLEIF root
9. Apply business logic policies (e.g., check the role matches required permissions)
10. Make access control decision based on verification results

Witness Receipt Verification

Witnesses provide receipts that must be verified to confirm event promulgation:

Scenario: A controller rotates keys and needs to verify witnesses have properly receipted the rotation event.

Verification Steps:

1. Retrieve witness receipts for the rotation event
2. For each witness, retrieve the witness's KEL
3. Verify each witness's KEL to determine current authoritative keys
4. Verify each witness's signature on the rotation event receipt
5. Confirm the receipt references the correct event (by digest)
6. Count the number of valid receipts
7. Compare against the TOAD threshold
8. If threshold is met, consider the event confirmed
9. If threshold is not met, wait for additional receipts or investigate

Multi-Signature Verification

Multi-sig AIDs require verifying multiple signatures satisfy the threshold:

Scenario: A multi-sig group AID with 3 members and a 2-of-3 threshold signs a credential.

Verification Steps:

1. Extract the indexed signatures from the CESR attachments
2. Retrieve the multi-sig AID's KEL
3. Determine the key state at the time of signing
4. Extract the signing threshold (e.g., 2-of-3)
5. For each indexed signature, identify which key was used (by index)
6. Verify each signature using the corresponding public key
7. Count the number of valid signatures
8. Confirm the count meets or exceeds the threshold
9. If threshold is satisfied, accept the credential
10. If threshold is not satisfied, reject

Delegated Identifier Verification

Delegated AIDs require verifying both the delegate's KEL and the delegator's authorization:

Scenario: A QVI (delegate) issues a credential, and the verifier must confirm GLEIF (delegator) authorized the QVI.

Verification Steps:

1. Retrieve the QVI's KEL (delegate)
2. Identify the QVI's inception event as a delegated inception (dip)
3. Extract the delegator's AID from the inception event
4. Retrieve the delegator's (GLEIF) KEL
5. Locate the interaction or rotation event in GLEIF's KEL that contains the delegation seal
6. Verify the seal references the QVI's inception event (by digest)
7. Verify GLEIF's signature on the event containing the seal
8. Confirm the delegation is still valid (not revoked)
9. Proceed with verifying the QVI's KEL and credential signature

Best Practices

Verify Early, Verify Often:

• Verify credentials immediately upon receipt
• Re-verify credentials before making trust decisions
• Periodically re-verify cached credentials to detect revocations

Fail Securely:

• Default to rejection when verification fails
• Log all verification failures for security monitoring
• Provide clear error messages for debugging without leaking sensitive information

Cache Intelligently:

• Cache verified KELs to improve performance
• Implement cache invalidation when new events are discovered
• Set appropriate cache TTLs based on risk tolerance

Handle Asynchrony:

• Design verification workflows to handle network delays
• Implement retry logic with exponential backoff
• Provide user feedback during long-running verifications

Detect Duplicity:

• Compare KELs from multiple sources (witnesses, watchers)
• Flag inconsistencies for investigation
• Implement ambient duplicity detection through watcher networks

Validate Schemas:

• Verify credentials conform to their declared schemas
• Reject credentials with unknown or unsupported schemas
• Keep schema definitions up-to-date

Check Revocation Status:

• Always check credential registry state before trusting credentials
• Implement appropriate fail-open or fail-closed policies for registry unavailability
• Monitor for revocation events in real-time when possible

Integration Considerations

API Design:

• Provide synchronous verification APIs for simple use cases
• Offer asynchronous verification APIs for complex workflows
• Return structured verification results with detailed error information

Performance Optimization:

• Batch verification operations when possible
• Parallelize independent verification steps (e.g., multiple credential verifications)
• Use connection pooling for network operations

Error Reporting:

• Distinguish between transient failures (network errors) and permanent failures (invalid signatures)
• Provide actionable error messages for developers
• Log sufficient detail for security auditing

Policy Enforcement:

• Separate cryptographic verification from policy evaluation
• Allow configurable policies for different use cases
• Support policy updates without code changes

Monitoring and Alerting:

• Track verification success/failure rates
• Alert on unusual patterns (e.g., spike in verification failures)
• Monitor verification latency to detect performance issues

Testing:

• Test verification with valid and invalid inputs
• Test edge cases (expired credentials, revoked credentials, malformed data)
• Test performance under load
• Test error handling and recovery

Synchronous API: For simple use cases, provide a blocking verification function that returns success/failure.

Asynchronous API: For complex workflows, provide async verification that handles network operations efficiently.

Streaming Verification: For large KELs or credential chains, support streaming verification to avoid loading entire structures into memory.

Testing Requirements

Positive Tests: Verify valid KELs, credentials, and signatures succeed.

Negative Tests: Verify invalid signatures, tampered data, and malformed structures are rejected.

Edge Cases: Test expired credentials, revoked credentials, threshold boundaries, and empty witness sets.

Performance Tests: Verify performance under load, with large KELs, and with many concurrent verifications.