From 507b700a9e9f2c7021e6aeccdbd4d5cdcd6afdca Mon Sep 17 00:00:00 2001 From: umbynos Date: Wed, 30 Mar 2022 18:22:10 +0200 Subject: [PATCH 01/14] add secure boot for portenta h7 --- .../tutorials/secure-boot/secure-boot.md | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md diff --git a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md new file mode 100644 index 0000000000..306c1d8493 --- /dev/null +++ b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md @@ -0,0 +1,70 @@ +--- +title: 'Secure Boot' +description: 'Learn how to use secure boot on the Arduino Portenta H7.' +tags: + - Secure Boot +author: 'Umberto Baldi' +hardware: + - hardware/04.pro/boards/portenta-h7 + +software: + - ide-v1 + - ide-v2 + - cli +--- + +## Introduction +This short tutorial will teach how to enable the secure boot on the Portenta H7, how to generate custom security keys, and how you can use them with MCUBoot bootloader. + +## Hardware & Software Required +- [Portenta H7](https://store.arduino.cc/portenta-h7) or [Portenta H7 Lite](https://store.arduino.cc/products/portenta-h7-lite) or [Portenta H7 Lite Connected](https://store.arduino.cc/products/portenta-h7-lite-connected) +- Arduino IDE 1.8.19+ or Arduino IDE 2.0.0-rc5+ (https://www.arduino.cc/en/software) +- [Arduino Mbed OS Portenta Boards](https://github.com/arduino/ArduinoCore-mbed) version 3.0.0+ +- [imgtool](https://github.com/arduino/imgtool-packing/releases/latest) (optional) + +## Instructions + +### Flashing the Latest Bootloader +In order to have secureboot enabled you have to update the bootloader and use [MCUBoot](https://www.mcuboot.com/). You can find more info on how to perform the update in [this other tutorial](../por-ard-bl/content.md). + +### Use Default Security Keys +Once The bootloader has been updated to MCUBoot, it's possible to use [secure boot](https://www.keyfactor.com/blog/what-is-secure-boot-its-where-iot-security-starts/) to have an addition layer of security. From now on it's 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). Otherwise the board will not start the compiled sketch because is not trusted. + +If no operation is performed the default security keys are used. +They are embedded in the example sketch `STM32H747_updateBootloader` that can be found in **Files > Examples > STM32H747_System > STM32H747_updateBootloader**. A private 256bit [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) key is used for the encryption (`ecdsa-p256-encrypt-key.h`), while a public key is used for the signing (`ecdsa-p256-signing-key.h`). These two keys are the ones the bootloader uses to verify if a sketch is valid or not, before starting it. The default private keys used after compiling a sketch to sign and encrypt it, are located in `Arduino15/packages/arduino/hardware/mbed_portenta//libraries/MCUboot/default_keys/`. + +### 1. Generate Custom Cecurity Keys +The default keys that comes with the mbed platform are obviously only intended for development purposes. In a production environment it's suggested to generate a new key pair (public and private key). +This can be done with [**imgtool**](https://github.com/arduino/imgtool-packing/releases/latest). You can download and install it directly from the release section. + +***Pro tip: imgtool is already installed by the mbed platform and can be found in the `Arduino15/packages/arduino/tools/imgtool` directory.*** + +To generate the new keys you can use this command line: +``` +imgtool keygen --key my-sign-keyfile.pem -t ecdsa-p256 +imgtool 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 in a secure place** and don't loose them. + +### 2. Upload the Custom Keys to the Board +Once the keys have been generated they have to be uploaded on the Portenta. This procedure has to be done only once, because it's persistent. To extract the public\private key and encode it in to a "C" byte array inside a `.h` header file you can use: +``` +imgtool getpriv -k my-encrypt-keyfile.pem > ecsda-p256-encrypt-key.h +imgtool getpub -k my-sign-keyfile.pem > ecsda-p256-signing-key.h +``` + +Now you have to replace the keys in the sketch to update the bootloader(**STM32H747_updateBootloader**). +To do so just save the sketch to another location and replace the `ecsda-p256-encrypt-key.h` and `ecsda-p256-signing-key.h` files with the newly generated ones and then [update the bootloader](../por-ard-bl/content.md) again. + +### 3. Use the Custom Keys when Compiling +Since the default keys have been changed in favour of newly generated custom ones, The new ones have to be used when compiling and uploading a sketch, because the compiled sketch is signed and encrypted with them. + +To override the security keys used during the compile you have to use the Arduino CLI and specify the keys with: +``` +arduino-cli compile -b arduino:mbed_portenta:envie_m7 --board-options security=sien --keys-keychain --sign-key ecsdsa-p256-signing-key.pem --encrypt-key ecsdsa-p256-encrypt-key.pem /home/user/Arduino/MySketch +``` + +## Learn More +If you want to implement secure boot for your platform [this](https://arduino.github.io/arduino-cli/latest/guides/secure-boot/) should be helpful . From 2a220eb537593b92caa36a31c2fc8b1b0778eac8 Mon Sep 17 00:00:00 2001 From: umbynos Date: Thu, 31 Mar 2022 11:19:11 +0200 Subject: [PATCH 02/14] other portent boards are not yet supported --- .../boards/portenta-h7/tutorials/secure-boot/secure-boot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md index 306c1d8493..83bc777278 100644 --- a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md +++ b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md @@ -17,7 +17,7 @@ software: This short tutorial will teach how to enable the secure boot on the Portenta H7, how to generate custom security keys, and how you can use them with MCUBoot bootloader. ## Hardware & Software Required -- [Portenta H7](https://store.arduino.cc/portenta-h7) or [Portenta H7 Lite](https://store.arduino.cc/products/portenta-h7-lite) or [Portenta H7 Lite Connected](https://store.arduino.cc/products/portenta-h7-lite-connected) +- [Portenta H7](https://store.arduino.cc/portenta-h7) - Arduino IDE 1.8.19+ or Arduino IDE 2.0.0-rc5+ (https://www.arduino.cc/en/software) - [Arduino Mbed OS Portenta Boards](https://github.com/arduino/ArduinoCore-mbed) version 3.0.0+ - [imgtool](https://github.com/arduino/imgtool-packing/releases/latest) (optional) From 0c81eb4f48d838692bca900b36ed6c6431091e2d Mon Sep 17 00:00:00 2001 From: Umberto Baldi <34278123+umbynos@users.noreply.github.com> Date: Thu, 31 Mar 2022 17:33:07 +0200 Subject: [PATCH 03/14] Apply suggestions from code review Co-authored-by: Ubi de Feo --- .../tutorials/secure-boot/secure-boot.md | 24 ++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md index 83bc777278..9aefce6d59 100644 --- a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md +++ b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md @@ -1,5 +1,5 @@ --- -title: 'Secure Boot' +title: 'Secure Boot on Portenta H7' description: 'Learn how to use secure boot on the Arduino Portenta H7.' tags: - Secure Boot @@ -14,7 +14,7 @@ software: --- ## Introduction -This short tutorial will teach how to enable the secure boot on the Portenta H7, how to generate custom security keys, and how you can use them with MCUBoot bootloader. +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. ## Hardware & Software Required - [Portenta H7](https://store.arduino.cc/portenta-h7) @@ -25,16 +25,16 @@ This short tutorial will teach how to enable the secure boot on the Portenta H7, ## Instructions ### Flashing the Latest Bootloader -In order to have secureboot enabled you have to update the bootloader and use [MCUBoot](https://www.mcuboot.com/). You can find more info on how to perform the update in [this other tutorial](../por-ard-bl/content.md). +In order to have secure boot enabled you must update the bootloader on your Portenta H7 and use [MCUboot](https://www.mcuboot.com/). You can find more info on how to perform the update in [this other tutorial](../por-ard-bl/content.md). ### Use Default Security Keys -Once The bootloader has been updated to MCUBoot, it's possible to use [secure boot](https://www.keyfactor.com/blog/what-is-secure-boot-its-where-iot-security-starts/) to have an addition layer of security. From now on it's 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). Otherwise the board will not start the compiled sketch because is not trusted. +Once The bootloader has been updated to MCUboot, it's possible to use [secure boot](https://www.keyfactor.com/blog/what-is-secure-boot-its-where-iot-security-starts/) 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 no operation is performed the default security keys are used. -They are embedded in the example sketch `STM32H747_updateBootloader` that can be found in **Files > Examples > STM32H747_System > STM32H747_updateBootloader**. A private 256bit [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) key is used for the encryption (`ecdsa-p256-encrypt-key.h`), while a public key is used for the signing (`ecdsa-p256-signing-key.h`). These two keys are the ones the bootloader uses to verify if a sketch is valid or not, before starting it. The default private keys used after compiling a sketch to sign and encrypt it, are located in `Arduino15/packages/arduino/hardware/mbed_portenta//libraries/MCUboot/default_keys/`. +These keys are embedded in the example sketch `STM32H747_updateBootloader` which can be found in **Files > Examples > STM32H747_System > STM32H747_updateBootloader**. A private 256bit [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) key is used for the encryption (`ecdsa-p256-encrypt-key.h`), while a public key is used for the signing (`ecdsa-p256-signing-key.h`). These two keys are the ones the bootloader uses to verify if a sketch is valid or not, before starting it for the first time. The default private keys used after compiling a sketch to sign and encrypt it are located in `Arduino15/packages/arduino/hardware/mbed_portenta//libraries/MCUboot/default_keys/`. ### 1. Generate Custom Cecurity Keys -The default keys that comes with the mbed platform are obviously only intended for development purposes. In a production environment it's suggested to generate a new key pair (public and private key). +The default keys provided with the mbed platform are obviously only intended for development purposes. In a production environment it is advised to generate a new key pair (public and private key). This can be done with [**imgtool**](https://github.com/arduino/imgtool-packing/releases/latest). You can download and install it directly from the release section. ***Pro tip: imgtool is already installed by the mbed platform and can be found in the `Arduino15/packages/arduino/tools/imgtool` directory.*** @@ -46,7 +46,7 @@ imgtool 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 in a secure place** and don't loose them. +Remember to **save the keys to 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 on the Portenta. This procedure has to be done only once, because it's persistent. To extract the public\private key and encode it in to a "C" byte array inside a `.h` header file you can use: @@ -55,11 +55,13 @@ imgtool getpriv -k my-encrypt-keyfile.pem > ecsda-p256-encrypt-key.h imgtool getpub -k my-sign-keyfile.pem > ecsda-p256-signing-key.h ``` -Now you have to replace the keys in the sketch to update the bootloader(**STM32H747_updateBootloader**). +Now you have to replace the keys inside the Sketch to update the bootloader(**STM32H747_updateBootloader**). To do so just save the sketch to another location and replace the `ecsda-p256-encrypt-key.h` and `ecsda-p256-signing-key.h` files with the newly generated ones and then [update the bootloader](../por-ard-bl/content.md) again. -### 3. Use the Custom Keys when Compiling -Since the default keys have been changed in favour of newly generated custom ones, The new ones have to be used when compiling and uploading a sketch, because the compiled sketch is signed and encrypted with them. +***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: ``` @@ -67,4 +69,4 @@ arduino-cli compile -b arduino:mbed_portenta:envie_m7 --board-options security=s ``` ## Learn More -If you want to implement secure boot for your platform [this](https://arduino.github.io/arduino-cli/latest/guides/secure-boot/) should be helpful . +If you want to implement secure boot for your platform [this](https://arduino.github.io/arduino-cli/latest/guides/secure-boot/) should be helpful. From aa7fbee90afb3f6fcac0150cdec332c3f2126dea Mon Sep 17 00:00:00 2001 From: Umberto Baldi Date: Thu, 31 Mar 2022 18:05:02 +0200 Subject: [PATCH 04/14] Better explain where to find imgtool on different OS --- .../boards/portenta-h7/tutorials/secure-boot/secure-boot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md index 9aefce6d59..4d73ae7fd5 100644 --- a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md +++ b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md @@ -37,7 +37,7 @@ These keys are embedded in the example sketch `STM32H747_updateBootloader` which The default keys provided with the mbed platform are obviously only intended for development purposes. In a production environment it is advised to generate a new key pair (public and private key). This can be done with [**imgtool**](https://github.com/arduino/imgtool-packing/releases/latest). You can download and install it directly from the release section. -***Pro tip: imgtool is already installed by the mbed platform and can be found in the `Arduino15/packages/arduino/tools/imgtool` directory.*** +***Pro tip: 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: ``` From efcc9a5024e4f6f27efa9523ea8feea37173e08d Mon Sep 17 00:00:00 2001 From: Umberto Baldi Date: Mon, 4 Apr 2022 15:15:55 +0200 Subject: [PATCH 05/14] Apply suggestions from code review --- .../boards/portenta-h7/tutorials/secure-boot/secure-boot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md index 4d73ae7fd5..0e25131a98 100644 --- a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md +++ b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md @@ -34,7 +34,7 @@ If no operation is performed the default security keys are used. These keys are embedded in the example sketch `STM32H747_updateBootloader` which can be found in **Files > Examples > STM32H747_System > STM32H747_updateBootloader**. A private 256bit [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) key is used for the encryption (`ecdsa-p256-encrypt-key.h`), while a public key is used for the signing (`ecdsa-p256-signing-key.h`). These two keys are the ones the bootloader uses to verify if a sketch is valid or not, before starting it for the first time. The default private keys used after compiling a sketch to sign and encrypt it are located in `Arduino15/packages/arduino/hardware/mbed_portenta//libraries/MCUboot/default_keys/`. ### 1. Generate Custom Cecurity Keys -The default keys provided with the mbed platform are obviously only intended for development purposes. In a production environment it is advised to generate a new key pair (public and private key). +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**](https://github.com/arduino/imgtool-packing/releases/latest). You can download and install it directly from the release section. ***Pro tip: 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.*** From c0da15de18d81d86422a9123d305995e35c556fd Mon Sep 17 00:00:00 2001 From: Umberto Baldi <34278123+umbynos@users.noreply.github.com> Date: Tue, 5 Apr 2022 17:15:55 +0200 Subject: [PATCH 06/14] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pablo Marquínez Ferrándiz --- .../portenta-h7/tutorials/secure-boot/secure-boot.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md index 0e25131a98..87a8e4dc52 100644 --- a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md +++ b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md @@ -12,7 +12,6 @@ software: - ide-v2 - cli --- - ## 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. @@ -25,7 +24,7 @@ This short tutorial will guide the user through enabling the secure boot on the ## Instructions ### Flashing the Latest Bootloader -In order to have secure boot enabled you must update the bootloader on your Portenta H7 and use [MCUboot](https://www.mcuboot.com/). You can find more info on how to perform the update in [this other tutorial](../por-ard-bl/content.md). +In order to have secure boot enabled you must update the bootloader on your Portenta H7 and use [MCUboot](https://www.mcuboot.com/). You can find more info on how to perform the update in [this other tutorial](https://docs.arduino.cc/tutorials/portenta-h7/updating-the-bootloader). ### Use Default Security Keys Once The bootloader has been updated to MCUboot, it's possible to use [secure boot](https://www.keyfactor.com/blog/what-is-secure-boot-its-where-iot-security-starts/) 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. @@ -37,16 +36,16 @@ These keys are embedded in the example sketch `STM32H747_updateBootloader` which 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**](https://github.com/arduino/imgtool-packing/releases/latest). You can download and install it directly from the release section. -***Pro tip: 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.*** +***`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: ``` imgtool keygen --key my-sign-keyfile.pem -t ecdsa-p256 imgtool 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. +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 to a secure location** and not to lose them. +Remember to **save the keys on 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 on the Portenta. This procedure has to be done only once, because it's persistent. To extract the public\private key and encode it in to a "C" byte array inside a `.h` header file you can use: @@ -56,7 +55,7 @@ imgtool getpub -k my-sign-keyfile.pem > ecsda-p256-signing-key.h ``` Now you have to replace the keys inside the Sketch to update the bootloader(**STM32H747_updateBootloader**). -To do so just save the sketch to another location and replace the `ecsda-p256-encrypt-key.h` and `ecsda-p256-signing-key.h` files with the newly generated ones and then [update the bootloader](../por-ard-bl/content.md) again. +To do so just save the sketch to another location and replace the `ecsda-p256-encrypt-key.h` and `ecsda-p256-signing-key.h` files with the newly generated ones and then [update the bootloader](https://docs.arduino.cc/tutorials/portenta-h7/updating-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.*** From 49c15cf0192b94200485b1ae6c7c0187fbf461bd Mon Sep 17 00:00:00 2001 From: marqdevx Date: Wed, 6 Apr 2022 11:42:36 +0200 Subject: [PATCH 07/14] Add symlinks on the compatible boards --- .../boards/portenta-h7-lite-connected/tutorials/secureboot | 1 + .../hardware/04.pro/boards/portenta-h7-lite/tutorials/secureboot | 1 + 2 files changed, 2 insertions(+) create mode 120000 content/hardware/04.pro/boards/portenta-h7-lite-connected/tutorials/secureboot create mode 120000 content/hardware/04.pro/boards/portenta-h7-lite/tutorials/secureboot diff --git a/content/hardware/04.pro/boards/portenta-h7-lite-connected/tutorials/secureboot b/content/hardware/04.pro/boards/portenta-h7-lite-connected/tutorials/secureboot new file mode 120000 index 0000000000..9c40f4114a --- /dev/null +++ b/content/hardware/04.pro/boards/portenta-h7-lite-connected/tutorials/secureboot @@ -0,0 +1 @@ +../../portenta-h7/tutorials/secure-boot \ No newline at end of file diff --git a/content/hardware/04.pro/boards/portenta-h7-lite/tutorials/secureboot b/content/hardware/04.pro/boards/portenta-h7-lite/tutorials/secureboot new file mode 120000 index 0000000000..9c40f4114a --- /dev/null +++ b/content/hardware/04.pro/boards/portenta-h7-lite/tutorials/secureboot @@ -0,0 +1 @@ +../../portenta-h7/tutorials/secure-boot \ No newline at end of file From af3d86d91084d834861625b61769bd4fffb64918 Mon Sep 17 00:00:00 2001 From: Umberto Baldi <34278123+umbynos@users.noreply.github.com> Date: Mon, 11 Apr 2022 15:37:14 +0200 Subject: [PATCH 08/14] Apply suggestions from code review Co-authored-by: Sebastian Romero --- .../portenta-h7/tutorials/secure-boot/secure-boot.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md index 87a8e4dc52..8877bc7c51 100644 --- a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md +++ b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md @@ -18,7 +18,7 @@ This short tutorial will guide the user through enabling the secure boot on the ## Hardware & Software Required - [Portenta H7](https://store.arduino.cc/portenta-h7) - Arduino IDE 1.8.19+ or Arduino IDE 2.0.0-rc5+ (https://www.arduino.cc/en/software) -- [Arduino Mbed OS Portenta Boards](https://github.com/arduino/ArduinoCore-mbed) version 3.0.0+ +- [Arduino Core for mbed enabled devices](https://github.com/arduino/ArduinoCore-mbed) version 3.0.0+ - [imgtool](https://github.com/arduino/imgtool-packing/releases/latest) (optional) ## Instructions @@ -32,9 +32,9 @@ Once The bootloader has been updated to MCUboot, it's possible to use [secure bo If no operation is performed the default security keys are used. These keys are embedded in the example sketch `STM32H747_updateBootloader` which can be found in **Files > Examples > STM32H747_System > STM32H747_updateBootloader**. A private 256bit [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) key is used for the encryption (`ecdsa-p256-encrypt-key.h`), while a public key is used for the signing (`ecdsa-p256-signing-key.h`). These two keys are the ones the bootloader uses to verify if a sketch is valid or not, before starting it for the first time. The default private keys used after compiling a sketch to sign and encrypt it are located in `Arduino15/packages/arduino/hardware/mbed_portenta//libraries/MCUboot/default_keys/`. -### 1. Generate Custom Cecurity Keys +### 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**](https://github.com/arduino/imgtool-packing/releases/latest). You can download and install it directly from the release section. +This can be done with **imgtool**. You can download and install it directly from the [release section](https://github.com/arduino/imgtool-packing/releases/latest). ***`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.*** @@ -45,10 +45,10 @@ imgtool 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 on a secure location** and not to lose them. +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 on the Portenta. This procedure has to be done only once, because it's persistent. To extract the public\private key and encode it in to a "C" byte array inside a `.h` header file you can use: +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's persistent. To extract the public\private key and encode it in to a "C" byte array inside a `.h` header file you can use: ``` imgtool getpriv -k my-encrypt-keyfile.pem > ecsda-p256-encrypt-key.h imgtool getpub -k my-sign-keyfile.pem > ecsda-p256-signing-key.h @@ -68,4 +68,4 @@ arduino-cli compile -b arduino:mbed_portenta:envie_m7 --board-options security=s ``` ## Learn More -If you want to implement secure boot for your platform [this](https://arduino.github.io/arduino-cli/latest/guides/secure-boot/) should be helpful. +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/). From 589863c3ad856d8f4772f965db1f8a3f94d5e2c8 Mon Sep 17 00:00:00 2001 From: Umberto Baldi Date: Wed, 13 Apr 2022 15:24:36 +0200 Subject: [PATCH 09/14] Apply suggestions from code review --- .../boards/portenta-h7/tutorials/secure-boot/secure-boot.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md index 8877bc7c51..1b645904d6 100644 --- a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md +++ b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md @@ -30,7 +30,10 @@ In order to have secure boot enabled you must update the bootloader on your Port Once The bootloader has been updated to MCUboot, it's possible to use [secure boot](https://www.keyfactor.com/blog/what-is-secure-boot-its-where-iot-security-starts/) 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 no operation is performed the default security keys are used. -These keys are embedded in the example sketch `STM32H747_updateBootloader` which can be found in **Files > Examples > STM32H747_System > STM32H747_updateBootloader**. A private 256bit [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) key is used for the encryption (`ecdsa-p256-encrypt-key.h`), while a public key is used for the signing (`ecdsa-p256-signing-key.h`). These two keys are the ones the bootloader uses to verify if a sketch is valid or not, before starting it for the first time. The default private keys used after compiling a sketch to sign and encrypt it are located in `Arduino15/packages/arduino/hardware/mbed_portenta//libraries/MCUboot/default_keys/`. +Two keys are embedded in the example sketch `STM32H747_updateBootloader` which can be found in **Files > Examples > STM32H747_System > STM32H747_updateBootloader** and used by the bootloader. +A private 256bit [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) key is used to extract the encryption key and decrypt the binary update (`ecdsa-p256-encrypt-key.h`), while a public key is used for image verification (`ecdsa-p256-signing-key.h`). + +As counterpart, when building the image update, imgtool uses this private [key](https://github.com/arduino/ArduinoCore-mbed/pull/447/files#diff-f43e4850d60c61854678f6f80c6ddc4b59e3e68ca7e71b02e5ed15288c9aadb4) to sign the image and this public [key](https://github.com/arduino/ArduinoCore-mbed/pull/447/files#diff-95bb7b27de14276896a2bec099dc5a498d5332616458c04263efc8d24810e6a6) 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). From d21590ec2f0746a48b6cea3bfe3388579712e00d Mon Sep 17 00:00:00 2001 From: Umberto Baldi Date: Wed, 13 Apr 2022 15:46:28 +0200 Subject: [PATCH 10/14] add a paragraph in the Intro explaining what secure boot is --- .../boards/portenta-h7/tutorials/secure-boot/secure-boot.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md index 1b645904d6..cb7ed3c81e 100644 --- a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md +++ b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md @@ -15,6 +15,10 @@ software: ## 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 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 - [Portenta H7](https://store.arduino.cc/portenta-h7) - Arduino IDE 1.8.19+ or Arduino IDE 2.0.0-rc5+ (https://www.arduino.cc/en/software) From 567a4b43361523f1cbc709dd6087a7b920d9f5f1 Mon Sep 17 00:00:00 2001 From: Umberto Baldi Date: Tue, 26 Apr 2022 10:59:10 +0200 Subject: [PATCH 11/14] followup of https://github.com/arduino/arduino-cli/pull/1716 --- .../portenta-h7/tutorials/secure-boot/secure-boot.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md index cb7ed3c81e..92c44d1671 100644 --- a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md +++ b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md @@ -35,7 +35,7 @@ Once The bootloader has been updated to MCUboot, it's possible to use [secure bo If no operation is performed the default security keys are used. Two keys are embedded in the example sketch `STM32H747_updateBootloader` which can be found in **Files > Examples > STM32H747_System > STM32H747_updateBootloader** and used by the bootloader. -A private 256bit [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) key is used to extract the encryption key and decrypt the binary update (`ecdsa-p256-encrypt-key.h`), while a public key is used for image verification (`ecdsa-p256-signing-key.h`). +A private 256bit [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) key is used to extract the encryption key and decrypt the binary update (`ecdsa-p256-encrypt-pub-key.h`), while a public key is used for image verification (`ecdsa-p256-signing-priv-key.h`). As counterpart, when building the image update, imgtool uses this private [key](https://github.com/arduino/ArduinoCore-mbed/pull/447/files#diff-f43e4850d60c61854678f6f80c6ddc4b59e3e68ca7e71b02e5ed15288c9aadb4) to sign the image and this public [key](https://github.com/arduino/ArduinoCore-mbed/pull/447/files#diff-95bb7b27de14276896a2bec099dc5a498d5332616458c04263efc8d24810e6a6) for image encryption with elliptic curve integrated encryption scheme. @@ -57,12 +57,12 @@ Remember to **save the keys and keep them in a secure location** and not to lose ### 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's persistent. To extract the public\private key and encode it in to a "C" byte array inside a `.h` header file you can use: ``` -imgtool getpriv -k my-encrypt-keyfile.pem > ecsda-p256-encrypt-key.h -imgtool getpub -k my-sign-keyfile.pem > ecsda-p256-signing-key.h +imgtool getpriv -k my-encrypt-keyfile.pem > ecsda-p256-encrypt-priv-key.h +imgtool 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_updateBootloader**). -To do so just save the sketch to another location and replace the `ecsda-p256-encrypt-key.h` and `ecsda-p256-signing-key.h` files with the newly generated ones and then [update the bootloader](https://docs.arduino.cc/tutorials/portenta-h7/updating-the-bootloader) again. +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](https://docs.arduino.cc/tutorials/portenta-h7/updating-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.*** @@ -71,7 +71,7 @@ Since the default keys have been changed in favour of custom generated ones, the To override the security keys used during the compile you have to use the Arduino CLI and specify the keys with: ``` -arduino-cli compile -b arduino:mbed_portenta:envie_m7 --board-options security=sien --keys-keychain --sign-key ecsdsa-p256-signing-key.pem --encrypt-key ecsdsa-p256-encrypt-key.pem /home/user/Arduino/MySketch +arduino-cli compile -b arduino:mbed_portenta:envie_m7 --board-options security=sien --keys-keychain --sign-key ecdsa-p256-signing-priv-key.pem --encrypt-key ecdsa-p256-encrypt-pub-key.pem /home/user/Arduino/MySketch ``` ## Learn More From 559cb899a393aa557eac81131f31f958fedac82e Mon Sep 17 00:00:00 2001 From: Sebastian Romero Date: Tue, 3 May 2022 14:45:14 +0200 Subject: [PATCH 12/14] Swap keys Co-authored-by: Mattia Pennasilico --- .../boards/portenta-h7/tutorials/secure-boot/secure-boot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md index 92c44d1671..1fd8549438 100644 --- a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md +++ b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md @@ -35,7 +35,7 @@ Once The bootloader has been updated to MCUboot, it's possible to use [secure bo If no operation is performed the default security keys are used. Two keys are embedded in the example sketch `STM32H747_updateBootloader` which can be found in **Files > Examples > STM32H747_System > STM32H747_updateBootloader** and used by the bootloader. -A private 256bit [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) key is used to extract the encryption key and decrypt the binary update (`ecdsa-p256-encrypt-pub-key.h`), while a public key is used for image verification (`ecdsa-p256-signing-priv-key.h`). +A private 256bit [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) 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](https://github.com/arduino/ArduinoCore-mbed/pull/447/files#diff-f43e4850d60c61854678f6f80c6ddc4b59e3e68ca7e71b02e5ed15288c9aadb4) to sign the image and this public [key](https://github.com/arduino/ArduinoCore-mbed/pull/447/files#diff-95bb7b27de14276896a2bec099dc5a498d5332616458c04263efc8d24810e6a6) for image encryption with elliptic curve integrated encryption scheme. From 4bb3917415e79f5a78dca836d8a19e1113481d92 Mon Sep 17 00:00:00 2001 From: Sebastian Romero Date: Tue, 3 May 2022 14:49:08 +0200 Subject: [PATCH 13/14] Rephrase security keys statement --- .../boards/portenta-h7/tutorials/secure-boot/secure-boot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md index 1fd8549438..f1347878b5 100644 --- a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md +++ b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md @@ -33,7 +33,7 @@ In order to have secure boot enabled you must update the bootloader on your Port ### Use Default Security Keys Once The bootloader has been updated to MCUboot, it's possible to use [secure boot](https://www.keyfactor.com/blog/what-is-secure-boot-its-where-iot-security-starts/) 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 no operation is performed the default security keys are used. +If the security keys are not overridden, the default ones are used." Two keys are embedded in the example sketch `STM32H747_updateBootloader` which can be found in **Files > Examples > STM32H747_System > STM32H747_updateBootloader** and used by the bootloader. A private 256bit [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) 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`). From 7db071b52d0508d996f01278f2d570d23baa1649 Mon Sep 17 00:00:00 2001 From: Sebastian Romero Date: Tue, 3 May 2022 14:49:42 +0200 Subject: [PATCH 14/14] Fix typo --- .../boards/portenta-h7/tutorials/secure-boot/secure-boot.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md index f1347878b5..adf3b0529d 100644 --- a/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md +++ b/content/hardware/04.pro/boards/portenta-h7/tutorials/secure-boot/secure-boot.md @@ -33,7 +33,7 @@ In order to have secure boot enabled you must update the bootloader on your Port ### Use Default Security Keys Once The bootloader has been updated to MCUboot, it's possible to use [secure boot](https://www.keyfactor.com/blog/what-is-secure-boot-its-where-iot-security-starts/) 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." +If the security keys are not overridden, the default ones are used. Two keys are embedded in the example sketch `STM32H747_updateBootloader` which can be found in **Files > Examples > STM32H747_System > STM32H747_updateBootloader** and used by the bootloader. A private 256bit [ECDSA](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) 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`).