Add encrypt images design/usage documentation
Signed-off-by: Fabio Utzig <utzig@apache.org>
diff --git a/docs/design.md b/docs/design.md
index 5bd0b6a..4da4c99 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -685,3 +685,6 @@
For information on embedding public keys in the boot loader, as well as
producing signed images, see: [signed_images](signed_images.md).
+
+If you want to enable and use encrypted images, see:
+[encrypted_images](encrypted_images.md).
diff --git a/docs/encryped_images.md b/docs/encryped_images.md
new file mode 100644
index 0000000..82700e3
--- /dev/null
+++ b/docs/encryped_images.md
@@ -0,0 +1,120 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+-->
+
+## Rationale
+
+To provide confidentiality of image data while in transport to the
+device or while residing on an external flash, `MCUBoot` has support
+for encrypting/decrypting images on-the-fly while upgrading.
+
+The image header needs to flag this image as `ENCRYPTED` (0x04) and
+a TLV with the key must be present in the image. When upgrading the
+image from `slot1` to `slot0` it is automatically decrypted (after
+validation). If swap upgrades are enabled, the image located in `slot0`,
+also having the `ENCRYPTED` flag set and the TLV present, is
+re-encrypted while swapping to `slot1`.
+
+## Threat model
+
+The encrypted image support is supposed to allow for confidentiality
+if the image is not residing on the device or is written to external
+storage, eg a SPI flash being used for slot1.
+
+It does not protect against the possibility of attaching a JTAG and
+reading the internal flash memory, or using some attack vector that
+enables dumping the internal flash in any way.
+
+Since decrypting requires a private key (or secret if using symetric
+crypto) to reside inside the device, it is the responsibility of the
+device manufacturer to guarantee that this key is already in the device
+and not possible to extract.
+
+## Design
+
+When encrypting an image, only the payload (FW) is encrypted. The header,
+TLVs are still sent as plain data.
+
+Hashing and signing also remain functionally the same way as before,
+applied over the un-encrypted data. Validation on encrypted images, checks
+that the encrypted flag is set and TLV data is OK, then it decrypts each
+image block before sending the data to the hash routines.
+
+The image is encrypted using AES-CTR-128, with a counter that starts
+from zero (over the payload blocks) and increments by 1 for each 16-byte
+block. AES-CTR-128 was chosen for speed/simplicity and allowing for any
+block to be encrypted/decrypted without requiring knowledge of any other
+block (allowing for simple resume operations on swap interruptions).
+
+The key used is a randomized when creating a new image, by `imgtool` or
+`newt`. This key should never be reused and no checks are done for this,
+but randomizing a 16-byte block with a TRNG should make it highly
+improbable that duplicates ever happen.
+
+To distribute this AES-CTR-128 key, new TLVs were defined. The key can be
+encrypted using either RSA-OAEP or AES-KW-128. Also in the future support
+for EICES (using EC) can be added.
+
+For RSA-OAEP a new TLV with value `0x30` is added to the image, for
+AES-KW-128 a new TLV with value `0x31` is added to the image. The contents
+of both TLVs are the results of applying the given operations over the
+AES-CTR-128 key.
+
+## Upgrade process
+
+When starting a new upgrade process, `MCUBoot` checks that the image in
+`slot1` has the `ENCRYPTED` flag set and has the required TLV with the
+encrypted key. It then uses its internal private/secret key to decrypt
+the TLV containing the key. Given that no errors are found, it will then
+start the validation process, decrypting the blocks before check. A good
+image being determined, the upgrade consists in reading the blocks from
+`slot1`, decrypting and writing to `slot0`.
+
+If swap is used for the upgrade process, the encryption happens when
+copying the sectors of `slot1` to the scratch area.
+
+The `scratch` area is not encrypted, so it must reside in the internal
+flash of the MCU to avoid attacks that could interrupt the upgrade and
+dump the data.
+
+Also when swap is used, the image in `slot0` is checked for presence of
+the `ENCRYPTED` flag and the key TLV. If those are present the sectors
+are re-encrypted when copying from `slot0` to `slot1`.
+
+PS: Each encrypted image must have its own key TLV that should be unique
+and used only for this particular image.
+
+Also when swap method is employed, the sizes of both images are saved to
+the status area just before starting the upgrade process, because it
+would be very hard to determine this information when an interruption
+occurs and the information is spread across multiple areas.
+
+## Creating your keys
+
+<!--
+TODO: expand this section or add specific docs to imgtool, newt...
+
+XXX: add current key access method (reverse direction from sign)
+-->
+
+* If using RSA-OAEP, generating a keypair follows steps similar to those
+ described in [signed_images](signed_images.md)
+* If using AES-KW-128 (`newt` only), the `kek` can be generated with a
+ command like `dd if=/dev/urandom bs=1 count=16 | base64 > my_kek.b64`
diff --git a/docs/imgtool.md b/docs/imgtool.md
index eaf36da..1d5a7d7 100644
--- a/docs/imgtool.md
+++ b/docs/imgtool.md
@@ -59,7 +59,7 @@
--align [1|2|4|8] [required]
-v, --version TEXT [required]
-H, --header-size INTEGER [required]
- --pad-header Add `--header-size` zeroed bytes at the beginning
+ --pad-header Add --header-size zeroed bytes at the beginning
of the image
-S, --slot-size INTEGER Size of the slot where the image will be written
[required]
@@ -68,6 +68,8 @@
-M, --max-sectors INTEGER When padding allow for this amount of sectors
(defaults to 128)
--overwrite-only Use overwrite-only instead of swap upgrades
+ -e, --endian [little|big] Select little or big endian
+ -E, --encrypt filename Encrypt image using the provided public key
-h, --help Show this message and exit.
The main arguments given are the key file generated above, a version
@@ -90,6 +92,6 @@
not being used, `--overwrite-only` can be passed to avoid adding the swap
status area size when calculating overflow.
-The optional --pad argument will place a trailer on the image that
+The optional `--pad` argument will place a trailer on the image that
indicates that the image should be considered an upgrade. Writing
this image in slot 1 will then cause the bootloader to upgrade to it.