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

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.)

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.)