vHSM Agent

Learn about vHSM agent and how it can help you with secure access to secrets and cryptographic operations managed by a vHSM.

The vHSM Agent is a lightweight client-side daemon that simplifies secure access to secrets and cryptographic operations managed by a vHSM. Instead of requiring applications to handle authentication, token management, and secret retrieval directly, the agent automates these tasks through a configuration file called agent-config.json. Additionally, vHSM Agent supports Consul Template markup, allowing it to render secrets into files. This enables client applications to seamlessly access and load the required data.

By defining authentication methods, token sinks, and secret rendering templates in agent-config.json, you gain several advantages:

• Automated authentication: The agent securely authenticates to the vHSM server without manual intervention, using attestation or other identity methods.

• Token lifecycle management: Tokens are automatically renewed and stored in predictable locations, reducing the risk of expired credentials interrupting workloads.

• Seamless secret delivery: Applications do not need to call the vHSM API directly. Instead, they consume secrets as local files rendered by the agent.

• Consistent configuration: Using a declarative configuration file ensures repeatability and reduces human error.

• Integration flexibility: With support for templates, you can format secrets to match the exact input requirements of your applications, eliminating the need for custom parsing logic.

In practice, agent-config.json acts as the bridge between vHSM and applications running inside confidential computing environments. It enables a secure, standardized, and hands-off approach to handling sensitive data, while also improving reliability and maintainability of production deployments.

Example Use Case: Web Service with TLS Certificates

Imagine you are running a web service inside a confidential VM. This service needs a TLS certificate and private key to establish secure HTTPS connections.

Without the vHSM Agent:

• Your application would have to authenticate with vHSM, fetch the certificate and key, handle token renewals, and manage file updates manually.

• If a token expires or the certificate is rotated, the application could fail, leading to downtime.

With the vHSM Agent and a proper agent-config.json configuration:

1. The agent authenticates to vHSM using an attestation-based auth method such as Azure SEV-SNP vTPM.

2. It securely writes the token to a sink location such as /run/enclaive/vhsm-token.

3. A template definition in agent-config.json fetches the TLS certificate and private key from vHSM and writes them to /etc/webapp/certs/tls.pem and /etc/webapp/certs/tls.key.

4. The agent keeps these files up to date by automatically renewing and rewriting them whenever secrets change or tokens are refreshed.

5. The web service simply reads the files from disk at startup and reloads them when they are updated, without ever needing to contact vHSM directly.

This approach allows you to:

• Focus on application logic instead of secret management.

• Guarantee that sensitive material is always valid and fresh.

• Minimizes the attack surface by isolating direct communication with vHSM to the agent.