patch: add secure boot documentation #3441
Conversation
There was a problem hiding this comment.
@rosswesleyporter @vipulgupta2048 could we think ahead how the secure boot is going to be structured to include more than one device type?
Some of this content is generic content for all devices, while some is x86 specific. I suggest we keep them separate so we can then just add a RPI/CM4 version and not have to rework the whole.
There was a problem hiding this comment.
Sure, I thought Ross and you may have discussed this but here's what I was thinking. If the need was not to make this live ASAP but to take our time to plan it right, then I would recommend this structure.
Generic context for all devices goes into a file called index.md housed in a folder called secure-boot. This would create a tree directory structure in our houses. Each new device type getting support can be added as x86.md, rpi4.md, or cm4.md to have device-specific secure boot instructions and information.
Docusaurus (our docs framework) can accomplish this easily, and it can be easily extended to accommodate as many devices as possible.
There was a problem hiding this comment.
If you like this structure and I can use the review to split the documents and reping you for a review.
There was a problem hiding this comment.
The choice is to either have multiple pages or one long page.
One of the changes that I made to the content from AlexG's blog post is to decouple the general content from the x86 content, so those two sections are functionally independent. Thus we could add more sections e.g. for CM4. Or split into multiple pages e.g. general, x86, CM4. Given that independence, I don't think there's much of a maintenance difference. But I don't have a strong opinion here - happy for it to be split into multiple pages.
| @@ -0,0 +1,108 @@ | |||
| # Secure boot and full disk encryption | |||
|
|
|||
| > Available for the `Generic x86_64 (GPT)` device type. | |||
There was a problem hiding this comment.
I would probable move this to its own UEFI section
There was a problem hiding this comment.
Hello, CS had the view to make sure customers coming to this page knows that the what generic x86_64 at least for support and this index.md page I mentioned above could act as an announcement banner each time being updated to tell people landing on this parent page to find what device types we support secure boot for.
|
|
||
| Another balenaOS characteristic is that it provides unattended disk encryption – that is, there is no user interaction when mounting the encrypted disks as it is expected from an embedded device. In order to do this, the mounting of the encrypted disks happen on a trusted system that uses secure boot. Secure boot and disk encryption have been designed to work as a bundle in balenaOS and they cannot be configured separately. | ||
|
|
||
| BalenaOS distributes fully tested signed images and has taken care of the management of signing material. We maintain a secure signing server in Balena’s production infrastructure that is used to sign the build artifacts with Balena’s platform keys. These are programmed in the device by the balenaOS installer when first provisioning the device. The authentication of the different boot artifacts then uses the db and dbx UEFI variables to whitelist and blacklist elements of the chain of trust. This allows updates to a new balenaOS version and prevents older versions from being bootable. |
There was a problem hiding this comment.
The above paragraph is UEFI specific, while the rest is generic.
|
|
||
| Balena recommends only to use a secure boot and disk encrypted system when it is a product requirement, and to consider the limitations well. | ||
|
|
||
| # Secure boot and full disk encryption for Generic x86_64 (GPT) |
There was a problem hiding this comment.
I would make a UEFI section, and then specify which are the UEFI compatible hardware supported.
| Balena recommends only to use a secure boot and disk encrypted system when it is a product requirement, and to consider the limitations well. | ||
|
|
||
| # Secure boot and full disk encryption for Generic x86_64 (GPT) | ||
| Secure boot and full disk encryption is available for the `Generic x86_64 (GPT)` device type as of balenaOS v2.114.21. This feature was updated for wider device hardware compatibility as of balenaOS 5.3.15, and balena recommended that all customers use this updated release. Secure boot and full disk encryption is available for the `Generic x86_64 (GPT)` device type. It is not available for other x86 device types such as `Generic x86-64 (legacy MBR)` and `Intel NUC`. For clarity, one can use secure boot on Intel NUC hardware and x86 hardware in general, using the `Generic x86_64 (GPT)` device type. |
There was a problem hiding this comment.
The callout about Intel-NUC and MBR should just mention these are not UEFI devices.
| * Enable secure boot. | ||
| * Reset secure boot to setup mode | ||
|
|
||
| On booting in setup mode, the installer will enroll the keys into UEFI variables and encrypt the disks using the TPM device. Note that enrolling the keys manually via the UEFI setup application, while possible on some systems, is not currently supported by balenaOS as the installer’s bootloader is not signed. |
|
|
||
| On booting in setup mode, the installer will enroll the keys into UEFI variables and encrypt the disks using the TPM device. Note that enrolling the keys manually via the UEFI setup application, while possible on some systems, is not currently supported by balenaOS as the installer’s bootloader is not signed. | ||
|
|
||
| If you are using balenaOS earlier than 5.3.15, an important note is that the first boot after programming is not fully secured yet as the UEFI settings (and the boot order in particular) will only be locked down during the first boot after installation. Make sure to also perform the initial boot after programming with the device in a secure controlled environment. |
There was a problem hiding this comment.
That might be better formatted as a callout if that's supported.
There was a problem hiding this comment.
@alexgg Ross had the same doubt and I also recommended we do a callout for it. Is it supported?
| ``` | ||
| ~# dmesg | grep -i "secure boot" | ||
| [ 0.004752] Secure boot enabled | ||
| ``` |
| /dev/mapper/luks-785890e2-b7f5-4bc6-8536-471e4ec56cd0 on /etc/machine-id type ext4 (rw,relatime) | ||
| /dev/mapper/luks-0a2df5ae-194f-4f47-ac37-ce8a66084878 on /mnt/data type ext4 (rw,relatime) | ||
| /dev/mapper/luks-1ac7ec1d-85bb-4866-86ac-28648980eb80 on /mnt/boot type ext4 (rw,relatime) | ||
| ``` |
There was a problem hiding this comment.
That's common though - maybe it can at least be a re-usable partial.
|
|
||
| ## For more information | ||
| If you’d like a more in-depth explanation of the secure boot and full disk encryption implementation for x86, head for the [source](https://github.com/balena-os/meta-balena/blob/master/docs/uefi-secure-boot.md). For more information on the general approach to secure boot, see [Secure boot abstractions](https://github.com/balena-os/meta-balena/blob/master/docs/secure-boot-abstractions.md). | ||
|
|
There was a problem hiding this comment.
Here too, general, UEFI and RPI specific links.
Added documentation for secure boot and full disk encryption. The content is largely from AlexG's earlier blog post. Modified to reflect changes since that blog post was published.
https://ae937916.balena-os.pages.dev/secure-boot
[skip ci]