Loading vLEI.wiki
Fetching knowledge base...
Fetching knowledge base...
This comprehensive explanation has been generated from 21 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.
KRAM (KERI Request Authentication Method) is a non-interactive authentication protocol that provides replay attack protection by requiring all web client requests to include an ISO-8601 formatted timestamp that must fall within an acceptable time window relative to the server's current time, enabling scalable, path-independent end-to-end verifiability without challenge-response handshakes.
KRAM (KERI Request Authentication Method) is a non-interactive authentication protocol specifically designed for KERI-based systems that need to authenticate requests without the overhead of interactive challenge-response exchanges. The protocol accomplishes replay attack protection through timestamp-based validation while maintaining the zero-trust security model fundamental to KERI.
KRAM solves a critical problem in decentralized identity systems: how to provide scalable, secure authentication for high-volume request processing without requiring synchronous interactive handshakes. Traditional authentication mechanisms rely on challenge-response protocols where the server issues a challenge (typically a nonce), the client responds with a signed challenge, and the server validates the response. While secure, this approach:
KRAM eliminates these limitations by making each request self-authenticating through the inclusion of a timestamp that serves as a time-bound nonce. The server validates that the timestamp falls within an acceptable window, preventing replay attacks without requiring prior interaction.
KRAM is employed in several critical KERI ecosystem contexts:
The choice of window parameters (d, l, m) significantly impacts both security and usability:
Narrow windows (2-3 seconds): Provide stronger replay attack protection but require:
Wide windows (10+ seconds): Improve reliability but:
Document 2 extensively discusses this trade-off in the context of group multi-sig coordination, noting that Simple KRAM's narrow window is "impractical" for operations requiring human coordination across hours or days.
KRAM assumes "reasonably synchronized clocks" between client and server. Implementation must:
Client-side:
Server-side:
Simple KRAM is stateless, providing scalability benefits but limiting replay protection to the timestamp window. Extended KRAM variants introduce state (nonce tracking) for extended protection:
Stateless (Simple KRAM):
Stateful (Extended KRAM):
KERIA Agent Communications: All requests from Signify clients to KERIA cloud agents must use KRAM for authentication. This is documented in Document 17, which specifies that "All requests must be signed by the Client AID using the Signify Request Authentication mechanism."
SKRAP Protocol: KRAM forms the foundation of the Signify/KERIA Request Authentication Protocol, which defines the complete authentication framework between lightweight clients and cloud agents.
vLEI Verification Services: The vLEI Verifier Router (Document 19) implements KRAM for signed header verification, with a dedicated endpoint POST /signed-headers-verification that validates AID, signature, and serialized data using KRAM principles.
Web-Based KERI Applications: Any web client interacting with KERI infrastructure requires KRAM to ensure requests cannot be captured and replayed by attackers.
The KRAM protocol involves two primary participants:
Requester (Client): The entity making authenticated requests, typically:
Replier (Server): The entity receiving and validating requests, typically:
Critically, Document 11 emphasizes that "the date-time stamps are controlled by the replier (the system responding to requests) rather than the querier (the system making requests)." This design prevents attackers from manipulating timestamps to replay old authenticated messages.
The client prepares an authenticated request by:
Constructing the request body: The client creates the request payload containing the operation to be performed (e.g., creating an AID, issuing a credential, querying key state).
Adding timestamp field: The client includes a datetime field in the request body formatted according to ISO-8601 standard. Document 1 specifies: "All requests from web clients must include a datetime string field in the request body... The datetime must be formatted according to the ISO-8601 standard."
Signing the request: The client uses its private key to create a digital signature over the entire request body, including the timestamp. This signature proves:
The signed request is transmitted to the server. Unlike interactive authentication, no prior handshake is required. The request is self-contained with all authentication information embedded.
Upon receiving the request, the server performs timestamp validation:
Extract timestamp: Parse the ISO-8601 datetime string from the request body.
Calculate time window: Document 3 provides the detailed formula for the acceptance window. For Simple KRAM, the window is defined as [t-d-m*l, t+d] where:
t = current time at recipient (server)d = clock drift/skew (typically 0.01-0.1 seconds)l = average network latency (typically 1 second)m = integer multiple (typically 3)This creates a window typically spanning 3-4 seconds, accounting for:
Validate timestamp: Check if the request timestamp falls within the calculated window. If the timestamp is:
If the timestamp is valid, the server:
Retrieve public key: Look up the current public key for the claimed AID by querying the KEL (Key Event Log).
Verify signature: Use the public key to verify the signature over the request body. This confirms:
Check key state: Ensure the signing key is currently authoritative according to the key state in the KEL. This prevents use of stale keys from previous rotations.
Based on validation results:
Success path: If both timestamp and signature are valid, the server processes the request and returns a signed response. Document 17 specifies: "All responses are expected to be signed by the Agent AID, establishing bidirectional cryptographic verification."
Failure path: If validation fails, the server rejects the request with an appropriate error code indicating:
KRAM is designed to be stateless from the server's perspective:
This stateless design enables:
The protocol includes several critical decision points:
Window size configuration: Administrators must balance security (narrow window) against reliability (wider window to accommodate network variability). Document 2 discusses this trade-off extensively in the context of group multi-sig coordination.
Clock synchronization requirements: Systems must decide whether to require NTP synchronization or allow larger drift parameters.
Replay attack tolerance: Some applications may accept slightly wider windows for usability, while high-security applications require tighter constraints.
Digital Signature Algorithm: KRAM requires asymmetric cryptography for signing requests. KERI supports multiple signature schemes through derivation codes:
Signature Coverage: The signature must cover the entire request body including the timestamp field. Partial signatures are not acceptable as they would allow timestamp manipulation.
Key State Verification: The server must verify signatures against the current authoritative keys from the KEL, not cached or stale keys. This requires:
Clock Synchronization: Document 3 emphasizes that KRAM assumes "reasonably synchronized clocks" between client and server. Best practices include:
d based on measured clock accuracyNetwork Latency: The window must accommodate typical network latency. The multiplier m (typically 3) provides buffer for:
Window Size Trade-offs: Document 2 identifies a critical limitation of Simple KRAM: "The acceptance window is defined as [t-d-m*l, t+d]... This creates a narrow time window (typically 3-4 seconds) within which all signatures on a group multi-sig message must arrive."
For group multi-sig scenarios requiring loose coordination (hours to weeks), this narrow window is impractical. The document proposes Extended KRAM variants that use:
Timestamp Rejection: When a timestamp falls outside the acceptable window:
Signature Verification Failure: When signature validation fails:
Key State Issues: When the signing key is not authoritative:
Replay Detection: If the same timestamp appears multiple times:
This is the primary use case documented in Document 17:
Client prepares request: A Signify web client needs to create a new AID. It constructs a request body containing:
{
"operation": "inception",
"datetime": "2024-01-15T14:30:00.000Z",
"parameters": {
"transferable": true,
"witnesses": ["witness1", "witness2"],
"threshold": 2
}
}
Client signs request: The client uses its private key to sign the entire JSON body.
Client sends request: The signed request is sent to the KERIA agent's Admin Interface.
Agent validates: The KERIA agent:
Agent responds: The agent returns a signed response containing the new AID and inception event.
Document 19 describes KRAM usage in credential verification:
Holder prepares presentation: A vLEI credential holder constructs a presentation request including:
Holder signs presentation: The holder signs the presentation with their AID's private key.
Presentation submitted: The signed presentation is sent to the vLEI Verifier Router's /presentation endpoint.
Router validates: The router:
Verifier processes: The verifier checks:
When a controller submits a key event to witnesses:
Controller creates event: A rotation event is created with new keys.
Controller adds timestamp: Current timestamp is included in the event submission.
Controller signs: The event is signed with current authoritative keys.
Submission to witnesses: The signed event is sent to all configured witnesses.
Witness validation: Each witness:
Client-Side Clock Management:
Server-Side Configuration:
Security Hardening:
Group Multi-Sig Considerations: Document 2 provides extensive guidance for group scenarios:
KERI Protocol Stack Integration:
Witness and Watcher Integration:
Credential Lifecycle Integration:
Multi-Tenant Environments:
Document 2 proposes several Extended KRAM variants:
Nonce-Based Extended KRAM:
Hybrid KRAM:
Escrow-Aware KRAM:
Document 3 provides detailed comparison:
FIDO2/WebAuthn:
KRAM:
Document 3 emphasizes KRAM's role in zero-trust architectures:
This aligns with KERI's broader goal of providing ambient verifiability for all identity operations.
Document 2 identifies that Simple KRAM's narrow window creates "coordination challenges" for group multi-sig scenarios. Implementations must:
Assess coordination timeframes: Determine if group members can coordinate within 3-4 seconds or require extended timeframes
Choose appropriate KRAM variant:
Implement escrow mechanisms: Allow partial signatures to accumulate over time while maintaining security
Document governance policies: Clearly specify expected signing timeframes and procedures
Never reveal server time: Error messages must not disclose the server's current time, as this enables timing attacks
Rate limiting: Implement progressive delays for repeated authentication failures to prevent:
Logging and monitoring: Track all authentication failures for security analysis:
Key state validation: Always verify signatures against current authoritative keys from the KEL, never cached or stale keys
KRAM operates at the application layer but must integrate with lower-level KERI components:
Distinguish error types: Provide different error codes for:
Provide actionable feedback: Error messages should guide clients toward resolution:
Implement retry logic: Clients should automatically retry with fresh timestamps on certain failures