Learn how to use the Hanzo KMS Proxy to proxy requests to Hanzo KMS with built-in caching for high availability.

Overview

Hanzo KMS Proxy is a client-side daemon that acts as an API proxy for Hanzo KMS, providing caching capabilities for high availability. Applications connect to the proxy instead of directly to Hanzo KMS, and the proxy handles request forwarding, response caching, and automatic cache refresh.

Key features:

API Proxy: Forwards all requests to your Hanzo KMS instance transparently

Caching: Caches secret responses in-memory with automatic refresh

High Availability: Continues serving cached secrets even when Hanzo KMS is unreachable (optimistic eviction strategy)

Automatic Cache Invalidation: Purges stale cache entries when secrets are mutated through the proxy

Token Validation: Periodically validates access tokens and evicts entries for revoked tokens

TLS Support: Supports TLS encryption for secure communication

The Hanzo KMS Proxy is ideal for scenarios where you need to reduce load on your Hanzo KMS instance, improve response times, or ensure secret availability during network disruptions.

How It Works

%%{init: {'theme': 'base', 'themeVariables': { 'edgeLabelBackground':'#ffffff', 'lineColor': '#333'}}}%%
flowchart LR
    A[Application] -->|Request| B[Hanzo KMS Proxy]
    B -->|Cache Hit| A
    B -->|Cache Miss| C[Hanzo KMS]
    C -->|Response| B
    B -->|Cache & Return| A
    
    style A fill:#ECF26D,stroke:#333,color:#000
    style B fill:#ECF26D,stroke:#333,color:#000
    style C fill:#ECF26D,stroke:#333,color:#000

The Hanzo KMS Proxy sits between your applications and your Hanzo KMS instance, acting as a transparent intermediary. Applications make requests to the proxy using the same API endpoints they would use with Hanzo KMS directly, simply replace your Hanzo KMS host URL with the proxy's address. The proxy handles authentication headers transparently, forwarding them to Hanzo KMS as needed.

When a request arrives, the proxy first checks its in-memory cache for a matching response. Cache lookups are based on the request method, path, query parameters, and authentication token, ensuring that different users and query variations are cached separately. If a matching entry exists, the proxy returns the cached response immediately without contacting Hanzo KMS, significantly reducing latency and load on your Hanzo KMS instance.

For requests that aren't in the cache, the proxy forwards them to Hanzo KMS, waits for the response, and then stores the response in its cache before returning it to the application. This means the first request for any unique combination of parameters will have normal latency, but subsequent identical requests will be served from cache.

To keep cached data fresh, the proxy runs two background processes. The first periodically validates that cached access tokens are still valid by making test requests to Hanzo KMS. If a token has been revoked, all cache entries associated with that token are immediately evicted. The second process refreshes cached secrets on a configurable interval, re-fetching data from Hanzo KMS and updating the cache with the latest values. Both processes use an optimistic strategy: if Hanzo KMS is unreachable, the proxy continues serving cached data rather than evicting entries, ensuring your applications remain operational during outages.

Install the Hanzo KMS Proxy

The Hanzo KMS Proxy is available through the KMS CLI. Please refer to the CLI installation documentation for more information on how to install the KMS CLI.

Quick Start

Start the proxy with minimal configuration:

kms proxy start \
  --domain=https://app.kms.hanzo.ai \
  --listen-address=localhost:8081 \
  --tls-enabled=false

Then configure your application to use http://localhost:8081 as the Hanzo KMS host instead of https://app.kms.hanzo.ai.

For production deployments, it is strongly recommended to enable TLS by providing --tls-cert-file and --tls-key-file, and setting --tls-enabled to true.

Configuration

Command Options

Domain of your Hanzo KMS instance (e.g., https://app.kms.hanzo.ai)

Address and port for the proxy to listen on, e.g. localhost:8081

Whether to enable TLS encryption for secure communication for the proxy. Defaults to true.

Note that all communication between the proxy and Hanzo KMS is always encrypted by default. If you are self-hosting your Hanzo KMS instance, ensure that your Hanzo KMS instance is configured to use TLS.

Path to the TLS certificate file to use for proxy TLS encryption. This field is required if --tls-enabled is true.

Path to the TLS private key file. This field is required if --tls-enabled is true.

The eviction strategy to use for cached secrets. Defaults to optimistic, and currently this is the only supported eviction strategy.

The eviction strategy is used to determine when to evict cached secrets from the cache.

optimistic - Only evict cached secrets when the proxy is able to reach Hanzo KMS and verify that the underlying cached secret is stale.

How often to validate that access tokens are still valid. If a token is deemed to be invalid (such as if it has been revoked or has expired), the proxy will evict all cached secrets that are associated with that token. Supports duration formats like 60s|5m|1h|1d|1w|1y.

How often to refresh cached secrets from Hanzo KMS. Defaults to 1h. Supports duration formats like 60s|5m|1h|1d|1w|1y.

Caching Behavior

What Gets Cached

The proxy selectively caches responses to optimize for the most common secret retrieval patterns. Only GET requests to secret endpoints are cached. This includes the list and retrieve endpoints across both API versions (/api/v3/secrets and /api/v4/secrets), as well as their raw variants and any sub-paths. These endpoints represent read operations where caching provides the most benefit: reducing latency for frequently accessed secrets and decreasing load on your Hanzo KMS instance.

All other requests pass through the proxy without caching. This includes mutation operations like creating, updating, or deleting secrets (POST, PATCH, DELETE), as well as requests to non-secret endpoints such as authentication, project management, or user operations. These requests are forwarded directly to Hanzo KMS and their responses are returned to the application without being stored. This design ensures that write operations always reach Hanzo KMS immediately and that the cache only contains secret data that benefits from being cached.

Request Uniqueness

Each cache entry is uniquely identified by a SHA-256 hash of the request's method, path, query parameters, and authentication token. This ensures that different query combinations and users are cached separately.

The cache key is constructed as follows:

sha256(method + path + query + access_token)

Automatic Cache Refresh

The proxy automatically refreshes cached secrets and validates cached access tokens to ensure the data in the cache remains fresh and valid.

Access Token Validation

The proxy periodically validates that cached access tokens are still valid, running every 5 minutes by default. For each unique token in the cache, the proxy makes a test request to Hanzo KMS using one of that token's cached requests. If Hanzo KMS returns 401 Unauthorized or 403 Forbidden, all cache entries associated with that token are immediately evicted.

When the proxy is configured with the optimistic eviction strategy: If Hanzo KMS is unreachable during token validation (network errors or 5xx responses), the proxy keeps cached entries intact rather than evicting them. This ensures that your applications remain operational even if Hanzo KMS is temporarily unavailable.

Static Secrets Refresh

The proxy automatically refreshes cached secrets to ensure data stays current, running every hour by default. During each refresh cycle, the proxy identifies all cache entries that were last updated longer ago than the refresh interval, then re-fetches each one from Hanzo KMS. Successful responses update the cached data with fresh values. Entries that return 401, 403, or 404 during refresh are evicted from the cache, as these indicate the token has lost access or the resource no longer exists.

When the proxy is configured with the optimistic eviction strategy: If Hanzo KMS is unreachable during the refresh cycle (network errors or 5xx responses), the proxy keeps cached entries intact rather than evicting them. This ensures that your applications remain operational even if Hanzo KMS is temporarily unavailable.

Mutation-Based Cache Invalidation

When a mutation request is processed through the proxy (POST, PATCH, or DELETE requests), the proxy extracts the projectId, environment, and secretPath from the request body and purges all cache entries that match these criteria—regardless of which token was used to cache them. This cross-token purging ensures that all users see consistent data after a secret is modified. The proxy also supports wildcard path matching, so a mutation to /production/database will invalidate cache entries for both exact path matches and recursive queries that included that path.

For immediate cache invalidation, perform secret mutations through the proxy rather than directly to Hanzo KMS. For optimal performance it's recommended to use the proxy for all API requests.

Eviction Strategy

The eviction strategy is used to determine when to evict cached entries from the cache. Currently the Hanzo KMS Proxy only supports the optimistic eviction strategy.

Optimistic Eviction

Keeps cached data when Hanzo KMS is unreachable (network errors, or 5xx responses)

Ensures high availability when your Hanzo KMS instance is unreachable

Cache entries are only evicted on:

Token invalidation (401/403 response)
Resource not found (404 response)
Explicit mutation through the proxy
Proxy restart (when the proxy is restarted, all cached entries are evicted because the cache is stored in memory)

The optimistic eviction strategy prioritizes availability. Applications will continue receiving cached secrets even if Hanzo KMS is down, at the cost of potentially serving slightly stale data.

TLS Configuration

By default, TLS is enabled. For production deployments, provide your TLS certificate and key:

kms proxy start \
  --domain=https://app.kms.hanzo.ai \
  --listen-address=0.0.0.0:8081 \
  --tls-cert-file=/path/to/cert.pem \
  --tls-key-file=/path/to/key.pem

To disable TLS (not recommended for production):

kms proxy start \
  --domain=https://app.kms.hanzo.ai \
  --listen-address=localhost:8081 \
  --tls-enabled=false

Examples

Using the Proxy with SDKs

Configure your Hanzo KMS SDK to point to the proxy instead of Hanzo KMS directly:

Node.js


const client = new Hanzo KMSSDK({
  siteUrl: "http://localhost:8081", // Proxy address instead of Hanzo KMS
  // ... other configuration options
});

Python SDK

from kms_sdk import Hanzo KMSSDKClient
client = Hanzo KMSSDKClient(host="http://localhost:8081") # Proxy address instead of Hanzo KMS

Direct API Calls

# Instead of calling Hanzo KMS directly:
# curl https://app.kms.hanzo.ai/api/v3/secrets/raw?...

# Call the proxy:
curl -G http://localhost:8081/api/v4/secrets \
  -H "Authorization: Bearer <your-access-token>" \
  --data-urlencode "projectId=<your-project-id>" \
  --data-urlencode "environment=dev" \
  --data-urlencode "secretPath=/" \
  --data-urlencode "recursive=true"

Security Considerations

Cache Encryption

All cached secret data is encrypted at rest in memory using AES-256 with GCM authentication. Secrets are only decrypted momentarily when serving a response to a client, and are otherwise stored in encrypted form. The encryption key is randomly generated at proxy startup and persists only for the lifetime of the process, and restarting the proxy generates a new key and clears all cached data.

The encryption key itself is protected in memory, using multiple layers of memory protection techniques.

Memory locking via mlock(): prevents the key from being swapped to disk

Memory protection via mprotect(): guards against buffer overflows and unauthorized access

Secure allocation via mmap(): ensures the memory region is allocated safely

In-memory encryption using XSalsa20-Poly1305: protects the key even within RAM

Network Security

Enable TLS in production to encrypt traffic between your applications and the proxy. Without TLS, secrets are transmitted in plaintext over the network between your applications and the proxy.

Access Control

Restrict network access to the proxy's listen address to prevent unauthorized clients from querying cached secrets. The proxy should only be accessible to trusted applications within your infrastructure.

Token Isolation

The proxy caches responses separately for each authentication token. If a token is compromised, only the cache entries associated with that specific token are exposed. Other tokens' cached data remains isolated and protected.

Troubleshooting

If you're updating secrets directly in Hanzo KMS (not through the proxy), the proxy will not automatically invalidate the cache. You will need to manually purge the cache by restarting the proxy, or by waiting for the next static-secrets-refresh-interval cycle.

The static-secrets-refresh-interval is the interval at which the proxy will refresh cached secrets from Hanzo KMS.

For immediate invalidation, perform mutations through the proxy.

Hanzo KMS Proxy

On this page