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."

Key Participants

The KRAM protocol involves two primary participants:

1. Requester (Client): The entity making authenticated requests, typically:

   • A Signify client application
   • A web browser with KERI capabilities
   • A mobile application using KERI identity
   • An automated service with a controller-managed AID

2. Replier (Server): The entity receiving and validating requests, typically:

   • A KERIA agent providing cloud services
   • A witness accepting key event submissions
   • A verifier processing credential presentations
   • Any KERI-aware service endpoint

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.

Process Flow

Step 1: Request Preparation

The client prepares an authenticated request by:

1. 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).

2. 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."

3. 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 request originated from the claimed AID
   • The request has not been tampered with
   • The timestamp was included at signing time

Step 2: Request Transmission

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.

Step 3: Timestamp Validation

Upon receiving the request, the server performs timestamp validation:

1. Extract timestamp: Parse the ISO-8601 datetime string from the request body.

2. 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:

   • Network transmission delays
   • Clock synchronization differences between client and server
   • Processing time variations

3. Validate timestamp: Check if the request timestamp falls within the calculated window. If the timestamp is:

   • Too old: The request is rejected as potentially replayed
   • Too new: The request is rejected as potentially from a client with incorrect clock
   • Within window: Proceed to signature verification

Step 4: Signature Verification

If the timestamp is valid, the server:

1. Retrieve public key: Look up the current public key for the claimed AID by querying the KEL (Key Event Log).

2. Verify signature: Use the public key to verify the signature over the request body. This confirms:

   • The request was signed by the holder of the private key
   • The request body (including timestamp) has not been modified
   • The claimed AID is authentic

3. 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.

Step 5: Request Processing or Rejection

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:

  • Timestamp out of acceptable window (potential replay attack)
  • Invalid signature (authentication failure)
  • Unknown or revoked AID (authorization failure)

State Changes

KRAM is designed to be stateless from the server's perspective:

• No session state: The server does not maintain session information between requests
• No nonce tracking: Unlike challenge-response protocols, the server does not need to track issued challenges
• Timestamp window only: The only state consideration is the server's current time and configured window parameters

This stateless design enables:

• Horizontal scaling across multiple server instances
• Load balancing without session affinity requirements
• Simplified server implementation

Decision Points

The protocol includes several critical decision points:

1. 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.

2. Clock synchronization requirements: Systems must decide whether to require NTP synchronization or allow larger drift parameters.

3. Replay attack tolerance: Some applications may accept slightly wider windows for usability, while high-security applications require tighter constraints.

Technical Requirements

Cryptographic Requirements

1. Digital Signature Algorithm: KRAM requires asymmetric cryptography for signing requests. KERI supports multiple signature schemes through derivation codes:

   • Ed25519 (default, recommended)
   • ECDSA with secp256k1
   • ECDSA with secp256r1
   • Post-quantum algorithms (future support)

2. 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.

3. Key State Verification: The server must verify signatures against the current authoritative keys from the KEL, not cached or stale keys. This requires:

   • Access to the complete KEL for the signing AID
   • Ability to compute current key state
   • Validation of witness receipts if required by the AID's configuration

Timing Considerations

1. Clock Synchronization: Document 3 emphasizes that KRAM assumes "reasonably synchronized clocks" between client and server. Best practices include:

   • NTP (Network Time Protocol) synchronization on both client and server
   • Monitoring clock drift and alerting on excessive skew
   • Configuring drift parameter d based on measured clock accuracy

2. Network Latency: The window must accommodate typical network latency. The multiplier m (typically 3) provides buffer for:

   • Variable network conditions
   • Packet retransmission
   • Processing delays

3. 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:

   • Longer-lived timestamps with explicit expiration
   • Nonce-based replay protection for extended timeframes
   • Hybrid approaches combining timestamp and nonce mechanisms

Error Handling

1. Timestamp Rejection: When a timestamp falls outside the acceptable window:

   • Return HTTP 401 Unauthorized or 403 Forbidden
   • Include error message indicating timestamp issue
   • Do NOT reveal server's current time (prevents timing attacks)
   • Log rejection for security monitoring

2. Signature Verification Failure: When signature validation fails:

   • Return HTTP 401 Unauthorized
   • Indicate authentication failure without revealing specific cause
   • Check for common issues:
     • Wrong key used (client may have stale key state)
     • Tampered request body
     • Incorrect signature format

