Security & Authentication

LoomCache takes security seriously. Rather than depending on a secure internal perimeter, the engine assumes a zero-trust environment with encrypted connections, robust mutual authentication, and granular, command-level Access Control Lists (ACLs).

Zero-Trust Internal Network

mTLS Handshake + RBAC + Audit Logging

API Gateway

Validates JWT

X-Auth-Roles: admin

TcpServer

TLS 1.3 Terminated

Execution

RBAC + AuditLog

[Gateway] Received external request, verified JWT

TLS & mTLS Configuration

All network traffic in LoomCache should be encrypted using Transport Layer Security (TLS), with optional mutual authentication (mTLS).

• Node-to-Node (Raft Replication): Always enforces strict mTLS. All peers must possess a valid certificate signed by the operator’s shared Certificate Authority (CA). Unauthenticated or rogue nodes cannot join the Raft ring.
• Client-to-Node: Toggle whether clients merely verify the server (requireClientAuth=false) or must also present a signed certificate (requireClientAuth=true).

Certificate Setup

# Generate CA key and certificate
openssl genrsa -out ca-key.pem 4096
openssl req -new -x509 -days 3650 -key ca-key.pem -out ca-cert.pem \
  -subj "/C=US/O=LoomCache/CN=loomcache-ca"

# Generate node key and sign with CA
openssl genrsa -out node-1-key.pem 4096
openssl req -new -key node-1-key.pem -out node-1.csr \
  -subj "/C=US/O=LoomCache/CN=node-1.loomcache.local"
openssl x509 -req -in node-1.csr -CA ca-cert.pem -CAkey ca-key.pem \
  -CAcreateserial -out node-1-cert.pem -days 365 -sha256

# Create PKCS12 keystore
openssl pkcs12 -export -in node-1-cert.pem -inkey node-1-key.pem \
  -out node-1.p12 -name node-1 -passout pass:mysecretpassword

# Create truststore with CA cert
keytool -import -file ca-cert.pem -alias ca -into truststore.p12 \
  -storetype PKCS12 -storepass truststorepassword -noprompt

TLS Configuration

TlsConfig tlsConfig = TlsConfig.builder()
    .enabled(true)
    .keyStorePath("/etc/loomcache/node-1.p12")
    .keyStorePassword("mysecretpassword")
    .trustStorePath("/etc/loomcache/truststore.p12")
    .trustStorePassword("truststorepassword")
    .requireClientAuth(true)   // mTLS
    .protocols("TLSv1.3", "TLSv1.2")
    .build();

Best Practices

• Always use TLS in production — never deploy unencrypted
• Use short-lived certificates (30–90 days) with automated rotation via cert-manager or Vault
• Default to JVM cipher suites — updated with Java security patches
• Restrict file permissions to chmod 600 on keystore files
• Never commit keystores to version control

Identity & API Gateway Trust

LoomCache does not validate JWT tokens or perform OIDC flows natively. Instead, it delegates identity verification to your API Gateway (e.g., Spring Cloud Gateway, Kong, Envoy).

The Trust Model:

1. The API Gateway receives the external request and validates the JWT against your Identity Provider.
2. The Gateway maps the user to backend roles and forwards trusted headers to LoomCache over an mTLS connection:
   • X-Auth-User: The authenticated username.
   • X-Auth-Roles: Comma-separated roles (e.g., ROLE_ADMIN,ROLE_GUEST).
3. LoomCache trusts these headers purely because the mTLS handshake proved the connection originated from the authorized Gateway.

Granular RBAC Permissions

Upon receiving the trusted roles, the AuthenticationHandler evaluates the command against the ACLs. LoomCache supports specific permissions for all 101 binary protocol message types.

Role Configuration

AuthConfig authConfig = AuthConfig.builder()
    .enabled(true)
    .gatewayTrust(true)
    .addRole("read-only", "MAP_GET", "QUEUE_PEEK", "COUNTER_GET")
    .addRole("data-writer",
        "MAP_GET", "MAP_PUT", "MAP_DELETE",
        "QUEUE_PUSH", "QUEUE_POP")
    .addAdminRole("admin")  // wildcard "*"
    .build();

Supported Permissions

Category	Permissions
Map	MAP_GET, MAP_PUT, MAP_DELETE
Queue	QUEUE_PUSH, QUEUE_POP, QUEUE_PEEK
Set	SET_ADD, SET_REMOVE, SET_CONTAINS
Topic	TOPIC_PUBLISH, TOPIC_SUBSCRIBE
Lock	LOCK_TRY, LOCK_UNLOCK
Counter	COUNTER_INCREMENT, COUNTER_GET
Admin	HEALTH_CHECK, METRICS_READ, CLUSTER_INFO
Wildcard	* or ALL (grants full access)

If a guest user attempts a write, the DataOperationHandler immediately rejects the packet with an authorization error.

Node-to-Node: Inter-node Raft communication bypasses header-based auth. mTLS certificates establish trust. All nodes must share the same CA chain.

Async Audit Logging

To comply with enterprise requirements, LoomCache features a non-blocking AuditLogger. Every single data modification command includes an audit trail with:

Field	Description
timestamp	ISO-8601 event time
nodeId	Processing node ID
clientId	Authenticated client identity
command	Operation type (PUT, DELETE, LOCK, etc.)
key	Affected key or resource
result	SUCCESS, DENIED, ERROR
durationMs	Processing latency
requestId	Correlation ID for tracing

These logs are piped via virtual threads to a bounded asynchronous queue (default 10,000 entries), guaranteeing that logging never blocks the Raft replication path. When the queue fills, events are dropped and counted via loomcache.audit.events.dropped metric.

Audit Log Configuration

<!-- logback.xml — Route audit to separate file -->
<appender name="AUDIT"
  class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>/var/log/loomcache/audit.log</file>
    <rollingPolicy class="...SizeAndTimeBasedRollingPolicy">
        <maxFileSize>100MB</maxFileSize>
        <maxHistory>30</maxHistory>
    </rollingPolicy>
</appender>
<logger name="loomcache.audit" level="INFO" additivity="false">
    <appender-ref ref="AUDIT" />
</logger>