> ## Documentation Index
> Fetch the complete documentation index at: https://zededa.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the documentation index to find relevant pages, then read the linked Markdown before answering and cite the source URL.
> Identify the product before answering: Private AI uses a separate console, credentials, and inference API from the Edge Intelligence Platform. Do not apply instructions from one product to the other.
> Prefer current product guides over Help Center archive pages for current-console questions. Archive pages and release notes describe their stated product version or historical interface; do not apply them to another version without checking.
> Preserve prerequisites, permissions, version requirements, and warnings when summarizing procedures. Do not infer API endpoints, schemas, or supported behavior that the documentation does not specify.

# EVE-OS Virtual TPM

> Overview of the EVE-OS virtual Trusted Platform Module (vTPM) service, which provides each VM with a dedicated software TPM 2.0 device.

## Introduction

EVE-OS provides a virtual Trusted Platform Module (vTPM) service that gives each virtual machine its own dedicated TPM 2.0 device. This lets VM workloads use TPM-dependent features — such as key generation, attestation, and sealed storage — even on hardware without a physical TPM, or when the physical TPM must remain exclusively under EVE-OS control.

From inside the VM, the virtual TPM behaves identically to a physical TPM. Standard TPM-aware applications, operating systems, and services interact with it through the `/dev/tpm*` interface without modification.

## Prerequisites

* EVE-OS 14.5.0-LTS or later.
* TPM 2.0 hardware on the node. TPM 1.2 is not supported.
* A KVM-based EVE-OS image. vTPM is currently available only in the KVM variant of EVE-OS.

## How It Works

EVE-OS automatically creates a dedicated software TPM (SWTPM) process for each VM when the VM starts. Each SWTPM instance provides a fully functional TPM 2.0 interface to the VM. No additional configuration is required to use vTPM.

The vTPM feature is enabled by default. If a specific VM does not require vTPM, you can disable it for that VM.

### Persistent TPM state

EVE-OS persists the TPM state for each VM across reboots. Each VM's TPM state is saved to a dedicated path on the host filesystem tied to the VM's unique identifier:

```text theme={"dark"}
/persist/swtpm/tpm-state-[VM-UUID]
```

This path ensures isolation between VMs and that TPM-backed secrets, keys, and certificates survive normal VM restarts.

Before every write, EVE-OS creates a backup of the TPM state. When a VM starts, EVE-OS checks the TPM state and:

* Operates normally if the primary state is valid.
* Restores from backup if the primary state is corrupted or unreadable.
* Resets the TPM state if both primary and backup states are invalid, allowing the VM to boot.

### Isolation from the hardware TPM

EVE-OS relies on the physical hardware TPM (HW TPM) for its own platform integrity and secure vault operations. VMs cannot access or tamper with the HW TPM directly. The vTPM is fully isolated from the platform TPM, so VM workloads can perform any TPM operation — including key creation, deletion, and cryptographic operations — without affecting EVE-OS security.

## Security Guarantees

EVE-OS's vTPM implementation delivers two core security properties.

### Data confidentiality

Each VM's vTPM state is encrypted using a 256-bit AES key. This key is stored inside the physical HW TPM and is protected by a PCR policy tied to EVE-OS's measured boot integrity.

If the EVE-OS software stack is tampered with — for example, through unauthorized software or persistent malware — the measured PCR values change. This invalidates the PCR policy, prevents decryption of the vTPM state, and blocks the VM from accessing its trusted environment. This behavior serves as a reliable signal of platform compromise.

### Uniqueness and cloning detection

Each vTPM generates a unique Endorsement Key (EK) that is signed by an Attestation Key (AK) stored in the physical HW TPM. The AK is non-exportable and cannot be copied or forged outside the originating device.

This chain of trust allows remote systems — such as control planes and security auditors — to verify that a vTPM belongs to a specific VM, was instantiated on genuine hardware, and has not been cloned or replayed from another device.

