Create or update identities

Identities in this system are versioned by their creation timestamp. For verification purposes, the most recently created identity for a given name is always used. This design allows you to easily update an identity when it becomes outdated without needing to change your policy or the attestation configuration itself.

Prerequisites

• Install and configure Nitride.

• Install vHSM CLI.

• Install curl and jq tools.

• Log in as root user to use the vHSM CLI tool, else use the root token for vHSM instance to use curl.

Create a new identity named test of the type firmware :

vHSM CLI

vhsm write auth/ratls/identities - <<'EOF'
{
  "type": "firmware",
  "name": "test-local",
  "values": {
    "measurement": "eb5c02d3ba319e65218994fc47925cf8a5e9a433081c44d4d989434f15a7c6d715d302401b3147da04e49abc99e50aea"
  }
}
EOF

cURL

This method is more universal and directly interacts with the API endpoint. Remember to replace hvs.XXXXX with your valid authentication token.

curl -H "X-Vault-Token: hvs.XXXXX" \
    http://localhost:8200/v1/auth/ratls/identities \
    --data '{"type":"firmware","name":"test-local","values":{"measurement":"eb5c02d3ba319e65218994fc47925cf8a5e9a433081c44d4d989434f15a7c6d715d302401b3147da04e49abc99e50aea"}}'9e65218994fc47925cf8a5e9a433081c44d4d989434f15a7c6d715d302401b3147da04e49abc99e50aea"}}'

The output is similar to:

vHSM CLI

Key        Value
---        -----
created    1749465559
name       test-local
type       firmware
values     map[measurement:eb5c02d3ba319e65218994fc47925cf8a5e9a433081c44d4d989434f15a7c6d715d302401b3147da04e49abc99e50aea]

cURL

{
  "request_id": "97074d26-615c-a20d-ff88-8b14d2a75b93",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "created": 1734559789,
    "name": "test-local",
    "type": "firmware",
    "values": {
      "measurement": "eb5c02d3ba319e65218994fc47925cf8a5e9a433081c44d4d989434f15a7c6d715d302401b3147da04e49abc99e50aea"
    }
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Possible Error Response:

If there is an. issue with the request body, such as unknown identity type, you might receive an error:

{
  "errors": [
    "failed parsing: unknown type"
  ]
}

Description of values field content by Identity type:

The content you put in the values field within the request body depends on the type of the identity you are creating or updating.

Identity Type	Description of values Content
platform	It would typically contain platform-specific attestation data.
firmware	Used for firmware-level identities. - measurement: The OVMF/UEFI measurement (e.g., a SHA256 hash). - firmware: The firmware version of the platform. Supports semantic versioning constraints like >= 1.55.22. - root_of_trust: The certificate chain used in the verification process.
workload	Used for workload-level identities. - hash: A human-readable name of the hash function used (e.g., "sha256"). - pcrs: A dictionary mapping integer PCR (Platform Configuration Register) indices to their encoded PCR values (strings).
metadata	More details about the identity.