STPM4RasPI expansion board

1 Article purpose[edit]

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]

2.1 Hardware prerequisites[edit]

  • 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[1]
Image.PF267656.en.feature-description-include-personalized-no-cpn-medium.jpg

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]

The STM32MP1 distribution package must be installed on a host PC. The process has been validated with the delivery ecosystem release v1.1.0 Warning.png and ecosystem release v1.2.0 Warning.png 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.

TSS2 tpm.png

To check the TPM features, use the tool openssl (for the signature verification usecase).

3 Software customization to support STPM4RasPI expansion board[edit]

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]

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]

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]

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]

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]

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]

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]

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]