Attesting a buckypaper VM

This tutorial is aimed at creating an attestation for confidential VMs.

Create a namespace (Optional)

If the plugin was enabled with the namespacing option, you will need to create a namespace for your attestation. You can learn how to create and use namespaces in the documentation.

Register new attestation

After creating the required identities and a policy, you are ready to create an attestation. This will hold the information for a specific workload.

Method and URL

POST http://localhost:8200/v1/auth/{mount}/attestations

Headers

Name	Value
X-Vault-Token	<token>

Body

Name	Type	Description
name	string	Test-VM
description	string	Example VM on CSP
namespace	string	your-namespace
policy	string	test
events	string	http://localhost:3000/webhook

Request

CLI

vault write auth/ratls/attestations - <<'EOF'
{
  "name": "Example",
  "description": "Add your text",
  "namespace": "my-namespace",
  "events": "http://localhost:8000",
  "policy": "test"
}
EOF

cURL

curl -H "X-Vault-Token: hvs.XXXX" \
    https://vault.enclaive.cloud/v1/auth/ratls/attestations \
     --data '{"name":"Example","description":"Add your text","namespace":"my-namespace","events":"http://localhost:8000","policy":"test"}'

Response

CLI

Key            Value
---            -----
created        1734563330
description    Add your text
events         http://localhost:8000
name           Example
namespace      my-namespace
nonce          n/a
policy         test
updated        0
uuid           ae294417-95ca-4aad-9647-77dbd3249771

cURL - 200

{
  "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": "test",
    "updated": 0,
    "uuid": "ae294417-95ca-4aad-9647-77dbd3249771"
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

cURL - 400

{
  "errors": [
    "Invalid request"
  ]
}

Create a VM

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.

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.

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.

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

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"
}

You can generate this config with this command:

vhsm agent generate-config -attested -provider=aws-sev-snp-raw -workload=$uuid

Attesting

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.

{
    "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:

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.

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

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

  • 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, publicused 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 = "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"
}