1. Article purpose[edit | edit source]
The purpose of this article is to explain how to integrate the STPM4RasPI expansion board with STM32MP157C-DK2, managed by LinuxTM on Cortex®-A7.
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.
2. Prerequisites[edit | edit source]
2.1. Hardware prerequisites[edit | edit source]
- STM32MP157C-DK2
For more information on the STM32 discovery board and how to start it up, go to section Getting_started/STM32MP1_boards/STM32MP157C-DK2
- 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 | edit source]
The STM32MP1 distribution package must be installed on a host PC. The process has been validated with the delivery ecosystem release v1.1.0 
and ecosystem release v1.2.0 of the OpenSTlinux distribution . 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) [2] implemented in the OpenSTLinux distribution. The TPM can be handled by the tpm2-tools delivered with the TSS.
To check the TPM features, use the tool openssl (for the signature verification usecase).
3. Software customization to support STPM4RasPI expansion board[edit | edit source]
The STM32MP157C-DK2 LinuxTM software must be configured to activate the STM4RasPI expansion board on the STM32MP157C-DK2 board.
The configuration consists in modifying the STM32MP157C-DK2 Linux kernel, managing the appropriate device tree elements and including TSS components and openssl tool.
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: (source .../drivers/char/tpm/tpm_tis_spi.c, .../drivers/char/tpm/tpm_tis_core.c, .../drivers/char/tpm/tpm_tis.c).
To check whether associated drivers are enabled inside the kernel, execute the following instrucions on the target:
Board $> cat /proc/config.gz | gunzip | grep TCG CONFIG_TCG_TPM=y CONFIG_TCG_TIS_CORE=y CONFIG_TCG_TIS_SPI=y
If the above configuration are not enabled, the kernel config has to be modified:
PC $>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 Menuconfig_or_how_to_configure_kernel
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.
&pinctrl {
.
.
.
.
/* USER CODE BEGIN pinctrl */
spi5_pins_mx: spi5_mx-0 {
pins {
pinmux = <STM32_PINMUX('F', 8, AF5)>, /* SPI5_MISO */
<STM32_PINMUX('F', 9, AF5)>, /* SPI5_MOSI */
<STM32_PINMUX('F', 7, AF5)>; /* SPI5_SCK */
bias-disable;
drive-push-pull;
slew-rate = <1>;
};
};
spi5_sleep_pins_mx: spi5_sleep_mx-0 {
pins {
pinmux = <STM32_PINMUX('F', 8, ANALOG)>, /* SPI5_MISO */
<STM32_PINMUX('F', 9, ANALOG)>, /* SPI5_MOSI */
<STM32_PINMUX('F', 7, ANALOG)>; /* SPI5_SCK */
};
};
/* USER CODE END pinctrl */
};
&spi5{
pinctrl-names = "default", "sleep";
pinctrl-0 = <&spi5_pins_mx>;
pinctrl-1 = <&spi5_sleep_pins_mx>;
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>;
};
};
Information to define a custom device tree is written in How_to_create_your_board_device_tree
3.3. tpm2 TSS components software[edit | edit source]
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 "
3.4. openssl tool[edit | edit source]
Add the openssl tool to the image, in the file .../layers/meta-st/meta-st-openstlinux/recipes-st/images/st-image-weston.bb
CORE_IMAGE_EXTRA_INSTALL += " \
.
.
.
openssl-bin \
"
3.5. 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.
Note that the Software customizations have been applied on a (DISTRO : openstlinux-weston, MACHINE : stm32mp1) OpenSTLinux distribution environment, and for a st-image-weston image.
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.
Board $>dmesg | grep tpm
[ 1.525447] tpm_tis_spi spi0.0: 2.0 TPM (device-id 0x0, rev-id 78)
Board $>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 create a key signature, and a hash (digest) of a file "msg.txt" is encrypted with this key. A verification is done with the openssl dgst command.
Primary key creation :
Board $>tpm2_createprimary -H o -g sha256 -G rsa -K hex:01020304 -A sensitivedataorigin\|userwithauth\|restricted\|decrypt -C file.txt
Signature key creation :
Board $>tpm2_create -P hex:01020304 -K hex:05060708 -g sha256 -G rsa -A sensitivedataorigin\|sign\|userwithauth -C file.txt -u sign_pub_key.bin -r sign_priv_key.bin
Loading of the created signature key in TPM :
Board $>tpm2_load -P hex:01020304 -u sign_pub_key.bin -r sign_priv_key.bin -c file.txt -n key_name.out -C sign_key.out
Hash (digest) of the file msg.txt
Board $>openssl dgst -sha256 -binary -out hash.bin msg.txt
Signature of the hash with the TPM signed key
Board $>tpm2_sign -c sign_key.out -P hex:05060708 -g sha256 -f plain -s hash.plain -m hash.bin
Read of the public part of the TPM signing key
Board $>tpm2_readpublic -c sign_key.out -f pem -o sign_pub_key.pem
Verification with openssl dgst
Board $>openssl dgst -verify sign_pub_key.pem -keyform pem -sha256 -signature hash.plain msg.txt
6. References[edit | edit source]