Add Secure Boot and Full Disk Encryption reference docs #3145
Conversation
Change-type: minor Signed-off-by: Rahul Thakoor <[email protected]>
rahul-thakoor
force-pushed
the
rahul/sb-and-fde
branch
from
f7f3b8d to
fa6fc26
Compare
|
Website deployed to CF Pages, 👀 preview link https://fad6cf0a.balenacloud-docs.pages.dev |
| BalenaOS’s chain of trust ends with the Linux kernel, as the root filesystem itself is not signed. While this means the filesystem cannot be authenticated in its entirety at runtime, all partitions are encrypted, preventing tampering at rest. The operating system strictly refuses to mount partitions that are either unencrypted or encrypted with unknown credentials. Consequently, any modifications to the filesystem content would be detectable through decryption failures or mismatch in encryption keys. | ||
|
|
||
| ### Application Authentication | ||
| Currently, applications (container images) are not cryptographically signed. However, only a fully verified operating system (one that has passed secure boot checks) is permitted to install new applications. Furthermore, the container images themselves are downloaded exclusively from balenaCloud’s authenticated registry, providing an additional layer of trust and ensuring that only legitimate images reach production devices. |
There was a problem hiding this comment.
This could be improved a bit, as we have more security checks in place; on a production device:
- the manifest (target state) can only come from balena-cloud api via a https/TLS connection.
- the engine pulls images from balena-cloud registry only, referencing the image with the exact hash of the image; this is again secured by https/tls
- if the hash of the image or any of its layers doesn't match, the pull fails and the image will not be loaded/run
There's a few inherent risks of this design:
- a compromised balena-cloud account can push anything to the balena builder, and it will be deployed to device (if the device/fleet is not pinned to another version)
- a compromised balena builder could alter the code during the build (this is mitigated by balena internal security measures)
- if a device trust extra certificates (or one of the root certs is compromised) the target-state (manifest) could be altered in a mitm attack
- a vulnerability in the application could lead to a device take-over, including in the worst scenario, access to the FDE keys (this requires multiple vulnerabilities and a bad application design)
| Secure boot depends fundamentally on cryptographic keys and certificates to verify the integrity of every component in the boot process. | ||
|
|
||
| These typically include: | ||
| - **Signing Keys** : A private key—controlled by the device or OS vendor—signs the bootloader, kernel, and other critical binaries. |
There was a problem hiding this comment.
by the device or OS vendor
? by the user? by the customer?
There was a problem hiding this comment.
—controlled by the device or OS vendor—
I would remove the above as it's too early to discuss key ownerships I reckon.
|
|
||
| These typically include: | ||
| - **Signing Keys** : A private key—controlled by the device or OS vendor—signs the bootloader, kernel, and other critical binaries. | ||
| This key must be kept confidential; anyone possessing it can produce binaries that devices would trust implicitly. |
There was a problem hiding this comment.
implicitly
It's actually rather explicit. We can drop "implicitly".
| These typically include: | ||
| - **Signing Keys** : A private key—controlled by the device or OS vendor—signs the bootloader, kernel, and other critical binaries. | ||
| This key must be kept confidential; anyone possessing it can produce binaries that devices would trust implicitly. | ||
| - **Public Certificates or keys** : The matching public certificate (or key) is stored on securely on the device. |
There was a problem hiding this comment.
is stored on securely on the device.
is injected|intalled|enrolled|copied during the provisioning of the device.
There was a problem hiding this comment.
stored on securely on the device
It's a public key - does not need to be stored securely, and it's not really. Leave stored on the device
There was a problem hiding this comment.
We also have two ons in this part which should be removed "...stored on securely on the device..."
| Provisioning a device with secure boot and full disk encryption enabled typically involves the following high-level processes: | ||
|
|
||
| - Enroll secure boot keys into the device | ||
| - Generate a unique disk encryption key and uses it to encrypt the storage |
There was a problem hiding this comment.
Idk which one is first? generating the FDE key or copying the OS
Not a big issue tho
There was a problem hiding this comment.
IIRC the device is only considered secure after it's been booted once after the flasher image finish the provisioning.
There was a problem hiding this comment.
Unique customer keys can also be provided as an extra service
I don't think we envision to provide customer keys - we can use unique customer keys, but the ownership will still be with balena.
I would say Unique customer keys can also be used as an extra service
| ### Secure Boot Installer Images | ||
| Typically, balenaOS images can be categorized as: | ||
| - **Flasher images** : The internal storage of a device is programmed directly with balenaOS using a live image | ||
| - **Non-flasher images**: Used when the devices did not expose the internal storage. The flasher image boots from an external storage medium and then the os is programmed to the required internal storage |
There was a problem hiding this comment.
This is the inverted:
- Flasher images: install the OS on the internal storage (i.e. x86)
- Non-flasher images: the OS is directly copied on the storage (i.e. by etcher when flashing a sd card for a non securboot raspberry pi)
| - **Flasher images** : The internal storage of a device is programmed directly with balenaOS using a live image | ||
| - **Non-flasher images**: Used when the devices did not expose the internal storage. The flasher image boots from an external storage medium and then the os is programmed to the required internal storage | ||
|
|
||
| For secure boot-enabled devices, the distinction blurs - all secure boot-enabled devices have flasher images. Moreover, given that the image not only writes the os to disk but also does other tasks such as enrolling required can be considered as `installer` images. So, secure boot enabled devices provide an `installer` image instead that can be programmed either on external or internal storage, in the latter case running from memory and performing the installation on the same disk it is booted from. |
There was a problem hiding this comment.
the distinction blurs
We can remove that, we just use flasher images
There was a problem hiding this comment.
other tasks such as enrolling required can be considered as
installerimages.
Missing some words: "enrolling required keys and/or certificates"
|
|
||
| For secure boot-enabled devices, the distinction blurs - all secure boot-enabled devices have flasher images. Moreover, given that the image not only writes the os to disk but also does other tasks such as enrolling required can be considered as `installer` images. So, secure boot enabled devices provide an `installer` image instead that can be programmed either on external or internal storage, in the latter case running from memory and performing the installation on the same disk it is booted from. | ||
|
|
||
| The secure boot installer is itself using signed binaries and can be used to re-program locked devices. Re-running the installer will irrevocably lose all data on the disks as the encryption key is erased. |
There was a problem hiding this comment.
The secure boot installer is itself using signed binaries and can be used to re-program locked devices.
On X86 this doesn't matter, as to re-program you need to deactivate SB (set it back in setup mode);
This might be important for other DT in the future, but would require some more discussion.
Re-running the installer will irrevocably lose all data on the disks as the encryption key is erased.
This is important tho.
There was a problem hiding this comment.
as to re-program you need to deactivate SB
You can re-program without having to re-enter setup mode - you will just use the existing keys. Best for @mtoman to confirm this point.
|
|
||
| The notion of a chain of trust arises because each stage in the boot process validates the integrity of the subsequent stage before executing it. If at any point a link in this chain is corrupted, unsigned, or otherwise fails validation, the boot process halts or reverts to a known-good state. This sequential validation ensures that if the first link is trusted, every subsequent link remains trustworthy, preventing unauthorized or tampered code from ever running. | ||
|
|
||
| The root of trust is always the device’s `bootROM`. `bootROM` refers to the very first piece of firmware that runs when a device powers on. It resides in read-only memory (ROM) that is physically embedded in the processor or system-on-chip (SoC). Because the code stored in bootROM is difficult or impossible to modify (without physically altering the chip), it serves as the hardware-enforced starting point or “root of trust” for the boot process. |
There was a problem hiding this comment.
This is critical to whole security and requires proper checks of the chosen hardware platform, apply bios updates, and turn on bios security features.
There's a requirement of having a hardware secure element (TPM, or equivalent depending on the platform). And that a fTPM is considered more secure than a discrete TPM to prevent bus sniffing.
| Secure boot depends fundamentally on cryptographic keys and certificates to verify the integrity of every component in the boot process. | ||
|
|
||
| These typically include: | ||
| - **Signing Keys** : A private key—controlled by the device or OS vendor—signs the bootloader, kernel, and other critical binaries. |
There was a problem hiding this comment.
—controlled by the device or OS vendor—
I would remove the above as it's too early to discuss key ownerships I reckon.
| These typically include: | ||
| - **Signing Keys** : A private key—controlled by the device or OS vendor—signs the bootloader, kernel, and other critical binaries. | ||
| This key must be kept confidential; anyone possessing it can produce binaries that devices would trust implicitly. | ||
| - **Public Certificates or keys** : The matching public certificate (or key) is stored on securely on the device. |
There was a problem hiding this comment.
stored on securely on the device
It's a public key - does not need to be stored securely, and it's not really. Leave stored on the device
| Provisioning a device with secure boot and full disk encryption enabled typically involves the following high-level processes: | ||
|
|
||
| - Enroll secure boot keys into the device | ||
| - Generate a unique disk encryption key and uses it to encrypt the storage |
There was a problem hiding this comment.
Unique customer keys can also be provided as an extra service
I don't think we envision to provide customer keys - we can use unique customer keys, but the ownership will still be with balena.
I would say Unique customer keys can also be used as an extra service
|
|
||
| For secure boot-enabled devices, the distinction blurs - all secure boot-enabled devices have flasher images. Moreover, given that the image not only writes the os to disk but also does other tasks such as enrolling required can be considered as `installer` images. So, secure boot enabled devices provide an `installer` image instead that can be programmed either on external or internal storage, in the latter case running from memory and performing the installation on the same disk it is booted from. | ||
|
|
||
| The secure boot installer is itself using signed binaries and can be used to re-program locked devices. Re-running the installer will irrevocably lose all data on the disks as the encryption key is erased. |
There was a problem hiding this comment.
as to re-program you need to deactivate SB
You can re-program without having to re-enter setup mode - you will just use the existing keys. Best for @mtoman to confirm this point.
| # Secure Boot and Full Disk Encryption | ||
| Balena’s secure boot and full disk encryption feature addresses two critical aspects of device security. Secure boot ensures that only trusted software can run on the device, while full disk encryption safeguards data at rest by preventing unauthorized access to the contents of storage media. | ||
|
|
||
| Given the diversity of hardware platforms that balenaOS targets, it was essential to design a flexible framework capable of integrating device-specific secure boot mechanisms. Key goals of balenaOS secure boot and encryption design include: |
There was a problem hiding this comment.
I think "Key goals of balenaOS secure..." should start on a new line as in the rendered version it looks a bit off
| These typically include: | ||
| - **Signing Keys** : A private key—controlled by the device or OS vendor—signs the bootloader, kernel, and other critical binaries. | ||
| This key must be kept confidential; anyone possessing it can produce binaries that devices would trust implicitly. | ||
| - **Public Certificates or keys** : The matching public certificate (or key) is stored on securely on the device. |
There was a problem hiding this comment.
We also have two ons in this part which should be removed "...stored on securely on the device..."
|
|
||
| Secure Boot-enabled balenaOS images are provided pre-signed using balena owned secrets - this is a convenient way to guarantee that only trusted software runs in the device while avoiding the friction of secrets generation, managing and safeguarding. | ||
|
|
||
| __Note:__ We are aware that balena owned keys might not fit all use cases. Unique customer keys can also be provided as an extra service. Contact [[email protected]](mailto:[email protected]) to discuss [custom hardware support](https://www.balena.io/pricing/#custom-device-support) packages. |
There was a problem hiding this comment.
I wonder if we should just leave it at "contact us" and not link to the current CDS pricing as it probably will be cheaper than standard CDS and this could turn people away.
| The secure boot installer is itself using signed binaries and can be used to re-program locked devices. Re-running the installer will irrevocably lose all data on the disks as the encryption key is erased. | ||
|
|
||
|
|
||
| __Note:__ This imposes a limitation on the specifications for device types to support secure boot - they must have enough memory to hold the raw image that is being programmed into disk. BalenaOS reduces this restriction by using compressed memory to hold the raw image, but still, memory constrained devices will not be able to support secure boot with the current design. |
There was a problem hiding this comment.
Do we have recommendations of how much memory is too small @rahul-thakoor and @alexgg . I guess 1GB might be too small but is 2GB? Just wondering if people will have an idea of what "enough memory to hold a compressed image" means.
There was a problem hiding this comment.
With the current rootfs sizes 1GB is the minimum for 300MB rootfs sizes - this will change as we increase the rootfs sizes. For example, I'd expect that if we make the default rootfs 600MB this will be 2GBs. Also, not all DTs have the same rootfs sizes, so it will vary.
|
|
||
|
|
||
| ### Partition Layout and Disk Encryption | ||
| Balena uses the `dm-crypt` Linux kernel subsystem and `device-mapper` framework to encrypt block devices. Both direct `dm-crypt` and `LUKS` (Linux Unified Key Setup) are supported. |
There was a problem hiding this comment.
Is there a user configurable way to switch to using LUKS if they wanted or is this something we decide during secureboot integration? If it is the latter, should we maybe not mention it as it sounds like this is a user choice they can make.
|
|
||
| A typical boot chain of trust for balenaOS involves: | ||
| - The `bootROM` validates the balena bootloader and device trees and executes the balena bootloader | ||
| - The balena bootloader mounts the encrypted storage, validates the appropriate Linux kernel plus initramfs using in-kernel X.509 certificates |
There was a problem hiding this comment.
in the last bullet below we put X.509 in code quotes but here we don't, we should be consistent.
No description provided.