X-LINUX-TPM expansion package

Applicable for

1 Article purpose

The purpose of this article is to explain how to integrate the STPM4RasPI expansion board with STM32MP157F-DK2 Discovery kit or STM32MP135F-DK Discovery kit . The X-LINUX-TPM OpenSTLinux expansion package provides the software add-ons for this integration. A signature verification use case is included, in order to verify the TPM integration.
Multiple services are available using TPM (mostly on PC and mobile devices):

Cryptographic keys generation, protection, management and usage
Cryptographic device identity
Secure logging, log-reporting and, certification or authentication
Secure non volatile storage
Other functions including hashing, random number generation and secure clock

Several use cases are available:

Platform integrity: the boot process relies on TPM for software integrity and authentication during each boot stage
Disk encryption: encrypt and decrypt drive using TPM crypto core
Password protection, and so on.

The usecase described in this article uses the cryptographic key generation functionality on the TPM.

2 Prerequisites

2.1 Hardware prerequisites

STM32MP157F-DK2 Discovery kit or STM32MP135F-DK Discovery kit

For more information on the STM32 discovery board and how to start it up, go to section Getting started with STM32MP157x-DK2 or Getting started with STM32MP135x-DK

STM32MP157F-DK2

STM32MP135F-DK

STPM4RasPI expansion board^[1]

The STPM4RasPI is an official extension board to connect the ST33 TPM products to the Raspberry Pi^® device.
It is designed for development, proof of concept or demonstration activities.
The board is shipped with one soldered trusted platform module.
The ST33 TPM device soldered is the ST33TPHF20SPI, and is a TPM V2.0 specification implementation.

2.2 Software prerequisites

Be familiar with OpenSTLinux Distribution Package, see STM32MP1 Distribution Package article for more information.

Get the OpenSTLinux ecosystem release v5.0.0 (steps described in the article above).

3 Hardware setup

Whatever discovery board you have, they both offer a 40 pins connector, also called a Raspberry PI connector. To setup your hardware, plug the STPM4RasPI expansion board on this connector (a small number "1" indicates the direction in which the expansion board should be oriented).

4 Software setup

X-LINUX-TPM is an STM32 MPU OpenSTLinux expansion package that aims to bring the support of STPM4RasPI^[2] expansion board into the OpenSTLinux distribution.

This package is provided as a Yocto meta layer and can be applied directly in the OpenSTLinux distribution.

TPM Expansion Package In STM32MPU Embedded Software.png

Information

This version is compatible with the Yocto Project^® build system Mickledore. It is validated against the OpenSTLinux ecosystem release v5.0.0 on the following boards:

STM32MP157F-DK2
STM32MP135F-DK

4.1 Main software modification

Through the Yocto meta layer delivered by this package, we mainly change the OpenSTLinux distribution at 2 levels:

The Linux^® kernel: at kernel configuration and Device tree level
User space: with bringing necessary libraries and tools to use the TPM expansion board features.

4.1.1 Linux kernel configuration

To activate and use the right TPM SPI and I2C drivers, X-LINUX-TPM changes the Linux kernel configuration to set the followings:

CONFIG_TCG_TPM=y
CONFIG_TCG_TIS=y
CONFIG_TCG_TIS_SPI=y
CONFIG_TCG_TIS_I2C=y
CONFIG_CRC_CCITT=y

4.1.2 Linux kernel board device trees

On discovery boards mentioned in this article, both Raspberry PI connectors are linked with SPI5 provided by the STM32 device. This is this SPI instance that is used to access TPM features.
In the same way, some other TPM chips are driven by I2C interface. In this situation, I2C5 instance is used on Raspberry PI connector.

Note that some TPM devices can support both SPI and I2C interfaces.

The board device trees are so patched into the X-LINUX-TPM to get the following SPI5 and I2C5 nodes:

arch/arm/boot/dts/stm32mp157f-dk2.dts Device Tree Source file:

&spi5{
	pinctrl-names = "default", "sleep";
	pinctrl-0 = <&spi5_pins_a>;
	pinctrl-1 = <&spi5_sleep_pins_a>;
	cs-gpios = <&gpiof 6 0>;
	status = "okay";

	st33htpm0: st33htpm@0{
		status="okay";
		compatible = "st,st33htpm-spi";
		#address-cells = <1>;
		#size-cells = <0>;
		reg = <0>; /* CS #0 */
		spi-max-frequency = <10000000>;
	};
};

&i2c5 {
	pinctrl-names = "default", "sleep";
	pinctrl-0 = <&i2c5_pins_a>;
	pinctrl-1 = <&i2c5_sleep_pins_a>;
	i2c-scl-rising-time-ns = <185>;
	i2c-scl-falling-time-ns = <20>;
	clock-frequency = <400000>;
	/* spare dmas for other usage */
	/delete-property/dmas;
	/delete-property/dma-names;
	status = "okay";

	st33htpi: st33htpi@0{
		compatible = "infineon,slb9673", "tcg,tpm-tis-i2c";
		reg = <0x2e>;
		status="okay";
	};
};

arch/arm/boot/dts/stm32mp135f-dk.dts Device Tree Source file:

