Updated documentation (uart remote flash, encrypted partitions)

Author: danielinux

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:

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.
+
+

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.
+
+
+
+