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.
A controller is an entity (person, organization, or autonomous software) that possesses the cryptographic private keys necessary to prove control authority over an Autonomic Identifier (AID) and make changes to its associated Key Event Log (KEL). In multi-sig configurations, a controller may consist of multiple controlling entities operating under threshold signature schemes.
In the KERI protocol, a controller represents the fundamental locus of authority over an identifier. The controller is the entity that possesses the private cryptographic keys associated with an AID and can therefore cryptographically prove control authority through digital signatures. This control authority enables the controller to:
The controller concept is central to KERI's security model because it establishes who has the authority to make authoritative statements about an identifier's key state. Unlike traditional PKI systems where control authority is mediated by certificate authorities, KERI's controllers exercise direct cryptographic control without intermediaries.
Cryptographic Authority: Control is proven through possession and use of private keys, not through administrative processes or trusted third parties. The controller must be able to generate valid signatures using the current authoritative key set.
Persistence Through Rotation: Controllers maintain persistent control over identifiers even as the underlying cryptographic keys change. The pre-rotation mechanism ensures that only the legitimate controller can authorize key rotations, even if current signing keys are compromised.
Controllers must implement appropriate key storage based on their security requirements:
High Security (HSM/TEE): For organizational identifiers, credential issuers, or high-value applications, controllers should use Hardware Security Modules or Trusted Execution Environments. These provide physical protection against key extraction.
Medium Security (Encrypted Keystores): For personal identifiers or moderate-value applications, encrypted keystores with strong passphrases provide reasonable security. The KERI KLI uses LMDB-based encrypted keystores protected by user-supplied passcodes.
Distributed Security (MPC/Multi-sig): For organizational scenarios, distributing key material across multiple parties using multi-party computation or multi-signature schemes provides resilience against single-party compromise.
Controllers should carefully configure their witness pools:
Minimum Witnesses: At least 3 witnesses are recommended for production use. The TOAD (Threshold of Accountable Duplicity) should be set to ensure sufficient witness confirmation.
Witness Diversity: Select witnesses from different geographic locations, jurisdictions, and organizations to resist localized attacks or coordinated compromise.
Witness Availability: Ensure witnesses have high uptime and reliable network connectivity. Witness unavailability can prevent key rotations and event propagation.
Controllers should establish clear key rotation policies:
Routine Rotation: Regular key rotation (e.g., annually) limits the exposure window for any single key set. This is particularly important for long-lived identifiers.
Emergency Rotation: Procedures for rapid rotation in case of suspected compromise should be documented and tested. This includes secure storage and access to pre-rotated keys.
Pre-rotation Key Management: Pre-rotated keys must be generated securely and stored separately from current signing keys. Loss of pre-rotated keys prevents future rotations.
For multi-sig controllers:
Threshold Selection: Use the "ample" calculation to ensure immune agreement. The threshold should balance security (higher is more secure) against operational availability (higher makes operations more difficult).
Signing Coordination: Establish clear procedures for collecting signatures from multiple parties. This may involve secure communication channels and time-bounded signing windows.
Separable Authority Types: KERI distinguishes between signing authority (the right to sign non-establishment events) and rotation authority (the right to rotate keys). This separation enables sophisticated delegation patterns, such as custodial arrangements where an agent holds signing authority while the controller retains rotation authority.
Multi-Entity Control: A controller may consist of multiple entities in multi-signature configurations. The complete set of controlling entities collectively constitutes the controller, with threshold schemes determining how many signatures are required for operations.
The controller concept applies specifically to the management of AIDs and their KELs. Controllers do not necessarily control the data or credentials associated with an identifier—they control the identifier itself and its key state. For example, a controller of a Legal Entity vLEI credential controls the AID used to sign the credential, but the Legal Entity itself (the subject of the credential) may be a separate entity.
Controllers are distinguished from other roles in the KERI ecosystem:
The concept of cryptographic control over identifiers has roots in public key cryptography and self-certifying identifiers. Traditional PKI systems established control through certificate authorities that vouched for the binding between identifiers and public keys. However, this administrative trust model created centralized points of failure and made identifiers non-portable.
The W3C DID specification introduced the concept of DID controllers as entities capable of making changes to DID documents. However, many DID methods still rely on ledgers or other shared infrastructure to establish control authority, creating dependencies on external systems.
KERI's controller concept evolved from earlier work on self-certifying identifiers and autonomic namespaces, where the goal was to create identifiers that could be controlled purely through cryptographic means without any dependency on external infrastructure or trusted third parties.
KERI controllers exercise authority through self-certifying identifiers where the identifier itself is cryptographically derived from the controlling keys. This creates a direct, verifiable binding between the identifier and its controller without requiring external registries or certificate authorities.
The inception event that creates an AID includes:
This inception event is signed by the controller using the initial private keys, establishing the cryptographic root of trust for the identifier.
The Key Event Log (KEL) serves as the authoritative record of all control authority changes. Every event in the KEL must be signed by the controller using the current authoritative keys at the time of the event. This creates an append-only, cryptographically verifiable history of control authority.
The KEL enables:
KERI's pre-rotation mechanism is fundamental to how controllers maintain persistent control. In each establishment event (inception or rotation), the controller makes a cryptographic commitment to the next set of rotation keys by including digests of those keys.
This creates a critical security property: even if the current signing keys are compromised, an attacker cannot rotate to their own keys because they don't possess the pre-rotated keys whose digests were committed in the previous event. Only the legitimate controller, who generated and stored the pre-rotated keys, can perform the next rotation.
This mechanism enables:
KERI supports sophisticated multi-signature control configurations where multiple entities collectively act as the controller. This is implemented through:
Threshold Schemes: The current threshold (kt) specifies how many signatures from the current key set are required for non-establishment events. The next threshold (nt) specifies requirements for the next rotation.
Weighted Thresholds: KERI supports fractionally-weighted thresholds where different keys have different weights, and the combined weight must exceed the threshold.
Partial Rotation: In multi-sig configurations, not all pre-rotated keys need to be exposed in each rotation. This enables reserve keys and graduated security models.
Multi-sig control is essential for organizational use cases where multiple parties must cooperatively authorize actions, such as:
Controllers can delegate authority to other AIDs, creating hierarchical control structures. In a delegation:
Delegator: The controller of the delegating AID that authorizes the creation of a delegated AID Delegate: The controller of the delegated AID that receives delegated authority
Delegation is cooperative, meaning both delegator and delegate must participate in establishment events for the delegated identifier. The delegator anchors the delegate's establishment events in their own KEL, creating a verifiable chain of authority.
This enables:
KERI's separation of signing and rotation authority enables custodial arrangements where:
Custodial Agent: Holds signing authority and can sign non-establishment events on behalf of the controller Principal Controller: Retains rotation authority and can "fire" the custodian by rotating keys
This is implemented through partial rotation where:
This pattern is critical for:
In credential systems, it's important to distinguish:
Controller of the Issuer AID: The entity that controls the cryptographic keys used to sign credentials Subject of the Credential: The entity about whom claims are made in the credential
These may be the same entity (self-issued credentials) or different entities (third-party issued credentials). For example:
Individual Identity Management: Individuals control AIDs for their personal digital identity, maintaining control over their identifiers across different contexts and service providers. The controller can rotate keys if a device is lost or compromised, maintaining persistent identity.
Organizational Identity: Legal entities control AIDs representing their organizational identity. Multi-sig configurations ensure that multiple executives must authorize key operations, preventing single points of failure.
IoT Device Management: Autonomous devices can be controllers of their own AIDs, enabling machine-to-machine authentication and authorization without human intervention. Manufacturers can delegate authority to devices while retaining ultimate control.
Credential Issuance: Credential issuers control AIDs used to sign verifiable credentials. The KEL provides an auditable history of the issuer's key state, enabling verifiers to check that credentials were signed with authoritative keys.
Supply Chain Tracking: Each participant in a supply chain controls AIDs used to sign transfer-of-custody events. The chain of controllers creates a verifiable provenance trail for physical goods.
Cryptographic Verifiability: Control authority can be verified purely through cryptographic operations on the KEL, without requiring trust in external infrastructure or authorities.
Portability: Controllers can move their identifiers between different systems and infrastructure providers without losing control. The KEL is the authoritative record, not any particular storage system.
Recovery from Compromise: The pre-rotation mechanism enables controllers to recover from key compromise by rotating to pre-rotated keys that were never exposed.
Flexible Delegation: Controllers can delegate authority in sophisticated ways, from simple custodial arrangements to complex organizational hierarchies, while maintaining ultimate control.
Duplicity Detection: The KEL structure makes duplicitous behavior by controllers evident. If a controller creates conflicting versions of their KEL, this can be detected by comparing logs from different sources.
Key Management Burden: Controllers bear full responsibility for protecting their private keys. Unlike systems with account recovery mechanisms, losing all copies of private keys means permanent loss of control over the identifier.
Operational Complexity: Multi-sig configurations and delegation hierarchies require careful coordination between multiple parties. Threshold schemes must be designed to balance security against operational availability.
Witness Coordination: Controllers must maintain relationships with witnesses to ensure their KEL is properly witnessed and available. Witness selection and management adds operational overhead.
Rotation Latency: Key rotations require coordination with witnesses and propagation through the ecosystem. This creates latency between initiating a rotation and having it universally recognized.
Custodial Trust: While custodial arrangements enable convenient key management, they require trusting the custodian not to abuse signing authority. The principal retains rotation authority but must monitor custodian behavior.
Key Storage: Controllers must implement secure key storage appropriate to their security requirements. Options include:
Witness Selection: Controllers should select witnesses based on:
Threshold Configuration: Multi-sig thresholds should be set considering:
Rotation Policies: Controllers should establish policies for:
Delegation Strategies: When delegating authority, controllers should:
Partial Rotation: Consider using partial rotation to keep some keys in reserve, providing additional security layers and recovery options.
When delegating authority:
Scope Definition: Clearly define what authority is being delegated. Document whether delegates can further delegate (recursive delegation) or only perform specific operations.
Monitoring: Implement monitoring of delegate behavior. The delegator should regularly review the delegate's KEL for unexpected events.
Revocation Procedures: Establish clear procedures for revoking delegated authority, including how to communicate revocation to relying parties.
For custodial control patterns:
Authority Separation: Ensure signing authority and rotation authority are properly separated. The custodian should never have access to pre-rotated keys.
Monitoring and Auditing: The principal controller should monitor the custodian's use of signing authority and be prepared to rotate keys if abuse is detected.
Recovery Procedures: Document procedures for the principal to recover control by rotating to new keys, potentially with a different custodian.
When using KERIA agents:
Client-Agent Relationship: The Signify client (edge) maintains the controller's private keys. The KERIA agent (cloud) manages KEL storage and witness coordination but never has access to private keys.
Delegated Agent AID: The KERIA agent has its own AID that is delegated from the client's AID. This enables the agent to perform operations on behalf of the controller while maintaining clear authority boundaries.
Passcode Security: The client's passcode (bran) is used to derive keys. This passcode must be protected and should never be transmitted to the agent.
Controllers should be aware that their behavior is subject to duplicity detection:
Consistent KEL Publication: Controllers must ensure they publish consistent versions of their KEL to all witnesses and watchers. Publishing conflicting versions will be detected as duplicitous behavior.
Witness Coordination: All witnesses should receive the same events in the same order. Controllers should not attempt to present different event sequences to different witnesses.
Watcher Networks: Validators may use watcher networks to compare KEL versions from multiple sources. Controllers should assume their KEL will be widely observed and compared.