3. Key State Issues: When the signing key is not authoritative:

   • Return HTTP 403 Forbidden
   • Indicate that the key is no longer valid
   • Provide OOBI (Out-Of-Band Introduction) for current key state if appropriate

4. Replay Detection: If the same timestamp appears multiple times:

   • Simple KRAM does not track individual timestamps (stateless)
   • Extended KRAM variants may implement nonce tracking
   • Application-level replay detection may be needed for critical operations

Usage Patterns

Typical Scenarios

Scenario 1: Signify Client to KERIA Agent

This is the primary use case documented in Document 17:

1. 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
     }
   }
   

2. Client signs request: The client uses its private key to sign the entire JSON body.

3. Client sends request: The signed request is sent to the KERIA agent's Admin Interface.

4. Agent validates: The KERIA agent:

   • Checks timestamp is within acceptable window
   • Verifies signature using client's public key
   • Processes the inception operation

5. Agent responds: The agent returns a signed response containing the new AID and inception event.

Scenario 2: vLEI Credential Presentation

Document 19 describes KRAM usage in credential verification:

1. Holder prepares presentation: A vLEI credential holder constructs a presentation request including:

   • The SAID of the credential being presented
   • Current timestamp
   • Any additional context required by the verifier

2. Holder signs presentation: The holder signs the presentation with their AID's private key.

3. Presentation submitted: The signed presentation is sent to the vLEI Verifier Router's /presentation endpoint.

4. Router validates: The router:

   • Validates timestamp
   • Verifies signature
   • Routes to appropriate verifier instance

5. Verifier processes: The verifier checks:

   • Credential validity
   • Credential status (not revoked)
   • Holder's authorization to present

Scenario 3: Witness Event Submission

When a controller submits a key event to witnesses:

1. Controller creates event: A rotation event is created with new keys.

2. Controller adds timestamp: Current timestamp is included in the event submission.

3. Controller signs: The event is signed with current authoritative keys.

4. Submission to witnesses: The signed event is sent to all configured witnesses.

5. Witness validation: Each witness:

   • Validates timestamp
   • Verifies signature against current key state
   • Checks event sequence and consistency
   • Issues receipt if valid

Best Practices

1. Client-Side Clock Management:

   • Implement NTP synchronization
   • Monitor clock drift and alert users if excessive
   • Provide user feedback if timestamp validation fails
   • Consider implementing automatic retry with fresh timestamp

2. Server-Side Configuration:

   • Set window parameters based on measured network conditions
   • Monitor rejection rates to detect:
     • Clock synchronization issues
     • Potential replay attacks
     • Network latency problems
   • Implement rate limiting to prevent timestamp probing attacks

3. Security Hardening:

   • Never reveal server's current time in error messages
   • Log all authentication failures for security analysis
   • Implement progressive delays for repeated failures
   • Consider IP-based rate limiting for suspicious patterns

4. Group Multi-Sig Considerations: Document 2 provides extensive guidance for group scenarios:

   • Use Extended KRAM for operations requiring loose coordination
   • Implement escrow mechanisms for partial signatures
   • Consider hybrid approaches combining KRAM with application-level coordination
   • Document expected signing timeframes in governance policies

Integration Considerations

1. KERI Protocol Stack Integration:

   • KRAM operates at the application layer above CESR encoding
   • Requests must be properly CESR-encoded before transmission
   • Responses must be validated using the same KRAM principles

2. Witness and Watcher Integration:

   • Witnesses must implement KRAM for event submissions
   • Watchers may use KRAM for querying witness pools
   • OOBI discovery may incorporate KRAM-authenticated endpoints

3. Credential Lifecycle Integration:

   • ACDC issuance requests use KRAM
   • IPEX exchanges incorporate KRAM
   • TEL (Transaction Event Log) updates require KRAM authentication

4. Multi-Tenant Environments:

   • KERIA agents serving multiple clients must:
     • Isolate timestamp validation per client
     • Maintain separate key state for each client AID
     • Prevent cross-client replay attacks

Advanced Topics

Extended KRAM for Group Multi-Sig

Document 2 proposes several Extended KRAM variants:

