infineon/ek-based-onboarding-optiga-tpm

Guide for Setting Up and Operating Device Onboarding with OPTIGA™ TPM Endorsement Key (EK)

Introduction

This project explains how to use an OPTIGA™ TPM 2.0 on a Raspberry Pi to perform Endorsement Key (EK)-based device onboarding to a private cloud. EK-based device onboarding is a mechanism for registering a device on a cloud service using EK as the device identity, without the need to provision the TPM with an additional key or certificate. Additionally, there is a way to securely transfer server-generated keys (HMAC/RSA/ECC) to a TPM of a device. The in-transit encrypted key blobs can be associated with an EK, and as a result, the blobs can only be imported to a TPM that holds the specified EK. Depending on the application, these keys can be used for various purposes, such as data encryption/decryption and digital signing.

Table of Contents

• Prerequisites
• Project Overview
• Preparing Raspberry Pi for First Use
• Installing Software for First Use
• Operation Guide
  • TPM Simulator
  • Server
  • Device
• License

Prerequisites

There are two options for TPM usage: using an actual TPM or a simulated TPM.

Option 1:
To use an actual TPM, you will need the following hardware:

• You can use either of the following TPM2.0 boards:
  • IRIDIUM9670 TPM2.0 board
    
  • OPTIGA™ TPM SLB 9672 RPI evaluation board
    
• A Raspberry Pi 4 with TPM mounted.
  

Option 2:
For a simulated TPM, you can use any host machine with one of the following Linux distributions installed: Debian (Bullseye, Buster), Ubuntu (18.04, 20.04).

Project Overview

The purpose of this project is to demonstrate the following flow:

Flow	Description
1. Onboarding	This step is performed once to onboard a device to a server and follows this sequence: The server verifies that the EK certificate is issued by Infineon's CA. If the whitelist feature is enabled, only devices with a whitelisted EK public key can be onboarded. Three TPM key objects (HMAC, RSA, and ECC) are generated on the server and transferred to the TPM of the device.
2. Authentication	The authentication step requires the device to produce a total of three signatures using the three imported keys (for demonstration purposes only; in normal circumstances, a single signature may suffice). After a successful authentication, the device will receive a server-signed JWT-formatted token. The JWT is necessary for all subsequent communication with the server as proof of identity. The JWT is only valid for a limited period. The authentication step can be repeated to obtain a new JWT.
3. Key Derivation and Second-Layer Encryption	This step demonstrates that the imported HMAC key can be used to add another layer of data encryption. A session-based encryption key can be derived using the HMAC function after exchanging seeds between the server and the device.

Preparing Raspberry Pi for First Use

Skip this section if you do not plan to use Raspberry Pi.

This section outlines the steps required to prepare an SD card image that can be used to boot a Raspberry Pi.

To begin, flash the Raspberry Pi OS image 2021-01-11 release onto a micro-SD card that is at least 8GB in size.

After inserting the SD card that you just flashed, boot up your Raspberry Pi. To enable TPM, execute the following commands:

$ sudo sh -c "echo 'dtoverlay=tpm-slb9670' >> /boot/config.txt"

Reboot the Raspberry Pi and check if TPM is activated by:

$ ls /dev | grep tpm
tpm0
tpmrm0

Installing Software for First Use

Download package information:

$ sudo apt update

Install generic packages:

$ sudo apt -y install xxd jq maven openjdk-11-jre autoconf-archive libcmocka0 libcmocka-dev procps iproute2 build-essential git pkg-config gcc libtool automake libssl-dev uthash-dev autoconf doxygen libjson-c-dev libini-config-dev libcurl4-openssl-dev uuid-dev pandoc acl libglib2.0-dev xxd curl

Install platform dependent packages on Ubuntu (18.04, 20.04):

$ sudo apt -y install python-yaml

Install tpm2-tss:

$ git clone https://github.com/tpm2-software/tpm2-tss ~/tpm2-tss
$ cd ~/tpm2-tss
$ git checkout 3.2.0
$ ./bootstrap
$ ./configure
$ make -j$(nproc)
$ sudo make install
$ sudo ldconfig

# For debugging:
# Possible levels are: NONE, ERROR, WARNING, INFO, DEBUG, TRACE
# export TSS2_LOG=all+TRACE

Install tpm2-tools:

$ git clone https://github.com/tpm2-software/tpm2-tools ~/tpm2-tools
$ cd ~/tpm2-tools
$ git checkout 5.2
$ ./bootstrap
$ ./configure
$ make -j$(nproc)
$ sudo make install
$ sudo ldconfig

