From 54d6ab20440bf2363e58c2d32d2d5a8bc184fb9c Mon Sep 17 00:00:00 2001 From: "harshal.patil" Date: Thu, 1 Dec 2022 17:46:18 +0530 Subject: [PATCH] docs: Added documentation for using pre-calculated signatures to generate secure boot enabled binaries. --- docs/en/security/secure-boot-v2.rst | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/en/security/secure-boot-v2.rst b/docs/en/security/secure-boot-v2.rst index ef890c9cec..d84c341a94 100644 --- a/docs/en/security/secure-boot-v2.rst +++ b/docs/en/security/secure-boot-v2.rst @@ -368,9 +368,12 @@ Remember that the strength of the Secure Boot system depends on keeping the sign Remote Signing of Images ------------------------ +Signing using espsecure.py +~~~~~~~~~~~~~~~~~~~~~~~~~~ + For production builds, it can be good practice to use a remote signing server rather than have the signing key on the build machine (which is the default esp-idf Secure Boot configuration). The espsecure.py command line program can be used to sign app images & partition table data for Secure Boot, on a remote system. -To use remote signing, disable the option "Sign binaries during build". The private signing key does not need to be present on the build system. +To use remote signing, disable the option :ref:`CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES` and build the firmware. The private signing key does not need to be present on the build system. After the app image and partition table are built, the build system will print signing steps using espsecure.py:: @@ -380,6 +383,17 @@ The above command appends the image signature to the existing binary. You can us espsecure.py sign_data --version 2 --keyfile PRIVATE_SIGNING_KEY --output SIGNED_BINARY_FILE BINARY_FILE +Signing using an external HSM +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For security reasons, you might also use an external Hardware Security Module (HSM) to store your private signing key, which cannot be accessed directly but has an interface to generate the signature of a binary file and its corresponding public key. + +In such cases, disable the option :ref:`CONFIG_SECURE_BOOT_BUILD_SIGNED_BINARIES` and build the firmware. The public key and the binary file signature generated using external HSM can be provided as inputs to the following command to generate a signed binary. :: + + espsecure.py sign_data --version 2 --pub-key PUBLIC_SIGNING_KEY --signature SIGNATURE_FILE --output SIGNED_BINARY_FILE BINARY_FILE + +The above command verifies the signature, generates a signature block (refer to :ref:`signature-block-format`) and appends it to the binary file. The signed binary is written to the filename provided to the `--output` argument. + Secure Boot Best Practices --------------------------