Commit 9fd145f3 authored by Denis Pynkin's avatar Denis Pynkin

secure-boot.md: secure boot integration for Apertis

Described how to add the HAB signing into the images
and Apertis build pipeline.
Signed-off-by: default avatarDenis Pynkin <denis.pynkin@collabora.com>
parent fc27695c
......@@ -2,6 +2,7 @@
title: Apertis secure boot
authors:
- name: Sjoerd Simons
- name: Denis Pynkin
...
# Apertis secure boot
......@@ -562,5 +563,90 @@ $ cst -i vmlinuz-pad-ivt.csf -o vmlinuz-pad-ivt.bin
CSF Processed successfully and signed data available in vmlinuz-pad-ivt.bin
```
## Signing bootloader and kernel from the image build pipeline
Starting with v2021dev1 Apertis uses single signed FIT kernel image for OSTree-based
systems. The signed version of U-Boot is a part of U-Boot installer.
For signing binaries with the `cst` tool we need some files from the
[Apertis development keys](https://gitlab.apertis.org/infrastructure/apertis-imx-srk)
git repository. The minimal working setup should include only 6 files:
- `SRK_1_2_3_4_table.bin` -- Super Root Keys table
- `key_pass.txt` -- file with password
- CSF certificate and key in PEM format
- IMG certificate and key in PEM format
In addition we need a template for the FIT source file and CSF template suitable for
signing U-Boot and FIT kernel.
All files listed above are added into the git repository inside [sign/imx6](https://gitlab.apertis.org/infrastructure/apertis-image-recipes/-/tree/apertis/v2021dev1/sign/imx6)
subdirectory. Since all secrets for Apertis are public we are able to use them directly
from the repo. However this is not acceptable for production.
Fortunately the most of CI tools have possibility to add files as secrets
available only on several steps. Hence we add "private" keys and password
file as "Secret file" global credentials to demonstrate the integration
into the Jenkins pipeline:
![](media/secure-boot-jenkins-creds.png)
For keys usage they should be available during the call of `cst` tool,
so we have to add into the Jenkins pipeline copying of these secret files
with the same names as used in [CSF template](https://gitlab.apertis.org/infrastructure/apertis-image-recipes/-/blob/apertis/v2021dev1/sign/imx6/fit_image_csf.template)
and remove them after the usage.
For instance the simple secrets copying for Jenkins:
```
withCredentials([ file(credentialsId: csf_csf_key, variable: 'CSF_CSFKEY'),
file(credentialsId: csf_img_key, variable: 'CSF_IMGKEY'),
file(credentialsId: csf_key_pass, variable: 'CSF_PASSWD')]) {
// Setup keys for cst tool from Jenkins secrets
// Have to keep keys and password file near certificates
sh(script: """
cd ${WORKSPACE}/sign/imx6
cp -af $CSF_CSFKEY ./
cp -af $CSF_IMGKEY ./
cp -af $CSF_PASSWD ./""")
}
```
### U-Boot signing
To sign the U-Boot the script [scripts/sign-u-boot.sh](https://gitlab.apertis.org/infrastructure/apertis-image-recipes/-/blob/apertis/v2021dev1/scripts/sign-u-boot.sh)
has been added. It automatically generates the CSF configuration
from the template [sign/imx6/fit_image_csf.template](https://gitlab.apertis.org/infrastructure/apertis-image-recipes/-/blob/apertis/v2021dev1/sign/imx6/fit_image_csf.template)
and call the `cst` tool to sign the U-Boot binary.
The script is called by the [Debos recipe for the SabreLite U-Boot installer
image](https://gitlab.apertis.org/infrastructure/apertis-image-recipes/-/blob/apertis/v2021dev1/mx6qsabrelite-uboot-installer.yaml):
```
- action: run
description: Sign U-Boot
script: scripts/sign-u-boot.sh "${ROOTDIR}/deb-binaries/usr/lib/u-boot/{{ $target }}/u-boot.imx"
```
### FIT image creation and signing
The FIT image is more complex. So for Apertis we use 2 scripts:
- the [`scripts/generate_signed_fit_image.py` script](https://gitlab.apertis.org/infrastructure/apertis-image-recipes/-/blob/apertis/v2021dev1/scripts/generate_signed_fit_image.py)
is used for generation FIT image, padding, IVT calculation and signing.
This script can be used standalone to automate all steps described
in the section "[Sign kernel images for U-Boot to load](#sign-kernel-images-for-uboot-to-load)"
- the [`scripts/generate_fit_image.sh` script](https://gitlab.apertis.org/infrastructure/apertis-image-recipes/-/blob/apertis/v2021dev1/scripts/generate_fit_image.sh)
is a wrapper for the former providing it the paths
for kernel, initramfs and DTB to include them in the signed FIT image.
The integration with the build pipeline happens **after** the kernel is installed
by the [OSTree commit recipe](https://gitlab.apertis.org/infrastructure/apertis-image-recipes/-/blob/apertis/v2021dev1/apertis-ostree-commit.yaml) by adding the step below:
```
- action: run
description: Generate FIT image
script: scripts/generate_fit_image.sh
```
**NB**: this action must be done prior to ostree commit action
to add the signed FIT kernel into OSTree repository for OTA upgrades.
## As next steps the following could be undertaken:
* Integration of PCKS#11 support in the signing process to support HSM devices
* Automated testing of secure boot if possible
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment