"}'
```
{% endtab %}
{% endtabs %}
**Response**
{% tabs %}
{% tab title="CLI" %}
```
Key Value
--- -----
created 1734563330
description Add your text
events http://localhost:8000
name Example
namespace my-namespace
nonce n/a
policy my-policy
updated 0
uuid ae294417-95ca-4aad-9647-77dbd3249771
```
{% endtab %}
{% tab title="cURL - 200" %}
```json
{
"request_id": "c3aba2a0-0d75-ef05-b6da-6a34bd608cb2",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": {
"created": 1734563360,
"description": "Add your text",
"events": "http://localhost:8000",
"name": "Example",
"namespace": "my-namespace",
"nonce": "",
"policy": "my-policy",
"updated": 0,
"uuid": "ae294417-95ca-4aad-9647-77dbd3249771"
},
"wrap_info": null,
"warnings": null,
"auth": null
}
```
{% endtab %}
{% tab title="cURL - 400" %}
```json
{
"errors": [
"Invalid request"
]
}
```
{% endtab %}
{% endtabs %}
### Create a VM
{% tabs %}
{% tab title="Azure" %}
At this stage, we will create an Azure VM from the DC2as\_v5 family with the Ubuntu 20\_04-lts-cvm operating system version, as it supports confidential VMs.
Use the provider `azure-sev-snp-vtpm`.
{% endtab %}
{% tab title="AWS" %}
At this stage, we will create an AWS EC2 from the M6a family with the Ubuntu 23.04 operating system version, as it supports confidential VMs.
Use the provider `aws-sev-snp-raw`.
{% endtab %}
{% tab title="GCP" %}
At this stage, we will create an GCP VM from the N2D family with an Ubuntu operating system version, as it supports confidential VMs.
Use the provider `gcp-sev-snp-raw`.
{% endtab %}
{% endtabs %}
Download and run the `vhsm agent` inside the VM with your desired configuration. The binary is available from the attestation server at `http://localhost:8200/static/vhsm`.
When creating the VM, you can include all of this in cloud-init to automate the process.
#### Configuration
{% tabs %}
{% tab title="Azure" %}
auto_auth {
method {
type = "nitride"
mount_path = "ratls"
min_backoff = "1h"
max_backoff = "2h"
config {
provider = "azure-sev-snp-vtpm"
workload = "ae294417-95ca-4aad-9647-77dbd3249771"
}
}
}
template_config {
static_secret_render_interval = "5m"
exit_on_retry_failure = true
}
vault {
address = "https://external-address:8200"
}
{% endtab %}
{% tab title="AWS" %}
```hcl
auto_auth {
method {
type = "nitride"
mount_path = "ratls"
min_backoff = "1h"
max_backoff = "2h"
config {
provider = "aws-sev-snp-raw"
workload = "ae294417-95ca-4aad-9647-77dbd3249771"
}
}
}
template_config {
static_secret_render_interval = "5m"
exit_on_retry_failure = true
}
vault {
address = "https://external-address:8200"
}
```
{% endtab %}
{% tab title="GCP" %}
```hcl
auto_auth {
method {
type = "nitride"
mount_path = "ratls"
min_backoff = "1h"
max_backoff = "2h"
config {
provider = "gcp-sev-snp-raw"
workload = "ae294417-95ca-4aad-9647-77dbd3249771"
}
}
}
template_config {
static_secret_render_interval = "5m"
exit_on_retry_failure = true
}
vault {
address = "https://external-address:8200"
}
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
**Note**: Add a `sink` to `auto_auth` sink if you want to test only the attestation without rendering secrets.
{% endhint %}
Sink configuration
```hcl
sinks {
sink {
type = "file"
config = {
path = "/path/to/hsv/secret"
}
}
}
```
You can generate this config with the following command:
{% hint style="info" %}
**Note**: Ensure that you replace $uuid with the UUID that you obtained in this [request](#request).
{% endhint %}
{% tabs %}
{% tab title="Azure" %}
vhsm agent generate-config -attested -provider=azure-sev-snp-vtpm -workload=$uuid
{% endtab %}
{% tab title="AWS" %}
vhsm agent generate-config -attested -provider=aws-sev-snp-raw -workload=$uuid
{% endtab %}
{% tab title="GCP" %}
vhsm agent generate-config -attested -provider=gcp-sev-snp-raw -workload=$uuid
{% endtab %}
{% endtabs %}
#### Attesting
```bash
vhsm agent -config=agent.hcl
```
### Webhook data
Once all the steps have been completed, the result of the attestation will be sent to the webhook you specified when creating the attestation. Below is an example of what is sent to the webhook. Ensure that the **webhook** accepts the **HTTP POST** method.
```json
{
"Success": bool,
"Message": string,
"Instance": string,
"Quote": string,
"Warnings": []string,
}
```
This will indicate errors using the `Success` field with an optional `Message`. `Instance` corresponds to your attestation instance. `Quote` contains the raw received attestation. If there were some recoverable errors during the verification, these will be included as `Warnings`. This can include the inability to fetch the most recent certificates from the respective service and a fallback to cached values that are still valid.
### Provisioning a secret
Using the `vhsm agent` you can also provision secrets with the received token, that is optionally restricted to a child namespace. The required configuration can be generated:
```bash
vhsm agent generate-config -file=/tmp/secret=buckypaper/workloads/:uuid/env/:name
```
This will template a file at `/tmp/secret` with the contents of a secret in the mount `buckypaper` at the path `:uuid/env/:name`. You can modify the contents using the go templating.
```hcl
template {
destination = "/tmp/secret"
create_dest_dirs = true
contents = "{{ with secret \"buckypaper/data/workloads/:uuid/env/:name\" }}{{ .Data.data | toJSONPretty }}{{ end }}"
error_on_missing_key = true
perms = "0600"
}
```
### Using a trustlet
The vhsm agent supports `env_template` and `exec` configurations as well. This can start a process with provisioned environment variables. We extended this even further with trustlets.
Trustlets allow custom features to be executed based on `templates`. After all templates are rendered, the trustlets are started. After all trustlets are finished, the `exec` is allowed to start
```hcl
trustlet {
name = "luks"
source = "internal"
arguments = ["/dev/sda", "/tmp/secret", "/data"]
}
```
#### Supported trustlets
Currently supported:
* `luks`
* `aes-xts-plain64` with no integrity with an `ext4` filesystem
* Arguments: Source-Device, Secret-Json, Mount-Location, Variable amount of arguments for `luksFormat`
* Secret: Field `value` is used as password
* `installer`
* Download, verify and extract to location
* Arguments: Root-FS-URL, Root-FS-Hash, Extract-Location
* `cloud-users`
* Write `cloud-init` user configuration to yaml, username is based on filename split before `.`
* Arguments: Target-File, variable amount of Secret-Json (at least one)
* Secret: `value` used as password, `public`used as key (auto-detected)
* `cloud-config`
* Write any `cloud-init` configuration to a file
* Arguments: Target-File, Base64-Config
### Full example
This will install a verified root filesystem into an encrypted disk and prepare cloud-init configurations so that `root` and `user` are created and access is configured:
template {
destination = "/tmp/disk.secret"
create_dest_dirs = true
contents = "{{ with secret \"buckypaper/data/:workload/disk/:root?dynamic\" }}{{ .Data.data | toJSONPretty }}{{ end }}"
error_on_missing_key = true
perms = "0600"
}
template {
destination = "/tmp/users/root.secret"
create_dest_dirs = true
contents = "{{ with secret \"buckypaper/data/:user/ssh-key/:name?dynamic\" }}{{ .Data.data | toJSONPretty }}{{ end }}"
error_on_missing_key = true
perms = "0600"
}
template {
destination = "/tmp/users/user.secret"
create_dest_dirs = true
contents = "{{ with secret \"buckypaper/data/:user/ssh-pw/:name?dynamic\" }}{{ .Data.data | toJSONPretty }}{{ end }}"
error_on_missing_key = true
perms = "0600"
}
# azure: sda2
# gcp: nvme0n1p2
# aws: nvme0n1p2
trustlet {
source = "internal"
name = "luks"
arguments = ["/dev/nvme0n1p2", "/tmp/disk.secret", "/run/nextroot"]
}
trustlet {
source = "internal"
name = "luks"
arguments = ["/dev/nvme0n1p2", "/tmp/disk.secret", "/run/nextroot", "--key-size=256"]
}
trustlet {
source = "internal"
name = "installer"
arguments = ["https://s3.ig.ecl.d3d1.de/buckypaper/ubuntu/noble/1.0.0_1741907403.tar.zst", "b246e968380bb884f86f518081d9d62fc125a1963d14a3207d0c594ae972bc45", "/run/nextroot"]
}
trustlet {
source = "internal"
name = "cloud-users"
arguments = ["/run/nextroot/etc/cloud/cloud.cfg.d/99-enclaive-users.cfg", "/tmp/users/root.secret", "/tmp/users/user.secret"]
}
trustlet {
source = "internal"
name = "cloud-config"
arguments = ["/run/nextroot/etc/cloud/cloud.cfg.d/99-enclaive-config.cfg", "I2Nsb3VkLWNvbmZpZwo="]
}
exec {
command = ["systemctl", "soft-reboot"]
restart_on_secret_changes = "always"
restart_stop_signal = "SIGTERM"
}
---
# 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/attesting-a-buckypaper-vm.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.