Last edited one month ago

X-LINUX-TPM expansion package

Applicable for STM32MP13x lines, STM32MP15x lines

1. Article purpose[edit source]

The purpose of this article is to explain how to integrate the STPM4RasPI expansion board with STM32MP157F-DK2 Discovery kit More info green.png or STM32MP135F-DK Discovery kit More info green.png. 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[edit source]

2.1. Hardware prerequisites[edit source]

  • STM32MP157F-DK2 Discovery kit More info green.png or STM32MP135F-DK Discovery kit More info green.png

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]
STPM4RasPi.png

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[edit source]

  • Get the OpenSTLinux ecosystem release v5.0.0 More info.png (steps described in the article above).

3. Hardware setup[edit source]

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[edit source]

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
Info white.png Information
This version is compatible with the Yocto Project® build system Mickledore. It is validated against the OpenSTLinux ecosystem release v5.0.0 More info.png on the following boards:
  • STM32MP157F-DK2 More info green.png
  • STM32MP135F-DK More info green.png

4.1. Main software modification[edit source]

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[edit source]

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[edit source]

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[edit source]

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.

TSS2 tpm.png

4.2. How to build the OpenSTLinux distribution with X-LINUX-TPM[edit source]

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[edit source]

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

4.2.2. Install the X-LINUX-TPM environment[edit source]

  • 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[edit source]

 bitbake st-image-weston
Info white.png 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[edit source]

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

4.3. How to validate the good behavior of X-LINUX-TPM[edit source]

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

4.3.1. Driver load check[edit source]

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[edit source]

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[edit source]

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[edit source]