Skip to content

Intel® TDX Enabling Guide

Introduction

This Intel® TDX enabling guide provides a distilled set of instructions for integrating, deploying, and using Intel® Trust Domain Extensions (Intel TDX). Among other things, it covers essential prerequisites, integration steps, testing procedures, performance measurement, and maintenance steps. In the following, we provide a brief introduction to Intel TDX. More specific details and explanations are covered in dedicated specification documents and other documentation.

What is Intel TDX?

Intel TDX is Intel's newest Confidential Computing technology. The Trusted Execution Environment (TEE) provided by Intel TDX provides hardware isolation of individual Virtual Machines (VMs) designed to protect sensitive data and applications from unauthorized access. VMs protected by Intel TDX are called Trust Domains (TDs).

A CPU-measured Intel TDX Module enables Intel TDX. This software module runs in a new CPU Secure Arbitration Mode (SEAM) as a peer to the Virtual Machine Manager (VMM), and it supports TD entries and exits using the existing virtualization infrastructure. The module is hosted in a reserved memory space identified by the SEAM Range Register (SEAMRR).

Intel TDX uses hardware extensions for managing and encrypting memory and it protects both the confidentiality and integrity of the TD CPU state from all software in non-SEAM mode. Intel TDX also uses architectural elements such as SEAM, a shared bit in Guest Physical Address (GPA), secure Extended Page Table (EPT), physical-address-metadata table, Intel® Total Memory Encryption – Multi-Key (Intel® TME-MK), and remote attestation.

Intel TDX is designed to ensure data integrity, confidentiality, and authenticity, which empowers engineers and tech professionals to create and maintain more secure systems, enhancing trust in virtualized environments.

Intended Audience

This guide is for engineers and technical staff from Cloud Service Providers (CSPs), System Integrators (SIs), on-premises enterprises involved in cloud feature integration, as well as cloud guest users (i.e., end users). Throughout this document, we use CSPs as examples for brevity.

Scope

In its current version, this guide is for Intel TDX on 5th Gen Intel® Xeon® Scalable processors. The following TDX features are currently supported in this guide:

  • Launching a TD
  • Shutting down a TD
  • Attesting a TD

Additional features may be added to this guide in the future, as the features become available in the ecosystem. Examples include:

  • TD Preserving Updates
  • TD Live Migration
  • TD Partitioning
  • Intel® TDX Connect

Reading Guideline

This guide encompasses the entire workflow of an Intel TDX deployment as illustrated in the following figure, and the guide is structured accordingly with every step in the workflow having a dedicated page.

graph LR
    %%{init:{'flowchart':{'diagramPadding':0}}}%%
    A("<p style='width:100px;color:#36464e'>Infrastructure\nSetup</p>")
    B("<p style='width:100px;color:#36464e'>Hardware\nSelection</p>")
    C("<p style='width:100px;color:#36464e'>Hardware\nSetup</p>")
    D("<p style='width:100px;color:#36464e'>Host OS\nSetup</p>")
    E("<p style='width:100px;color:#36464e'>Guest OS\nSetup</p>")
    F("<p style='width:100px;color:#36464e'>Trust Domain\nat Runtime</p>")
    A:::boxes --> B
    B:::boxes --> C
    C:::boxes --> D
    D:::boxes --> E
    E:::boxes --> F:::boxes
    classDef boxes fill:#85b4ff,stroke-width:0px

Depending on the target offering, the different steps are covered by employees of the provider of the offering or by the end user. In the following, we show cases that might happen in a concrete Intel TDX implementation project. Note these examples are just for illustrative purposes and the situation might be different in your case.

  • Bare metal offering:

    graph LR
    %%{init:{'flowchart':{'diagramPadding':0}}}%%
    A("<p style='width:100px;color:#36464e'>Infrastructure\nSetup</p>")
    B("<p style='width:100px;color:#36464e'>Hardware\nSelection</p>")
    C("<p style='width:100px;color:#36464e'>Hardware\nSetup</p>")
    D("<p style='width:100px;color:#36464e'>Host OS\nSetup</p>")
    E("<p style='width:100px;color:#36464e'>Guest OS\nSetup</p>")
    F("<p style='width:100px;color:#36464e'>Trust Domain\nat Runtime</p>")
    A:::boxProv --> B
    B:::boxProv --> C
    C:::boxProv --> D
    D:::boxProv --> E
    E:::boxUser --> F:::boxUser
    classDef boxProv fill:#ffc000,stroke-width:0px
    classDef boxUser fill:#92d050,stroke-width:0px
    graph LR
    %%{init:{'flowchart':{'diagramPadding':0}}}%%
    A(" "):::boxProv --- |Provider| B
    B(" "):::boxUser --- |User| C(" "):::hidden

    classDef boxProv fill:#ffc000,stroke-width:0px
    classDef boxUser fill:#92d050,stroke-width:0px
    classDef hidden fill:#FFFFFF,stroke-width:0px,visibility:hidden

    linkStyle 0,1 stroke-width:0px,background-color:black;

  • Virtual machine offering:

    graph LR
    %%{init:{'flowchart':{'diagramPadding':0}}}%%
    A("<p style='width:100px;color:#36464e'>Infrastructure\nSetup</p>")
    B("<p style='width:100px;color:#36464e'>Hardware\nSelection</p>")
    C("<p style='width:100px;color:#36464e'>Hardware\nSetup</p>")
    D("<p style='width:100px;color:#36464e'>Host OS\nSetup</p>")
    E("<p style='width:100px;color:#36464e'>Guest OS\nSetup</p>")
    F("<p style='width:100px;color:#36464e'>Trust Domain\nat Runtime</p>")
    A:::boxProv --> B
    B:::boxProv --> C
    C:::boxProv --> D
    D:::boxProv --> E
    E:::boxProv --> F:::boxUser
    classDef boxProv fill:#ffc000,stroke-width:0px
    classDef boxUser fill:#92d050,stroke-width:0px
    graph LR
    %%{init:{'flowchart':{'diagramPadding':0}}}%%
    A(" "):::boxProv --- |Provider| B
    B(" "):::boxUser --- |User| C(" "):::hidden

    classDef boxProv fill:#ffc000,stroke-width:0px
    classDef boxUser fill:#92d050,stroke-width:0px
    classDef hidden fill:#FFFFFF,stroke-width:0px,visibility:hidden

    linkStyle 0,1 stroke-width:0px,background-color:black;

  • Platform service offering:

    graph LR
    %%{init:{'flowchart':{'diagramPadding':0}}}%%
    A("<p style='width:100px;color:#36464e'>Infrastructure\nSetup</p>")
    B("<p style='width:100px;color:#36464e'>Hardware\nSelection</p>")
    C("<p style='width:100px;color:#36464e'>Hardware\nSetup</p>")
    D("<p style='width:100px;color:#36464e'>Host OS\nSetup</p>")
    E("<p style='width:100px;color:#36464e'>Guest OS\nSetup</p>")
    F("<p style='width:100px;color:#36464e'>Trust Domain\nat Runtime</p>")
    A:::boxProv --> B
    B:::boxProv --> C
    C:::boxProv --> D
    D:::boxProv --> E
    E:::boxProv --> F:::boxProv
    classDef boxProv fill:#ffc000,stroke-width:0px
    classDef boxUser fill:#92d050,stroke-width:0px
    graph LR
    %%{init:{'flowchart':{'diagramPadding':0}}}%%
    A(" "):::boxProv --- |Provider| B
    B(" "):::boxUser --- |User| C(" "):::hidden

    classDef boxProv fill:#ffc000,stroke-width:0px
    classDef boxUser fill:#92d050,stroke-width:0px
    classDef hidden fill:#FFFFFF,stroke-width:0px,visibility:hidden

    linkStyle 0,1 stroke-width:0px,background-color:black;

Please read the pages that are most suitable for your target offering and your persona.

Infrastructure Setup

On this page, we provide important information that needs to be considered by the infrastructure provider of an Intel® TDX offering.

Intel TDX Remote Attestation

One main feature of Intel TDX is remote attestation. At its core, remote attestation is a process used by software to demonstrate to a remote party that the software has been properly instantiated on a platform. Intel TDX attestation allows a remote party to ensure that a Virtual Machine (VM) is using Intel TDX for hardware-isolation and protection, as well as ensuring all components of the Intel TDX Trusted Compute Base (TCB) are up to date (or at an expected level).

In this section, we will cover all aspects related to remote attestation relevant during infrastructure setup. Each of the following topics has a dedicated sub-section:

Background Information

The base piece of information used for Intel TDX remote attestation is called a quote, or more explicitly for Intel TDX, a TD Quote. A TD Quote is a cryptographic attestation, or secure proof, generated by Intel TDX hardware to prove the authenticity and state of a Trust Domain (TD).

