feat: Add image signing instrctuons, docs and scripts

Co-authored-by: MarkoSagadin <marko.sagadin42@gmail.com>

Author: TjazVracko

.github/workflows/build.yaml

@@ -15,6 +15,7 @@ on:
 
 env:
   GIT_CREDENTIALS: ${{ secrets.GIT_CREDENTIALS }}
+  IMAGE_SIGN_KEY: ${{ secrets.IMAGE_SIGN_KEY}}
 
 jobs:
   build:

.github/workflows/codechecker.yaml

@@ -20,6 +20,7 @@ env:
   CODECHECKER_CREDENTIALS: ${{ secrets.CODECHECKER_CREDENTIALS }}
   EAST_CODECHECKER_SERVER_URL: ${{ secrets.CODECHECKER_SERVER_URL }}
   GIT_CREDENTIALS: ${{ secrets.GIT_CREDENTIALS }}
+  IMAGE_SIGN_KEY: ${{ secrets.IMAGE_SIGN_KEY}}
 
 jobs:
   codechecker:

.gitignore

@@ -60,3 +60,6 @@ codechecker-diffs/*
 
 # version files
 VERSION
+
+# private keys
+*.pem

README.md

@@ -29,6 +29,8 @@ The project's documentation can be found in the [doc/](./doc/README.md) folder.
 - [ ] Provide repository setup instructions, use the template in the
       [Setup document](./doc/development/setup.md). Replace `<repo-name>` and `<board_name>` as
       appropriate for your project.
+- [ ] Create signing keys for MCUboot and set them up for the project. See the
+      [Signing Keys document](./doc/development/signing_keys.md) for more information.
 
 ### GitHub Actions
 

app/sysbuild.conf

@@ -1,2 +1,10 @@
 # Enable MCUBOOT
 SB_CONFIG_BOOTLOADER_MCUBOOT=y
+
+# Below path can look a bit confusing.
+# At this point the APPLICATION_CONFIG_DIR is still unmodified, so it points to
+# the directory where this sysbuild.conf file is located.
+# But during the app build it gets modified (in the CMakeLists.txt) to point to
+# the conf/ directory.
+SB_CONFIG_BOOT_SIGNATURE_KEY_FILE="${APPLICATION_CONFIG_DIR}/signing_key.pem"
+SB_CONFIG_BOOT_SIGNATURE_TYPE_ECDSA_P256=y

doc/development/setup.md

@@ -21,3 +21,19 @@ make pre-build
 Turn on `pre-commit` tool by running `pre-commit install`. If you do not have it installed or the
 **command did not succeed** follow
 [these instructions](https://github.com/IRNAS/irnas-guidelines-docs/tree/main/tools/pre-commit).
+
+## Setup signing keys
+
+This project uses the MCUboot bootloader which uses private-public key cryptography to validate the
+image signatures at boot time. When building images the build system needs to have access to the
+signing keys, so it can sign the built image.
+
+1. Find the keys in 1Password, search by the repository GitHub name.
+2. Copy the contents of the signing key files to a local file at the expected paths. The expected
+   paths can be found by checking the `pre-build` make target in the `Makefile`.
+
+<!-- prettier-ignore -->
+> [!WARNING]
+> Signing keys are private keys! Therefore, they must never be leaked to the public. That is why
+> they are not included in the repository and ignored in the `.gitignore` file.
+> They must always be added to each developer's local environment manually, as described above.

doc/development/signing_keys.md

@@ -0,0 +1,43 @@
+# Signing keys
+
+Each project using MCUBoot requires signing keys to sign the firmware images. These keys are used to
+verify the integrity and authenticity of the firmware during the boot process.
+
+In most cases, the project will require only a single signing key, due to using a single application
+firmware. If more than one application firmware is needed, multiple signing keys are probably needed
+as well.
+
+## Creating the first signing key
+
+1. Create a signing key file using the following command from the root of the project:
+
+   ```shell
+   east bypass -- python3 ../bootloader/mcuboot/scripts/imgtool.py keygen -t ecdsa-p256 -k app/signing_key.pem
+   ```
+
+2. Create an entry in 1Password and paste contents of the created signing key file, so that it can
+   be used by other developers. Use GitHub repository name and keys purpose as the entry title, for
+   example `client-project-firmware - Main application signing key`.
+
+3. Add a new GitHub secret with the signing key file contents:
+
+   - Go to your GitHub repository.
+   - Navigate to `Settings -> Secrets and variables -> Actions`.
+   - Press the `New secret` button.
+   - Set the name of the secret to `IMAGE_SIGN_KEY`, and paste the contents of the signing key file.
+
+The `app/signing_key.pem` file is not tracked by Git, so it will not be included in the repository.
+If you ever delete the file, you will need to recreate it from the 1Password entry.
+
+## Creating additional signing keys
+
+For each additional signing key you need to create, follow these steps:
+
+1. Follow the steps from the "Creating the first signing key" section to create an additional
+   signing key. Use a different name for the signing key file, 1Password entry and GitHub secret.
+   Use a consistent naming scheme.
+2. Update the `env` section in each workflow file (found in `.github/workflow`) that calls the
+   `make pre-build` target. The `env` section should convert the secret into an environment
+   variable, e.g. `EXTRA_IMAGE_SIGN_KEY: ${{ secrets.EXTRA_IMAGE_SIGN_KEY}}`.
+3. Update the `pre-build` make target in the `Makefile` by adding an additional call to the
+   `create_signing_keys.sh` script with chosen signing key filename.

makefile

@@ -33,6 +33,8 @@ project-setup:
 
 pre-build:
 	east util version
+	# Create signing keys from env variables
+	./scripts/create_signing_keys.sh app/signing_key.pem IMAGE_SIGN_KEY
 
 # Runs on every push to the main branch
 quick-build:

scripts/create_signing_keys.sh

@@ -0,0 +1,37 @@
+#! /usr/bin/env bash
+# Usage: ./create_signing_keys.sh key_file secret_key_var
+#
+# Description:
+#
+#   Create private key files from env vars.
+#
+# Arguments:
+#
+#   key_file The full path of the key file to create, e.g. app/signing_key_rsa2048.pem
+#   secret_key_var The name of the ENV variable or Github secret that contains the private keys,
+#                  e.g. IMAGE_SIGN_KEY.
+
+NUM_ARGS=2
+# Print help text and exit if -h, or --help or insufficient number of arguments
+# was given.
+if [ "$1" = "-h" ] || [ "$1" = "--help" ] || [ $# -lt ${NUM_ARGS} ]; then
+    sed -ne '/^#/!q;s/.\{1,2\}//;1d;p' <"$0"
+    exit 1
+fi
+
+FILE_PATH="$1"
+KEY_VAR="$2"
+
+# Check that the key content is not empty
+# If it is, we are probably running in a local environment.
+# In CI, the key should be set as a GitHub secret and the variable should not be empty.
+# If it is empty, the file will not be created, and the build will fail.
+if [ -z "${!KEY_VAR}" ]; then
+    echo "${KEY_VAR} is not set, doing nothing."
+    exit 0
+fi
+
+# Create the key file
+echo "${!KEY_VAR}" >"${FILE_PATH}"
+
+echo "Created key file ${FILE_PATH} from environment variable ${KEY_VAR}"