Install tpm2-abrmd:

$ git clone https://github.com/tpm2-software/tpm2-abrmd ~/tpm2-abrmd
$ cd ~/tpm2-abrmd
$ git checkout 2.4.1
$ ./bootstrap
$ ./configure
$ make -j$(nproc)
$ sudo make install
$ sudo ldconfig

Install libtpms-based TPM simulator:

# Install dependencies
$ sudo apt-get install -y dh-autoreconf libtasn1-6-dev net-tools libgnutls28-dev expect gawk socat libfuse-dev libseccomp-dev make libjson-glib-dev gnutls-bin

# Install libtpms-devel
$ git clone https://github.com/stefanberger/libtpms ~/libtpms
$ cd ~/libtpms
$ git checkout v0.9.5
$ ./autogen.sh --with-tpm2 --with-openssl
$ make -j$(nproc)
$ sudo make install
$ sudo ldconfig

# Install Libtpms-based TPM simulator
$ git clone https://github.com/stefanberger/swtpm ~/swtpm
$ cd ~/swtpm
$ git checkout v0.7.3
$ ./autogen.sh --with-openssl --prefix=/usr
$ make -j$(nproc)
$ sudo make install
$ sudo ldconfig

Download the project:

$ git clone https://github.com/infineon/ek-based-onboarding-optiga-tpm ~/ek-based-onboarding-optiga-tpm

Operation Guide

TPM Simulator

If you don't plan to use TPM simulator, you may skip this section.

Start Libtpms-based TPM simulator:

$ mkdir /tmp/simulated_tpm

# Create configuration files for swtpm_setup:
# - ~/.config/swtpm_setup.conf
# - ~/.config/swtpm-localca.conf
#   This file specifies the location of the CA keys and certificates:
#   - ~/.config/var/lib/swtpm-localca/*.pem
# - ~/.config/swtpm-localca.options
$ swtpm_setup --tpm2 --create-config-files overwrite,root

# Initialize the swtpm
$ swtpm_setup --tpm2 --config ~/.config/swtpm_setup.conf --tpm-state /tmp/simulated_tpm --overwrite --create-ek-cert --create-platform-cert --write-ek-cert-files /tmp/simulated_tpm

# Launch the swtpm
$ swtpm socket --tpm2 --flags not-need-init --tpmstate dir=/tmp/simulated_tpm --server type=tcp,port=2321 --ctrl type=tcp,port=2322 &   <--- to debug, add "--log level=?"
$ sleep 5

Copy swtpm CA certificates to the server source:

# Root CA
$ openssl x509 -outform der -in ~/.config/var/lib/swtpm-localca/swtpm-localca-rootca-cert.pem -out ~/ek-based-onboarding-optiga-tpm/server/src/main/resources/rootCAs/swtpm-localca-rootca-cert.crt

# Intermediate CA
$ mkdir ~/ek-based-onboarding-optiga-tpm/server/src/main/resources/intermediateCAs
$ openssl x509 -outform der -in ~/.config/var/lib/swtpm-localca/issuercert.pem -out ~/ek-based-onboarding-optiga-tpm/server/src/main/resources/intermediateCAs/issuercert.crt

Start a session dbus which is limited to the current login session:

$ sudo apt install -y dbus
$ export DBUS_SESSION_BUS_ADDRESS=`dbus-daemon --session --print-address --fork`

Start TPM resource manager:

$ tpm2-abrmd --allow-root --session --tcti=swtpm:host=127.0.0.1,port=2321 &
$ sleep 5

Server

Build and start the server:

$ cd ~/ek-based-onboarding-optiga-tpm/server
$ mvn package
$ mvn spring-boot:run &
$ sleep 20

The server is ready for operation once you see the following message:

...
2023-02-17 07:52:53.582  INFO 8998 --- [main] o.s.m.s.b.SimpleBrokerMessageHandler     : Started.
2023-02-17 07:52:53.915  INFO 8998 --- [main] o.s.b.w.embedded.tomcat.TomcatWebServer  : Tomcat started on port(s): 443 (https) 80 (http) with context path ''
2023-02-17 07:52:53.916  INFO 8998 --- [main] com.ifx.server.ServerApplication         : Started ServerApplication in 3.51 seconds (JVM running for 3.732)

To view the webpage, open a web browser and navigate to https://localhost. A warning message may appear due to the server using a self-signed certificate. You can bypass this warning and proceed as usual. Once the webpage has loaded, click on "Start" in the upper menu bar to enter the sign-in page (Screenshot-1). Use the following credentials to sign in:

• Username: infineon
• Password: noenifni