TD Quote Generation is the process by which a TD Quote is generated in a remote attestation flow. TD Quote Generation is always done on the Intel TDX hardware. The generation can be triggered on boot of the TD, by an external party sending a request to the TD, or by other signals, but the actual flow starts by the TD reaching out to the hardware to request a TD Report. This TD Report contains measurements of the TD and other security critical attributes. All security critical steps to generate a TD Report are executed by hardware instructions.

A quote generation service (qgs) is a service that aids in the TD Quote Generation flow. The qgs has to run on the same host as the TD and it can run directly in the host operating system (OS) or a dedicated Virtual Machine (VM). In particular, the qgs hosts the TD Quoting Enclave, which receives the TD Report from the TD, verifies that the TD Report was generated on the same host, and then signs the TD Report with a private key for which the trust is rooted in Intel. The signed TD Report is called a TD Quote. Note that the TD Quoting Enclave is an Intel SGX enclave and therefore, requires Intel SGX to be enabled on the platform.

TD Quote Verification is the process by which a TD Quote is verified in a remote attestation flow. This verification can be done by any party and the checks performed are defined by this party. Among others, these checks can include:

  • Verification of the signature of the TD Quote using the certification chain rooted in an Intel CA. This guarantees that the TD Quote was generated by a genuine Intel CPU.
  • Verification that all the components of the Intel TDX TCB are at a certain level (see TCB-Recovery section).
  • Verification that measurements of the TD are as expected.
  • Verification that TD-supplied report data contained in the TD Quote is as expected, e.g., that it contains a certain public key or matching an expected nonce.

A quote verification service (qvs) can be used to support the verification of the TD Quote.

Collateral Caching Service

For TD Quote Generation and TD Quote Verification, collateral is needed. Intel provides the necessary collateral through the Intel® Provisioning Certification Service for ECDSA Attestation (PCS). According to the terms of use of the PCS, requesting collateral on the fly at runtime is not allowed. Instead, caching of the collateral is mandatory to avoid unnecessary high-frequency calls to the PCS.

You have to set up a collateral caching service in your infrastructure and configure the infrastructure in a way making this service accessible during TD Quote Generation and/or TD Quote Verification. Among others, the following deployment models are possible:

  • Deploy one collateral caching service on the host OS of each platform doing TD Quote Generation and/or TD Quote Verification.
  • Deploy a collateral caching service centrally in your infrastructure serving multiple platforms during TD Quote Generation and/or TD Quote Verification. The central server does not have to support Intel TDX.

For TD Quote Generation, it is only needed to cache the PCK Certificate of a platform. For TD Quote Verification, Quote Verification Collateral (e.g., TCBInfo, Quoting Enclave Identity, and Certificate Revocation Lists) is needed. The Quote Verification Collateral has to be updated regularly. Every piece of the Quote Verification Collateral contains a nextUpdate field that should be considered the collateral expiration date. Currently, the expiration date is set to 30 days from the time of download, which means that this collateral needs to be refreshed at least every 30 days.

Provisioning Certificate Caching Service (PCCS)

Intel provides a reference, open-source implementation of a collateral caching service called Provisioning Certificate Caching Service (PCCS) via GitHub. There is also a design guide available for parties who want to know more about how Intel's PCCS works or those wanting to write their own collateral caching service.

The PCCS can be installed in multiple ways, among others, as a system service from a distribution repository, as a Docker container somewhere in your network, or even as a Kubernetes pod. In the following, we provide details of the first alternative.

Set up PCCS as system service

  1. To setup the PCCS in the next step, you need a subscription key for the Intel PCS.

    • If you did not request such a subscription key before, subscribe to Intel PCS, which requires to log in (or to create an account). Two subscription keys are generated (for key rotation) and both can be used for the following steps.
    • If you did request such a subscription key before, retrieve one of your keys, which requires to log in. You have two subscription keys (for key rotation), and both can be used for the following steps.

  2. If not done during another component installation, set up the appropriate Intel SGX package repository for your distribution of choice:

    sudo dnf install -y wget yum-utils
sudo mkdir /opt/intel
cd /opt/intel
sudo wget https://download.01.org/intel-sgx/latest/dcap-latest/linux/distro/centos-stream9/sgx_rpm_local_repo.tgz
sudo tar xvf sgx_rpm_local_repo.tgz
sudo yum-config-manager --add-repo file:///opt/intel/sgx_rpm_local_repo

    echo 'deb [signed-by=/etc/apt/keyrings/intel-sgx-keyring.asc arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu mantic main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list
wget https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key
sudo mkdir -p /etc/apt/keyrings
cat intel-sgx-deb.key | sudo tee /etc/apt/keyrings/intel-sgx-keyring.asc > /dev/null
sudo apt-get update

  3. Install PCCS with following commands. During installation, answer Y when asked if the PCCS should be installed now, Y when asked if PCCS should be configured now, and enter subscription key generated in step 1 when asked for Intel PCS API key. Answer the remaining questions according to your needs, e.g., your proxy settings, a desired user password, and an admin password. The configuration step will also allow you to create a self-signed SSL certificate for the PCCS.

    Warning

    A self-signed SSL certificate should only be used for testing. In a production environment, a trusted SSL certificate from a known certificate authority should be used.

    curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo -E bash -
sudo yum install -y nodejs-20.11.1-1nodesource
sudo yum install -y --nogpgcheck sgx-dcap-pccs
sudo -u pccs /opt/intel/sgx-dcap-pccs/install.sh
sudo systemctl start pccs

    curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -yq --no-install-recommends nodejs=20.11.1-1nodesource1
sudo apt-get install -y cracklib-runtime
sudo apt install -y --no-install-recommends sgx-dcap-pccs
How to check successful PCCS setup?

You can verify PCCS is active and can reach the PCS with the command below: 

curl -k -G "https://localhost:8081/sgx/certification/v4/rootcacrl"

If successful, the HEX-encoded DER representation of the Intel Root CA CRL will be displayed. 

308201213081c8020101300a06082a8648ce3d0403023068311a301806035504030c11496e74656c2053475820526f6f74204341311a3018060355040a0c11496e74656c20436f72706f726174696f6e3114301206035504070c0b53616e746120436c617261310b300906035504080c024341310b3009060355040613025553170d3233303430333130323235315a170d3234303430323130323235315aa02f302d300a0603551d140403020101301f0603551d2304183016801422650cd65a9d3489f383b49552bf501b392706ac300a06082a8648ce3d0403020348003045022051577d47d9fba157b65f1eb5f4657bbc5e56ccaf735a03f1b963d704805ab118022100939015ec1636e7eafa5f426c1e402647c673132b6850cabd68cef6bad7682a03

How to check service log of the PCCS?

You can check the service log of the PCCS with the following command:

sudo journalctl -u pccs

The PCCS should be running. Example output after PCCS start:

date time localhost systemd[1]: Started pccs.service - Provisioning Certificate Caching Service (PCCS).
date time localhost node[3305]: date time [info]: HTTPS Server is running on: https://localhost:8081
How to change the configuration of the PCCS?

If you need to make changes to the PCCS setup after installation, the default location of the PCCS configuration file is /opt/intel/sgx-dcap-pccs/config/default.json. If changes are made to the PCCS configuration file, you will need to restart the PCCS service using the following command:

sudo systemctl restart pccs

sudo systemctl restart pccs

Platform Registration

To enable remote attestation on platforms containing one or more Intel® Xeon® Scalable Processors, the platform needs to be registered with the Intel® SGX and Intel® TDX Registration Service for Scalable Platforms (IRS). This registration is always done from the host OS of the platform.

When is a platform registration necessary?

A platform registration is necessary in the following cases:

  • First boot of the machine.
  • An SGX Factory Reset is triggered in the BIOS setup menu.
  • Anytime a TCB-Recovery occurs where platform firmware components other than the Intel TDX Module are impacted.
  • Adding or swapping a CPU in the platform.
  • Flash with shared platform keys gets wiped.
Is registration required if I only have one CPU installed?

Platform registration is required no matter the count of CPUs installed in a system. Even if only one CPU is present, platform registration is still necessary.

How to troubleshot registration?

See the dedicated troubleshooting section.

A key piece of information required for this registration is the Platform Manifest (PM). The PM is a blob of data containing information about all CPUs in the system, including the shared platform keys which are negotiated between the available CPU packages in the platform. The contained shared platform keys are encrypted with the Registration Server's Encryption Key (RSEK), which is a public key. The PM is prepared by the BIOS and provided to host OS software via a UEFI variable. Note that by default, VMs do not have access to the UEFI variable that holds the PM.

Two platform registration variants are possible: Direct Registration and Indirect Registration. In the following sections, we introduce these two variants and describe the following five sub-variants:

  1. Online, automatic, single platform Direct Registration.
  2. On-/offline, manual, single platform Direct Registration.
  3. Online, manual, single platform, PCCS-based Indirect Registration.
  4. On-/offline, manual, multi platform, PCCS-based Indirect Registration.
  5. On-/offline, manual, multi platform, local cache-based Indirect Registration.

