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
  • What is vHSM Agent?
  • Auto-Auth
  • API Proxy
  • Caching
  • Quit API (Optional)
  • Starting the vHSM Agent
  • Example Configuration

Was this helpful?

  1. Documentation
  2. Setup

vHSM Agent

Learn about using Agent for rendering secrets into files or environment variables, allowing your applications to consume them seamlessly without directly interacting with vHSM APIs.

The vHSM Agent is designed to simplify and scale your integration with vHSM, especially for environments where modifying application code isn't ideal. The agent works by rendering secrets into files or environment variables, allowing your applications to consume them seamlessly without directly interacting with vHSM APIs.

What is vHSM Agent?

The vHSM Agent is a lightweight client daemon that acts as a secure intermediary between your application and vHSM. It supports a variety of use cases to streamline secret management and authentication workflows.

Key Features:

  • Auto-Auth: Automatically authenticate to vHSM and manage the lifecycle of the token.

  • API Proxy: Proxy vHSM's API with optional or enforced use of Auto-Auth tokens.

  • Caching: Locally cache tokens and leased secrets, including automatic renewal.

  • Windows Service: Support for running the agent as a Windows Service.

  • Templating: Render secrets from vHSM into files using user-defined templates.

  • Process Supervisor Mode: Launch applications with secrets injected as environment variables.

Auto-Auth

The Auto-Auth feature handles the initial authentication to Vault automatically and renews tokens when needed.

  • Configuration is done via the auto_auth stanza.

  • Works in a variety of environments (e.g., AWS, Kubernetes).

API Proxy

The agent can act as a proxy to vHSM’s API through a configured listener. You can optionally force the use of the Auto-Auth token for all proxy requests.

  • Configured via a listener block and an api_proxy stanza.

Caching

vHSM Agent provides client-side caching of:

  • Token creation responses.

  • Leased secrets.

  • Renewals of these tokens and leases.

Quit API (Optional)

The agent supports a special API to shut itself down:

  • Endpoint: POST /agent/v1/quit

  • Disabled by default; enable via agent_api stanza in the listener.

Note: Enable only on trusted interfaces. No auth is required to access this endpoint.

Starting the vHSM Agent

Follow these steps to start the agent:

  1. Download the vHSM binary on the client system such as a VM, container, or others.

  2. Run the agent using:

    vhsm agent -config=/etc/vault/agent-config.hcl

Additional Help

vhsm agent -h

Configuration Options

You can pass the -config flag in three ways:

  • A single file: -config=/path/to/file.hcl

  • Multiple files: -config=file1 -config=file2

  • A directory: -config=/path/to/config/dir

Vault Agent Command Options

Option
Description

-log-level (string: "info")

Log verbosity level. Supported values (in order of descending detail): trace, debug, info, warn, and error. Can also be set via the VAULT_LOG_LEVEL environment variable.

-log-format (string: "standard")

Log format. Supported values: standard and json. Can also be set via the VAULT_LOG_FORMAT environment variable.

-log-file

Writes all Vault Agent log messages to a file. The value is used as a prefix for the log file name; a timestamp is appended. - If the value ends with a path separator (/), vault-agent will be appended. - If the filename has no extension, .log is appended. - Example: setting -log-file=/var/log/ results in /var/log/vault-agent-{timestamp}.log. Can be combined with -log-rotate-bytes and -log-rotate-duration for log rotation.

-log-rotate-bytes

Specifies the maximum file size (in bytes) before the log is rotated. No limit is applied if this is not set.

-log-rotate-duration

Specifies the maximum duration a log file is written to before rotation. Accepts duration values like 30s, 1h, etc. Default: 24h.

-log-rotate-max-files

Specifies the maximum number of old log files to keep. - Default: 0 (no deletion). - Set to -1 to discard old logs when a new one is created.

Example Configuration

Here’s a sample configuration showing the various features in use:

pid_file = "./pidfile"

vault {
  address = "https://vault-fqdn:8200"
  retry {
    num_retries = 5
  }
}

auto_auth {
  method "aws" {
    mount_path = "auth/aws-subaccount"
    config = {
      type = "iam"
      role = "foobar"
    }
  }

  sink "file" {
    config = {
      path = "/tmp/file-foo"
    }
  }

  sink "file" {
    wrap_ttl = "5m"
    aad_env_var = "TEST_AAD_ENV"
    dh_type = "curve25519"
    dh_path = "/tmp/file-foo-dhpath2"
    config = {
      path = "/tmp/file-bar"
    }
  }
}

cache {
  # An empty stanza still enables caching
}

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
}

template {
  source = "/etc/vault/server.key.ctmpl"
  destination = "/etc/vault/server.key"
}

template {
  source = "/etc/vault/server.crt.ctmpl"
  destination = "/etc/vault/server.crt"
}
PreviousvHSM Telemetry ParametersNextAgent Configuration

Last updated 2 months ago

Was this helpful?

Create a configuration file agent-config.hcl or agent-config.json, see .

Example Configuration