&spi5{
	pinctrl-names = "default", "sleep";
	pinctrl-0 = <&spi5_pins_a>;
	pinctrl-1 = <&spi5_sleep_pins_a>;
	cs-gpios = <&gpioh 11 0>;
	status = "okay";

	st33htpm0: st33htpm@0{
		status="okay";
		compatible = "st,st33htpm-spi";
		#address-cells = <1>;
		#size-cells = <0>;
		reg = <0>; /* CS #0 */
		spi-max-frequency = <10000000>;
	};
};

&i2c5 {
	pinctrl-names = "default", "sleep";
	pinctrl-0 = <&i2c5_pins_a>;
	pinctrl-1 = <&i2c5_sleep_pins_a>;
	i2c-scl-rising-time-ns = <170>;
	i2c-scl-falling-time-ns = <5>;
	clock-frequency = <400000>;
	status = "okay";
	/* spare dmas for other usage */
	/delete-property/dmas;
	/delete-property/dma-names;

	st33htpi: st33htpi@0{
		compatible = "infineon,slb9673", "tcg,tpm-tis-i2c";
		reg = <0x2e>;
		status="okay";
	};
};

cs-gpios property for SPI is schematics dependent as it needs to target the SPI5_NSS pin. Other SPI5 pins are defined by pinctrl nodes.

reg property for I2C represents the I2C address of the TPM device.

4.1.3 User space additional stacks

The X-LINUX-TPM package brings TPM2 software stack (TSS) ^[3] into the OpenSTLinux distribution. It deals with TSS libraries as well as tpm2-tools. These last ones are used to handle the TPM. The diagram below gives an overview of the software architecture, in the context of a such device driven by SPI.

4.2 How to build the OpenSTLinux distribution with X-LINUX-TPM

With the following procedure, the complete distribution is regenerated by enabling the X-LINUX-TPM expansion package.

4.2.1 Download the STM32MP1 Distribution Package

For ecosystem release v5.0.0 :
Install the STM32MP1 Distribution Package v5.0.0.

4.2.2 Install the X-LINUX-TPM environment

Add the Yocto Layer meta-security into your environment (it provides TPM2 recipes):

 cd <Distribution Package installation directory>/layers
 git clone https://git.yoctoproject.org/meta-security -b mickledore
 cd ..

Clone the meta-st-x-linux-tpm git repository:

 cd <Distribution Package installation directory>/layers/meta-st
 git clone -b yocto/mickledore https://github.com/STMicroelectronics/meta-st-x-linux-tpm.git
 cd ../..

Source the build environment (same for MP15 and MP13 series):

 DISTRO=openstlinux-weston MACHINE=stm32mp1 source layers/meta-st/scripts/envsetup.sh
 bitbake-layers add-layer ../layers/meta-st/meta-st-x-linux-tpm

4.2.3 Build the image

 bitbake st-image-weston

Information

Note that building the image might take a long time depending on the host computer performance.

4.2.4 Program the built image into the flash memory

Follow this link to see how to program the built image.

4.3 How to validate the good behavior of X-LINUX-TPM

You can find below some checks to verify that TPM2 features are working well.

4.3.1 Driver load check

When the TPM driver is loaded, /dev/tpm0 and /dev/tpmrm0 are present, as shown in the figure below.

dmesg | grep tpm

[    1.525447] tpm_tis_spi spi0.0: 2.0 TPM (device-id 0x0, rev-id 78)

ls -l /dev | grep tpm

crw------- 1 tss  tss    10,   224 Oct 11 15:27 tpm0
crw------- 1 root root  253, 65536 Oct 11 15:27 tpmrm0

4.3.2 Simple TPM tool command check

If the driver is well loaded, you can test to run a simple 'tpm2' command in the Linux kernel console :

tpm2_getrandom --hex 20

If no error is raised, it means that STM32 device well communicates with STPM4RasPI expansion board.

5 How to run a signature use case with X-LINUX-TPM

This is an example of using the TPM to perform signature of a file "msg.txt" hash (digest). A verification is done with the openssl "dgst -verify" command.

Message creation example :

 echo dzeydezyetrefygzuedghdgie > msg.txt

Primary key creation :

tpm2_createprimary -C o -c pri.txt

Signature key creation :

tpm2_create -C pri.txt -g sha256 -G rsa -u kpub.bin -r kpriv.bin

Loading of the created signature key in TPM :

tpm2_load -u kpub.bin -r kpriv.bin -C pri.txt -c key.txt

Signature of the hash with the TPM signed key

tpm2_sign -c key.txt -g sha256 -f plain -o hash.plain msg.txt

Read of the public part of the TPM signing key

tpm2_readpublic -c key.txt -f der -o key_sig_pub.der

Verification with openssl dgst

openssl dgst -verify key_sig_pub.der -keyform der -sha256 -signature hash.plain msg.txt

6 References

[1] STPM4RasPI expansion board

[2] STPM4RasPI TPM development kit

[3] Trusted Computing Group

[1]

[2]

[3]

Expert	Approved
Technical writer	Approved
Maintainer	Approved

User

Wiki

Categories

General Books