1. Nonce-Based Extended KRAM:

   • Server issues a nonce with extended lifetime (hours/days)
   • Client includes nonce in request instead of timestamp
   • Server tracks used nonces to prevent replay
   • Suitable for group operations requiring human coordination

2. Hybrid KRAM:

   • Combines timestamp for initial validation
   • Adds nonce for extended replay protection
   • Balances stateless benefits with extended coordination needs

3. Escrow-Aware KRAM:

   • Integrates with KERI's escrow mechanisms
   • Allows partial signatures to accumulate over time
   • Final validation occurs when threshold is met

KRAM vs. FIDO2/WebAuthn

Document 3 provides detailed comparison:

FIDO2/WebAuthn:

• Requires registration ceremony with MFA
• Keys are device-bound and non-portable
• Limited to browser environments
• No built-in key rotation

KRAM:

• No registration ceremony required
• Keys are portable via KERI infrastructure
• Works across any environment
• Native support for key rotation via KEL
• Enables delegation and multi-sig

Zero-Trust Architecture Implications

Document 3 emphasizes KRAM's role in zero-trust architectures:

• Path-independent verification: Any intermediary can validate requests without trusted channels
• End-to-end security: Authentication is not delegated to network infrastructure
• No pre-authenticated channels: Each request is independently authenticated
• Ambient verifiability: Requests can be verified by any party with access to the KEL

This aligns with KERI's broader goal of providing ambient verifiability for all identity operations.

• Pros: Extended replay protection, supports group multi-sig, flexible coordination
• Cons: Requires nonce storage, complicates scaling, needs cleanup mechanisms

Group Multi-Sig Coordination

Document 2 identifies that Simple KRAM's narrow window creates "coordination challenges" for group multi-sig scenarios. Implementations must:

1. Assess coordination timeframes: Determine if group members can coordinate within 3-4 seconds or require extended timeframes

2. Choose appropriate KRAM variant:

   • Simple KRAM: For tightly coordinated groups (automated systems)
   • Extended KRAM: For loosely coordinated groups (human signers)
   • Hybrid approaches: For mixed scenarios

3. Implement escrow mechanisms: Allow partial signatures to accumulate over time while maintaining security

4. Document governance policies: Clearly specify expected signing timeframes and procedures

Security Hardening

1. Never reveal server time: Error messages must not disclose the server's current time, as this enables timing attacks

2. Rate limiting: Implement progressive delays for repeated authentication failures to prevent:

   • Timestamp probing attacks
   • Brute force attempts
   • Denial of service

3. Logging and monitoring: Track all authentication failures for security analysis:

   • Timestamp rejections (potential replay attempts)
   • Signature failures (potential key compromise)
   • Unusual patterns (coordinated attacks)

4. Key state validation: Always verify signatures against current authoritative keys from the KEL, never cached or stale keys

Integration with KERI Protocol Stack

KRAM operates at the application layer but must integrate with lower-level KERI components:

1. CESR encoding: Requests must be properly CESR-encoded before transmission
2. KEL access: Servers must have access to complete KELs for signature verification
3. Witness coordination: Witness pools must implement KRAM consistently
4. OOBI discovery: Authenticated endpoints should be discoverable via OOBI

Performance Optimization

1. Signature verification caching: Cache public keys (but not key state) to reduce KEL lookups
2. Parallel validation: Timestamp and signature verification can occur in parallel
3. Early rejection: Reject invalid timestamps before expensive signature verification
4. Connection pooling: Reuse connections for multiple authenticated requests

Error Handling Best Practices

1. Distinguish error types: Provide different error codes for:

   • Timestamp out of window (401)
   • Invalid signature (401)
   • Stale key (403)
   • Unknown AID (404)

2. Provide actionable feedback: Error messages should guide clients toward resolution:

   • "Timestamp outside acceptable window - check clock synchronization"
   • "Signature verification failed - ensure using current keys"
   • "Key no longer authoritative - retrieve updated key state"

3. Implement retry logic: Clients should automatically retry with fresh timestamps on certain failures

Testing Considerations

1. Clock skew testing: Simulate various clock drift scenarios
2. Network latency testing: Test with artificial delays to validate window sizing
3. Replay attack testing: Attempt to replay captured requests
4. Key rotation testing: Verify rejection of requests signed with rotated keys
5. Group coordination testing: Test extended KRAM variants with realistic signing delays