secretserver.io
Documentation menu

Clients & Libraries

Offline cache service

A proposed local daemon for encrypted, time-bounded offline access to secrets an administrator approved in the dashboard.

This is a reviewed design package, not a running daemon. There is nothing to install yet, and the client --cache option described below is not implemented in the current libraries.

What it is

An offline lease cache, not a general-purpose cache:

  • A tenant administrator enables the feature and creates a policy in the dashboard that fixes the device, secret set, versions, consumers, delivery modes, capacity, assurance tier and TTL.
  • The device generates non-exportable enrollment and wrapping keys. SecretServer issues a signed policy and a device-wrapped, per-lease cache key.
  • The daemon cannot add secrets, extend a lease, change its TTL or widen local consumers.
  • Each entry is encrypted individually and bound to the signed lease and policy through AEAD associated data.
  • Expiration fails closed. An offline device cannot hear about revocation, so exposure is bounded by the remaining lease lifetime.
  • No TCP listener: a root-owned Unix socket or a Windows named pipe. No plaintext at rest, in logs, arguments, environment variables, crash dumps or metrics.

Planned client contract

ModeBehavior
offBypass the cache. The default until the feature is enabled and a device is enrolled.
preferUse the cache for eligible resources; on a miss, expiry or daemon error, make the normal remote request. Remote results are never written into the cache.
requiredUse only the cache and fail closed on any miss, expiry, provenance failure or daemon error.
# CLI flag (planned)
--cache=off|prefer|required

# SDK fields (planned)
Go:      CacheMode CacheMode
Node:    cacheMode: "off" | "prefer" | "required"
Python:  cache_mode: Literal["off", "prefer", "required"]
PHP:     cache_mode => 'off'|'prefer'|'required'

# environment fallback (planned)
SS_CACHE_MODE

There is deliberately no TTL, secret-set, renewal, encryption-key or populate option on the client side.

Planned endpoints

PlatformLocal endpoint
Linux/run/secretserver-cache/daemon.sock
macOS/var/run/secretserver-cache/daemon.sock
Windows\\.\pipe\secretserver-cache

Reading, writing and listing

Under the design, only cache-eligible reads go to the daemon. Writes, deletes, rotations, revocations, exports and signing are never served from the cache, and there is no local listing or populate interface. Until the daemon ships, use a client library directly.

Design documents

The secretserver-cache-service/ directory holds the full design:

  • docs/ARCHITECTURE.md, docs/THREAT_MODEL.md, docs/PROTOCOL.md
  • docs/CLIENT_INTEGRATION.md, docs/ADR-001-OFFLINE-LEASE-CACHE.md, docs/IMPLEMENTATION_PLAN.md
  • api/openapi.yaml (local API sketch) and schemas/cache-policy.schema.json (signed policy)
All clients →Design on GitHub →