Merge pull request #41 from danielinux/wolfboot-1.11-update

Updated manual to wolfBoot-1.11

Author: lealem47

wolfBoot/src/chapter02.md

@@ -170,7 +170,7 @@ For more details, see the section [Remote External flash memory support via UART
 
 #### Encryption support for external partitions
 
-When update and swap partitions are mapped to an external device using `EXT_FLASH=1`, either in combination with `SPI_FLASH`, `UART_FLASH`, or any custom external mapping, it is possible to enable ChaCha20 encryption when accessing those partition from the bootloader. The update images must be pre-encrypted at the source using the key tools, and wolfBoot should be instructed to use a temporary ChaCha20 symmetric key to access the content of the updates.
+When update and swap partitions are mapped to an external device using `EXT_FLASH=1`, either in combination with `SPI_FLASH`, `UART_FLASH`, or any custom external mapping, it is possible to enable ChaCha20, Aes128 or Aes256 encryption when accessing those partition from the bootloader. The update images must be pre-encrypted at the source using the key tools, and wolfBoot should be instructed to use a temporary ChaCha20 symmetric key to access the content of the updates.
 
 For more details about this optional feature, please refer to the [Encrypted external partitions](chapter06.md#encrypted-external-partitions) section.
 
@@ -221,3 +221,9 @@ LC_ALL=
 
 Then run the normal `make` steps.
 
+### Enabling mitigations against glitches and fault injections
+
+One type of attacks against secure boot mechanisms consists in skipping the execution of authentication and validation steps by injecting faults into the CPU through forced voltage or clock anomalies, or electromagnetic interferences at close range.
+
+Extra protection from specific attacks aimed to skip CPU instructions can be enabled using `ARMOR=1`. This feature is currently only available for ARM Cortex-M targets.
+

wolfBoot/src/chapter03.md

@@ -869,22 +869,25 @@ the monitor command sequence below:
 
 ## NXP iMX-RT
 
-NXP RT1060/1062 (RT1060-EVK)
+NXP RT1060/1062 and RT1050
 
 The NXP iMX-RT1060 is a Cortex-M7 with a DCP coprocessor for SHA256 acceleration.
 Example configuration for this target is provided in `/config/examples/imx-rt1060.config`.
 
 ### Building wolfBoot
 
 MCUXpresso SDK is required by wolfBoot to access device drivers on this platform.
-A package can be obtained from the [MCUXpresso SDK Builder](https://mcuxpresso.nxp.com/en/welcome), by selecting `EVK-MIMXRT1060` as target, and keeping the default choice of components.
+A package can be obtained from the [MCUXpresso SDK Builder](https://mcuxpresso.nxp.com/en/welcome), by selecting a target and keeping the default choice of components.
 
-Set the `MCUXPRESSO` configuration variable to the path where the SDK package is extracted, then build wolfBoot normally by running `make`.
+* For the RT1060 use `EVKB-IMXRT1060`. See configuration example in `config/examples/imx-rt1060.config`.
+* For the RT1050 use `EVKB-IMXRT1050`. See configuration example in `config/examples/imx-rt1050.config`.
 
-wolfBoot support for iMX-RT1060 has been tested using MCUXpresso SDK version 2.8.2.
+Set the wolfBoot `MCUXPRESSO` configuration variable to the path where the SDK package is extracted, then build wolfBoot normally by running `make`.
+
+wolfBoot support for iMX-RT1060/iMX-RT1050 has been tested using MCUXpresso SDK version 2.11.1.
 
 DCP support (hardware acceleration for SHA256 operations) can be enabled by using PKA=1 in the configuration file.
-Firmware can be directly uploaded to the target by copying `factory.bin` to the virtual USB drive associated to the device (RT1060-EVK).
+Firmware can be directly uploaded to the target by copying `factory.bin` to the virtual USB drive associated to the device.
 
 
 ## NXP Kinetis

wolfBoot/src/chapter06.md

@@ -418,16 +418,24 @@ can be used to set a temporary encryption key for the external partition, or era
 
 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
+### Symmetric encryption algorithms
 
-The algorithm currently used to encrypt and decrypt data in external partitions is Chacha20-256.
+Encryption can be enabled in wolfBoot using `ENCRYPT=1`.
+
+The default algorithm used to encrypt and decrypt data in external partitions is Chacha20-256.
+AES-128 and AES-256 options are also available and can be selected using  `ENCRYPT_WITH_AES128=1` or `ENCRYPT_WITH_AES256=1`
+
+### Chacha20-256
+
+
+When ChaCha20 is selected:
 
  - 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
+#### Example usage with ChaCha20-256
+
 
 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.
 
@@ -453,6 +461,44 @@ secret file:
 
 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.
 
+### AES-CTR
+
+
+AES is used in CTR mode. When AES is selected:
+ - The `key` provided to `wolfBoot_set_encrypt_key()` must be 16 Bytes (AES128) or 32 Bytes (AES256) long.
+ - The `nonce` argument is a 128-bit (16 Byyes) randomly generated buffer, used as initial counter for encryption and decryption.
+
+
+#### Example usage with AES-256
+
+
+In case of AES-256, the encryption secret is provided in a binary file that should contain a concatenation of
+a 32B key and a 16B IV.
+
+In the examples provided, the test application uses the following parameters:
+
+```
+key = "0123456789abcdef0123456789abcdef"
+iv = "0123456789abcdef"
+```
+
+So it is easy to prepare the encryption secret in the test scripts or from the command line using:
+
+```
+echo -n "0123456789abcdef0123456789abcdef0123456789abcdef" > 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. To select AES-256, use the `--aes256` option.
+
+```
+./tools/keytools/sign.py --aes256 --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