Attention

You are viewing an older version of the documentation. The latest version is v3.3.

Intel® Trusted Edge Platform

Important

Intel® Trusted Edge Platform must be enabled in the legacy-poky-acrn image before it can be used. Creating a legacy-poky-acrn image that contains the Trusted Edge Platform feature can be accomplished by selecting the Trusted VM feature option during image setup. See the section legacy-poky-acrn for more information.

Intel® Trusted Edge Platform (TEP) provides a Trusted VM, which is specifically for use in conjunction with the ACRN Hypervisor. This section explains the concept of the Trusted VM, its components, and its interaction with other VMs. For a high-level architecture and design overview of TEP, please refer to Intel TEP Design Guide.pdf.

Definitions and Acronyms

Term	Description
TPM	Trusted Platform Module
RPC	Remote Procedure Call
eRPC	Embedded RPC
PKCS#11	Public-Key Cryptography Standards

TEP Architecture

TEP is designed to provide isolated & Trusted environment at HW level using Intel silicon technologies and hypervisor protections to create a higher privileged Trusted Environment. The Trusted VM or the container is launched during the system boot. A lightweight trusted OS runs in the trusted VM to keep the surface attack to minimum. Administrators could host their services within Trusted VM to keep their data confidential and minimize their exposure to threats from other workloads running on the same system.

For a Bare Metal, the trusted environment is a hardened Trusted Container.

Trusted VM (or Trusted Container) offers:

• Integrity protection for Trusted OS & its services during boot-up time

• Run-time protection for Trusted OS & its services

• Data at rest protection

• Remote Attestation to verify the integrity of Trusted OS & its services during run-time

• Secure Configuration Update service

• Exclusive access to the TPM for hardware tethering

• Unified logging

Some of the components the Trusted VM utilizes:

• Secure boot: The hypervisor, trusted OS, and its file system are verified using secure boot chain of trust, which is rooted to the hardware root of trust for boot time integrity protection.

• Pass-through access to HW: Trusted VM also has a pass-through access to the PCI devices on the platform providing it exclusive access as per user configuration.

  • Storage: Trusted VM is configured to have a direct pass through access to NVMe-based storage device that could be used for exclusive storage. System Administrators can modify and configure to include other types of storage devices (USB, SATA, NVMe, and so on) in the Trusted VM. All other VMs, including Service VM, do not have access to this storage.

  • TPM: Trusted VM also has exclusive MMIO pass-through access to the Intel® Platform Trust Technology (Intel PTT) or discrete TPM on the platform. During the boot up, Trusted VM has the single ownership of the TPM and has a single Storage Root Key and password, one Endorsement Key, and a single set of Platform Configuration Registers (PCRs).

• Read-Only Mode: Trusted VM is launched in a Read-Only mode using a file system residing in RAM. Any changes made to the Trusted VM file system do not persist to storage and always comes back to known-good-state upon a system reboot.

• Inter VM IPC Communication: Guest VMs and Service VM can communicate with the Trusted VM and its services using an interface library with the PKCS#11 API interface. Standard PKCS#11 API (2.4 version of spec) interfaces are supported. Any OEM application that needs key store services can compile with this interface library and start making PKCS#11 API calls. The provided sample applications show how to use these APIs.

The Trusted VM design consists of Trusted OS, Security Micro Services, and Interface Library. While Trusted OS and Micro services form the Trusted VM, Interface Library itself executes from the Service VM/Guest VM.

Trusted OS and Services

This section describes the Trusted VM and a high-level design of its components. The Trusted VM is built using Yocto infrastructure but designed to be a lightweight Trusted OS to keep the surface attack minimal. Security micro services that run on Trusted OS include the TPM TSS stack, TPM2-PKCS#11 stack, eRPC stack, and Initialization scripts. The following figure illustrates the different layers of the Yocto recipe, which combine to form the Trusted VM image.

Component-level View of Stack

The following section is applicable to:

The component-level view of the stack describes the Trusted VM components versus the User VM components.

A customer application built using the Interface library /usr/lib/libpkcs11_client_wrapper.so can make direct calls to the PKCS#11 interface APIs. Each application is bound to a virtual UART channel (tty device) over which it communicates with the Trusted VM. The application will have an exclusive lock on the tty channel and its session until it chooses to release it and then a different application can bind itself to that virtual UART channel.

Functionality for this release is limited to the following virtual UART channels: ttyS4, ttyS5, ttyS6, ttyS7, ttyS8, ttyS9.

Trusted VM Prerequisites

The following section is applicable to:

The Trusted VM requires certain hardware, BIOS, and software configurations to be present on the target system to function correctly. The specific requirements include:

