Skip to content

Installing the Trust Agent for Linux

Installing the Trust Agent for Linux

Required For

The Trust Agent for Linux is REQUIRED for all use cases.

  • Platform Integrity with Data Sovereignty and Signed Flavors

  • Application Integrity

  • Workload Confidentiality (both VMs and Containers)

Package Dependencies

The Trust Agent requires the following packages and their dependencies:

  • Tboot (Optional, for TXT-based deployments without UEFI SecureBoot only)

  • openssl

  • tar

  • redhat-lsb

If they are not already installed, the Trust Agent installer attempts to install these automatically using the package manager. Automatic installation requires access to package repositories (the RHEL subscription repositories, the EPEL repository, or a suitable mirror), which may require an Internet connection. If the packages are to be installed from the package repository, be sure to update the repository package lists before installation.

Tboot will not be installed automatically. Instructions for installing and configuring tboot are documented later in this section.

Supported Operating Systems

The Intel® Security Libraries Trust Agent for Linux supports:

  • Red Hat Enterprise Linux 8.4

  • Ubuntu 20.04

Prerequisites

The following must be completed before installing the Trust Agent:

  • Supported server hardware including an Intel® Xeon® processor with Intel Trusted Execution Technology activated in the system BIOS.

  • Trusted Platform Module (version 2.0) installed and activated in the system BIOS, with cleared ownership status OR a known TPM ownership secret.

Note

Starting in Intel SecL-DV 4.0, the Trust Agent will now default to using a null TPM owner secret, and does not require ownership permissions except during the provisioning step. If ownership has already been taken when the Trust Agent will be provisioned, it will be necessary to either provide the ownership secret or clear the TPM ownership before provisioning.

  • System must be booted to a tboot boot option OR use UEFI SecureBoot.

  • (Provisioning step only) Intel® SecL Verification Service server installed and active.

  • (Required for NATS mode only) A NATS server must be configured and available
  • (REQUIRED for servers configured with TXT and tboot only) If the server is installed using an LVM, the LVM name must be identical for all Trust Agent systems. The Grub bootloader line that calls the Linux kernel will contain the LVM name of the root volume, and this line with all arguments is part of what is measured in the TXT/Tboot boot process. This will cause the OS Flavor measurements to differ between two otherwise identical hosts if their LVM names are different. Simply using a uniform name for the LVM during OS installation will resolve this possible discrepancy.
  • (Optional, REQUIRED for Virtual Machine Confidentiality only):
  • QEMU/KVM must be installed
  • Libvirt must be installed

Tboot Installation

Tboot is required to build a complete Chain of Trust for Intel® TXT systems that are not using UEFI Secure Boot. Tboot acts to initiate the Intel® TXT SINIT ACM (Authenticated Code Module), which populates several TPM measurements including measurement of the kernel, grub command line, and initrd. Without either tboot or UEFI Secure Boot, the Chain of Trust will be broken because the OS-related components will be neither measured nor signature-verified prior to execution. Because tboot acts to initiate the Intel® TXT SINIT ACM, tboot is only required for platforms using Intel® TXT, and is not required for platforms using another hardware Root of Trust technology like Intel® Boot Guard.

Important Note: SGX Attestation fails when SGX is enabled on a host booted using tboot

Root Cause: tboot requires the "noefi" kernel parameter to be passed during boot, in order to not use unmeasured EFI runtime services. As a result, the kernel does not expose EFI variables to user-space. SGX Attestation requires these EFI variables to fetch Platform Manifest data.

Workaround:

The EFI variables required by SGX are only needed during the SGX provisioning/registration phase. Once this step is completed successfully, access to the EFI variables is no longer required. This means this issue can be worked around by installing the SGX agent without booting to tboot, then rebooting the system to tboot. SGX attestation will then work as expected while booted to tboot.

  1. Enable SGX and TXT in the platform BIOS

  2. Perform SGX Factory Reset and boot into the “plain” distribution kernel (without tboot or TCB)

  3. Install tboot and ISecL components (SGX Agent, Trust Agent and Workload Agent)

  4. The SGX Agent installation fetches the SGX Platform Manifest data and caches it

  5. Reboot the system into the tboot kernel mode.

  6. Verify that TXT measured launch was successful:

​ txt-stat |grep "TXT measured launch"

  1. The SGX and Platform Integrity Attestation use cases should now work as normal.

