Portenta H7 Lite
Secure Boot on Portenta H7

Secure Boot on Portenta H7

Learn how to use secure boot on the Arduino Portenta H7.
AUTHOR: Umberto Baldi

Introduction

This short tutorial will guide the user through enabling the secure boot on the Portenta H7, generating custom security keys, and using them with the MCUboot bootloader.

Secure boot is the process where a compiled sketch is authenticated against the hardware before it is authorized to be used in the boot process. The hardware is pre-configured to authenticate code using trusted security credentials.

In other words, secure boot ensures that the boot technology and operating system software are the legitimate manufacturer version and have not been altered or tampered with by any malicious actor or process.

Hardware & Software Required

Instructions

Flashing the Latest Bootloader

In order to have secure boot enabled, you must update the bootloader on your Portenta H7 and use MCUboot. You can find more info on how to perform the update in this other tutorial.

Use Default Security Keys

Once the bootloader has been updated to MCUboot, it is possible to use secure boot to have an additional layer of security. From that point on, it is required to upload a compiled sketch with the Custom Board Option "Security settings" set to "Signature + Encryption" (the option can be found under Tools > Security settings in the IDE when selecting Portenta H7 as board or you can use 

--board-options security=sien
if using the Arduino CLI). Failing to provide such option will cause the bootloader not to run the compiled sketch because it is not trusted.

If the security keys are not overridden, the default ones are used. Two keys are embedded in the example sketch 

STM32H747_manageBootloader
, which can be found in Files > Examples > STM32H747_System > STM32H747_manageBootloader and used by the bootloader. A private 256bit ECDSA key is used to extract the encryption key and decrypt the binary update (
ecdsa-p256-encrypt-priv-key.h
), while a public key is used for image verification (
ecdsa-p256-signing-pub-key.h
).

As counterpart, when building the image update, imgtool uses this private key to sign the image and this public key for image encryption with elliptic curve integrated encryption scheme.

1. Generate Custom Security Keys

The default keys provided with the mbed platform are obviously only intended for development purposes. In a production environment it is strongly recommended to generate a new key pair (public and private key). This can be done with imgtool. You can download and install it directly from the release section.

imgtool
is already installed by the mbed platform and can be found in the 
%LOCALAPPDATA%\Arduino15\packages\arduino\tools\imgtool
directory on Windows, in 
~/.arduino15/packages/arduino/tools/imgtool
on Linux and in 
~/Library/Arduino15/packages/arduino/tools/imgtool
on macOS.

To generate the new keys you can use this command line:

1imgtool keygen --key my-sign-keyfile.pem -t ecdsa-p256
2imgtool keygen --key my-encrypt-keyfile.pem -t ecdsa-p256

This command line will generate two private PEM encoded security keys and save them in the current directory with 

my-sign-keyfile.pem
and 
my-encrypt-keyfile.pem
names. The algorithm used to generate the keys is ECDSA 256bit.

Remember to save the keys and keep them in a secure location and not to lose them.

2. Upload the Custom Keys to the Board

Once the keys have been generated, they have to be uploaded to the Portenta H7. This procedure has to be done only once, because it is persistent. To extract the public\private key and encode it in to a "C" byte array inside a 

.h
header file you can use:

1imgtool getpriv -k my-encrypt-keyfile.pem > ecsda-p256-encrypt-priv-key.h 
2imgtool getpub -k my-sign-keyfile.pem > ecsda-p256-signing-pub-key.h

Now you have to replace the keys inside the Sketch to update the bootloader(STM32H747_manageBootloader). To do so, just save the sketch to another location and replace the 

ecsda-p256-encrypt-priv-key.h
and 
ecsda-p256-signing-pub-key.h
files with the newly generated ones and then update the bootloader again.

NOTE: In case the keys are compromised, this process can be performed again with a new set of keys, but any firmware signed with the previous pair will no longer work.

3. Use the Custom Keys when Compiling

Since the default keys have been changed in favour of custom generated ones, the new ones have to be used when compiling and uploading a sketch, because the compiled sketch is signed and encrypted using such keys.

To override the security keys used during the compile, you have to use the Arduino CLI and specify the keys with:

1arduino-cli compile -b arduino:mbed_portenta:envie_m7 --board-options security=sien --keys-keychain <path-to-your-keys> --sign-key ecdsa-p256-signing-priv-key.pem --encrypt-key ecdsa-p256-encrypt-pub-key.pem /home/user/Arduino/MySketch

Learn More

If you want to implement secure boot for your platform, have a look at [this article] (https://arduino.github.io/arduino-cli/latest/guides/secure-boot/).

Tutorial Toolbox

Portenta H7

Contribute to Arduino

Join the community and suggest improvements to this article via GitHub. Make sure to read out contribution policy before making your pull request.
CONTRIBUTE

Missing something?

Check out our store and get what you need to follow this tutorial.
VISIT OUR STORE

Suggest Changes

The content on docs.arduino.cc is facilitated through a public GitHub repository. You can read more on how to contribute in the contribution policy.
EDIT THIS PAGE