|
| 1 | +.. _mcuboot_with_encryption: |
| 2 | + |
| 3 | +MCUboot with encryption enabled |
| 4 | +############################### |
| 5 | + |
| 6 | +.. contents:: |
| 7 | + :local: |
| 8 | + :depth: 2 |
| 9 | + |
| 10 | +The MCUboot with encryption enabled sample demonstrates secure device firmware update (DFU) using MCUboot with encryption enabled. |
| 11 | +You will learn how to build encrypted images and deploy them to supported development kits, protecting application code from unauthorized access during updates. |
| 12 | +This sample does not contain its own application code. |
| 13 | +Instead, it focuses on configuring encryption in MCUboot and generating encrypted DFU images. |
| 14 | +To provide a working example, the sample uses the :zephyr:code-sample:`smp-svr` project as its application by directly importing the project's sources in the main :file:`CMakeLists.txt` file. |
| 15 | + |
| 16 | +Requirements |
| 17 | +************ |
| 18 | + |
| 19 | +The sample supports the following development kits: |
| 20 | + |
| 21 | +.. table-from-sample-yaml:: |
| 22 | + |
| 23 | +.. note:: |
| 24 | + |
| 25 | + On the nRF54LV10 DK, the :zephyr:code-sample:`smp-svr` configuration is trimmed to fit the application slot size. |
| 26 | + For the nRF54L15 DK, an overlay is used to increase the size of the MCUboot partition. |
| 27 | + It is necessary because the enabled logging features require more space than the default partitioning provides. |
| 28 | + |
| 29 | +Overview |
| 30 | +******** |
| 31 | + |
| 32 | +This sample provides a practical starting point for using MCUboot with application image encryption enabled. |
| 33 | +It walks you through the process of building encrypted firmware images and updating them securely on a supported development kit. |
| 34 | + |
| 35 | +MCUboot in this sample is built with enhanced debug output, making it easier to observe and understand the secure boot process. |
| 36 | +For more information on minimal builds and optimization, see the :ref:`MCUboot minimal configuration <mcuboot_minimal_configuration>` documentation. |
| 37 | + |
| 38 | +The firmware update protocol is handled by the :ref:`MCUmgr SMP server<zephyr:mcu_mgr>`, so you can use all related configuration options. |
| 39 | + |
| 40 | +Platform-specific information |
| 41 | +============================= |
| 42 | + |
| 43 | +The nRF54L Series platforms use the following cryptographic algorithms: |
| 44 | + |
| 45 | +* ED25519 for digital signature verification. |
| 46 | +* X25519 for securely exchanging AES encryption keys during image updates. |
| 47 | + |
| 48 | +.. _mcuboot_with_encryption_config: |
| 49 | + |
| 50 | +Configuration |
| 51 | +************* |
| 52 | + |
| 53 | +|config| |
| 54 | + |
| 55 | +Configuration options |
| 56 | +===================== |
| 57 | + |
| 58 | +You can use the following Kconfig options to configure the sample: |
| 59 | + |
| 60 | +* :kconfig:option:`CONFIG_FPROTECT` - This option is disabled by default. |
| 61 | + It enables flash protection for the MCUboot code. |
| 62 | + You can disable it for development and enable it for production purposes to prevent MCUboot overwriting at runtime. |
| 63 | +* :kconfig:option:`CONFIG_MCUBOOT_LOG_LEVEL_DBG` - This option is enabled by default. |
| 64 | + It allows you to easily verify that MCUboot is starting up. |
| 65 | + Disable it for production builds. |
| 66 | +* :kconfig:option:`CONFIG_BOOT_SWAP_SAVE_ENCTLV` - Enable this option in the MCUboot configuration if you are performing DFU to an external storage device. |
| 67 | + This ensures that the random AES key used for the currently swapped image is not exposed. |
| 68 | +* :kconfig:option:`SB_CONFIG_BOOT_ENCRYPTION_KEY_FILE` - MCUboot uses a default encryption key. |
| 69 | + To override it, adjust this option by setting a path to your custom encryption key file. |
| 70 | +* :kconfig:option:`CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION` - Use this option to set the application image version for software updates. |
| 71 | + |
| 72 | +To configure the sample to use KMU crypto storage, add ``-DSB_EXTRA_CONF_FILE=kmu.sysbuild.conf`` to the build command line. |
| 73 | +This option brings in sysbuild configuration file that selects two additional options: |
| 74 | + |
| 75 | + * :kconfig:option:`SB_CONFIG_MCUBOOT_SIGNATURE_USING_KMU` - This option enables KMU support. |
| 76 | + * :kconfig:option:`SB_CONFIG_MCUBOOT_GENERATE_DEFAULT_KMU_KEYFILE` - This option uses the build system to generate and prepare a bundle of default KMU keys to be used with the sample. |
| 77 | + Do not use this option in a production build. |
| 78 | + |
| 79 | +Signature key |
| 80 | +************* |
| 81 | + |
| 82 | +Even with encryption enabled, MCUboot relies on signature keys to verify images at each boot. |
| 83 | +On some devices, you can store the public signature key in one of the following ways: |
| 84 | + |
| 85 | +* Compile it into the device firmware. |
| 86 | +* Use the crypto storage. |
| 87 | + |
| 88 | +If your application is not using crypto storage, you can set a key with the :kconfig:option:`SB_CONFIG_BOOT_SIGNATURE_KEY_FILE` Kconfig option. |
| 89 | +In this case, MCUboot can only use one signature key file compiled into the firmware. |
| 90 | + |
| 91 | +On devices that store keys in crypto storage, the number of stored keys depends on the specific device and may range from one to several. |
| 92 | +Typically, three slots are reserved for storing MCUboot signature keys. |
| 93 | +To use MCUboot with crypto storage, you must provision a set of keys to the device in addition to compiling in support for crypto storage. |
| 94 | +If you use KMU for signature key storage, follow the instructions in :ref:`ug_nrf54l_developing_provision_kmu` to provision the keys. |
| 95 | + |
| 96 | +Security considerations |
| 97 | +*********************** |
| 98 | + |
| 99 | +See the list of best practices, security-related options, and recommended settings when configuring the sample: |
| 100 | + |
| 101 | +* For secure production builds, enable the :kconfig:option:`CONFIG_FPROTECT` and :kconfig:option:`CONFIG_BOOT_SWAP_SAVE_ENCTLV` Kconfig options. |
| 102 | + For production builds, it is recommended to manage keys independently rather than rely on the :kconfig:option:`SB_CONFIG_MCUBOOT_GENERATE_DEFAULT_KMU_KEYFILE`. |
| 103 | + See the :ref:`mcuboot_with_encryption_config` section for details. |
| 104 | +* MCUmgr's shell is enabled by default, allowing you to manage commands using a serial terminal. |
| 105 | +* MCUboot accepts unencrypted images in the secondary slot if signature verification passes. |
| 106 | + For higher security, use encrypted images wherever possible. |
| 107 | +* KMU key handling: |
| 108 | + |
| 109 | + * By default, KMU is not used to store keys in MCUboot. |
| 110 | + * If KMU is enabled, the asymmetric private key used for transport encryption of the random AES key is still compiled into MCUboot in plain text. |
| 111 | + Use hardware-backed key storage in production. |
| 112 | + * Do not leave encryption keys or private keys in plain text inside the MCUboot binary. |
| 113 | + |
| 114 | +Building and running |
| 115 | +******************** |
| 116 | + |
| 117 | +.. |sample path| replace:: :file:`samples/dfu/mcuboot_with_encryption` |
| 118 | + |
| 119 | +.. include:: /includes/build_and_run.txt |
| 120 | + |
| 121 | +By default, the sample builds without KMU support, and the encryption key is embedded within the MCUboot binary. |
| 122 | +To see the encryption workflow, you must build two application images with different version numbers (for example, set the :kconfig:option:`CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION` Kconfig option to ``1.0.0`` and ``2.0.0``), using separate build directories. |
| 123 | + |
| 124 | +Testing |
| 125 | +======= |
| 126 | + |
| 127 | +After programming the device with the first image, verify its functionality: |
| 128 | + |
| 129 | +1. Connect to the device's serial console. |
| 130 | +#. Reset the device. |
| 131 | +#. Observe the boot output confirming successful start of the SMP Server application: |
| 132 | + |
| 133 | + .. code-block:: console |
| 134 | +
|
| 135 | + *** Booting MCUboot v2.3.0-dev-0d263faf6e55 *** |
| 136 | + *** Using nRF Connect SDK v3.1.99-4f1d50b83bfb *** |
| 137 | + *** Using Zephyr OS v4.2.99-164b47d30942 *** |
| 138 | +
|
| 139 | + *** Booting nRF Connect SDK v3.1.99-4f1d50b83bfb *** |
| 140 | + *** Using Zephyr OS v4.2.99-164b47d30942 *** |
| 141 | + [00:00:00.075,512] <inf> bt_sdc_hci_driver: SoftDevice Controller build revision: |
| 142 | + 9d dc 12 f9 d0 01 5e 7e af 5b 84 59 45 12 69 4e |
| 143 | + |......^~ .[.YE.iN |
| 144 | + 5e dc 0b 2f |^../ |
| 145 | + [00:00:00.076,807] <inf> bt_hci_core: HW Platform: Nordic Semiconductor (0x0002) |
| 146 | + [00:00:00.076,822] <inf> bt_hci_core: HW Variant: nRF54Lx (0x0005) |
| 147 | + [00:00:00.076,836] <inf> bt_hci_core: Firmware: Standard Bluetooth controller (0x00) Version |
| 148 | + 157.4828 Build 1577177337 |
| 149 | + [00:00:00.077,217] <inf> bt_hci_core: HCI transport: SDC |
| 150 | + [00:00:00.077,269] <inf> bt_hci_core: Identity: C0:0A:89:ED:8F:B9 (random) |
| 151 | + [00:00:00.077,285] <inf> bt_hci_core: HCI: version 6.1 (0x0f) revision 0x30c0, manufacturer 0x0059 |
| 152 | + [00:00:00.077,299] <inf> bt_hci_core: LMP: version 6.1 (0x0f) subver 0x30c0 |
| 153 | + [00:00:00.077,765] <inf> smp_bt_sample: Advertising successfully started |
| 154 | +
|
| 155 | +#. To test encrypted updates, upload the second (encrypted) image using any supported method, such as MCUmgr over Bluetooth, serial shell, or another DFU transport. |
| 156 | + For more information on DFU, see the :ref:`Zephyr Device Firmware Upgrade documentation <zephyr:dfu>`. |
| 157 | +#. After uploading the image, mark the new image for test. |
| 158 | +#. On reboot, verify that the new firmware version is running. |
| 159 | + If the image is not confirmed, the bootloader will revert to the previous version. |
| 160 | + The image will then be re-encrypted if swapped out of the boot slot. |
| 161 | + |
| 162 | +.. note:: |
| 163 | + |
| 164 | + This sample also accepts unencrypted firmware updates. |
| 165 | + If you upload an unencrypted and properly signed image, MCUboot will successfully boot it. |
| 166 | + |
| 167 | +Further information on image encryption and generating keys |
| 168 | +=========================================================== |
| 169 | + |
| 170 | +More information on MCUboot support for image encryption can be found in the :ref:`mcuboot_wrapper` section under Encrypted images. |
| 171 | +Users should familiarize themselves with this section, as they will need to generate their own keys for encryption key exchange. |
| 172 | + |
| 173 | +.. note:: |
| 174 | + |
| 175 | + The keys used in this sample are publicly known. |
| 176 | + Do not use them in your product under any circumstances. |
| 177 | + |
| 178 | +To learn how to upload custom keys to KMU, see the :ref:`ug_nrf54l_dfu_config` documentation page. |
| 179 | + |
| 180 | +Dependencies |
| 181 | +************ |
| 182 | + |
| 183 | +The sample depends on following subsystems and libraries: |
| 184 | + |
| 185 | +* :ref:`MCUboot <mcuboot_index_ncs>` |
| 186 | +* :ref:`zephyr:mcu_mgr` |
| 187 | +* :ref:`nrf_security` |
0 commit comments