Skip to content

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.