vHSM Proxy quickstart

Learn to start vHSM Proxy and read secrets from a specified path in the vHSM server through vHSM Proxy.

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 vHSM CLI

• Install vHSM and start a Dev server

• Install jq 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:

{
   "organization": "Enclaive",
   "customer_id": "ABXX2398YZPIE7391",
   "region": "US-West",
   "zip_code": "94105",
   "type": "premium",
   "contact_email": "[email protected]",
   "status": "active"
}

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

pid_file = "./pidfile"

vault {
   address = "http://127.0.0.1:8200"
   tls_skip_verify = true
}

auto_auth {
   method {
      type = "token_file"
      config = {
         token_file_path = "$HOME/.vault-token"
      }
   }
   sink "file" {
      config = {
            path = "$HOME/vault-proxy"
      }
   }
}

listener "tcp" {
   address     = "127.0.0.1:8100"
   tls_disable = true
}

api_proxy {
   use_auto_auth_token = true
   enforce_consistency = "always"
}

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.

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

1. Open another command terminal and send an API request to the vHSM Proxy.

   Read the secrets at secret/customers/enclaive via the proxy address.

   curl -s http://127.0.0.1:8100/v1/secret/data/customers/enclaive \
      | jq -r ".data.data"

   Output:

   {
      "contact_email": "[email protected]",
      "customer_id": "ABXX2398YZPIE7391",
      "organization": "Enclaive",
      "region": "US-West",
      "status": "active",
      "type": "premium",
      "zip_code": "94105"
   }

   A token was automatically attached to the request by the vHSM Proxy because you set the use_auto_auth_token parameter to true in the configuration.

2. Read the secrets again. This time, vHSM's Proxy returns the cached secrets.

   curl --verbose -s http://127.0.0.1:8100/v1/secret/data/customers/enclaive \
      | jq -r ".data.data"

   Use the --verbose or -v option with the cURL command so that you can see more detail.

   *   Trying 127.0.0.1:8100...
   * Connected to 127.0.0.1 (127.0.0.1) port 8100 (#0)
   > GET /v1/secret/data/customers/enclaive HTTP/1.1
   > Host: 127.0.0.1:8100
   > User-Agent: curl/8.1.2
   > Accept: */*
   > 
   < HTTP/1.1 200 OK
   < Cache-Control: no-store
   < Content-Length: 465
   < Content-Type: application/json
   < Date: Mon, 10 Mar 2025 15:43:34 GMT
   < Strict-Transport-Security: max-age=31536000; includeSubDomains
   < X-Cache: MISS
   < 
   { [465 bytes data]
   * Connection #0 to host 127.0.0.1 left intact
   {
     "contact_email": "[email protected]",
     "customer_id": "ABXX2398YZPIE7391",
     "organization": "Enclaive",
     "region": "US-West",
     "status": "active",
     "type": "premium",
     "zip_code": "94105"
   }

3. Update the secrets to see what happens.

   vhsm kv patch secret/customers/enclaive "customer_since"="2011"

4. Read the secrets again through vHSM Proxy.

   curl --verbose http://127.0.0.1:8100/v1/secret/data/customers/enclaive \
      | jq -r ".data.data"

   The output is similar to:

   * Connected to 127.0.0.1 (127.0.0.1) port 8100 (#0)
   > GET /v1/secret/data/customers/enclaive HTTP/1.1
   > Host: 127.0.0.1:8100
   > User-Agent: curl/8.1.2
   > Accept: */*
   > 
   < HTTP/1.1 200 OK
   < Cache-Control: no-store
   < Content-Length: 489
   < Content-Type: application/json
   < Date: Mon, 10 Mar 2025 15:52:55 GMT
   < Strict-Transport-Security: max-age=31536000; includeSubDomains
   < X-Cache: MISS
   < 
   { [489 bytes data]
   100   489  100   489    0     0  58612      0 --:--:-- --:--:-- --:--:--  238k
   * Connection #0 to host 127.0.0.1 left intact
   {
     "contact_email": "[email protected]",
     "customer_id": "ABXX2398YZPIE7391",
     "customer_since": "2011",
     "organization": "Enclaive",
     "region": "US-West",
     "status": "active",
     "type": "premium",
     "zip_code": "94105"
   }

5. Press Ctrl + C to stop the running vHSM Proxy.