Merge pull request #62 from danielinux/ext_flash_encryption

External flash encryption

Author: dgarske

.gdbinit

@@ -125,6 +125,11 @@ ifeq ($(UART_FLASH),1)
   EXT_FLASH=1
 endif
 
+ifeq ($(ENCRYPT),1)
+    CFLAGS+=-DEXT_ENCRYPTED=1
+    WOLFCRYPT_OBJS+=./lib/wolfssl/wolfcrypt/src/chacha.o
+endif
+
 ifeq ($(EXT_FLASH),1)
   CFLAGS+= -DEXT_FLASH=1 -DPART_UPDATE_EXT=1 -DPART_SWAP_EXT=1
   ifeq ($(NO_XIP),1)
@@ -179,8 +184,7 @@ ifeq ($(WOLFTPM),1)
   OBJS += lib/wolfTPM/src/tpm2.o \
     lib/wolfTPM/src/tpm2_packet.o \
     lib/wolfTPM/src/tpm2_tis.o \
-    lib/wolfTPM/src/tpm2_wrap.o \
-    hal/spi/spi_drv_$(SPI_TARGET).o
+    lib/wolfTPM/src/tpm2_wrap.o
   CFLAGS+=-DWOLFBOOT_TPM -DSIZEOF_LONG=4 -Ilib/wolfTPM \
     -DMAX_COMMAND_SIZE=1024 -DMAX_RESPONSE_SIZE=1024 -DWOLFTPM2_MAX_BUFFER=1500 \
     -DMAX_SESSION_NUM=1 -DMAX_DIGEST_BUFFER=973 \
@@ -189,6 +193,9 @@ ifeq ($(WOLFTPM),1)
   CFLAGS+=-DWOLFTPM_SLB9670
   # Use TPM for hashing (slow)
   #CFLAGS+=-DWOLFBOOT_HASH_TPM
+  ifneq ($(SPI_FLASH),1)
+    WOLFCRYPT_OBJS+=hal/spi/spi_drv_$(SPI_TARGET).o
+  endif
 endif
 OBJS+=$(WOLFCRYPT_OBJS)
 
@@ -232,6 +239,7 @@ standalone:
 	$(Q)$(SIZE) test-app/image.elf
 
 include tools/test.mk
+include tools/test-enc.mk
 
 ed25519.der:
 	@$(KEYGEN_TOOL) $(KEYGEN_OPTIONS) src/ed25519_pub_key.c
@@ -303,6 +311,10 @@ include/target.h: include/target.h.in FORCE
 config: FORCE
 	make -C config
 
+../src/libwolfboot.o: ../src/libwolfboot.c FORCE
+	@echo "\t[CC-$(ARCH)] $@"
+	$(Q)$(CC) $(CFLAGS) -c -o $@ ../src/libwolfboot.c
+
 %.o:%.c
 	@echo "\t[CC-$(ARCH)] $@"
 	$(Q)$(CC) $(CFLAGS) -c -o $@ $^

Makefile

@@ -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:

README.md

@@ -0,0 +1,29 @@
+ARCH?=ARM
+TARGET?=stm32wb
+SIGN?=ECC256
+HASH?=SHA256
+DEBUG?=0
+VTOR?=1
+CORTEX_M0?=0
+NO_ASM?=0
+EXT_FLASH?=1
+SPI_FLASH?=0
+NO_XIP?=0
+UART_FLASH?=1
+ALLOW_DOWNGRADE?=0
+NVM_FLASH_WRITEONCE?=1
+WOLFBOOT_VERSION?=0
+V?=0
+NO_MPU?=0
+SPMATH?=1
+RAM_CODE?=0
+DUALBANK_SWAP?=0
+IMAGE_HEADER_SIZE?=256
+PKA?=0
+ENCRYPT=1
+WOLFTPM?=0
+WOLFBOOT_PARTITION_SIZE?=0x20000
+WOLFBOOT_SECTOR_SIZE?=0x1000
+WOLFBOOT_PARTITION_BOOT_ADDRESS?=0x08010000
+WOLFBOOT_PARTITION_UPDATE_ADDRESS?=0x0
+WOLFBOOT_PARTITION_SWAP_ADDRESS?=0x20000

config/examples/stm32wb-uart-flash-encryption.config

@@ -0,0 +1,109 @@
+## 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 distributing, 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, const uint8_t *nonce);
+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 retrieved 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 `key` provided to `wolfBoot_set_encrypt_key()` must be exactly 32 Bytes long.
+ - The `nonce` argument must be a 96-bit (12 Bytes) randomly generated buffer, to be used as IV for encryption and decryption.
+
+## Example usage
+
+### Signing and encrypting the update bundle
+
+The `sign.py` tool can sign and encrypt the image with a single command.
+The encryption secret is provided in a binary file that should contain a concatenation of
+a 32B ChaCha-256 key and a 12B nonce.
+
+In the examples provided, the test application uses the following parameters:
+
+```
+key = "0123456789abcdef0123456789abcdef"
+nonce = "0123456789ab"
+```
+
+So it is easy to prepare the encryption secret in the test scripts or from the command line using:
+
+```
+echo -n "0123456789abcdef0123456789abcdef0123456789ab" > enc_key.der
+```
+
+The `sign.py` script can now be invoked to produce a signed+encrypted image, by using the extra argument `--encrypt` followed by the
+secret file:
+
+```
+./tools/keytools/sign.py --encrypt enc_key.der test-app/image.bin ecc256.der 24
+
+```
+
+which will produce as output the file `test-app/image_v24_signed_and_encrypted.bin`, that can be transferred to the target's external device.
+
+
+### API usage in the application
+
+When transferring the image, the application can still use the libwolfboot API functions to store the encrypted firmware. When called from the application,
+the function `ext_flash_write` will store the payload unencrypted.
+
+In order to trigger an update, before calling `wolfBoot_update_trigger` it is necessary to set the temporary key used by the bootloader by calling `wolfBoot_set_encrypt_key`.
+
+An example of encrypted update trigger can be found in the [stm32wb test application source code](test-app/app_stm32wb.c).
+
+
+
+

docs/encrypted_partitions.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 previous 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.
+
+
+
+