All registration variants support end-to-end Intel TDX remote attestation. It is up to the infrastructure owner to decide which variant and sub-variant to use, based on the provided attributes.

Note that the Intel TDX remote attestation flow is based on a remote attestation flow originally designed for Intel SGX and was enhanced to also support Intel TDX. Therefore, it is required to install Intel SGX packages in many of the described steps. For information beyond the level of detail presented in the following, see the Remote Attestation for Multi-Package Platforms using Intel® SGX Datacenter Attestation Primitives (DCAP) documentation.

Direct Registration

With Direct Registration, the PM is sent directly to the IRS via the service's REST API. The IRS is able to recognize a platform containing genuine Intel TDX-enabled CPUs based on the PM. The IRS uses the encrypted, shared platform keys contained in the PM to generate a Provisioning Certification Key Certificate (PCK Certificate) for the platform. In this case, the PM (and the included encrypted, shared platform keys) are stored by the IRS. As a result, each request later asking for the PCK Certificate for this platform does only need to contain the platform's Platform Provisioning ID (PPID). Alternatively, the PM can be contained in such a request.

How can a PCK Certificate generated via Direct Registration be recognized?

Every PCK Certificate generated via Direct Registration will contain true in its CachedKeys attribute.

In the next subsections, we describe the following variants of direct registration:

  1. Online, automatic, single platform Direct Registration.
  2. On-/offline, manual, single platform Direct Registration.
Online, automatic, single platform Direct Registration

Requirements of this method:

The basic flow of this registration method:

  1. In the BIOS of the platform to register, enable the "SGX Auto MP Registration Agent" setting. As a result, the BIOS sets a specific UEFI variable on boot indicating direct registration should be attempted by the MPA. A PM is available if a registration is necessary.
  2. On the host OS of platform to register, install the MPA.
  3. On the host OS of platform to register, the MPA runs as a service and starts when the OS boots.
    • If the MPA finds a PM in a specific UEFI variable, the MPA attempts to send the PM to the IRS.
    • If the MPA does not find a PM in a specific UEFI variable, it sleeps until next OS boot.

Detailed steps to use this registration method:

  1. In the BIOS of the platform to register, set the SGX Auto MP Registration Agent setting to Enabled.

  2. On the host OS of platform to register, set up MPA:

    • If not done during another component installation, set up the appropriate Intel SGX package repository for your distribution of choice:

      sudo dnf install -y wget yum-utils
sudo mkdir /opt/intel
cd /opt/intel
sudo wget https://download.01.org/intel-sgx/latest/dcap-latest/linux/distro/centos-stream9/sgx_rpm_local_repo.tgz
sudo tar xvf sgx_rpm_local_repo.tgz
sudo yum-config-manager --add-repo file:///opt/intel/sgx_rpm_local_repo

      echo 'deb [signed-by=/etc/apt/keyrings/intel-sgx-keyring.asc arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu mantic main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list
wget https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key
sudo mkdir -p /etc/apt/keyrings
cat intel-sgx-deb.key | sudo tee /etc/apt/keyrings/intel-sgx-keyring.asc > /dev/null
sudo apt-get update

      sudo mkdir /opt/intel
cd /opt/intel
sudo wget https://download.01.org/intel-sgx/latest/dcap-latest/linux/distro/suse15.4-server/sgx_rpm_local_repo.tgz
sudo tar xvf sgx_rpm_local_repo.tgz
sudo zypper addrepo /opt/intel/sgx_rpm_local_repo sgx_rpm_local_repo

    • Install MPA:

      sudo dnf --nogpgcheck install -y sgx-ra-service

      sudo apt install -y sgx-ra-service

      sudo zypper --no-gpg-checks install -y sgx-ra-service

  3. Reboot host OS to trigger registration.

How to check successful MPA-based registration?

A log file for the MPA can be found at /var/log/mpa_registration.log. The following shows a sample log for a successful registration:

cat /var/log/mpa_registration.log
[date time] INFO: SGX Registration Agent version: 1.20.100.2
[date time] INFO: Starts Registration Agent Flow.
[date time] INFO: Server URL: https://api.trustedservices.intel.com:443
[date time] INFO: Registration Flow - PLATFORM_ESTABLISHMENT or TCB_RECOVERY.
...
[date time] INFO: Registration Flow - PLATFORM_ESTABLISHMENT or TCB_RECOVERY passed successfully.
[date time] INFO: Finished Registration Agent Flow.
How to check service log of the MPA?

You can check the service log of the MPA with the following command:

sudo journalctl -u mpa_registration_tool

sudo journalctl -u mpa_registration_tool

sudo journalctl -u mpa_registration_tool
How to change the configuration of the MPA?

If you need to make changes to the MPA configuration (for example, increase log level or manually add a proxy), edit the configuration file located at /etc/mpa_registration.conf. Information on settings in this MPA configuration file can be found in the MPA's readme on GitHub.

On-/offline, manual, single platform Direct Registration

Requirements of this method:

  • Dependent on the used option of this method:

    1. Online option: platform to be registered needs Internet access during the registration procedure.
    2. Offline option: platform to be registered does not need Internet access, but another platform with Internet access is necessary. This option is usable in an air-gapped environment. The platform with Internet access does not need to support Intel TDX.

  • The PCK Cert ID Retrieval Tool (PCKCIDRT) — a tool to support the retrieval of the PM and other platform information.

The basic flow of this registration method:

  1. On the host OS of platform to register, deploy the PCKCIDRT.
  2. On the host OS of platform to register, use the PCKCIDRT to gather the PM and other platform information into a single file.
  3. On the host OS of platform to register, extract the PM from the generated file.

  4. Dependent on the used option of this method:

    1. Online option: nothing needs to be done.
    2. Offline option: transfer the PM to the platform with Internet access.

    Independent of the used option, we call the platform with Internet access Registration Platform in the following.

  5. On the Registration Platform, send the PM to the IRS. The IRS generates a PCK Certificate and returns the PPID of the registered platform, i.e., a PCK Certificate is not returned in this registration method.

Detailed steps to use this registration method:

  1. On the host OS of platform to register, retrieve the PCKCIDRT with one of the following two alternatives:

    1. From the package repository of your distribution of choice:

      • If not done during another component installation, set up the appropriate Intel SGX package repository:

        sudo dnf install -y wget yum-utils
sudo mkdir /opt/intel
cd /opt/intel
sudo wget https://download.01.org/intel-sgx/latest/dcap-latest/linux/distro/centos-stream9/sgx_rpm_local_repo.tgz
sudo tar xvf sgx_rpm_local_repo.tgz
sudo yum-config-manager --add-repo file:///opt/intel/sgx_rpm_local_repo

        echo 'deb [signed-by=/etc/apt/keyrings/intel-sgx-keyring.asc arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu mantic main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list
wget https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key
sudo mkdir -p /etc/apt/keyrings
cat intel-sgx-deb.key | sudo tee /etc/apt/keyrings/intel-sgx-keyring.asc > /dev/null
sudo apt-get update

        sudo mkdir /opt/intel
cd /opt/intel
sudo wget https://download.01.org/intel-sgx/latest/dcap-latest/linux/distro/suse15.4-server/sgx_rpm_local_repo.tgz
sudo tar xvf sgx_rpm_local_repo.tgz
sudo zypper addrepo /opt/intel/sgx_rpm_local_repo sgx_rpm_local_repo

      • Install PCKCIDRT:

        sudo dnf --nogpgcheck install -y sgx-pck-id-retrieval-tool

        sudo apt install -y sgx-pck-id-retrieval-tool

        sudo zypper --no-gpg-checks install -y sgx-pck-id-retrieval-tool
sudo ./PCKIDRetrievalTool

    2. From a standalone package available for various distributions:

      Note

      The version/filename of the PCKCIDRT standalone package may change over time, so browsing for the latest version/filename may be required.

      sudo dnf install -y wget
wget https://download.01.org/intel-sgx/latest/dcap-latest/linux/distro/centos-stream9/PCKIDRetrievalTool_v1.20.100.2.tar.gz
tar xvzf PCKIDRetrievalTool_v1.20.100.2.tar.gz

      wget https://download.01.org/intel-sgx/latest/dcap-latest/linux/distro/ubuntu23.10-server/PCKIDRetrievalTool_v1.20.100.2.tar.gz
tar xvzf PCKIDRetrievalTool_v1.20.100.2.tar.gz

      wget https://download.01.org/intel-sgx/latest/dcap-latest/linux/distro/suse15.4-server/PCKIDRetrievalTool_v1.20.100.2.tar.gz
tar xvzf PCKIDRetrievalTool_v1.20.100.2.tar.gz

  2. On the host OS of platform to register, execute the PCKCIDRT. This step depends on the method used for PCKCIDRT retrieval in step 1:

    1. If retrieved from a package repository:

      cd /opt/intel/sgx-pck-id-retrieval-tool
sudo ./PCKIDRetrievalTool

      cd /opt/intel/sgx-pck-id-retrieval-tool
