Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 11 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.
Access-controlled interaction is a KERI protocol pattern for managing actions requiring authorization (such as report submission), where infrastructure components like load balancers must implement deduplication mechanisms to drop repeated requests for resources that already exist in the system, primarily to prevent DDoS attacks through resubmission rather than traditional replay attacks.
Access-controlled interaction is a term that emerged from technical discussions within the KERI Suite development community, specifically from a conversation between Samuel Smith, Daniel Hardman, and Lance Byrd during a January 16, 2024 Zoom meeting. The concept addresses how KERI-based systems handle operations that require authorization enforcement before execution.
The available source material on this topic is intentionally minimal, consisting primarily of stub definitions and meeting notes rather than formal specifications. This reflects the early-stage nature of the concept within the KERI protocol's development process.
Access-controlled interactions are actions that require protective mechanisms to ensure proper authorization and prevent resource abuse. The canonical example provided in all source documents is report submission - a scenario where a system must control who can submit reports and prevent the same report from being submitted multiple times.
The fundamental challenge addressed is: when a report has already been submitted and exists in the system, how should the infrastructure handle repeated submission attempts?
A critical clarification emphasized across all source documents is that replay attacks are "less of a concern" in access-controlled interactions. Instead, the primary security threat is DDoS (Distributed Denial of Service) attacks that exploit the ability to resubmit requests.
This distinction is important because it shifts the focus from traditional replay attack mitigation (which typically involves timestamps, nonces, or sequence numbers) to resource exhaustion prevention. The threat model is not about an attacker replaying captured requests to impersonate someone or repeat a transaction maliciously, but rather about an attacker (or even a legitimate but misbehaving client) overwhelming system resources by repeatedly submitting the same request.
The deduplication mechanism is the cornerstone of access-controlled interactions. Implementers must carefully design the deduplication index:
Storage Backend: Choose a storage backend that supports:
Options include Redis, Memcached, or distributed caches like Hazelcast.
Expiration Strategy: Implement time-based expiration to prevent unbounded growth:
Distributed Coordination: In multi-node deployments:
Caching Strategy: Cache frequently accessed data:
Use appropriate cache invalidation strategies based on KEL and TEL update patterns.
Signature Verification: Optimize cryptographic operations:
Early Rejection: Reject invalid requests as early as possible:
This ordering minimizes resource consumption for invalid requests.
Rate Limiting: Implement per-controller rate limiting:
The technical requirement specified in the source documents is straightforward: load balancers must have mechanisms to drop repeated requests for resources that already exist in the system.
This deduplication must occur at the infrastructure edge (the load balancer level) rather than in backend services. By implementing deduplication at this level, the system:
The source documents do not specify how this deduplication mechanism should be implemented - whether through in-memory caches, distributed state, or other approaches. This remains an implementation detail left to system architects.
The source documents consistently reference registration-interaction as a related concept. The registration interaction provides important context for understanding access-controlled interactions more broadly.
A registration interaction is described as a "setup/registration interaction" involving:
The key concern articulated is preventing credential capture and misuse during presentation. The solution suggested is narrowing the credential's scope to a specific role (exemplified as "Document Submitter") through delegatable authority. This represents a form of pre-registration that limits what actions can be performed with a presented credential.
The source documents raise several unresolved questions about authentication requirements in access-controlled interactions, particularly regarding credentials functioning as bearer tokens:
The consistent answer across sources is: "Depends on the context."
This context dependency is influenced by several factors mentioned in the documents:
Process Idempotency: In idempotent processes where resubmission has no effect, signature requirements may differ from non-idempotent scenarios. If repeating an operation causes no harm, the authentication requirements might be relaxed.
Governance Model: The governing framework determines signature requirements. Different governance models may mandate different levels of authentication based on their risk profiles and trust assumptions.
Operational Context: The specific use case and threat model influence whether issuee signatures are necessary for credential delivery.
The source material explicitly notes that "depending on the context or governance model the issuance itself needs / should / could be signed," indicating variability rather than prescriptive requirements.
The documents describe credentials in access-controlled interactions as being "like a bearer token" that serves as proof of authorization. This characterization has important implications:
A bearer token, in traditional security systems, grants authority to whoever possesses it, regardless of the bearer's identity. Similarly, in some KERI access-controlled interaction contexts, possession of a valid credential may be sufficient for authorization, independent of whether the bearer is the original issuee.
However, the source documents make clear this is not a universal rule. The bearer token analogy describes one possible authentication model within access-controlled interactions, not the only model. Systems implementing access-controlled interactions must determine, based on their context and governance framework, whether:
While the documents state that replay attacks are "less of a concern," they acknowledge that replay attack prevention is still critical when resubmission is used as a vector for DDoS attacks. The implementation of replay prevention depends on:
The source material does not provide specific technical mechanisms for replay prevention (such as nonce validation, timestamp checking, or sequence number verification). These implementation details are left unspecified.
An important pattern mentioned in the registration interaction context is using delegatable authority to narrow credential scope to specific roles. While this is discussed in relation to registration interactions specifically, it represents a broader principle applicable to access-controlled interactions generally.
By limiting a credential's authority to a specific role (like "Document Submitter"), the system:
This scope narrowing functions as a form of pre-registration, establishing limited authority before the actual protected operation is attempted.
The source material is explicitly exploratory, raising questions rather than providing definitive answers:
These questions reflect the early-stage nature of access-controlled interaction as a concept within KERI's development. The term captures important principles (DDoS prevention through deduplication, context-dependent authentication, credential scope narrowing) while leaving implementation details and specific requirements to be determined based on use case requirements.
The available documentation on access-controlled interactions is minimal by design. The source documents consist of:
This reflects an emerging concept where core principles have been identified, but detailed specifications, implementation patterns, and formal requirements remain to be developed by the KERI community.
Implementers working with access-controlled interactions should understand that they are working with a conceptual framework rather than a fully specified protocol element. The emphasis on DDoS prevention through load balancer deduplication represents the most concrete technical requirement, while authentication requirements remain context-dependent and subject to governance framework decisions.
Monitoring and Alerting: Implement comprehensive monitoring:
Audit Logging: Log all access-controlled interactions:
Ensure logs are tamper-evident and retained for compliance requirements.
The source documents emphasize that security requirements "depend on the context." Provide configuration options for:
Idempotency Mode: Allow operators to configure whether operations are idempotent:
Governance Model: Support different governance models:
Replay Protection Level: Allow tuning of replay protection:
KEL Access: Ensure efficient access to controller KELs:
TEL Integration: For credential verification:
Witness Coordination: When verifying key state:
Duplicate Detection: When duplicates are detected:
Authorization Failures: When authorization fails:
Backend Failures: When backend processing fails:
Deduplication Testing: Verify deduplication works correctly:
Security Testing: Verify security properties:
Performance Testing: Verify performance under load:
Monitoring Dashboards: Create dashboards showing:
Capacity Planning: Plan capacity based on:
Incident Response: Prepare for:
Implement runbooks for common scenarios and ensure monitoring alerts trigger appropriate responses.