Virtual HSM
Home
  • Virtual HSM
  • Documentation
    • What is Virtual HSM?
    • Use Case: Attested Secret Provisioning in the Cloud
    • Setup
      • Install
      • vHSM Server Configuration
        • Parameters
        • vHSM Telemetry Parameters
      • vHSM Agent
        • Agent Configuration
      • vHSM Proxy
        • Proxy Configuration
    • Get Started
      • Start the Vault server
      • MariaDB root admin password provisioning on Azure DCXas_v5 VM
    • Supported Cloud Configurations
  • Tutorials
    • Deploying the vhsm Container on an EC2 Instance
    • CLI quickstart
    • vHSM Agent quickstart
    • vHSM Proxy quickstart
    • Passing vHSM secrets using ConfigMaps
    • Provisioning MariaDB Password on Azure DCXas_v5 VM
    • Registering a buckypaper plugin
    • Monitoring vHSM with Grafana
  • Integration with Utimaco SecurityServer
    • Integrate enclaive vHSM with Utimaco HSM
  • API
    • Auth
    • Default
    • Secrets
    • System
    • Identity
    • Models
  • vHSM CLI
    • Server and Infrastructure Management
      • vhsm server
      • vhsm proxy
      • vhsm monitor
      • vhsm status
      • vhsm agent
    • Secret Management
      • vhsm read
      • vhsm write
      • vhsm delete
      • vhsm list
      • vhsm secrets
        • vhsm secrets enable
        • vhsm secrets disable
        • vhsm secrets list
        • vhsm secrets move
        • vhsm secrets tune
      • vhsm unwrap
    • Configuration and Management
      • vhsm plugin
        • vhsm plugin info
        • vhsm plugin deregister
        • vhsm plugin list
        • vhsm plugin register
        • vhsm plugin reload
        • vhsm plugin reload-status
      • vhsm namespace
      • vhsm operator
      • vhsm print
      • vhsm path-help
      • vhsm lease
    • Auditing and Debugging
      • vhsm audit
      • vhsm debug
    • Attestation
    • Security and Encryption
      • vhsm pki
        • vhsm pki health-check
        • vhsm pki issue
        • vhsm pki list-intermediates
        • vhsm pki reissue
        • vhsm pki verify-sign
      • vhsm transit
      • vhsm ssh
      • vhsm transform
    • Authentication and Authorization
      • vhsm login
      • vhsm auth
      • vhsm token
      • vhsm policy
    • Storage and Data Mangement
      • vhsm kv
      • vhsm patch
    • vhsm version
      • vhsm version-history
  • Troubleshooting
    • CA Validity Period
    • CRL Validity Period
    • Root Certificate Issued Non-CA Leaves
    • Role Allows Implicit Localhost Issuance
    • Role Allows Glob-Based Wildcard Issuance
    • Performance Impact
    • Accessibility of Audit Information
    • Allow If-Modified-Since Requests
    • Auto-Tidy Disabled
    • Tidy Hasn't Run
    • Too Many Certificates
    • Enable ACME Issuance
    • ACME Response Headers Configuration
  • Resources
    • Community
    • GitHub
    • Youtube
    • CCx101 wiki
Powered by GitBook
On this page
  • Features
  • API Endpoints
  • Start a vHSM Proxy
  • Example configuration

Was this helpful?

  1. Documentation
  2. Setup

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. Start vHSM Proxy with the configuration file:

    vhsm proxy -config=/etc/vhsm/proxy-config.hcl
  3. 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
}
PreviousAgent ConfigurationNextProxy Configuration

Last updated 2 months ago

Was this helpful?

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

Example configuration