sudo ./PCKIDRetrievalTool

      cd /opt/intel/sgx-pck-id-retrieval-tool
sudo ./PCKIDRetrievalTool

    2. If retrieved from a standalone package:

      cd PCKIDRetrievalTool_v1.20.100.2
sudo su
LD_LIBRARY_PATH=. ./PCKIDRetrievalTool

      cd PCKIDRetrievalTool_v1.20.100.2
sudo su
LD_LIBRARY_PATH=. ./PCKIDRetrievalTool

      cd PCKIDRetrievalTool_v1.20.100.2
sudo su
LD_LIBRARY_PATH=. ./PCKIDRetrievalTool

    On successful execution of the PCKCIDRT, you'll see output similar to the following:

    Intel(R) Software Guard Extensions PCK Cert ID Retrieval Tool Version 1.20.100.2

Registration status has been set to completed status.
pckid_retrieval.csv has been generated successfully!

    As mentioned in the output, a file called pckid_retrieval.csv is generated. This is a comma-delimited file containing the PM and other platform data. For more about the included data, see our PCKCIDRT README on GitHub.

    Note

    Once the PCKCIDRT successfully retrieved the PM, it (by design) sets a bit in a UEFI variable telling the BIOS to not present the PM on subsequent boots. So, once the .csv file is written, make sure it’s stored/secured. It is not possible to retrieve the same PM again. It is only possible to retrieve a new PM by triggering "SGX Factory Reset" in the BIOS by setting the corresponding BIOS setting to Enabled. As a result, the CPUs will establish a new shared platform key and that a new registration is necessary afterwards.

  3. On the host OS of platform to register, use the following commands to extract the PM from the pckid_retrieval.csv and store the result in the file platformmanifest.bin:

    sudo dnf config-manager --set-enabled crb
sudo dnf install -y ocaml-csv
csvtool col 6 pckid_retrieval.csv | xxd -r -p > platformmanifest.bin

    sudo apt-get install -y csvtool
csvtool col 6 pckid_retrieval.csv | xxd -r -p > platformmanifest.bin

    sudo zypper install -y ocaml-csv
csvtool col 6 pckid_retrieval.csv | xxd -r -p > platformmanifest.bin

  4. Dependent on the used option of this method:

    1. Online option: nothing needs to be done.
    2. Offline option: use any out-of-band mechanism to copy the platformmanifest.bin file from the platform to register to a platform with Internet access.

    Independent of the used option, we call the platform with Internet access Registration Platform in the following, and we assume that the platformmanifest.bin file is stored at the path <pm_path>.

  5. On the Registration Platform, send the PM to the registration REST API endpoint of the IRS. As shown in the linked API documentation, this can be done with a simple curl command (after adjusting the path placeholder):

    curl -i \
--data-binary @<pm_path> \
-X POST "https://api.trustedservices.intel.com/sgx/registration/v1/platform" \
-H "Content-Type: application/octet-stream"

    curl -i \
--data-binary @<pm_path> \
-X POST "https://api.trustedservices.intel.com/sgx/registration/v1/platform" \
-H "Content-Type: application/octet-stream"

    curl -i \
--data-binary @<pm_path> \
-X POST "https://api.trustedservices.intel.com/sgx/registration/v1/platform" \
-H "Content-Type: application/octet-stream"

    If the registration is successful, the IRS will return a "HTTP/1.1 201 Created" reply, with the PPID of the registered platform as content. Sample response:

    HTTP/1.1 201 Created
Content-Length: 32
Content-Type: text/plain
Request-ID: <request id>
Date: <date>

<PPID>

Indirect Registration

With Indirect Registration, the PM is sent to the PCS via the service's REST APIs instead of directly to the IRS. The PCS will forward the PM to the IRS, which is able to recognize a platform containing genuine Intel TDX-enabled CPUs based on the PM. The IRS uses the encrypted, shared platform keys contained in the PM to generate a Provisioning Certification Key Certificate (PCK Certificate) for the platform. In this case, the PM (and the included encrypted, shared platform keys) are not stored by the IRS. As a result, each request later asking for the PCK Certificate for this platform must contain the PM. Requesting a PCK Certificate for this platform with only the PPID is not sufficient.

How can a PCK Certificate generated via Indirect Registration be recognized?

Every PCK Certificate generated via Indirect Registration will contain false in its CachedKeys attribute.

Note that an Indirect Registration forbids later Direct Registration attempts. To switch to Direct Registration, an "SGX Factory Reset" must be triggered in the BIOS by setting the corresponding BIOS setting to Enabled. As a result, the CPUs will establish new shared platform keys, the BIOS will provide a new PM, and a new registration is necessary afterwards.

In the next subsections, we describe the following variants of indirect registration:

  1. Online, manual, single platform, PCCS-based Indirect Registration.
  2. On-/offline, manual, multi platform, PCCS-based Indirect Registration.
  3. On-/offline, manual, multi platform, local cache-based Indirect Registration.
Online, manual, single platform, PCCS-based Indirect Registration

Requirements of this method:

  • Platform to register needs access to a PCCS, which has Internet access.
  • The PCK Cert ID Retrieval Tool (PCKCIDRT) — a tool to support the retrieval of the PM and other platform information.

The basic flow of this registration method:

  1. On the host OS of platform to register or on any platform in your infrastructure, deploy a PCCS. The PCCS must be reachable from the platform to register.
  2. On the host OS of platform to register, deploy the PCKCIDRT.
  3. On the host OS of platform to register, use the PCKCIDRT to gather the PM and other platform information into a single file and to send this data to a PCCS.
    • The PCCS sends the required data to the PCS, which forwards the information to the IRS.
    • The IRS generates a PCK Certificate, and returns it to the PCS.
    • The PCS returns the PCK Certificate to the PCCS.
    • The PCCS caches the PCK Certificate so it is available when a request for it comes in during TD Quote Generation.

Detailed steps to use this registration method:

  1. On the host OS of platform to register or on any platform in your infrastructure, deploy a PCCS following the setup instructions provided in the PCCS section. If the PCCS is not deployed on the platform to register, the environment must be configured to allow access from the platform to register to the PCCS. The PCCS must run in "LAZY" or "REQ" mode.
  2. On the host OS of platform to register, deploy the PCKCIDRT following the PCKCIDRT retrieval instructions provided as step 1 in the On-/offline, manual, single platform Direct Registration.

  3. On the host OS of platform to register, trigger the Indirect Registration with the PCKCIDRT using the following command (after adjusting the command line options to your environment):

    sudo ./PCKIDRetrievalTool \
    -url https://YOUR_PCCS_URL:YOUR_PCCS_PORT \
    -user_token YOUR_USER_TOKEN \
    -proxy_type YOUR_PROXY_TYPE \
    -use_secure_cert true

    sudo ./PCKIDRetrievalTool \
    -url https://YOUR_PCCS_URL:YOUR_PCCS_PORT \
    -user_token YOUR_USER_TOKEN \
    -proxy_type YOUR_PROXY_TYPE \
    -use_secure_cert true

    sudo ./PCKIDRetrievalTool \
    -url https://YOUR_PCCS_URL:YOUR_PCCS_PORT \
    -user_token YOUR_USER_TOKEN \
    -proxy_type YOUR_PROXY_TYPE \
    -use_secure_cert true

    Note

    If you have configured the PCCS to use a self-signed SSL certificate, you have to set the use_secure_cert flag in the presented command to false. As mentioned in the PCCS setup instructions, a self-signed SSL certificate should only be used for testing. In a production environment, a trusted SSL certificate from a known certificate authority should be used.

    For more information on this use and other command line options, see the PCKCIDRT help command (i.e., -h) or the PCKCIDRT's GitHub page.

On-/offline, manual, multi platform, PCCS-based Indirect Registration

Requirements of this method:

  • Dependent on the used option of this method:

    1. Online option: All platforms to register have access to a central PCCS, which has Internet access.
    2. Offline option: All platforms to register have access to a central PCCS, which does not have Internet access. Another platform with Internet access must be available. This option is usable in an air-gapped environment. The platform with Internet access does not need to support Intel TDX.

  • The PCK Cert ID Retrieval Tool (PCKCIDRT) — a tool to support the retrieval of the PM and other platform information.

  • The PCCS Admin Tool — a tool to facilitate Indirect Registration, PCK Certificate retrieval, and verification collateral retrieval especially in multi-platform environments.

