Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 175 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.
Key state is the complete set of currently authoritative keypairs for an AID plus all information necessary to secure or establish control authority, including current keys, prior next key digests, current thresholds, prior next thresholds, witnesses, witness thresholds, and configurations.
Key state represents the complete cryptographic and governance configuration required to manage an AID (Autonomic Identifier) at any given point in time. As defined in the IETF KERI specification, key state is the authoritative snapshot of all information needed to verify control authority over an identifier.
The key state structure encompasses multiple components that work together to establish and verify control:
Current Authoritative Keys: The set of public keys that currently have signing authority over the identifier. These keys are used to sign non-establishment events and validate the controller's authority for day-to-day operations.
Pre-Rotated Key Commitments: Cryptographic digests of the next set of keys that will become authoritative in the subsequent rotation event. This pre-rotation mechanism is fundamental to KERI's security model, providing forward security and enabling recovery from key compromise.
Threshold Structures: Both current and next thresholds that define how many signatures are required from the key sets. These thresholds enable multi-signature schemes and flexible governance models.
Witness Configuration: The set of witnesses designated to provide receipts for key events, along with the witness threshold defining how many witness signatures are required for event validation.
Implementations MUST process the entire KEL from inception to derive accurate key state. Skipping events or processing out of order will result in incorrect key state. The processing algorithm must:
Implementations must support both simple integer thresholds and fractional weight thresholds. For rotation events, BOTH the prior next threshold (from the previous establishment event) AND the current threshold (from the new key state) must be satisfied. This dual-threshold requirement is critical for security.
When processing a rotation event, implementations MUST verify that:
Failure to properly verify pre-rotation commitments undermines KERI's security model.
For identifiers using indirect mode (with witnesses), implementations should:
Implementations MUST implement duplicity detection by:
For identifiers with long KEL histories:
Configuration Data: Additional metadata including whether the identifier is transferable, delegation information if the identifier is delegated, and other protocol-specific settings.
Key state is derived from processing the Key Event Log (KEL) for an identifier. While the KEL contains the complete history of all key events, the key state represents the current authoritative configuration at a specific sequence number.
The key state structure includes the following fields:
i (Identifier): The AID prefix itself, which is the self-certifying identifier derived from the inception event.
s (Sequence Number): The sequence number of the most recent establishment event that defines this key state. This is critical for determining which key state is authoritative at any point in time.
d (Digest): The SAID (Self-Addressing Identifier) of the establishment event that created this key state. This provides cryptographic binding to the specific event.
t (Event Type): The type of the last establishment event (icp for inception, rot for rotation, dip for delegated inception, drt for delegated rotation).
k (Current Keys): An ordered list of the current authoritative public keys. Each key is represented as a CESR-encoded qualified cryptographic primitive.
kt (Current Threshold): The signing threshold for the current key set. This can be a simple integer (e.g., "2" meaning 2-of-N signatures required) or a fractional weight specification for more complex threshold schemes.
n (Next Key Digests): An ordered list of cryptographic digests representing commitments to the next set of keys. These digests are revealed during the next rotation event, enabling pre-rotation security.
nt (Next Threshold): The threshold that will apply to the next key set when it becomes current through a rotation event.
b (Backers/Witnesses): An ordered list of witness AIDs that provide key event receipts for this identifier.
bt (Backer Threshold): The number of witness receipts required for an event to be considered properly witnessed. This is also known as the TOAD (Threshold of Accountable Duplicity).
c (Configuration): An array of configuration trait strings that define operational characteristics of the identifier.
di (Delegator Identifier): If this is a delegated identifier, this field contains the AID of the delegating identifier.
Key state information is typically represented in JSON format for human readability and debugging, but can be serialized in any format supported by KERI including CBOR and MessagePack. All cryptographic primitives within the key state use CESR encoding, which provides composable, self-describing representations that work in both text and binary domains.
Example key state representation:
{
"i": "EaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM",
"s": "3",
"d": "ELvaU6Z-i0d8JJR2nmwyYAZAoTNZH3UfSVPzhzS6b5CM",
"t": "rot",
"k": ["DaU6JR2nmwyZ-i0d8JZAoTNZH3ULvYAfSVPzhzS6b5CM"],
"kt": "1",
"n": ["EZ-i0d8JZAoTNZH3ULvaU6JR2nmwyYAfSVPzhzS6b5CM"],
"nt": "1",
"b": [
"BBilc4-L3tFUnfM_wJr4S4OJanAv_VmF_dJNN6vkf2Ha",
"BLskRTInXnMxWaGqcpSyMgo0nYbalW99cGZESrz3zapM"
],
"bt": "2",
"c": [],
"di": ""
}
The size of a key state structure varies based on:
There are no hard limits on these values, but practical considerations around witness coordination and signature collection typically keep witness counts below 20 and key counts below 10 for most applications.
Key state is derived rather than directly created. The initial key state is established through an inception event, which is the first entry in the KEL. The inception event specifies:
Processing the inception event produces the initial key state at sequence number 0. This key state remains authoritative until the next establishment event (typically a rotation) occurs.
Key state is immutable at any given sequence number but evolves through establishment events. The key state can only be modified through:
Rotation Events: A rotation event changes the key state by:
The rotation process follows strict cryptographic rules:
Delegated Rotation Events: For delegated identifiers, rotation requires cooperation between the delegate and delegator, with both parties contributing cryptographic commitments.
Interaction Events: Interaction events do not modify key state. They anchor external data to the current key state without changing any authoritative keys, thresholds, or witnesses.
Verifying key state involves multiple validation steps:
KEL Verification: The validator must process the entire KEL from inception through the target sequence number, verifying:
Witness Receipt Verification: For identifiers using indirect mode, validators should verify that sufficient witness receipts exist for each establishment event, meeting the witness threshold requirement.
Duplicity Detection: Validators must check for duplicity by comparing the KEL against other versions they may have seen. If multiple inconsistent but internally valid KELs exist for the same identifier, this indicates duplicitous behavior by the controller.
Current vs. Historical Key State: Validators must distinguish between:
This distinction is critical for verifying ACDCs (Authentic Chained Data Containers) and other signed statements that reference a specific key state.
Key state is fundamental to multiple KERI-related protocols:
KERI Core Protocol: Key state is the primary mechanism for establishing control authority over AIDs. Every operation that requires proving control (signing events, issuing credentials, making authoritative statements) depends on the current key state.
ACDC Protocol: When issuing ACDCs, the issuer's key state at the time of issuance determines which keys are authoritative for signing the credential. Verifiers must reconstruct the issuer's key state at the issuance sequence number to validate the credential signature.
IPEX Protocol: The Issuance and Presentation Exchange (IPEX) protocol uses key state to verify that presentation and disclosure operations are authorized by the current controller of the presenting identifier.
did:keri and did:webs: These DID methods generate DID Documents by transforming the current key state into W3C DID Document format, mapping current keys to verification methods and witnesses to service endpoints.
Key state lifecycle follows the identifier lifecycle:
Inception Phase: Initial key state is established with the inception event. This defines the starting security posture and governance structure.
Operational Phase: The key state remains stable during normal operations. Non-establishment events are signed using the current key state but don't modify it.
Rotation Phase: When keys need to be rotated (due to compromise, routine security hygiene, or governance changes), a rotation event creates a new key state at the next sequence number.
Delegation Phase: For delegated identifiers, key state changes require coordination with the delegating identifier, adding complexity to the lifecycle.
Recovery Phase: If keys are compromised, the pre-rotation mechanism allows recovery by rotating to the pre-committed next keys, even if the current signing keys are controlled by an attacker.
Abandonment Phase: An identifier can be made non-transferable by rotating to an empty next key digest list with a next threshold of zero, effectively abandoning the identifier and preventing any future rotations.
Key state interacts with several related data structures:
Key Event Log (KEL): The KEL is the source of truth from which key state is derived. The KEL contains the complete history, while key state represents the current snapshot.
Key Event Receipt Log (KERL): A KERL includes both the KEL and witness receipts. Validators use KERLs to verify that the key state has been properly witnessed.
Key State Notice (KSN): A KSN is a signed statement by the controller asserting their current key state. This provides a compact way to communicate key state without requiring the recipient to process the entire KEL.
Transaction Event Log (TEL): TELs for credential registries are anchored to the issuer's KEL. The key state at the time of anchoring determines which keys are authoritative for the registry operations.
Duplicitous Event Log (DEL): When duplicity is detected, the conflicting versions of events are stored in a DEL. Comparing key states derived from different KEL versions reveals the duplicitous behavior.
Key state becomes more complex in multi-signature scenarios:
Threshold Schemes: The kt and nt fields can specify complex threshold requirements. For example, kt: "2" means 2-of-N signatures are required, while fractional weights enable more sophisticated governance (e.g., "2/3" meaning signatures with combined weight of 2 out of total weight 3).
Indexed Signatures: When verifying signatures on events, the indexed signature mechanism indicates which specific key from the key state was used for each signature, enabling efficient verification in multi-sig scenarios.
Partial Rotation: Partial rotation allows rotating only a subset of keys while keeping others in reserve. This creates key states where some next key digests are revealed while others remain blinded.
Custodial Rotation: The key state structure enables custodial rotation patterns where signing authority and rotation authority are split between different key sets, allowing operational delegation while maintaining ultimate control.
For delegated identifiers, key state includes additional complexity:
Delegator Reference: The di field contains the delegating identifier's AID, establishing the delegation relationship.
Cooperative Rotation: Rotation of a delegated identifier requires both the delegate's signature (satisfying the delegate's thresholds) and the delegator's approval (through an anchoring seal in the delegator's KEL).
Delegation Recovery: The delegator can supersede the delegate's key state through a superseding rotation, enabling recovery from delegate key compromise.
Nested Delegation: Delegated identifiers can themselves delegate to other identifiers, creating delegation trees where key state verification must traverse the entire delegation chain.
Applications need mechanisms to discover and verify key state:
OOBI (Out-Of-Band Introduction): OOBIs provide URLs for discovering an identifier's KEL and witnesses, enabling key state verification.
Key State Queries: The KERI protocol includes query messages that allow validators to request the current key state from witnesses or watchers.
Watcher Networks: Watchers maintain copies of KELs and can provide key state information to validators, enabling ambient verifiability.
Key State Caching: Validators may cache key state to avoid repeatedly processing the entire KEL, but must implement cache invalidation when new events are discovered.
Key state provides several critical security properties:
Cryptographic Binding: The key state is cryptographically bound to the KEL through the event SAID, preventing tampering.
Forward Security: Pre-rotation provides forward security by committing to future keys before they're exposed, protecting against certain classes of key compromise.
Duplicity Evidence: Inconsistent key states for the same identifier at the same sequence number provide cryptographic proof of duplicitous behavior.
Threshold Flexibility: The threshold mechanism enables flexible governance models while maintaining cryptographic security.
Witness Validation: The witness configuration in key state enables distributed validation without requiring a shared ledger or consensus mechanism.
Implementing key state management requires careful attention to:
KEL Processing: Implementations must correctly process all event types and maintain accurate key state as events are added to the KEL.
Threshold Validation: Both simple integer thresholds and fractional weight thresholds must be correctly validated during signature verification.
Pre-Rotation Verification: Implementations must verify that rotation events correctly reveal previously committed next keys.
Witness Receipt Handling: For indirect mode identifiers, implementations must collect and verify witness receipts to ensure proper witnessing.
Duplicity Detection: Implementations should maintain mechanisms for detecting and handling duplicitous KELs.
Performance Optimization: For identifiers with long KEL histories, implementations may need to cache key state and implement incremental updates rather than reprocessing the entire KEL for each verification.
Key state is the cornerstone of KERI's security model, providing the authoritative configuration that enables verifiable control over identifiers without requiring centralized infrastructure or shared consensus mechanisms.
When implementing multi-sig support:
For delegated identifiers:
di fieldImplementations should handle:
Comprehensive testing should cover:
To ensure interoperability: