vHSM Proxy is designed to simplify and accelerate the adoption of vHSM by providing a scalable, lightweight way for applications to interact with vHSM server seamlessly. Acting as an API proxy, vHSM Proxy streamlines authentication and token management, enabling applications to integrate with vHSM without handling complex auth workflows directly.
vHSM Proxy runs as a client-side daemon and offers the following key capabilities:
Auto-Auth: Automatically authenticates to vHSM and handles the lifecycle of dynamic secrets, including token acquisition and renewal.
API Proxy: Transparently proxies requests to vHSM’s API, with the option to use—or enforce the use of—an automatically authenticated token for all client interactions.
Caching: Supports local caching of responses for newly created tokens and leased secrets, reducing latency and minimizing redundant requests. It also manages the renewal of cached tokens and leases automatically.
Prerequisites
Install for better readability of the JSON output
1. Create a directory for storing test files and configuration.
mkdir -p $HOME/vhsm-test && cd $HOME/vhsm-test
2. Create a mock dataset data.json representing a customer record, using an editor of your choice:
Upload the test data to the vHSM KV v2 secrets engine:
vhsm kv put secret/customers/enclaive @data.json
4. Create the proxy configuration file vhsm-proxy-config.json that defines API endpoint for the client application to send requests to rather than VAULT_ADDR.
Note: The vault and auto_auth stanzas in the vHSM Proxy and vHSM Agent configurations are identical; however, you must define listener and api_proxy stanzas for vHSM Proxy.
Start the vHSM Proxy.
vhsm proxy -config=vault-proxy-config.json
The output is similar to:
==> vHSM Proxy started! Log data will stream in below:
==> vHSM Proxy configuration:
Api Address 1: http://127.0.0.1:8100
Cgo: disabled
Log Level:
Version: Vhsm v1.3.7-0, built 2025-01-29T15:11:42Z
Version Sha: 00d245ed8143844db6761fd947433aab237f914f+CHANGES
2025-03-10T18:28:43.946+0530 [INFO] proxy.sink.file: creating file sink
2025-03-10T18:28:43.947+0530 [INFO] proxy.sink.file: file sink configured: path=/Users/rkodhandapani/vault-token-via-agent mode=-rw-r-----
2025-03-10T18:28:43.947+0530 [INFO] proxy.sink.server: starting sink server
2025-03-10T18:28:43.947+0530 [INFO] proxy.auth.handler: starting auth handler
2025-03-10T18:28:43.947+0530 [INFO] proxy.auth.handler: authenticating
2025-03-10T18:28:43.949+0530 [INFO] proxy.auth.handler: authentication successful, sending token to sinks
2025-03-10T18:28:43.949+0530 [INFO] proxy.auth.handler: not starting token renewal process, as token has unlimited TT
Open another command terminal and send an API request to the vHSM Proxy.
Read the secrets at secret/customers/enclaive via the proxy address.
