Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 171 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.
A digital signature scheme enabling multiple parties to collectively sign data, where signatures from a threshold-satisfying subset of authorized keys are required to validate operations on an identifier or credential.
Multisig (multi-signature, multisignature, multi-sig) is a cryptographic authorization mechanism that distributes signing authority across multiple key pairs, requiring signatures from a configurable threshold of authorized keys to validate operations. In KERI, multisig enables cooperative control over Autonomic Identifiers (AIDs) through threshold signature schemes where M-of-N signatures must be collected to authorize establishment events (inception, rotation) and interaction events.
KERI implements multisig through thresholded sets of non-repudiable signatures, where each signature is cryptographically independent and verifiable against its corresponding public key. Unlike collective signature schemes that produce a single aggregate signature, KERI's approach maintains individual signatures with explicit indexing, enabling transparent verification of which specific keys authorized an operation.
Multisig serves three critical functions in the KERI ecosystem:
KERI supports multiple multisig configurations:
When implementing multisig AIDs, carefully select thresholds based on security requirements and operational constraints:
Simple Thresholds: Use integer values for straightforward M-of-N schemes. For a 3-of-5 board of directors, set kt: "3" and provide 5 keys in the k array.
Weighted Thresholds: Use fractional weights for complex governance. For a CEO (weight 0.5), CFO (weight 0.25), and CTO (weight 0.25) with threshold 0.75, specify kt: ["1/2", "1/4", "1/4"].
Ample Requirements: For Byzantine fault tolerance, ensure your threshold satisfies ample constraints. With n=7 participants and f=2 potential faults, the threshold must be between 5 and 5 (exactly 5). Use the ample calculation: (n + f + 1)/2 ≤ m ≤ n - f.
Synchronous Collection: For real-time signing (e.g., during video conferences), collect all signatures before publishing the event. This ensures atomic operations but requires all signers to be available simultaneously.
Asynchronous Collection: For distributed teams, implement an escrow mechanism where partially signed events are stored until the threshold is reached. Set reasonable timeouts (e.g., 24-48 hours) to handle abandoned signing attempts.
Mailbox Services: Use KERIA or similar agent services to provide mailboxes for offline signers. This enables asynchronous workflows where signers can retrieve pending events and add their signatures when available.
Key Generation: Each multisig participant should generate their key pair independently using a CSPRNG with at least 128 bits of entropy. For high-security applications, use hardware security modules (HSMs) or secure enclaves.
Key Storage: Store private keys encrypted with strong passphrases. For organizational multisig, consider using separate HSMs for each key to prevent single points of compromise.
Key Rotation: Coordinate rotation ceremonies where all participants generate new keys and pre-rotation commitments. Use the partial rotation feature to keep some keys in reserve, unexposed until needed.
Key State Tracking: Maintain a cache of key states indexed by sequence number to avoid repeatedly walking the KEL. Update the cache as new events are processed.
Signature Verification: Verify signatures in parallel when possible, as each verification is independent. Use batch verification techniques if your cryptographic library supports them.
KERI's multisig implementation follows a "dumb crypto" philosophy, using well-established, freely available cryptographic primitives:
Signature Algorithms:
Key Derivation:
KERI multisig provides several critical security guarantees:
Non-Repudiation: Each signature is individually verifiable and cannot be denied by the signer. The KEL provides an immutable audit trail of which keys authorized which operations.
Threshold Security: An attacker must compromise M keys to gain control, where M is the signing threshold. For a 3-of-5 scheme, compromising 2 keys is insufficient for unauthorized operations.
Independent Verification: Each signature can be verified independently without requiring coordination between signers, enabling asynchronous signing workflows.
Duplicity Detection: KERI's duplicity detection mechanisms work with multisig - if a controller produces conflicting events with valid multisig signatures, both versions serve as cryptographic proof of malfeasance.
Pre-Rotation Protection: Multisig identifiers benefit from KERI's pre-rotation mechanism, where next rotation keys are cryptographically committed in advance. Even if current signing keys are compromised, attackers cannot rotate to their own keys without the pre-rotated keys.
Multisig operations in KERI produce variable-length outputs:
Individual Signatures:
Indexed Signatures: Each signature includes an index indicating which key signed:
Threshold Specifications:
KERI uses CESR (Composable Event Streaming Representation) for all cryptographic material, including multisig components:
Threshold Encoding:
Current threshold (kt): "2" // Simple 2-of-N
Next threshold (nt): "3" // Pre-rotated threshold
Weighted threshold (kt): ["1/2", "1/4", "1/4"] // Fractional weights
Key List Encoding:
Current keys (k): [
"DKxy2sgzfplyr-tgwIxS19f2OchFHtLwPWD3v4oYimBx", // Key 0
"D8KY1sKmgyjAiUDdUBPNPyrSz_ad_Qf9yzhDNZlEKiMc", // Key 1
"DEe1vHfH6HHq9INeqO0gKWPaq4fmuCTbxD0kJASe1Yg8" // Key 2
]
Each key is a qualified CESR primitive with:
Indexed Signature Encoding:
"sigs": [
"AABg3eESB_Pc2IxJhzFSvjrciYJxEX8-cL-SXVcKqLLPqLqvKvJO5lXhWq7Xt8aqmLqvKvJO5lXhWq7Xt8aqmLqv",
"ABBh4fFTC_Qd3JyKi0GTwksdjZKyFY9-dM-TYWdLrMqMMrwLvKwKP6mYiXr8Yu9brNmMrwLvKwKP6mYiXr8Yu9br"
]
Each indexed signature includes:
CESR provides text-binary composability, allowing multisig data to be represented in either domain:
Text Domain (Base64 URL-safe):
"AABg3eESB_Pc2IxJhzFSvjrciYJxEX8-cL-SXVcKqLLPq..."Binary Domain (raw bytes):
Round-Trip Conversion: CESR guarantees lossless conversion between text and binary domains, enabling efficient transmission (binary) with human-readable logging (text).
CESR derivation codes identify signature types and key indices:
Signature Type Codes:
0B: Ed25519 signature (64 bytes)0C: ECDSA secp256k1 signature2A: ECDSA secp256r1 signatureIndexed Signature Codes (dual indexed):
AA: Index 0, Ed25519 signatureAB: Index 1, Ed25519 signatureAC: Index 2, Ed25519 signatureCount Codes (for signature groups):
-AAA: Count of 0 signatures-AAB: Count of 1 signature-AAC: Count of 2 signaturesMultisig applies to all KERI event types:
Inception Events (icp):
{
"v": "KERI10JSON00011c_",
"t": "icp",
"d": "EL1L56LyoKrIofnn0oPChS4EyzMHEEk75INJohDS_Bug",
"i": "EL1L56LyoKrIofnn0oPChS4EyzMHEEk75INJohDS_Bug",
"s": "0",
"kt": "2", // Signing threshold: 2-of-3
"k": [ // Current keys (3 keys)
"DKxy2sgzfplyr-tgwIxS19f2OchFHtLwPWD3v4oYimBx",
"D8KY1sKmgyjAiUDdUBPNPyrSz_ad_Qf9yzhDNZlEKiMc",
"DEe1vHfH6HHq9INeqO0gKWPaq4fmuCTbxD0kJASe1Yg8"
],
"nt": "2", // Next threshold: 2-of-3
"n": [ // Next key digests (pre-rotation)
"ETNZH3ULvYawyZ-i0d8JZU6JR2nmAoAfSVPzhzS6b5CM",
"EYAfSVPzhzaU6JR2nmoTNZH3ULvwyZb6b5CMi0d8JZAS",
"EnmwyZdi0d8JZAoTNZYAfSVPzhzaU6JR2H3ULvS6b5CM"
],
"bt": "2", // Witness threshold
"b": [...], // Witness identifiers
"c": [],
"a": []
}
Rotation Events (rot):
Interaction Events (ixn):
Delegated Events (dip, drt):
Pattern 1: Organizational Governance
A legal entity creates a 3-of-5 multisig AID for its board of directors:
Pattern 2: Personal Security
An individual creates a 2-of-3 multisig AID across devices:
Pattern 3: Custodial Delegation
A company delegates signing authority to a custodian while retaining rotation authority:
Pattern 4: Hierarchical Multisig
GLEIF's vLEI ecosystem uses nested multisig:
Step 1: Retrieve Current Key State
Verifiers must determine which keys were authoritative when the event was signed:
# Walk the KEL to find key state at event sequence number
key_state = kel.get_key_state_at_sequence(event.sequence)
current_keys = key_state.keys
current_threshold = key_state.threshold
Step 2: Extract and Parse Signatures
Parse indexed signatures from event attachments:
for sig in event.signatures:
index = sig.index # From dual indexed code
signature = sig.raw # Raw signature bytes
public_key = current_keys[index] # Look up key by index
Step 3: Verify Individual Signatures
Verify each signature against its corresponding public key:
valid_signatures = []
for sig in event.signatures:
if verify_signature(event.serialize(), sig.raw, current_keys[sig.index]):
valid_signatures.append(sig.index)
Step 4: Check Threshold Satisfaction
Ensure sufficient valid signatures:
if len(valid_signatures) >= current_threshold:
# Event is validly signed
return True
else:
# Insufficient signatures
return False
Step 5: Verify Rotation Authority (for rotation events)
Rotation events must satisfy BOTH:
This dual requirement prevents unauthorized rotation even if current keys are compromised.
Multisig relies on threshold specifications that define signing requirements:
Thresholds appear in two contexts:
kt (current threshold): For current signing operationsnt (next threshold): For next rotation authorizationIndexed signatures are the mechanism for associating signatures with keys:
Multisig requires ordered key lists:
k: Current public keysn: Next key digests (pre-rotation commitments)Multisig AIDs typically use witness pools for event confirmation:
bt) specifies required receiptsMultisig combines with delegation for hierarchical structures:
Multisig requires coordinating multiple signers:
Synchronous Signing: All signers present simultaneously
Asynchronous Signing: Signatures collected over time
Escrow Mechanisms: Events held until threshold satisfied
Key Distribution: Each signer needs their private key
Key Rotation Coordination: Rotating multisig keys requires cooperation
Threshold Selection: Choosing appropriate thresholds
Signature Verification Cost: Linear in number of signatures
Event Size: Grows with number of signatures
Network Coordination: Asynchronous signing requires message passing
Threshold Selection: Use ample calculations
Key Isolation: Keep signing keys on separate systems
Pre-Rotation: Always use pre-rotation for multisig
Witness Configuration: Use sufficient witnesses
Threshold Checking: For weighted thresholds, sum the weights of valid signatures and compare to the threshold. For fractional weights, use exact rational arithmetic to avoid floating-point errors.
Insufficient Signatures: If an event has fewer than threshold signatures, place it in escrow rather than rejecting it immediately. It may receive additional signatures later.
Invalid Signatures: Log which signatures failed verification for debugging. This helps identify compromised keys or implementation bugs.
Threshold Violations: If a rotation event doesn't satisfy both current and next thresholds, reject it as unauthorized. This prevents rotation attacks even if current keys are compromised.
Caching: Cache verified events and key states to avoid redundant verification. Invalidate caches when new events are received.
Batch Processing: When processing multiple events, batch signature verifications to amortize setup costs.
Parallel Verification: Verify signatures from different events in parallel, as they are independent operations.
Key Isolation: Ensure each multisig participant's key is stored on a separate system. This prevents a single compromise from gaining control.
Pre-Rotation: Always use pre-rotation for multisig identifiers. This provides recovery capability even if current signing keys are compromised.
Witness Configuration: Use at least 5 witnesses with a threshold of 3 or higher. This provides Byzantine fault tolerance and prevents single witness control.
Audit Logging: Log all multisig operations, including who signed what and when. This provides accountability and helps detect unauthorized access attempts.