The basic flow of this registration method:

  1. On any central platform in your infrastructure, deploy a PCCS. The PCCS must be reachable from all platforms to register.
  2. On the host OS of each platform to register, deploy the PCKCIDRT.
  3. On the host OS of each platform to register, use the PCKCIDRT to gather the PM and other platform information into a single file.

  4. Copy the individual files created in step 3 to a single folder on a platform with Internet access.

    1. Online option: the platform with the PCCS has access to the Internet and can be used to hold all the files created in step 3.
    2. Offline option: a separate platform with Internet access must be used to hold all the files created in step 3.

    Independent of the used option, we call the platform with Internet access Registration Platform in the following.

  5. On the Registration Platform, deploy the PCCS Admin Tool.

  6. On the Registration Platform, use the PCCS Admin Tool to merge the files from the individual platforms into a single file.
  7. On the Registration Platform, use the PCCS Admin Tool to send the collected platform information to the PCS.
    • The PCS forwards the information to the IRS, which generates PCK Certificates, and returns them to the PCS.
    • The PCS returns the PCK Certificates to the PCCS Admin Tool.
    • The PCCS Admin Tool writes all platform PCK Certificates to result file.
    • The PCCS Admin Tool also requests all corresponding verification collateral from PCS and writes this information to the same result file.
  8. Copy the result file to any platform with access to the PCCS — called PCCS Insertion Platform in the following.
  9. On the PCCS Insertion Platform, deploy the PCCS Admin Tool.
  10. On the PCCS Insertion Platform, use the PCCS Admin Tool to insert the data from the result file to the PCCS.

Detailed steps to use this registration method:

  1. On a central platform in your infrastructure, deploy a PCCS following the setup instructions provided in the PCCS section. The environment must be configured to allow access from all platforms to register to the PCCS.

    1. Online option: the PCCS must run in "LAZY" or "REQ" mode.
    2. Offline option: the PCCS must run in "OFFLINE" mode.

  2. On the host OS of each platform to register, deploy the PCKCIDRT following the PCKCIDRT retrieval instructions provided as step 1 in the On-/offline, manual, single platform Direct Registration section.

  3. On the host OS of each platform to register, gather the PM and other platform information into a comma-delimited .csv file following the execution instructions provided as step 2 in the On-/offline, manual, single platform Direct Registration section. This section also provides details about successful execution of the tool and the resulting .csv file.

  4. Use any out-of-band mechanism to copy the .csv files from each platform to register to a single folder on a platform with Internet access.

    1. Online option: the platform with the PCCS has access to the Internet and can be used to hold all csv files.
    2. Offline option: a separate platform with Internet access must be used to hold all csv files.

    Independent of the used option, we call the platform with Internet access Registration Platform in the following. We also assume that all .csv files are stored at the path <platforms_to_register_path> on this platform.

  5. On the Registration Platform, execute the following commands to install prerequisites for the PCCS Admin Tool and download the tool:

    sudo dnf install git python3 python3-pip
git clone https://github.com/intel/SGXDataCenterAttestationPrimitives.git
cd SGXDataCenterAttestationPrimitives/tools/PccsAdminTool
pip3 install -r requirements.txt

    sudo apt install -y python3 python3-pip
git clone https://github.com/intel/SGXDataCenterAttestationPrimitives.git
cd SGXDataCenterAttestationPrimitives/tools/PccsAdminTool
pip3 install -r requirements.txt

  6. On the Registration Platform, execute the following command to trigger the merge of all individual .csv files to a single input JSON file using the PCCS Admin Tool (after adjusting the command line options to your environment). By default, the result file is called platform_list.json.

    python3 ./pccsadmin.py collect -d <platforms_to_register_path>

    python3 ./pccsadmin.py collect -d <platforms_to_register_path>

  7. On the Registration Platform, execute the following command to trigger the transmission of the data contained in the input JSON file to the PCS using the PCCS Admin Tool. All returned PCK Certificates are stored in the file platform_collaterals.json.

    python3 ./pccsadmin.py fetch

    python3 ./pccsadmin.py fetch

    By executing this command, the PCCS Admin Tool will also request the verification collateral for all platforms contained in the input JSON file. The result is also written into the file platform_collaterals.json.

  8. Use any out-of-band mechanism to copy the platform_collaterals.json file to any platform with access to the PCCS — called PCCS Insertion Platform in the following.

  9. If the PCCS Admin Tool is not already installed on the PCCS Insertion Platform, execute the commands described in step 5 to install prerequisites for the PCCS Admin Tool and to download the tool.

  10. On the PCCS Insertion Platform, execute the following command to insert the data from the platform_collaterals.json file into the PCCS (after adjusting the command line options to your environment):

    python3 ./pccsadmin.py put -u https://YOUR_PCCS_URL:YOUR_PCCS_PORT

    python3 ./pccsadmin.py put -u https://YOUR_PCCS_URL:YOUR_PCCS_PORT
On-/offline, manual, multi platform, local cache-based Indirect Registration

Requirements of this method:

  • This registration variant has two options:

    1. Online option: All platforms to register have Internet access.
    2. Offline option: All platforms to register do not have Internet access. Another platform with Internet access must be available. This option is usable in an air-gapped environment. The platform with Internet access does not need to support Intel TDX.

  • The PCK Cert ID Retrieval Tool (PCKCIDRT) — a tool to support the retrieval of the PM and other platform information.

  • The PCCS Admin Tool — a tool to facilitate Indirect Registration, PCK Certificate retrieval, and verification collateral retrieval especially in multi-platform environments.

The basic flow of this registration method:

  1. On the host OS of each platform to register, deploy the PCKCIDRT.
  2. On the host OS of each platform to register, use the PCKCIDRT to gather the PM and other platform information into a single file.

  3. Copy the individual files created in step 2 to a single folder on a platform with Internet access.

    1. Online option: any platform to register has access to the Internet and can be used to hold all the files created in step 2. A separate platform with Internet access can be used.
    2. Offline option: a separate platform with Internet access must be used to hold all the files created in step 2.

    Independent of the used option, we call the platform with Internet access Registration Platform in the following.

  4. On the Registration Platform, deploy the PCCS Admin Tool.

  5. On the Registration Platform, use the PCCS Admin Tool to merge the files from the individual platforms into a single file.
  6. On the Registration Platform, use the PCCS Admin Tool to request PCK Certificates and TCB Infos from the PCS.
  7. Distribute the individual cache files back to the corresponding registered platform.
  8. On each registered platform with a corresponding cache file, the cached data is used automatically during TD Quote Generation.

Detailed steps to use this registration method:

  1. On the host OS of each platform to register, deploy the PCKCIDRT following the PCKCIDRT retrieval instructions provided as step 1 in the On-/offline, manual, single platform Direct Registration section.
  2. On the host OS of each platform to register, gather the PM and other platform information into a comma-delimited .csv file following the execution instructions provided as step 2 in the On-/offline, manual, single platform Direct Registration section. This section also provides details about successful execution of the tool and the resulting .csv file.

  3. Use any out-of-band mechanism to copy the .csv files from all platforms to register to a single folder on a platform with Internet access.

    1. Online option: any platform to register has access to the Internet and can be used to hold all csv files. A separate platform with Internet access can be used.
    2. Offline option: a separate platform with Internet access must be used to hold all csv files.

    Independent of the used option, we call the platform with Internet access Registration Platform in the following. We also assume that all .csv files are stored at the path <platforms_to_register_path> on this platform.

  4. On the Registration Platform, execute the following commands to install prerequisites for the PCCS Admin Tool and download the tool:

    sudo dnf install git python3 python3-pip
git clone https://github.com/intel/SGXDataCenterAttestationPrimitives.git
cd SGXDataCenterAttestationPrimitives/tools/PccsAdminTool
pip3 install -r requirements.txt

    sudo apt install -y python3 python3-pip
git clone https://github.com/intel/SGXDataCenterAttestationPrimitives.git
cd SGXDataCenterAttestationPrimitives/tools/PccsAdminTool
pip3 install -r requirements.txt
    1. On the Registration Platform, execute the following command to trigger the merge of all individual .csv files to a single input JSON file using the PCCS Admin Tool (after adjusting the command line options to your environment). By default, the result file is called platform_list.json.
    python3 ./pccsadmin.py collect -d <platforms_to_register_path>

    python3 ./pccsadmin.py collect -d <platforms_to_register_path>

  5. On the Registration Platform, execute the following command. The PCCS Admin Tool uses the data contained in the input JSON file to retrieve the corresponding PCK Certificates and TCB Infos from the PCS. The tool generates a cache file for each platform contained in the input JSON file. The cache files are written to an output folder, and the default output folder is ./cache/.

    python3 ./pccsadmin.py cache

    python3 ./pccsadmin.py cache

  6. Use any out-of-band mechanism to copy the individual cache file of every registered platform back to the corresponding registered platform.

  7. On each registered platform with a corresponding cache file, the cached data is used automatically during TD Quote Generation. The cache file must pe placed in a folder named .dcap-qcnl. The possible locations for Linux are:

    • $AZDCAP_CACHE
    • $XDG_CACHE_HOME
    • $HOME
    • $TMPDIR
    • /tmp/

    For example, to use the last location in the list, the cache file be present inside: /tmp/.dcap-qcnl. See the sgx_default_qcnl.conf file for more information.

Troubleshooting