Once you have logged in successfully, you will see that the dashboard page (as shown in Screenshot-2 and Screenshot-3) has the following elements:

Element	Description
A	The table displays a list of onboarded devices, along with a button for unpairing devices.
B	Display of server activity log.
C	Upload a CSV-formatted file containing a list of whitelisted EK public keys.
D	You can enable or disable the effect of whitelisting. If the option is disabled, a device can only be onboarded if its TPM is issued by Infineon. If the option is enabled, a device can only be onboarded if both of the following conditions are met: The TPM is issued by Infineon. The EK public key is whitelisted.
E	The table displays a list of whitelisted devices, along with a button for blacklisting devices.

Screenshots:

Screenshot-1
Screenshot-2
Screenshot-3

Device

Depending on your choice of TPM:

• Hardware TPM
  Set the TCTI interface:

  $ export TPM2TOOLS_TCTI="device:/dev/tpmrm0"
  

  Grant access permissions to the TPM device nodes:

  $ cd ~/ek-based-onboarding-optiga-tpm/device
  $ ./0_prep.sh
  

• Simulated TPM
  Set the TCTI interface:

  $ export TPM2TOOLS_TCTI="tabrmd:bus_name=com.intel.tss2.Tabrmd,bus_type=session"
  

Once the server is up and running, execute the following scripts:

$ cd ~/ek-based-onboarding-optiga-tpm/device
$ ./1_clean.sh
$ ./2_tpm-clear-init.sh
$ ./3_onboard-req.sh
$ ./4_tpm-key-import.sh
$ ./5_onboard-ack.sh
$ ./6_auth.sh
$ ./7_seed-exchange.sh
$ ./8_derive-aes-key.sh
$ ./9_secured-download.sh

You can find more information about each individual script in the following table:

0_prep.sh	Authorizes non-privileged access to the TPM device nodes.
1_clean.sh	Cleans up the environment, erase non-essential files.
2_tpm-clear-init.sh	Performs the following actions: Clears the TPM. Creates an RSA EK. Reads the RSA EK certificate. Creates an RSA-based parent key that can be used as a wrapping key to securely transfer keys from a server to the TPM. Creates a CSV-formatted whitelist containing a single EK public key taken from the EK certificate that you have just read. Note: If the whitelist feature is enabled, you must import the CSV file through the dashboard page (Screenshot-3) before proceeding.
3_onboard-req.sh	Sends an onboarding request to the server, the request contains: The username ("infineon") to pair the device with. The EK certificate. The parent public key. The expected response from the server includes: A credential blob containing a decryption key (Ҡ). An encrypted device ID, secured by Ҡ. An encrypted HMAC-SHA256 key, secured by the parent key and an inner wrap key (Ҡ). An encrypted RSA-2048 key, secured by the parent key and Ҡ. An encrypted ECC NIST P-256 key, secured by the parent key and Ҡ. A challenge. Note: if the whitelist feature is enabled, only whitelisted devices can be onboarded.
4_tpm-key-import.sh	After receiving the server response: Perform TPM activate credential on the credential blob to recover the decryption key (Ҡ). Decrypt the device ID using Ҡ. Import the HMAC, RSA, and ECC keys into the TPM, using Ҡ as the inner wrap key and the RSA-based parent key. Sign the challenge using the three imported keys.
5_onboard-ack.sh	Acknowledges the challenge by sending the three signatures to the server. Once the signatures are verified, the device is now successfully onboarded to the server.
6_auth.sh	Starts an authentication sequence: Request a challenge from the server. Sign the challenge using the three imported keys. Upon receiving valid signatures, the server generates a token (JWT) and returns it to the device. The JWT contains a subject (device ID), a token validity period, and a server-generated signature. Now that you have obtained the necessary token for further communication with the server, it is mandatory to attach the JWT to all subsequent requests made to the server. This ensures that the server can authenticate your requests and authorize your access to the services.
7_seed-exchange.sh	Performs seed exchange.
8_derive-aes-key.sh	The device uses the HMAC key and seed values to perform an HMAC operation, from which it derives a session-based AES key (AES-256/CBC/PKCS5Padding).
9_secured-download.sh	After downloading encrypted media from the server, the device decrypts it using the AES key. The media that the device expects to receive include: A video in 3GP format (decrypted.3gp) that can be played using the Raspberry's built-in VLC Media Player. A text file (decrypted.txt) containing the message "You have successfully decrypted this message." A binary file (decrypted.hex) with a hexadecimal value of 0xdeadbeef (four bytes).

License

This project is licensed under the MIT License - see the LICENSE file for details.