vHSM Proxy

Learn about using Proxy for authentication, caching, and secure communication to streamline vHSM adoption.

vHSM Proxy simplifies application integration with vHSM by acting as an API proxy. It offers authentication, caching, and secure communication to streamline vHSM adoption.

vHSM Proxy provides the following key features:

• Auto-Auth: Automatically authenticates to vHSM and manages token renewal.

• API Proxy: Acts as a proxy for vHSM's API, optionally enforcing Auto-Auth token usage.

• Caching: Enables client-side caching of tokens and leased secrets, managing renewals automatically.

Features

Auto-Auth

vHSM Proxy supports automatic authentication in diverse environments. Auto-Auth functionality is configured using an auto_auth stanza. See Auto-Auth documentation for details.

API Proxy

vHSM Proxy serves as an API gateway to vHSM, allowing communication via a listener. It can be configured to enforce Auto-Auth token usage. Configure API Proxy behavior using the api_proxy stanza. See API Proxy documentation for more details.

Caching

vHSM Proxy enables client-side caching of authentication tokens and leased secrets. Configuration is managed via the cache stanza. See Caching documentation for details.

API Endpoints

Quit API

Triggers shutdown of the proxy. Disabled by default; enable it using the proxy_api stanza.

• Method: POST

• Path: /proxy/v1/quit

• Security Consideration: Should only be enabled on trusted interfaces as it lacks authentication.

Cache API

For cache API details, refer to the Caching documentation.

Start a vHSM Proxy

1. Install the vHSM binary on the application server (VM, Kubernetes pod, etc.).

2. Create a vHSM Proxy configuration file proxy-config.hcl or proxy-config.json . See Example configuration.

3. Start vHSM Proxy with the configuration file:

   vhsm proxy -config=/etc/vhsm/proxy-config.hcl

4. To display help options:

   vhsm proxy -h

Command Options

Option	Description
-log-level (string: "info")	Sets the log verbosity level. Supported values (in descending detail): trace, debug, info, warn, and error. Can also be set via the VAULT_LOG_LEVEL environment variable.
-log-format (string: "standard")	Sets the log format. Supported values: standard and json. Can also be set via the VAULT_LOG_FORMAT environment variable.
-log-file	Writes all Vault proxy log messages to a file. The value is used as a prefix for the log file name, and the current timestamp is appended. If the path ends with a separator, vault-proxy is appended. If no extension is given, .log is appended. Example: /var/log/ becomes /var/log/vault-proxy-{timestamp}.log. Can be used with -log-rotate-bytes and -log-rotate-duration.
-log-rotate-bytes	Specifies the number of bytes to write to a log file before rotation occurs. If not specified, there is no size limit.
-log-rotate-duration	Specifies the maximum time duration a log file is written to before rotation. Must be a valid duration (e.g., 30s). Defaults to 24h.
-log-rotate-max-files	Specifies the maximum number of archived log files to retain. Defaults to 0 (no files are deleted). Set to -1 to discard old logs when new ones are created.

Configuration File Usage

• Provide a single configuration file.

• Specify multiple configuration files (merged at runtime).

• Define a directory of configuration files (merged at runtime).

Example configuration

pid_file = "./pidfile"

vault {
  address = "https://vault.example.com:8200"
  retry {
    num_retries = 5
  }
}

auto_auth {
  method "aws" {
    mount_path = "auth/aws-subaccount"
    config = {
      type = "iam"
      role = "foobar"
    }
  }
  sink "file" {
    config = {
      path = "/tmp/token-file"
    }
  }
}

cache {}

api_proxy {
  use_auto_auth_token = true
}

listener "unix" {
  address = "/path/to/socket"
  tls_disable = true
  agent_api {
    enable_quit = true
  }
}

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