There are a number of reasons for failure replies that can occur during platform registration. One of the most common failure return codes from registration is HTTP error status 400 - Bad Request with the error message PackageNotFound. This can be caused by a number of things and the following steps can be used for troubleshooting:

  1. Install the necessary tool on your distribution of choice:

    sudo yum install epel-release
sudo yum install msr-tools

    sudo modprobe msr
sudo apt-get install msr-tools

  2. Read MSR 0xCE bit 27 to check for production or pre-production CPUs:

    sudo rdmsr 0xCE -f 27:27
    • If the result is 0, you have production CPUs. This enables you do to a regular registration and no changes to your setup are necessary.
    • If the result is 1, you have pre-production CPUs. This means you need to point your registration tool/method to our "SBX/Sandbox" environment with the URL https://sbx.api.trustedservices.intel.com instead of our "LIV/live" environment with the URL https://api.trustedservices.intel.com. If you are using the MPA for platform registration, you don't need to change anything, because MPA automatically detects which environment to connect to.

  3. Read MSR 0x503 to check for the "SGX Unlocked for Debug" state:

    sudo rdmsr 0x503
    • If the result is 0, the machine is not in "SGX Unlocked for Debug" mode. This enables you do to a regular registration and no changes to your setup are necessary.
    • If the result is not 0, the machine is in "SGX Unlocked for Debug" mode. There are a few reasons that can cause this:
      • You have a non-production signed microcode in your BIOS - see the troubleshooting step 4.
      • Delayed Authentication Mode (DAM) is enabled. This can be caused by a couple of reasons:
        • There is a BIOS option that has enabled DAM. You need to disable this option.
        • The BIOS image installed in this system has DAM enabled in its Firmware Interface Table (FIT) options. Contact your OEM/ODM or independent BIOS vendor for an updated BIOS with DAM disabled in the FIT.
      • "SGX Debug Mode" is explicitly enabled by a BIOS option setting. You must disable this setting.

  4. Read MSR 0x8b bits 32-63 to check the microcode version loaded on the platform:

    sudo rdmsr 0x8b -0 -f 63:32
    • If the microcode version number's most significant bit is not set (e.g., 0x00000001), you have a production-signed microcode. This enables you do to a regular registration and no changes to your setup are necessary.
    • If the microcode version number's most significant bit is set (e.g., 0x80000001), you don't have a production-signed microcode. Contact you OEM/ODM or independent BIOS vendor for an updated BIOS with a production signed microcode.

    Note

    Usually, the microcode version number can also be found in the platform's BIOS setup.

TD Quote Verification

TD Quote Generation and TD Quote Verification are two completely independent steps. TD Quote Generation is always done by the platform a TD is running on, but TD Quote Verification can be done by any party at an arbitrary location.

For TD Quote Verification, multiple alternatives exist:

  • Intel® Trust Authority is a SaaS offering containing TD Quote Verification capabilities consistent across on-prem, hybrid, multi-cloud, and edge deployments.
  • Some CSPs offer a TD Quote Verification service, e.g., Microsoft Azure Attestation.
  • Intel provides an open-source, Docker-based Quote Verification Service (QVS) with a minimal signing service via GitHub.
  • Intel provides a Quote Verification library via GitHub along with documentation that can be used as a foundation to build your own TD Quote Verification service.

TCB-Recovery (TCB-R)

The Trusted Computing Base (TCB) of Intel TDX encompasses all components in the platform that are required to implement the Intel TDX security objectives. The TCB level is defined as the combination of all patch versions of all the components that are part of the TCB. Examples of some of these components include the microcode, certain Intel-owned ACMs (e.g., SEAM Loader, TXT, Bios Guard, Boot Guard), as well as the Intel TDX Module.

When Intel becomes aware of a security problem with any component within the TCB, Intel will publish mitigation(s) for this problem and (in most cases) update the enforced TCB level. If any security mitigation is done via a BIOS update and/or loaded by the BIOS as (early load) microcode, the platform owner will need to upgrade all relevant software pieces of the affected platform and reboot these platforms. Applying all necessary mitigations is called TCB-Recovery (TCB-R).

Intel strives to perform TCB-Rs twice a year as part of our Intel Platform Update (IPU) process. For more details, Intel provides TCB-R Guidance Documentation to help with the process.

If the application of a security mitigation affected a BIOS contained component, the platform will need to be re-registered with IRS after the reboot. To be able to create quotes according to the new TCB level, new PCK Certificates have to be retrieved from the PCS and inserted into the local collateral cache, e.g., PCCS. To be able to verify quotes according to the new TCB level, new Quote Verification Collateral has to be retrieved from the PCS and inserted into the local collateral cache, e.g., PCCS.

Hardware Selection

On this page, we will explain what hardware is needed to enable Intel TDX. This encompasses CPU requirements and DIMM requirements. In most cases, the infrastructure provider is responsible for selecting the appropriate platform hardware. Please talk to your OEM/ODM provider to receive a platform fulfilling the listed requirements.

CPU Requirements

To enable Intel TDX, a 5th Gen Intel® Xeon® Scalable Processor is required.

DIMM (i.e., main memory) Requirements

At minimum, all slot 0's of all Integrated Memory Controller (IMC) channels for all installed CPUs must be populated (i.e., 8 DIMMs per populated CPU socket, at least). DIMM population must be symmetric across IMCs.

The following figure shows possible populations per populated CPU with 8 or 16 DIMMs:

Possible memory configuration per populated CPU with 8 or 16 DIMMs

Possible memory configuration per populated CPU with 8 or 16 DIMMs

Hardware Setup

On this page, we will present the settings that are necessary to setup the hardware for Intel TDX. We assume that the proper hardware is present. At the moment, it is only necessary to install an Intel TDX-enabled BIOS, enable Intel TDX in the BIOS, and optionally deploy a specific Intel TDX Module version.

Install Intel TDX-enabled BIOS

To use Intel TDX, a BIOS supporting the functionality is needed. Please reach out to your OEM/ODM or independent BIOS vendor to learn if such a BIOS is available and follow the corresponding installation instructions.

Enable Intel TDX in BIOS

Specific BIOS settings are needed to support Intel TDX. In the following, we present BIOS settings for specific machines and processor generations. Afterwards, we briefly describe these BIOS settings.

Note

The necessary BIOS settings or the menus might differ based on the platform that is used. Please reach out to your OEM/ODM or independent BIOS vendor for instructions dedicated for your BIOS.

Warning

It might be necessary to enable Intel TDX on the host OS, before Intel TDX is enabled in the BIOS.

BIOS settings for a Quanta S6Q system with 5th Gen Intel® Xeon® Scalable processors 
graph LR
SC[Socket<br />Configuration];
SC --> MC[Memory<br />Configuration];
MC --> A1[Memory Map] --> A2[Volatile Memory Mode] --> A3[1LM];
SC --> PC[Processor<br />Configuration];
PC --> B1["Memory Encryption (TME)"] --> B2[Enabled];
PC --> C1["Total Memory Encryption (TME) Bypass"] --> C2[Disabled];
PC --> D1["Total Memory Encryption Multi-Tenant (TME-MT)"] --> D2[Enabled];
PC --> E1["Memory integrity"] --> E2[Enabled or Disabled];
PC --> F1["Trust Domain Extension (TDX)"] --> F2[Enabled];
PC --> G1["TDX Secure Arbitration Mode Loader (SEAM Loader)"] --> G2[Enabled];
PC --> H1[TME-MT/TDX key split] --> H2[Non-zero value]
PC --> I1["SW Guard Extensions (SGX)"] --> I2[Enabled];
PC --> J1[SGX PRM Size] --> J2[Whatever size<br />needed];

Explanation of BIOS settings:

BIOS setting Notes
Volatile Memory Mode Defines how memory is connected to the system.
Memory Encryption (TME) Activates/deactivates Intel® Total Memory Encryption, which is a prerequisite for Intel® Total Memory Encryption–Multi-Key (Intel TME-MK).
Total Memory Encryption (TME) Bypass Activates/deactivates the Intel TME bypass mode. This mode allows memory outside of Intel TME-MK VMs, Intel SGX enclaves, and Intel TDX Trust Domains to be unencrypted to improve the performance of non-confidential software.
Total Memory Encryption Multi-Tenant (TME-MT) Activates/deactivates Intel® Total Memory Encryption–Multi-Key (Intel TME-MK), which is used by Intel TDX for the main memory encryption.
Memory integrity If disabled, only Logical Integrity (SW integrity) is used for main memory protection. If enabled, Cryptographic Integrity (HW integrity) is also used for main memory protection. NOTE: Enabling Cryptographic Integrity requires DIMMs with specific specs to be installed.
Trust Domain Extension (TDX) Activates/deactivates Intel TDX.
TDX Secure Arbitration Mode Loader (SEAM Loader) Defines from where the Intel TDX Module is loaded.
TME-MT/TDX key split Defines how many keys are used for Intel TME-MK and how many for Intel TDX.
SW Guard Extensions (SGX) Activates/deactivates Intel SGX, which is used by Intel TDX for remote attestation.
SGX PRM Size Defines the size of the Processor Reserved Memory (PRM), which is used by Intel SGX to hold enclaves and related protected data structures. A minimum SGX PRM is required to run the Quote Generation Service (QGS) on the host OS (or inside a dedicated VM).