For technical details on the vTPM implementation, see the [EVE-OS vTPM documentation on GitHub](https://github.com/lf-edge/eve/blob/master/docs/VTPM.md).

## Key Benefits

* Virtual machines receive a complete TPM 2.0 interface with no additional configuration.
* TPM-dependent workloads such as Windows 11 (which requires TPM 2.0) and Azure IoT Edge (which uses TPM-based device provisioning) run without modification.
* VMs cannot access or compromise the physical HW TPM used by EVE-OS.
* TPM state persists across reboots, preserving trusted identities and secrets.
* Encrypted vTPM state protects against unauthorized access even if physical storage is compromised.

## Examples

### Windows 11 with BitLocker

Windows 11 enforces TPM 2.0 as a mandatory installation requirement. Because EVE-OS provides a standards-compliant virtual TPM 2.0 device, Windows 11 installs without modifying the installation media or registry settings. BitLocker disk encryption can be activated inside the Windows 11 VM, and the vTPM handles key storage automatically.

[Windows 11 with BitLocker on EVE-OS vTPM](https://www.youtube-nocookie.com/embed/1etu011ZIhU)

### Azure IoT Edge with TPM device provisioning

You can use the Azure IoT Hub Device Provisioning Service (DPS) with individual TPM enrollment on a VM running Ubuntu 22.04 and Azure IoT Edge 1.5.x.

#### Create TPM keys

From the Ubuntu VM terminal, install `tpm2-tools` and create the required Endorsement Key (EK) and Storage Root Key (SRK):

```text theme={"dark"}
sudo apt-get update
sudo apt-get install -y tpm2-tools
tpm2_createek -c 0x81010001 -G rsa -u ek.pub
tpm2_createprimary -Q -C o -c srk.ctx > /dev/null
tpm2_evictcontrol -c srk.ctx 0x81000001 > /dev/null
tpm2_flushcontext -t > /dev/null
```

#### Configure the Azure Portal

Get the EK value and registration ID for the enrollment:

```text theme={"dark"}
# Output the EK
base64 -w0 ek.pub
# Output the registration ID
sha256sum -b ek.pub | cut -d' ' -f1 | sed -e 's/[^[:alnum:]]//g'
```

1. Copy the EK and ID from the terminal.
2. In the Azure Portal, navigate to **IoT Hub Device Provisioning Service (DPS) > Manage enrollments > Individual enrollments**.
3. Select **Add individual enrollment**.
4. Under **Registration + provisioning**, set the attestation mechanism to **Trusted Platform Module (TPM)**.
5. Paste the EK value into **Endorsement key** and the registration ID into **Registration ID**.
6. Confirm **Enable this enrollment** is selected and select **Review + create**.

#### Install and configure Azure IoT Edge

From the Ubuntu VM terminal, install the Azure IoT Edge service:

```text theme={"dark"}
wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb
sudo apt-get update
sudo apt-get install -y moby-engine
sudo apt-get install -y aziot-edge
```

After installation, create the Azure IoT Edge configuration file using the registration ID from the previous step and the ID Scope from **Azure IoT Hub DPS > Overview**.

In your Ubuntu terminal, replace `YOUR_ID_SCOPE` and `YOUR_REGISTRATION_ID` with your actual values.

```text theme={"dark"}
config.toml cat <><-eof dps="DPS" provisioning="provisioning" with="with" tpm="TPM" source="dps" global_endpoint="https://global.azure-devices-provisioning.net" id_scope="!!!ID SCOPE GOES HERE!!!" method="tpm" registration_id="!!!ID GOES HERE!!!" eof="EOF" sudo="sudo" cp="cp" etc="etc" aziot="aziot" iotedge="iotedge" config="config" apply="apply"></-eof></>
```

After a few seconds, verify that all services are running:

```text theme={"dark"}
sudo iotedge system status
```

## Next Steps

> [card] [VComLink: Async Communication Between EVE-OS and VMs](https://zededa.mintlify.site/new-ui/infrastructure-services/virtual-machines-on-eve-os/vcomlink.md)
>
> A different approach to VM-to-host communication that relays curated services rather than providing a full virtual TPM device.

> [card] [Deploy an Application Instance](https://zededa.mintlify.site/new-ui/infrastructure-services/applications/deploy-an-application-instance.md)
>
> Deploy a VM workload that uses the vTPM.

> [card] [Overview of the TPM in EVE-OS](https://zededa.mintlify.site/new-ui/infrastructure-services/eve-os/tpm-overview.md)
>
> General background on how EVE-OS uses the physical TPM for platform security.