• Access to the ACRN hypervisor shell to initialize the TPM via the Trusted VM. For more information, refer to Use ACRN Hypervisor Shell.

  Note: The ACRN hypervisor shell is only required to initialize the TPM, after which this access may be revoked.

• PTT (Intel Silicon TPM) must be enabled in the target system BIOS.

• A dedicated SATA storage device must be installed on the target system. This storage device must be formatted with at least one partition, of which the first partition filesystem must be either: ext2, ext3, ext4, FAT, or FAT32. For reference, the Trusted VM will attempt to mount the SATA device partition from /dev/sda1.

  Note: ACRN only allows PCI devices to be passed through to a pre-launch VM.

  Tip

  To reformat and create an ext4 partition on the SATA device, perform these steps:

  $ umount /dev/sda1
  $ dd if=/dev/zero of=/dev/sda bs=512 count=100
  $ fdisk /dev/sda
  
      Command (m for help): n
      p
      Partition number (1-4): 1
      Press `Enter` to accept default value
      Press `Enter` to accept default value
      Command (m for help): w
  
  $ mkfs.ext4 /dev/sda1
  

Prepare Trusted VM

The following section is applicable to:

1. Make sure that the Trusted VM Prerequisites are met.

2. Build an legacy-poky-acrn image with the Trusted Edge Platform feature option enabled. Creating an legacy-poky-acrn image that contains the Trusted Edge Platform feature can be accomplished by selecting the Trusted VM feature option during image setup. For more information, refer to legacy-poky-acrn.

   

3. After building a legacy-poky-acrn image with the Trusted VM feature option enabled, install the legacy-poky-acrn image onto a target system. For instructions, refer to Install ECI Image with Yocto-based ACRN (Legacy).

   Important

   Do not install the ``legacy-poky-acrn`` image to any SATA device since the SATA controller is passed through to the Trusted VM!

4. Boot the image and select ACRN at the GRUB boot menu. ACRN will launch the Trusted VM and the service OS simultaneously.

   Note: The Trusted VM can only be accessed via the ACRN hypervisor shell.

5. Access the ACRN hypervisor shell and open the console to the Trusted VM (ID 0):

   See also

   For more information on using the ACRN hypervisor shell, refer to Use ACRN Hypervisor Shell.

   ACRN:\>vm_console 0
   

   Tip

   Press Ctrl + Space to return to the ACRN shell console.

6. Login to the Secure VM using username root and password 123456*18.

7. Verify that the passthrough SATA device partition /dev/sda1 is correctly mounted at /home/root/tmp:

   root@sec-os-intel-corei7-64:~# mount | grep sda1
   /dev/sda1 on /home/root/tmp type ext4 (rw,relatime,sync)
   

8. Delete any existing database tpm2_pkcs11.sqlite3 file stored in the SATA device:

   rm -rf /home/root/tmp/tpm2_pkcs11.sqlite3
   

9. Initialize the TPM with an entry for use with the tep_test_app:

   /usr/bin/run_pkcs11.sh
   

Verify Trusted VM

The following section is applicable to:

1. Make sure that you have prepared the Trusted VM.

2. Login to the ACRN Service OS.

3. Copy a User OS ECI image to /var/lib/machines/images/vm1.wic if one does not already exist.

4. Use the Trusted VM launch script to launch the User VM and establish a virtual UART connection to the Trusted VM:

   $ /var/lib/machines/scripts/launch-uos_secureVM-communication.sh
   

5. Login to the User OS.

6. Export the COMM port, which will be used for communication, to the Trusted VM:

   $ export TEC_COMM_PORT=/dev/ttyS4
   

   Note: COMM port options include ttyS4, ttyS5, ttyS6, ttyS7, ttyS8, ttyS9.