Deploy Specific Intel TDX Module Version

Once you install a BIOS with Intel TDX support, it will include an Intel TDX Module and a corresponding Intel TDX Loader. To get other versions of the Intel TDX Module, you have two options:

  1. Update Intel TDX Module via BIOS update.
  2. Update Intel TDX Module via binary deployment.

In the following subsections, we provide more details on these two update variants. Independent of the used variant, please consider the following details:

  • Different platforms might require different Intel TDX Module binaries.
  • With the both of these Intel TDX Module update variants, a system reboot is required. Accordingly, all running VMs or TDs have to be stopped before updating.
  • Installing a specific Intel TDX Module version will make use of the Intel TDX Loader already present in the system BIOS even if updating via binary deployment.

Update Intel TDX Module via BIOS update

Steps:

  • Reach out to your OEM/ODM or Independent BIOS Vendor (IBV) to ask for a BIOS containing another version of the Intel TDX Module.
  • Once available, retrieve the BIOS update.
  • Flash BIOS update according the instructions of the BIOS provider.

Update Intel TDX Module via Binary Deployment

Steps:

  1. Download the Intel TDX Module binary:

    Download an archive containing the binary of the latest Intel TDX Module version and a corresponding signature structure. 

    wget -O intel_tdx_module.tar.gz \
    https://github.com/intel/tdx-module/releases/latest/download/intel_tdx_module.tar.gz

    To download a specific version of an Intel TDX Module and a corresponding signature structure, navigate to the releases page of the Intel TDX Module. Download the archive intel_tdx_module.tar.gz from the release you want to use.

  2. Unpack the downloaded archive:

    tar -xvzf intel_tdx_module.tar.gz

  3. If not done before, create an EFI directory:

    sudo mkdir -p /boot/efi/EFI/TDX/

  4. Copy the Intel TDX Module binary and the corresponding signature structure to the EFI directly created in step 3.

    sudo cp TDX-Module/intel_tdx_module.so \
    /boot/efi/EFI/TDX/TDX-SEAM.so
sudo cp TDX-Module/intel_tdx_module.so.sigstruct \
    /boot/efi/EFI/TDX/TDX-SEAM.so.sigstruct

  5. Check that the copied files are present in /boot/efi/EFI/TDX/ with a current date:

    sudo ls -ls /boot/efi/EFI/TDX/

  6. Reboot your machine.

How to reproduce an Intel TDX Module binary?

Every Intel TDX Module release comes with corresponding build instructions. Please follow these build instructions.

How to run an Intel TDX Module build from source?

You cannot run an Intel TDX Module build from source, because only binaries officially released and signed by Intel are allowed to run. Intel does not provide an environment to use Intel TDX with non-signed binaries.

Host OS Setup

On this page, we will introduce how an Intel TDX-enabled host OS can be configured. We assume that proper hardware was selected and the hardware setup was done.

Enable Intel TDX in the Host OS

The preferred way to enable Intel TDX in the host OS is to use the TDX Early Preview distributions. These distributions are provided by partners for a convenient Intel TDX enablement experience. Currently, the following Intel TDX-enabled host OSes are supported by TDX Early Preview distributions:

To install the Intel TDX host OS kernel with KVM support, as well as the QEMU and libvirt packages required to create and manage the launch of TDs, follow the instructions provided by the individual TDX Early Preview distributions:

After successful installation of these software components, reboot the system into the BIOS setup menu and perform the necessary Intel TDX enablement steps.

Check Intel TDX enablement

To check the status of your Intel TDX configuration, you can manually execute the following commands:

  • Check whether Intel TDX Module is initialized. The expected output contains tdx: TDX module initialized.

    sudo dmesg | grep -i tdx

  • As a prerequisite for the following commands, install the MSR Tools package and load the MSR module.

    sudo dnf config-manager --set-enabled crb
sudo dnf install epel-release epel-next-release
sudo dnf install msr-tools
sudo modprobe msr

    sudo apt install msr-tools
sudo modprobe msr

    sudo zypper addrepo https://download.opensuse.org/repositories/openSUSE:Backports:SLE-15-SP5/standard/openSUSE:Backports:SLE-15-SP5.repo
sudo zypper refresh
sudo zypper install msr-tools
sudo modprobe msr

  • Check whether Intel TME is enabled. The expected output is 1.

    sudo rdmsr -f 1:1 0x982

  • Check the maximum number of Intel TME keys. The expected output depends on what is configured in the BIOS.

    sudo rdmsr -f 50:36 0x981

  • Check the Intel SGX and MCHECK status. The expected output is 0.

    sudo rdmsr 0xa0

  • Check the Intel TDX status. The expected output is 1.

    sudo rdmsr -f 11:11 0x1401

  • Check the maximum number of Intel TDX keys. The expected output depends on what is configured in the BIOS.

    sudo rdmsr -f 63:32 0x87

Setup Quote Generation Service (QGS)

The main artifact used in a remote attestation flow is the TD Quote, which is generated on the Intel TDX hardware and then transferred to any other party/machine for verification. To generate a TD Quote, a TD first uses the hardware to generate a TD Report. This TD Report is then forwarded to an Intel SGX Architectural Enclave, called the TD Quoting Enclave. This enclave takes the incoming TD Report, verifies that the TD Report was generated by a TD on the same platform, and then signs the TD Report with a signature key for which the trust is rooted in an Intel CA. More details can be found in the Intel® Trust Domain Extensions Data Center Attestation Primitives (Intel® TDX DCAP): Quote Generation Library and Quote Verification Library documentation.

The Quote Generation Service (QGS) is a service that runs in the host OS (or inside a dedicated VM) to host the TD Quoting Enclave. Note that the QGS cannot run on another machine, because the verification of the TD Report requires that the corresponding TD and the TD Quoting Enclave run on the same machine.

Install QGS

  1. If not done during another component installation, set up the appropriate Intel SGX package repository for your distribution of choice:

    sudo dnf install -y wget yum-utils
sudo mkdir /opt/intel
cd /opt/intel
sudo wget https://download.01.org/intel-sgx/latest/dcap-latest/linux/distro/centos-stream9/sgx_rpm_local_repo.tgz
sudo tar xvf sgx_rpm_local_repo.tgz
sudo yum-config-manager --add-repo file:///opt/intel/sgx_rpm_local_repo

    echo 'deb [signed-by=/etc/apt/keyrings/intel-sgx-keyring.asc arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu mantic main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list
wget https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key
sudo mkdir -p /etc/apt/keyrings
cat intel-sgx-deb.key | sudo tee /etc/apt/keyrings/intel-sgx-keyring.asc > /dev/null
sudo apt-get update

    sudo mkdir /opt/intel
cd /opt/intel
sudo wget https://download.01.org/intel-sgx/latest/dcap-latest/linux/distro/suse15.4-server/sgx_rpm_local_repo.tgz
sudo tar xvf sgx_rpm_local_repo.tgz
sudo zypper addrepo /opt/intel/sgx_rpm_local_repo sgx_rpm_local_repo

  2. Install the QGS with the following command, which will also install the necessary prerequisites (the Quote Provider Library (QPL) and the Quoting Library (QL)).

    sudo dnf --nogpgcheck install -y \
    tdx-qgs \
    libsgx-dcap-default-qpl \
    libsgx-dcap-ql

    sudo apt install -y \
    tdx-qgs \
    libsgx-dcap-default-qpl \
    libsgx-dcap-ql

    sudo zypper --no-gpg-checks install -y \
    tdx-qgs \
    libsgx-dcap-default-qpl \
    libsgx-dcap-ql

    More detailed information about these instructions can be found in our Intel® SGX Software Installation Guide For Linux* OS.

How to check service log of the QGS?

You can check the service log of the QGS with the following command:

sudo journalctl -u qgsd -f

sudo journalctl -u qgsd -f

sudo journalctl -u qgsd -f

Configure QCNL

On start, the QGS reads the configuration file /etc/sgx_default_qcnl.conf, and uses the contained settings for TD Quote Generation. This file contains various settings that might be important in your environment.

Selected highlights regarding this configuration file:

  • If the QGS should use a PCCS in your infrastructure as a collateral caching service, you have to adjust the JSON-key pccs_url in the configuration file accordingly.

  • If the QGS should accept insecure HTTPS certificates from the PCCS, set the JSON-key use_secure_cert in the configuration file to false.

    Warning

    You must not use insecure HTTPS certificates in a production environment.

  • See the comments of the configuration file /etc/sgx_default_qcnl.conf for more information on other settings.

After changing settings in the file /etc/sgx_default_qcnl.conf, you have to restart the QGS:

