How to integrate AWS IoT Greengrass on top of openSTLinux distribution

1. Article purpose

The purpose of this article is to explain how to integrate Amazon Web Service (AWS) IoT Greengrass on top of OpenSTLinux, included the security part with the connection to a Hardware Security Module (a TPMv2.0).

This article explains step by step how to add the yocto "meta-demo-aws" on top of OpenSTLinux distribution, to configure the image and to add or not the extra elements for executing the AWS greengrass certification tests.

2. Prerequisites

2.1. Hardware prerequisites

• STM32MP157C-DK2

STM32MP157C-DK2

• STPM4RasPI expansion board

2.2. Software prerequisites

The STM32MP1 Distribution Package must be installed on your host. To do this follow the procedure described in the Install the STM32MP1 OpenSTLinux distribution article.

3. Software update with meta-st-demo-aws

1.Clone following git repository into [your STM32MP1 Distribution path]/layers/meta-st/

  
  PC $>git clone ssh://${USER}@gerrit.st.com:29418/stm32mpuapp/meta/meta-st-stm32mpu-app-aws.git meta-st-demo-aws

2.Update of the meta-security layer to support the pkcs11 with tpm2

cd [your STM32MP1 Distribution path]/layers/meta-security
git checkout warrior
(commit : 4f7be0d252f68d8e8d442a7ed8c6e8a852872d28)

3.Enable TPM build

Apply the following patch in the file [your STM32MP1 Distribution path]/layers/meta-st/meta-st-openstlinux/conf/distro/include/openstlinux.inc

DISTRO_FEATURES_append = " tpm2 "

4.Setup the build environment

Executes the command, on the host :

source [your STM32MP1 Distribution path]/layers/meta-st/scripts/envsetup.sh

Select your DISTRO (ex: openstlinux-weston) and Select the demo-aws MACHINE (ex: stm32mp1-demo-aws)

5.Build the image

The image is configured by default to include elements for the execution of the AWS greengrass test. If you don't want this feature you can delete it from the image. In the file recipes-st/images/st-image-demo-aws.bb delete ${IMAGE_AWSGREENGRASSTEST_PART} in CORE_IMAGE_EXTRA_INSTALL definition.

In the folder [your STM32MP1 Distribution path]//build-openstlinuxweston-stm32mp1-demo-aws Executes the command :

bitbake st-image-demo-aws

6.Flash the sdscard

Use the programmer tool STM32CubeProgrammer

The tsv file FlashLayout_sdcard_ stm32mp157c-demo-aws-mx-trusted.tsv is located in [your STM32MP1 Distribution path]/build-openstlinuxweston-stm32mp1-demo-aws/tmp-glibc/deploy/images/stm32mp1-demo-aws/flashlayout_st-image-demo-aws

4. AWS greengrass target initialization

1.Configuration of the target

Run the scripts for some extra configuration on the target (to execute only one time after the first boot).

source /greengrass/tpm_update.sh

If the image have been configured for the execution of the AWS greengrass test.

source /greengrass/awsgreengrass_certif.sh

2.TPM token initialization

Note : keep the PINs (123456) and PKCS11 STORE folder (usr/local/pkcs11_tpm), scripts and greengrass config files examples use these values.

Note : if something goes wrong, you can reset the TPM and PKCS11 store with the following commands :

