Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 135 GitHub source documents. All source documents are searchable here.
Last updated: October 7, 2025
This content is meant to be consumed by AI agents via MCP. Click here to get the MCP configuration.
Note: In rare cases it may contain LLM hallucinations.
For authoritative documentation, please consult the official GLEIF vLEI trainings and the ToIP Glossary.
Verify-signature is the cryptographic process of applying an algorithm that takes a message, public key, and signature as inputs to determine whether the signature was validly created by the corresponding private key holder, thereby accepting or rejecting the message's claim to authenticity.
Signature verification is a fundamental cryptographic operation in KERI that validates the authenticity and integrity of signed messages. The process applies a verification algorithm that processes three inputs: (1) the message data being verified, (2) the public key from the claimed signer, and (3) the cryptographic signature, producing a binary decision to either accept or reject the message's authenticity claim.
This operation is central to KERI's security model because every entry in a Key Event Log (KEL) must be cryptographically signed by the controller's authoritative key pairs. The verification process ensures that only events signed by authorized keys are accepted into the event stream, enabling KERI's duplicity detection mechanisms and end-verifiable security architecture.
Signature verification is used throughout KERI operations:
Key participants in the verification process include:
All signature verification implementations must correctly parse CESR-encoded primitives:
Proper key state management is critical:
Robust escrow handling is essential for KERI's asynchronous operation:
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:
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.
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:
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.
The core verification algorithm processes the three inputs:
Message Preparation: The verifier serializes the message data in the exact format that was signed (typically CESR-encoded)
Algorithm Selection: Based on the derivation code in the qualified public key, select the appropriate signature algorithm:
Ed25519 for Edwards-curve signaturesECDSA_secp256k1 for elliptic curve signaturesSignature Validation: Apply the verification algorithm:
verify(message, public_key, signature) → {accept, reject}
Result Interpretation:
For multi-signature identifiers, additional validation occurs:
Example: A 2-of-3 multi-sig requires at least 2 valid signatures from the 3 authorized keys.
Successful verification triggers state changes:
KEL Updates: Verified establishment events update the identifier's key state:
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
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.
Algorithm Support: Verifiers must support all cryptographic algorithms specified in the CESR code tables:
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:
Qualified Primitives: All cryptographic material must be processed as qualified primitives with derivation codes, not as raw binary data.
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:
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.
Graceful Degradation: Verification failures should not crash the verifier. Instead:
Escrow Management: Events that cannot be immediately verified due to missing dependencies should be:
Duplicity Reporting: When verification reveals duplicity:
Partial Verification: In multi-signature scenarios:
Scenario 1: KEL Validation
When a verifier receives a KEL for an identifier:
This pattern ensures the entire KEL is cryptographically valid and internally consistent.
Scenario 2: ACDC Credential Verification
When verifying an ACDC credential presentation:
This pattern combines cryptographic verification with policy-based validation.
Scenario 3: Witness Receipt Validation
When processing witness receipts:
This pattern implements KERI's distributed consensus mechanism.
Scenario 4: Multi-Signature Group Validation
This pattern enables cooperative multi-party control.
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:
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:
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:
Cryptographic Libraries: Integration with cryptographic libraries must support:
Performance Optimization: For high-throughput scenarios:
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.