sudo systemctl restart qgsd.service

sudo systemctl restart qgsd.service

sudo systemctl restart qgsd.service

Setup Communication Path between QGS and TD

The current TDX Early Preview distributions use vsock as the communication path from the TD to the QGS running in the host. A TD can be launched using QEMU or libvirt (see Launch a Trust Domain section). In both cases, special options are necessary to enable the vsock interface.

Add the following to the QEMU launch command: 

-device vhost-vsock-pci,guest-cid=3

Add a vsock entry inside the devices element of the libvirt XML config file of the TD:

...
<devices>
    ...
    <vsock model='virtio'>
        <cid auto='yes' address='3'/>
        <address type='pci' domain='0x0000' bus='0x05' slot='0x00' function='0x0'/>
    </vsock>
    ...
</devices>
...

Guest OS Setup

On this page, we will introduce how an Intel TDX-enabled guest image can be generated and how a TD using this image can be started. We assume that the host OS setup was done before.

Prepare an Intel TDX-enabled Guest Image

To start an Intel TDX protected VM (i.e., a TD), it is necessary to prepare an Intel TDX-enabled guest image. The TDX Early Preview distributions are the preferred way to prepare such an image. The TDX Early Preview distributions are special distributions provided by partners for a convenient Intel TDX enablement experience. Currently, the following Intel TDX-enabled guest OSes are supported by TDX Early Preview distributions:

To prepare a guest image for these OSes, follow the instructions provided by the individual TDX Early Preview distributions:

Launch a Trust Domain

To launch a TD, follow the instructions provided by the individual TDX Early Preview distributions:

Trust Domain at Runtime

On this page, we provide instructions on topics concerning a Trust Domain (TD) at runtime.

Perform Remote Attestation

As explained in the TDX remote attestation section of the Infrastructure Setup page, remote attestation is one of the main features of Intel TDX.

In this section, we assume that your infrastructure provider has done the necessary setup steps. This includes the setup of a collateral caching service in the infrastructure; a Quote Generation Service (QGS) is running on the same host as the TD; and a communication channel between the QGS and the TD was configured on TD start.

Based on this assumption, we explain how to configure the communication channel between the TD and the QGS from inside the TD. Then, we show how TD Quotes can be generated, which always has to happen inside a TD.

We also describe how generated TD Quotes can be verified to close the loop. TD Quote Verification can be done by any party at any place. Examples:

  • Inside the TD by the TD owner.
  • In the host OS by the host OS owner.
  • On any remote platform by the owner of the remote platform.

Note that there are multiple TD Quote Verification alternatives.

Configure TD to QGS Communication Channel

Inside the TD, create the file /etc/tdx-attest.conf file as root defining the vsock port that is for the communication between TD and QGS. The following command can be used to create and fill the file:

sudo tee -a /etc/tdx-attest.conf > /dev/null <<EOT
port=4050
EOT

TD Quote Generation

TD Quote Generation must always happen inside the TD. There are multiple ways to generate a TD Quote. In the following, we explore how TD Quote Generation can be tested using the TDX Quote Generation Sample.

Steps:

  1. Setup the appropriate Intel SGX package repository for your distribution of choice (if not done during another component installation):

    sudo dnf install -y yum-utils wget
sudo mkdir /opt/intel
cd /opt/intel
sudo wget https://download.01.org/intel-sgx/latest/dcap-latest/linux/distro/rhel9.2-server/sgx_rpm_local_repo.tgz
sudo tar xvf sgx_rpm_local_repo.tgz
sudo yum-config-manager --add-repo file:///opt/intel/sgx_rpm_local_repo

    echo 'deb [signed-by=/etc/apt/keyrings/intel-sgx-keyring.asc arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu mantic main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list
wget https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key
sudo mkdir -p /etc/apt/keyrings
cat intel-sgx-deb.key | sudo tee /etc/apt/keyrings/intel-sgx-keyring.asc > /dev/null
sudo apt-get update

    sudo mkdir /opt/intel
cd /opt/intel
sudo wget https://download.01.org/intel-sgx/latest/dcap-latest/linux/distro/suse15.4-server/sgx_rpm_local_repo.tgz
sudo tar xvf sgx_rpm_local_repo.tgz
sudo zypper addrepo /opt/intel/sgx_rpm_local_repo sgx_rpm_local_repo

  2. Execute the following commands to install and run the sample application generating a TD Quote:

    sudo dnf install -y gcc make
sudo dnf --nogpgcheck install -y libtdx-attest libtdx-attest-devel
cd /opt/intel/tdx-quote-generation-sample/
make
./test_tdx_attest

    sudo apt install -y libtdx-attest libtdx-attest-dev
cd /opt/intel/tdx-quote-generation-sample/
make
./test_tdx_attest

    sudo zypper --no-gpg-checks install -y libtdx-attest libtdx-attest-devel
cd /opt/intel/tdx-quote-generation-sample/
make
./test_tdx_attest

    If successful, a TD Quote will be written to disk in a quote.dat file. This quote.dat file can now be verified as described in the next section.

TD Quote Verification

TD Quote Verification can be done by any party at an arbitrary place. There are multiple TD Quote Verification alternatives. In the following, we explore how TD Quote Verification can be tested using the Quote Verification Sample application deployed in the host OS.

Steps:

  1. Copy the TD Quote file (e.g., quote.dat) to the host OS. Use a tool of your choice for this operation. Possible commands using scp or virt-copy-out:

    Note

    SSH access to your TD is necessary for this approach.

    Adjust the following command to your environment and use it to copy the file: 

    scp -p <TD SSH port> <TD user>@<TD IP>:<guest-path-to>/quote.dat <host_directory>/.

    Example command: 

    scp -P 10022 root@localhost:/opt/intel/tdx-quote-generation-sample/quote.dat ~/quote.dat

    Note

    Host OS access is necessary for this approach.

    Terminate TD. Then, adjust the following command to your environment and use it to copy the file: 

    virt-copy-out -a <image_path> <guest-path-to>/quote.dat <host_directory>

    Example command: 

    virt-copy-out -a ~/tdx/guest-tools/image/tdx-guest-ubuntu-23.10.qcow2 /opt/intel/tdx-quote-generation-sample/quote.dat ~

  2. Setup the appropriate Intel SGX package repository for your distribution of choice (if not done during another component installation):

    sudo dnf install -y wget yum-utils
sudo mkdir /opt/intel
cd /opt/intel
sudo wget https://download.01.org/intel-sgx/latest/dcap-latest/linux/distro/centos-stream9/sgx_rpm_local_repo.tgz
sudo tar xvf sgx_rpm_local_repo.tgz
sudo yum-config-manager --add-repo file:///opt/intel/sgx_rpm_local_repo

    echo 'deb [signed-by=/etc/apt/keyrings/intel-sgx-keyring.asc arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu mantic main' | sudo tee /etc/apt/sources.list.d/intel-sgx.list
wget https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key
sudo mkdir -p /etc/apt/keyrings
cat intel-sgx-deb.key | sudo tee /etc/apt/keyrings/intel-sgx-keyring.asc > /dev/null
sudo apt-get update

    sudo mkdir /opt/intel
cd /opt/intel
sudo wget https://download.01.org/intel-sgx/latest/dcap-latest/linux/distro/suse15.4-server/sgx_rpm_local_repo.tgz
sudo tar xvf sgx_rpm_local_repo.tgz
sudo zypper addrepo /opt/intel/sgx_rpm_local_repo sgx_rpm_local_repo

  3. Execute the following command to install the dependencies for the Quote Verification Sample application, retrieve the application, build the application, and use the application to verify the TD Quote (i.e., quote.dat):

    sudo dnf install -y gcc make
sudo dnf --nogpgcheck install -y libsgx-enclave-common-devel libsgx-dcap-quote-verify-devel libsgx-dcap-default-qpl-devel
cd ~
git clone https://github.com/intel/SGXDataCenterAttestationPrimitives.git
cd SGXDataCenterAttestationPrimitives/SampleCode/QuoteVerificationSample
make QVL_ONLY=1
./app -quote ~/quote.dat

    sudo apt install -y libsgx-enclave-common-dev libsgx-dcap-quote-verify-dev libsgx-dcap-default-qpl-dev
git clone https://github.com/intel/SGXDataCenterAttestationPrimitives.git
cd SGXDataCenterAttestationPrimitives/SampleCode/QuoteVerificationSample
make QVL_ONLY=1
./app -quote ~/quote.dat

    sudo zypper --no-gpg-checks install -y libsgx-enclave-common-devel libsgx-dcap-quote-verify-devel libsgx-dcap-default-qpl-devel
cd ~
git clone https://github.com/intel/SGXDataCenterAttestationPrimitives.git
cd SGXDataCenterAttestationPrimitives/SampleCode/QuoteVerificationSample
make QVL_ONLY=1
./app -quote ~/quote.dat

    If TD Quote Verification is successful, the output contains Verification completed successfully.