1. Article purpose[edit | edit source]
The purpose of this article is to explain how to integrate the STPM4RasPI expansion board with STM32MP157F-DK2 Discovery kit 
and STM32MP135F-DK Discovery kit .
A signature verification usecase 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.
This article also propose to guide the user through the different steps needed to add manually the necessary software inside OpenSTLinux distribution. This part can also be done by taking directly the X-LINUX-TPM package described in X-LINUX-TPM Expansion Package.
2. Prerequisites[edit | edit source]
2.1. Hardware prerequisites[edit | 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
- LAN connectivity.
- STPM4RasPI expansion board[1]
- STPM4RasPIV21 expansion board[2]
STPM4RasPI and STPM4RasPIV21 are extension boards to connect STSAFE-TPM products to the STM32 microprocessor development kits such as STM32MP157F-DK2, or STM32MP135F-DK. The boards are designed for product evaluation, use case development and integration activities. The boards are shipped with one trusted platform module soldered.
- STPM4RasPI is the extension board to connect ST33TPHF2XSPI or ST33TPHF2XI2C products. Please see board webpage for ordering information (https://www.st.com/en/evaluation-tools/stpm4raspi.html).
- STPM4RasPIV21 is the extension board to connect the ST33KTPM products. Please see board webpage for ordering information (https://www.st.com/en/evaluation-tools/stpm4raspiv21.html).
2.2. Software prerequisites[edit | edit source]
The STM32MP1 distribution package must be installed on a host PC. For more information on the OpenSTLinux distribution package go to STM32MP1 Distribution Package article.
For demonstration purposes, the TPM is used at runtime only, on top of the LinuxTM kernel. It uses the TPM2 software stack (TSS) [3] implemented in the OpenSTLinux distribution. The TPM can be handled by the tpm2-tools delivered with the TSS.
To check the TPM features, we use the tool openssl (for the signature verification usecase).
3. Software customization to support STPM4RasPI expansion board[edit | edit source]
The LinuxTM kernel must be configured to control the STPM4RasPI expansion board on the STM32MP157F-DK2 or STM32MP135F-DK .
The customization consists in modifying the Linux kernel configuration, managing the appropriate device tree elements and including TSS components.
Note that:
- The software customization has been validated in the OpenSTLinux distribution environment and with the configuration (DISTRO="openstlinux-weston", MACHINE="<stm32mp13-disco|stm32mp15-disco>", IMAGE="st-image-weston").
3.1. Kernel configuration[edit | edit source]
The LinuxTM kernel must be updated to include the TPM driver for SPI.
The ST33TPHF20SPI is TCG-compliant and supports the following standard TCG Linux SPI drivers:
To check whether associated drivers are enabled inside the kernel, executes the following instructions on the target:
cat /proc/config.gz | gunzip | grep TCG CONFIG_TCG_TPM=y CONFIG_TCG_TIS=y CONFIG_TCG_TIS_SPI=y
If the above configuration are not enabled, the kernel config has to be modified:
bitbake linux-stm32mp -c menuconfig
Select in the kernel menu config :
Device Drivers ---> Character devices ---> <*> TPM Harware Support ---> <*> TPM Interface Specification 1.3 Interface / TPM 2.0 FIFO Interface - (SPI)
For more information on the LinuxTM Kernel configuration refer to How to configure the Kernel with Menuconfig
3.2. Kernel device tree configuration[edit | edit source]
The TPM driver uses the SPI5 on the GPIO expansion connector.
The device tree must be updated to declare and initialize them.
Information to update the device tree in the OpenSTLinux distribution is written in How to cross-compile with the Distribution Package
3.2.1. DTS board STM32MP157F-DK2 [edit | edit source]
- Go to the <build dir>/workspace/sources/<name of kernel recipe>/ directory
cd <build dir>/workspace/sources/<name of kernel recipe>/
- Edit the arch/arm/boot/dts/stm32mp157f-dk2.dts Device Tree Source file, add the following lines to update the node spi5.
&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>;
};
};
3.2.2. DTS board STM32MP135F-DK [edit | edit source]
- Go to the <build dir>/workspace/sources/<name of kernel recipe>/ directory
cd <build dir>/workspace/sources/<name of kernel recipe>/
- Edit the arch/arm/boot/dts/stm32mp135f-dk.dts Device Tree Source file, add the following lines to update the node spi5.
&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>;
};
};
3.3. tpm2 TSS components software[edit | 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 ..
- Add the "tpm2 TSS" component software in the following image file
(layers/meta-st/meta-st-openstlinux/conf/distro/include/openstlinux.inc)
DISTRO_FEATURES:append = " tpm2 "
- Complete the tpm2 packagegroup to include the following packages
(layers/meta-security/meta-tpm/recipes-core/packagegroup/packagegroup-security-tpm2.bb)
IMAGE_INSTALL:append = " \ tpm2-tools \ tpm2-openssl \ libtss2 \ libtss2-tcti-device \ libtss2-tcti-mssim \ tpm2-abrmd \ tpm2-totp \ tpm2-tss \ tpm2-tss-engine \ tpm2-tss-engine-dev \ "
3.4. Image build and flash[edit | edit source]
Go the article STM32MP1 Distribution Package for the process to adapt and flash an image for any LinuxTM distributions.
4. TPM driver loading check[edit | 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
5. Sign data with TPM2 key & signature verification with OpenSSL[edit | 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 | edit source]