STPM4RasPI expansion board

1 Article purpose

The purpose of this article is to explain how to integrate the STPM4RasPI expansion board with STM32MP157C-DK2, managed by Linux^TM 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

2.1 Hardware prerequisites

• STM32MP157C-DK2

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

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

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 Linux^TM kernel. It uses the TPM2 software stack (TSS) 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

The STM32MP157C-DK2 Linux^TM 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

The Linux^TM 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:

  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:

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 Linux^TM Kernel configuration refer to Menuconfig_or_how_to_configure_kernel

3.2 Kernel device tree configuration

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

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

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

Go the article STM32MP1_Distribution_Package for the process to adapt and flash an image for any Linux^TM 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

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

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 :

tpm2_createprimary -H o -g sha256 -G rsa -K hex:01020304 -A sensitivedataorigin\|userwithauth\|restricted\|decrypt -C file.txt

Signature key creation :

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 :

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

openssl dgst -sha256 -binary -out hash.bin msg.txt

Signature of the hash with the TPM signed key

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

tpm2_readpublic -c sign_key.out -f pem -o sign_pub_key.pem

Verification with openssl dgst

openssl dgst -verify sign_pub_key.pem -keyform pem -sha256 -signature hash.plain msg.txt

Linux^® is a registered trademark of Linus Torvalds.

Cortex^®

Trusted platform module

TPM Software Stack

Serial peripheral interface

Trusted computing group

General-purpose input/output (A realization of open ended transmission between devices on an embedded level. These pins available on a processor can be programmed to be used to either accept input or provide output to external devices depending on user desires and applications requirements.)

Linux^® is a registered trademark of Linus Torvalds.

Cortex^®

Trusted platform module

TPM Software Stack

Serial peripheral interface

Trusted computing group

General-purpose input/output (A realization of open ended transmission between devices on an embedded level. These pins available on a processor can be programmed to be used to either accept input or provide output to external devices depending on user desires and applications requirements.)