# vHSM Agent 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](https://github.com/hashicorp/consul-template/blob/main/docs/templating-language.md), 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.enclaive.cloud/nitride/tutorials/vhsm-agent.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.