7. Run the example application built into ECI images:

   $ tep_test_app
   

   Expected Result

   Click to toggle visibility

   root@intel-rt-corei7-64:~# export TEC_COMM_PORT=/dev/ttyS4
   root@intel-rt-corei7-64:~# tep_test_app
   eRPC client initialize start
   Selected port is /dev/ttyS4
   Selected port is /dev/ttyS4
   eRPC client initialize done
   Calling C_Initialize_ERPC()
   Return value of C_Initialize:0
   Calling C_GetSlotList_ERPC()
   SlotCount = 2
   Return value of C_GetSlotList:0
   Calling C_GetSlotList_ERPC()
   Return value of C_GetSlotList:0
   Calling C_GetMechanismInfo_ERPC()
   Return value of C_GetMechanismInfo:0
   Calling C_GetMechanismInfo_ERPC()
   Return value of C_GetMechanismInfo:0
   selected slot: 1
   Calling C_GetTokenInfo_ERPC()
   Return value of C_GetTokenInfo:0
   Token already initialized
   Calling C_OpenSession_ERPC()
   Return value of C_OpenSession:0
   Calling C_Login_ERPC()
   Return value of C_Login:0
   Generating keypair....
   Calling C_GenerateKeyPair_ERPC()
   Return value of C_GenerateKeyPair:0
   Calling C_GetAttributeValue_ERPC()
   Return value of C_GetAttributeValue:0
   Calling C_GetAttributeValue_ERPC()
   Public Key data:
           Modulus bits: 2048
           Modulus: ffffffbe53ffffffbeffffff9dffffffd3ffffffd7ffffffc449fffffff1ffffffb9024b79ffffff806e25ffffff865bffffffe71effffffdd7cffffffa94affffffd2ffffffa35614ffffffb10dfffffffc552b35ffffffed65043b2c6effffffccffffff86ffffffecffffffc367ffffffcf55ffffffa8ffffffe25bffffffd6fffffff636ffffffb7fffffff8ffffffbe5bffffffe5ffffffd72a4fffffffbb7e52fffffffbffffff8affffff8bffffffba38fffffff72cffffff8f640d306cffffffe50170fffffff12effffffd3221bffffffea2e12ffffffcdffffff8740ffffffd6ffffff86ffffff8fffffff87ffffffb859ffffffeefffffff9ffffff84ffffffd7fffffff636ffffffcaffffffa3ffffffe64effffff93ffffffe7ffffff81ffffffb2ffffffbcfffffffd483743ffffffc6462c1476ffffffa51a1cffffffd9ffffffc7443bffffffebffffffe624ffffffda31ffffff8affffffef0558ffffffc61cffffffc3fffffffdffffffd4ffffffe6ffffffe9ffffff8affffffc311ffffffa20dffffffc4ffffffaffffffff5ffffff8433fffffff1ffffffa8ffffffb2787d2447fffffffb005bffffffdd6a61fffffff76677216c14ffffffcaffffffb4fffffff0120effffffe3ffffffadffffffb8ffffffd3ffffffc1ffffff97ffffffd616fffffffafffffffdfffffff9ffffffd0fffffffaffffffb4ffffffe9fffffff6ffffffa7ffffffd4ffffffae301620ffffffb5ffffffb318ffffffbc0bffffffaf4072ffffffbcfffffff5ffffff9d4affffffa3ffffffc725ffffff8e651cfffffff758ffffff8a127312ffffff840270140052fffffff00bffffff894d6c23fffffffe58fffffffefffffff2ffffffb227ffffff9cffffffb513ffffff893d42ffffffe7ffffffae4e23447fffffffc212ffffffa9
           Public Exponent: 010001
   Return value of C_GetAttributeValue:0
   Calling C_SignInit_ERPC()
   Return value of C_SignInit:0
   Calling C_Sign_ERPC()
   Return value of C_Sign:0
   Message was successfully signed with private key!
   Calling C_VerifyInit_ERPC()
   Return value of C_VerifyInit:0
   Calling C_Verify_ERPC()
   Return value of C_Verify:0
   Message was successfully verified with public key!
   Calling C_GenerateRandom()
   Calling C_SeedRandom_ERPC()
   C_seedRandom 0
   Calling C_GenerateRandom_ERPC()
   Return value for C_GenerateRandom:0
   Random number generated successfully: BC 7F CE 73 7E 9 7 A1 A4 BC DF 5A E9 8C 48 23 3B 29 AA 86 14 4 E7 DD 65 AA BA 9A 5 C0 5C 9D
   Calling C_CloseSession_ERPC()
   Return value of C_CloseSession
   Starting AES encrypt and decrypt
   
   Calling C_Initialize_ERPC()
   Calling C_GetSlotList_ERPC()
   slotCount = 2
   Calling C_GetSlotList_ERPC()
   Calling C_GetMechanismInfo_ERPC()
   Calling C_GetMechanismInfo_ERPC()
   selected slot: 1
   Calling C_GetTokenInfo_ERPC()
   Token already initialized
   Calling C_OpenSession_ERPC()
   Calling C_Login_ERPC()
   Calling C_FindObjectsInit_ERPC()
   Calling C_FindObjectsInit_ERPC()
   Calling C_FindObjects_ERPC()
   data objects count 1 found
   Calling C_FindObjectsFinal_ERPC()
   Calling C_GetAttributeValue_ERPC()
   This is my data object
   Calling C_DestroyObject_ERPC()
   Calling C_DigestInit_ERPC()
   Calling C_Digest_ERPC()
   digest
   5d fb ab ee df 31 8b f3 3c 9 27 c4 3d 76 30 f5 1b 82 f3 51 74 3 1 35 4f a3 d7 fc 51 f0 13 2e
   Get AES Key object....
   Calling C_FindObjectsInit_ERPC()
   Calling C_FindObjects_ERPC()
   AES object count 1 found
   Calling C_FindObjectsFinal_ERPC()
   AES Encrypt ....
   Calling C_EncryptInit_ERPC()
   Calling C_Encrypt_ERPC()
   AES Decrypt ....
   Calling C_DecryptInit_ERPC()
   Calling C_Decrypt_ERPC()
   Message was successfully decrypted!
   AES Encrypt using Update & Final....
   Calling C_EncryptInit_ERPC()
   Calling C_EncryptUpdate_ERPC()
   Calling C_EncryptUpdate_ERPC()
   Calling C_EncryptFinal_ERPC()
   Calling C_DecryptInit_ERPC()
   Calling C_DecryptUpdate_ERPC()
   Calling C_DecryptUpdate_ERPC()
   Calling C_DecryptFinal_ERPC()
   Message was successfully decrypted using Update & Final calls!
   Calling C_CloseSession_ERPC()
   Calling C_Finalize_ERPC()
   eRPC client deinitialize start
   eRPC client deinitialize done
   

