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 
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[edit source]
2.1 Hardware prerequisites[edit source]
- 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
- 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[edit source]
- 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[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.
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.
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 :
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
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