Intel® SecL-DC requires tboot 1.10.1 or greater. This may be a later version of tboot than is available on public software repositories.

The most current version of tboot can be found here:

https://sourceforge.net/projects/tboot/files/tboot/

Tboot requires configuration of the grub boot loader after installation. To install and configure tboot:

  • Install tboot
yum install tboot

If the package manager does not support a late enough version of tboot, it will need to be compiled from source and installed manually. Instructions can be found here:

https://sourceforge.net/p/tboot/wiki/Home/

Note that the step "copy platform SINIT to /boot" should not be required, as datacenter platforms include the SINIT in the system BIOS package.

  • Ensure that multiboot2.mod and relocator.mod are available for grub2

This step may not be necessary for all OS versions, for instance, this step is NA in case of Tboot installation on Ubuntu 18.04. In order to utilize tboot, grub2 requires these two modules from the grub2-efi-x64-modules package to be located in the correct directory (if they're absent, the host will throw a grub error when it tries to boot using tboot).

These files must be present in this directory:

/boot/efi/EFI/redhat/x86_64-efi/multiboot2.mod
/boot/efi/EFI/redhat/x86_64-efi/relocator.mod

If the files are not present in this directory, they can be moved from their installation location:

cp /usr/lib/grub/x86_64-efi/multiboot2.mod /boot/efi/EFI/redhat/x86_64-efi/
cp /usr/lib/grub/x86_64-efi/relocator.mod /boot/efi/EFI/redhat/x86_64-efi/

Make a backup of your current grub.cfg file

The below examples assume a RedHat OS that has been installed on a platform using UEFI boot mode. The grub path will be slightly different for platforms using a non-RedHat OS.

cp /boot/efi/EFI/redhat/grub.cfg /boot/efi/EFI/redhat/grub.cfg.bak

  • Generate a new grub.cfg with the tboot boot option

    # For RHEL
grub2-mkconfig -o /boot/efi/EFI/redhat/grub.cfg

# For Ubuntu
grub-mkconfig -o /boot/grub/grub.cfg

  • Update the default boot option

Ensure that the GRUB_DEFAULT value is set to the tboot option.

a. Update /etc/default/grub and set the GRUB_DEFAULT value to 'tboot-1.10.1'

GRUB_DEFAULT='tboot-1.10.1'

c. Regenerate grub.cfg:

# For RHEL
grub2-mkconfig -o /boot/efi/EFI/redhat/grub.cfg

# For Ubuntu
grub-mkconfig -o /boot/grub/grub.cfg
  • Reboot the system

Because measurement happens at system boot, a reboot is needed to boot to the tboot boot option and populate measurements in the TPM.

  • Verify a successful trusted boot with tboot

Tboot provides the txt-stat command to show the tboot log. The first part of the output of this command can be used to verify a successful trusted launch. In the output below, note the “TXT measured launch” and “secrets flag set” at the bottom. Both of these should show "TRUE" if the tboot measured launch was successful. If either of these show "FALSE" the measured launch has failed. This usually simply indicates that the tboot boot option was not selected during boot.

If the measured launch was successful, proceed to install the Trust Agent.

Intel(r) TXT Configuration Registers:
        STS: 0x0001c091
            senter_done: TRUE
            sexit_done: FALSE
            mem_config_lock: FALSE
            private_open: TRUE
            locality_1_open: TRUE
            locality_2_open: TRUE
        ESTS: 0x00
            txt_reset: FALSE
        E2STS: 0x0000000000000006
            secrets: TRUE
        ERRORCODE: 0x00000000
        DIDVID: 0x00000001b0078086
            vendor_id: 0x8086
            device_id: 0xb007
            revision_id: 0x1
        FSBIF: 0xffffffffffffffff
        QPIIF: 0x000000009d003000
        SINIT.BASE: 0x6fec0000
        SINIT.SIZE: 262144B (0x40000)
        HEAP.BASE: 0x6ff00000
        HEAP.SIZE: 1048576B (0x100000)
        DPR: 0x0000000070000051
            lock: TRUE
            top: 0x70000000
            size: 5MB (5242880B)
        PUBLIC.KEY:
            9c 78 f0 d8 53 de 85 4a 2f 47 76 1c 72 b8 6a 11
            16 4a 66 a9 84 c1 aa d7 92 e3 14 4f b7 1c 2d 11

***********************************************************
         TXT measured launch: TRUE
         secrets flag set: TRUE
***********************************************************

NATS Mode vs HTTP Mode

The Trust Agent can operate in either HTTP mode (default) or NATS mode. This distinction controls how the Agent communicates with the HVS. In HTTP mode, the TAgent presents a set of API endpoints for the HVS to access via individual TLS requests. In NATS mode, the Agent and HVS are connected via a persistent session maintained via a NATS server; in this mode, the Trust Agent will not listen on any HTTP ports.

Installation

Installation of the Trust Agent is split into two major steps: Installation, which covers the creation of system files and folders, and Provisioning, which involves the creation of keys and secrets and links the Trust Agent to a specific Verification Service. Both operations can be performed at the same time using an installation answer file. Without the answer file, the Trust Agent can be installed and left in an un-provisioned state regardless of whether a Verification Service is up and running, until such time as the datacenter administrator is ready to run the provisioning step and link the Trust Agent to a Verification Service.

To install the Trust Agent for Linux:

  • Copy the Trust Agent installation binary to the /root/ directory.

  • (Optional; required to perform Provisioning and Installation at the same time.) Create thetrustagent.env answer file in the /root directory (for full configuration options, see section 9.2). The minimum configuration options for installation are provided below.

For Platform Attestation only, provide the following in trustagent.env

shell HVS_URL=https://<Verification Service IP or Hostname>:8443/hvs/v2 PROVISION_ATTESTATION=y GRUB_FILE=<path to grub.cfg> CURRENT_IP=<Trust Agent IP address> CMS_TLS_CERT_SHA384=<CMS TLS digest> BEARER_TOKEN=<Installation token from populate-users script> AAS_API_URL=https://<AAS IP or Hostname>:8444/aas/v1 CMS_BASE_URL=https://<CMS IP or Hostname>:8445/cms/v1 SAN_LIST=<Comma-separated list of IP addresses and hostnames for the TAgent matching the SAN list specified in the populate-users script; may include wildcards>

For Workload Confidentiality with VM Encryption, add the following (in addition to the basic Platform Attestation sample):

shell WLA_SERVICE_USERNAME=<Username for the WLA service user> WLA_SERVICE_PASSWORD=<Username for the WLA service user> WLS_API_URL=https://<WLS IP address or hostname>:5000/wls/

For Workload Confidentiality with Container Encryption, add the following (in addition to the basic Platform Attestation sample):

shell WLA_SERVICE_USERNAME=<Username for the WLA service user> WLA_SERVICE_PASSWORD=<Username for the WLA service user> WLS_API_URL=https://<WLS IP address or hostname>:5000/wls/ REGISTRY_SCHEME_TYPE=https ##For the CRI-O container runtime: WA_WITH_CONTAINER_SECURITY_CRIO=yes

For NATS mode, add the following (in addition to the basic Platform Attestation sample and any other optional features):

TA_SERVICE_MODE=outbound
NATS_SERVERS=<nats-server-ip>:4222
TA_HOST_ID=<Any unique identifier for the host; this could be the server FQDN, a UUID, or any other unique identifier>

Note that the TA_HOST_ID unique identifier will also be the ID used as part of the connection string to reach this Trust Agent host in NATS mode.

  • Execute the Trust Agent installer and wait for the installation to complete.
./trustagent-v4.1.bin

If the trustagent.env answer file was provided with the minimum required options, the Trust Agent will be installed and also Provisioned to the Verification Service specified in the answer file.

If no answer file was provided, the Trust Agent will be installed, but will not be Provisioned. TPM-related functionality will not be available from the Trust Agent until the Provisioning step is completed.

The Trust Agent will add a new grub menu entry for application measurement. This new entry will include tboot if the existing grub contains tboot as the default boot option.

Note

If the Linux Trust Agent is installed without being Provisioned, the Trust Agent process will not actually run until the Provisioning step has been completed.

  • Legacy BIOS systems using tboot ONLY) Update the grub boot loader:
grub2-mkconfig -o /boot/grub2/grub.cfg
  • After Provisioning is completed, the Linux Trust Agent must be rebooted so that the default SOFTWARE Flavor manifest can be measured and extended to the TPM. If the Workload Agent will also be installed on the system (see the next section), wait to reboot the server until after the Workload Agent has been installed, as this modifies the default SOFTWARE Flavor manifest.
Back to top