Developing for Trusted VM

The following section is applicable to:

Do the following to create an application that uses the Trusted VM:

1. Make sure that you have prepared the Trusted VM.

2. Login to the ACRN Service OS.

3. Copy a User OS image to /var/lib/machines/images/*_vm1.wic if one does not already exists.

4. Use the Trusted VM launch script to launch the User VM and establish a virtual UART connection to the Trusted VM:

   $ /var/lib/machines/scripts/launch-uos_secureVM-communication.sh
   

5. Login to the User OS.

6. Export the COMM port, which will be used for communication, to the Trusted VM:

   $ export TEC_COMM_PORT=/dev/ttyS4
   

   Note: COMM port options include ttyS4, ttyS5, ttyS6, ttyS7, ttyS8, ttyS9.

7. Install the TEP client and interface library from the ECI APT repository. Setup the ECI APT repository, then perform either of the following commands to install this component:

   # For eRPC
   $ sudo apt install ipc-p11-client-erpc libipc-p11-client-erpc-dev
   
   # For gRPC
   $ sudo apt install ipc-p11-client-grpc libipc-p11-client-grpc-dev
   

   See also

   Refer to the following links for more information about eRPC and gRPC development libraries.

8. Compile the application, but for all instances where standard TPM2 library tpm2_pkcs11 would be used, link against libtep_interface.a instead. The interface library will transport the TPM2 API calls to the Trusted VM via the virtual UART channel specified in the previous step.

Use Trusted Edge Platform as Container

It is possible to build TEP as a container as opposed to a VM image.

To build and deploy the TEP as a container, you need to:

1. Prepare a TEP container image

2. Deploy the TEP container image

Prepare Trusted Edge Platform Container Image

The following section is applicable to:

Do the following to prepare a TEP container image:

1. Build a legacy-poky-acrn image with the Trusted Edge Platform feature option enabled. Creating a legacy-poky-acrn image that contains the Trusted Edge Platform feature can be accomplished by selecting the Trusted VM feature option during image setup. For more information, refer to legacy-poky-acrn.

   

2. After the build completes, prepare the system for manual build:

   $ cd /home/eci/Desktop/eci-release
   $ source oe-init-build-env /home/eci/Desktop/eci-release/build/eci-legacy-poky-acrn
   

3. Build the container image:

   $ bitbake mc:x86-tep-trusted-os-tgl-initramfs:core-image-trusted-os
   

4. After the build completes, navigate to the TEP image directory:

   $ cd eci-release/build/eci-legacy-poky-acrn/tmp-x86-tep-trusted-os-tgl-initramfs/deploy/images/intel-corei7-64
   

5. Copy the container image core-image-trusted-os-intel-corei7-64.tar.bz2 or note the location for later use.

Deploy Trusted Edge Platform Container Image

The following section is applicable to:

Do the following to deploy the TEP container image:

1. Transfer the container image core-image-trusted-os-intel-corei7-64.tar.bz2 to the target system. For more information on creating the container image, refer to Prepare Trusted Edge Platform Container Image.

2. Import the container image to Docker:

   $ docker import core-image-trusted-os-intel-corei7-64-*.tar.bz2 trusted_container:latest
   

3. Follow the instructions in 4.1.1 TEP Docker Container Setup of the Intel TEP Container User Guide_R_3.0.pdf .

   Use this docker_setup.sh script when prompted.