diff --git a/README.md b/README.md index 40c0cd42..63e77abe 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,11 @@ For detailed information about the configuration options for the target system, For more detailed information about firmware update implementation, see [Firmware Update](docs/firmware_update.md) + +### Additional features + - [Remote external flash interface](docs/remote_flash.md) + - [External encrypted partitions](docs/encrypted_partitions.md) + ## Troubleshooting 1. Python errors when signing a key: diff --git a/docs/encrypted_partitions.md b/docs/encrypted_partitions.md new file mode 100644 index 00000000..8b4aa2e2 --- /dev/null +++ b/docs/encrypted_partitions.md @@ -0,0 +1,63 @@ +## Encrypted external partitions + +wolfBoot offers the possibility to encrypt the content of the entire UPDATE partition, +by using a pre-shared symmetric key which can be temporarily stored in a safer non-volatile memory area. + +SWAP partition is also temporarily encrypted using the same key, so a dump of the external flash won't reveal +any content of the firmware update packages. + +### Rationale + +Encryption of external partition works at the level of the external flash interface. + +All write calls to external partitions from the bootloader perform an additional encryption step +to hide the actual content of the external non-volatile memory. + +Viceversa, all read operations will decrypt the data stored when the feature is enabled. + +An extra option is provided to the `sign.py` sign tool to encrypt the firmware update after signing it, so +that it can be stored as is in the external memory by the application, and will be decrypted by the bootloader +in order to verify the update and begin the installation. + + +### Temporary key storage + +By default, wolfBoot will store the pre-shared symmetric key used for encryption in a temporary area +on the internal flash. This allows read-out protections to be used to hide the temporary key. + +Alternatively, more secure mechanisms are available to store the temporary key in a different key storage +(e.g. using a hardware security module or a TPM device). + +The temporary key can be set at run time by the application, and will be used exactly once by the bootloader +to verify and install the next update. The key can be for example received from a back-end during the update +process using secure communication, and set by the application, using `libwolfboot` API, to be used by +wolfBoot upon next boot. + +Aside from setting the temporary key, the update mechanism remains the same for distrubuting, uploading and +installing firmware updates through wolfBoot. + +### Libwolfboot API + +The API to communicate with the bootloader from the application is expanded when this feature is enabled, +to allow setting a temporary key to process the next update. + +The functions + +``` +int wolfBoot_set_encrypt_key(const uint8_t *key, int len); +int wolfBoot_erase_encrypt_key(void); +``` + +can be used to set a temporary encryption key for the external partition, or erase a key previously set, respectively. + +Moreover, using `libwolfboot` to access the external flash with wolfboot hal from the application will not +use encryption. This way the received update, already encrypted at origin, can be stored in the external +memory unchanged, and retreived in its encrypted format, e.g. to verify that the transfer has been successful before +reboot. + +### Symmetric encryption algorithm + +The algorithm currently used to encrypt and decrypt data in external partitions +is Chacha20-256. The expected key to provide to `wolfBoot_set_encrypt_key()` must be exactly 32 Bytes long. + + diff --git a/docs/remote_flash.md b/docs/remote_flash.md new file mode 100644 index 00000000..ac7b2f89 --- /dev/null +++ b/docs/remote_flash.md @@ -0,0 +1,51 @@ +## Remote External flash memory support via UART + +wolfBoot can emulate external partitions using UART communication with a neighbor system. This feature +is particularly useful in those asynchronous multi-process architectures, where updates can be stored +with the assistance of an external processing unit. + +### Bootloader setup + +The option to activate this feature is `UART_FLASH=1`. This configuration option depends on the +external flash API, which means that the option `EXT_FLASH=1` is also mandatory to compile the bootloader. + +The HAL of the target system must be expanded to include a simple UART driver, that will be used by the +bootloader to access the content of the remote flash using one of the UART controllers on board. + +Example UART drivers for a few of the supported platforms can be found in the [hal/uart](hal/uart) directory. + +The API exposed by the UART HAL extension for the supported targets is composed by the following functions: + +``` +int uart_init(uint32_t bitrate, uint8_t data, char parity, uint8_t stop); +int uart_tx(const uint8_t c); +int uart_rx(uint8_t *c); +``` + +Consider implementing these three functions based on the provided examples if you want to use external flash memory +support on your platform, if not officially supported yet. + + +### Host side: UART flash server + +On the remote system hosting the external partition image for the target, a simple protocol can be implemented +on top of UART messages to serve flash-access specific calls. + +An example uart-flash-server daemon, designed to run on a GNU/Linux host and emulate the external partition with +a local file on the filesystem, is available in [tools/uart-flash-server](tools/uart-flash-server). + + +### External flash update mechanism + +wolfBoot treats external UPDATE and SWAP partitions in the same way as when they are mapped on a local SPI flash. +Read and write operations are simply translated into remote procedure calls via UART, that can be interpreted by +the remote application and provide read and write access to actual storage elements which would only be accessible +by the host. + +This means that after a successful update, a copy of the previos firmware will be stored in the remote partition to +provide exactly the same update mechanism that is available in all the other use cases. The only difference consist +in the way of accessing the physical storage area, but all the mechanisms at a higher level stay the same. + + + +