Identity secrets engine - TPM (API)

Vault represents a physical or virtual Trusted Platform Module (TPM) device as a record in the identity store identified by its Endorsement Key (EK) public key. TPM records allow Vault to track and control access for specific TPM devices.

Key characteristics of TPM records:

• The ID is automatically derived as the SHA-256 hash of the decoded bytes from the tpm_ek_public_key field and cannot be changed after creation.
• The tpm_ek_public_key field is immutable and is only set at creation time.
• TPM IDs are scoped to a namespace, so the same EK public key may be registered in multiple namespaces without conflict.
• A disabled TPM cannot be used for authentication or certificate generation.

Create a TPM

This endpoint creates a new TPM record. The tpm_ek_public_key field is required and must be a PEM-encoded public key with the PUBLIC KEY header. Create a new TPM record from a PEM-encoded public key with the PUBLIC KEY header.

Parameters

• name (string: "tpm-<random-hex>") – A human-friendly name for the TPM record. The TPM name must be unique within the namespace. If you do not provide a name, Vault generates a default name in the format tpm_<random-hex>. You can update the name later using the update endpoint.

• tpm_ek_public_key (string: <required>) – PEM-encoded TPM Endorsement Key (EK) public key. The key must be a valid PEM block with type PUBLIC KEY. The key value is immutable and cannot be changed after the TPM record is created.

• metadata (key-value-map: {}) – Metadata to be associated with the TPM record. In CLI commands, you can repeat the metadata parameter multiple times and Vault will merge them together to create a single update string.

• disabled (bool: false) – Whether the TPM is disabled. You cannot generate certificates or authenticate with a disabled TPM.

Sample payload

{
  "name": "my-tpm",
  "tpm_ek_public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----\n",
  "metadata": {
    "machine_name": "server-01",
    "location": "datacenter-east"
  },
  "disabled": false
}

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request POST \
    --data @payload.json \
    ${VAULT_ADDR}/v1/identity/tpm

Sample response

{
  "data": {
    "disabled": false,
    "id": "sha256-a3f1c2d4e5b6...",
    "metadata": {
      "location": "datacenter-east",
      "machine_name": "server-01"
    },
    "name": "my-tpm",
    "tpm_ek_public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----\n"
  }
}

Read TPM by ID

Query a TPM record by its identifier.

Parameters

• id (string: <required>) – Identifier of the TPM record.

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    ${VAULT_ADDR}/v1/identity/tpm/id/sha256-a3f1c2d4e5b6...

Sample response

{
  "data": {
    "disabled": false,
    "id": "sha256-a3f1c2d4e5b6...",
    "metadata": {
      "location": "datacenter-east",
      "machine_name": "server-01"
    },
    "name": "my-tpm",
    "tpm_ek_public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----\n"
  }
}

Update TPM by ID

Update an existing TPM record by its identifier.

The tpm_ek_public_key field cannot be changed. Supplying a value that differs from the existing key returns an error.

Parameters

• id (string: <required>) – Identifier of the TPM record.

• name (string: <optional>) – Updated name for the TPM record. The new name must be unique within the namespace.

• metadata (key-value-map: {}) – Updated metadata. Replaces the existing metadata entirely.

• disabled (bool: false) – Whether the TPM is disabled.

Sample payload

{
  "name": "renamed-tpm",
  "metadata": {
    "machine_name": "server-01-updated"
  },
  "disabled": true
}

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request POST \
    --data @payload.json \
    ${VAULT_ADDR}/v1/identity/tpm/id/sha256-a3f1c2d4e5b6...

Sample response

{
  "data": {
    "disabled": true,
    "id": "sha256-a3f1c2d4e5b6...",
    "metadata": {
      "machine_name": "server-01-updated"
    },
    "name": "renamed-tpm",
    "tpm_ek_public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----\n"
  }
}

Delete TPM by ID

Delete a TPM record by its identifier. Deleting a record that does not exist is idempotent and returns successfully as a no-op.

Parameters

• id (string: <required>) – Identifier of the TPM record.

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request DELETE \
    ${VAULT_ADDR}/v1/identity/tpm/id/sha256-a3f1c2d4e5b6...

List TPMs by ID

Fetch a list of all TPM record identifiers in the current namespace.

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request LIST \
    ${VAULT_ADDR}/v1/identity/tpm/id

Sample response

{
  "data": {
    "keys": [
      "sha256-a3f1c2d4e5b6...",
      "7d8e9f0a1b2c..."
    ]
  }
}

Create/Update TPM by name

Create or update a TPM record by name. Vault creates a new record if no TPM with the given name exists and the tpm_ek_public_key is set. Otherwise, Vault updates the record with the given name, if it exists.

Parameters

• name (string: <required>) – Name of the TPM record.

• tpm_ek_public_key (string: <required on create>) – PEM-encoded TPM Endorsement Key public key. Vault requires the key when creating a new record. You cannot change the key on an existing record.

• metadata (key-value-map: {}) – Metadata to be associated with the TPM record. Replaces the existing metadata entirely on update.

• disabled (bool: false) – Whether the TPM is disabled.

Sample payload

{
  "tpm_ek_public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----\n",
  "metadata": {
    "machine_name": "server-02"
  }
}

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request POST \
    --data @payload.json \
    ${VAULT_ADDR}/v1/identity/tpm/name/my-tpm

Sample response

{
  "data": {
    "disabled": false,
    "id": "sha256-a3f1c2d4e5b6...",
    "metadata": {
      "machine_name": "server-02"
    },
    "name": "my-tpm",
    "tpm_ek_public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----\n"
  }
}

Read TPM by name

Query a TPM record by its name.

Parameters

• name (string: <required>) – Name of the TPM record.

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    ${VAULT_ADDR}/v1/identity/tpm/name/my-tpm

Sample response

{
  "data": {
    "disabled": false,
    "id": "sha256-a3f1c2d4e5b6...",
    "metadata": {
      "machine_name": "server-02"
    },
    "name": "my-tpm",
    "tpm_ek_public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkq...\n-----END PUBLIC KEY-----\n"
  }
}

Delete TPM by name

Delete a TPM record by its name. Deleting a record that does not exist is idempotent and returns successfully as a no-op.

Parameters

• name (string: <required>) – Name of the TPM record.

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request DELETE \
    ${VAULT_ADDR}/v1/identity/tpm/name/my-tpm

List TPMs by name

Fetch a list of all TPM record names in the current namespace.

Sample request

$ curl \
    --header "X-Vault-Token: ${VAULT_TOKEN}" \
    --request LIST \
    ${VAULT_ADDR}/v1/identity/tpm/name

Sample response

{
  "data": {
    "keys": [
      "my-tpm",
      "server-02-tpm"
    ]
  }
}