cd /usr/bin
./tpm2_clear -Q
rm -rf /usr/local/pkcs11_tpm/*

Executes the commands, on the target :

cd /tools
./tpm2_ptool.py init --pobj-pin=123456 --path=/usr/local/pkcs11_tpm
./tpm2_ptool.py addtoken --pid=1 --pobj-pin=123456 --sopin=123456 --userpin=123456 --label=greengrass --path=/usr/local/pkcs11_tpm
./tpm2_ptool.py addkey --algorithm=rsa2048 --label=greengrass --userpin=123456 --key-label=greenkey --path=/usr/local/pkcs11_tpm

OPTIONAL : Verifications with pkcs11-tool

Executes this command on the target to verify the token created.

pkcs11-tool --module /usr/lib/libtpm2_pkcs11.so.0 -L

Example of output expected :

Available slots:
   Slot 0 (0x1): greengrass STMicro
     token label        : greengrass
     token manufacturer : STMicro
     token model        :
    token flags        : login required, rng, token initialized, PIN initialized
     hardware version   : 1.38
     firmware version   : 74.8
     serial num         : 0000000000000000
     pin min/max        : 5/128

AT THIS STEP, THE CONFIGURATION OF THE BOARD IS COMPLETED TO BE USED WITH THE AWS IoT Device Tester.

5. Process to execute the AWS Greengrass certification testing

1.Install the AWS IoT Device Tester.

Go to the AWS Amazon site to [AWS IoT Device Tester for AWS IoT Greengrass Versions]

2.Configure your ssh connection (ssh keys)

Go to the AWS Amazon site to [Configure Your Host Computer to Access Your Device Under Test]

3.Configure the IDT

Example of the install config folder for Windows.

C:\devicetester_greengrass_win\devicetester_greengrass_win\configs\

Go to the AWS Amazon site [Setting Configuration to Run the AWS IoT Greengrass Qualification Suite]

There is a IDT configuration file example installed on your Host :

/[your STM32MP1 Distribution path]/layers/meta-st/meta-st-demo-aws/recipes-aws/greengrasstests/greengrasstests/device-hsm.json

Note : With this example the certification tests are performed in Root.

4.Execute the tests

Go to the AWS Amazon site to [Running Tests]

6. Process to to create a Certificat Signature Request using the hardware-protected private key

1.Install the tool openssl on the target.

The packages are stored on your Host :

/[your STM32MP1 Distribution path]/build-openstlinuxweston-stm32mp1-demo-aws/tmp-glibc/deploy/deb/cortexa7t2hf-neon-vfpv4

package openssl-bin_1.1.1a-r0_armhf.deb (usr/bin/openssl)
package openssl_1.1.1a-r0_armhf.deb (usr/lib/ssl-1.1/openssl.cnf ....; etc/ssl/certs and private folder)
package openssl-conf_1.1.1a-r0_armhf.deb (/etc/ssl/openssl.cnf)

Executes the commands, on the Host (the board is connected to your internet network) :

 scp openssl-bin_1.1.1a-r0_armhf.deb root@IP address of the board://root
 scp openssl_1.1.1a-r0_armhf.deb root@IP address of the board://root
 scp openssl-conf_1.1.1a-r0_armhf.deb root@IP address of the board://root

Executes the commands, on the target:

 cd /root
 dpkg -i openssl-bin_1.1.1a-r0_armhf.deb
 dpkg -i openssl-conf_1.1.1a-r0_armhf.deb
 dpkg -i openssl_1.1.1a-r0_armhf.deb
 sync

2.Update openssl configuration to use module tpm2_pkcs11

add the following lines in /etc/ssl/openssl.cnf :

openssl_conf = openssl_init
[openssl_init]
engines=engine_section
[engine_section]
pkcs11 = pkcs11_section
[pkcs11_section]
engine_id = pkcs11
dynamic_path = /usr/lib/engines-1.1/pkcs11.so
MODULE_PATH = /usr/lib/libtpm2_pkcs11.so.0
init = 0

3. How to create a CSR "Certificat Signature Request" with openssl (Prerequisite : openssl installed) Executes the command, on target :

openssl req -engine pkcs11 -new -key "pkcs11:token=greengrass;object=greenkey;type=private;pin-value=123456" -keyform engine -out /usr/local/req.csr

This CSR "/usr/local/req.csr" is used to create clients certificats on the AWS amazon Cloud to store on the board.

There is a greengrass configuration file example to update with your AWS account parameter and certificats created, on the target : /greengrass/config/config_secu_example.json

You need also to download the root CA on Amazon site and stored it on the target greengrass/certs/root.ca.pem.

For more information about HSM (Hardware Secure Module) integration for AWS greengrass, go to AWS Amazon site [Hardware Security Integration]

4.Connection to Amazon cloud

Before starting the greengrass core on the target you need to set the TPM2_PKCS11_STORE environment variable.

Executes the commands on the target :

export TPM2_PKCS11_STORE=/usr/local/pkcs11_tpm
cd /greengrass/ggc/core/
./greengrassd start

Internet of Things

Trusted Platform Module

Flash memory shortened to gain space in titles, tables and block diagrams

Hardware security module