new file mode 100644
@@ -0,0 +1,121 @@
+.. SPDX-FileCopyrightText: 2023 Michael Glembotzki <michael.glembotzki@iris-sensing.com>
+.. SPDX-License-Identifier: GPL-2.0-only
+
+Asymmetrically Encrypted Update Images
+======================================
+
+To individually encrypt SWU images for any number of recipient devices,
+asymmetric image encryption is a suitable option. An asymmetrically encrypted
+AES file is decrypted and loaded from a Cryptographic Message Syntax file (DER)
+from within an SWU image. The AES key and IV are set from the decrypted AES
+file before processing any other files. The special feature is that only the
+decryption key is encrypted per device (or device group). The artifacts
+themselves remain symmetrically encrypted.
+
+
+Why asymmetrical encryption?
+----------------------------
+To be able to rotate the symmetrical aes key. In the
+:ref:`symmetric image encryption <sym-encrypted-images>`, the AES file
+(containing the symmetric key and initialization vector) cannot be rotated.
+This becomes problematic if the key is lost, as all devices are affected. A new
+key could always be decrypted with the current key. Once lost, it means lost
+forever.
+
+
+Creating self-signed Recipient Keypair's
+----------------------------------------
+
+As an example, an elliptic curve private key, a self-signed certificate and a
+combined keypair (PEM) are created for one recipient. This step must be
+repeated for all other recipients as well. An RSA key pair works just as well.
+
+::
+
+ # Private key and self-signed Certificate
+ openssl ecparam -name secp521r1 -genkey -noout -out recip-key-001.pem
+ openssl req -new -x509 -key recip-key-001.pem -out recip-cert-001.pem -subj "/O=SWUpdate /CN=target"
+
+ # Combined Recipient Keypair
+ cat recip-key-001.pem recip-cert-001.pem > recip-001.pem
+
+
+Create the AES file and encrypt artefacts
+-----------------------------------------
+
+Create a key and IV as already known from :ref:`symmetric image encryption <sym-encrypted-images>`.
+The encryption of the artifacts has not changed.
+
+::
+
+ # Create the AES file
+ KEY=$(openssl rand -hex 32); IV=$(openssl rand -hex 16)
+ echo "$KEY $IV" > aesfile
+
+ # Encryption of an artifact
+ INFILE=pre_post_inst.sh; OUTFILE=pre_post_inst.sh.enc
+ openssl enc -aes-256-cbc -in $INFILE -out $OUTFILE -K $KEY -iv $IV
+
+
+Create the encrypted AES file for multiple recipients
+-----------------------------------------------------
+
+All recipient certificates are required for the encryption, but not the private
+keys. The recipient key pair (private key + certificate combined) must be
+installed on the devices. The cert is optional on the devices, but speeds up
+decryption through faster key matching.
+
+::
+
+ # Encrypt for multiple recipients
+ openssl cms -encrypt -aes-256-cbc -in aesfile -out encrypted-aesfile -outform DER -recip recip-cert-001.pem recip-cert-002.pem recip-cert-003.pem
+
+ # Decrypt for one of the recipients (for the sake of completeness)
+ openssl cms -decrypt -in encrypted-aesfile -inform DER -out aesfile -inkey recip-key-001.pem # or recip-001.pem (Combined Recipient Keypair)
+
+
+Building an asymmetric encrypted SWU image
+------------------------------------------
+
+A simple script to create an asymmetric encrypted SWU image:
+
+::
+
+ #!/bin/sh
+
+ FILES="encrypted-aesfile sw-description sw-description.sig pre_post_inst.sh.enc"
+
+ for i in $FILES; do
+ echo $i;done | cpio -ov -H crc > firmware.swu
+
+
+Running SWUpdate with Encrypted Images
+--------------------------------------
+
+Asymmetric encryption support is enabled by setting the
+``ASYM_ENCRYPTED_AESFILE`` option in SWUpdate's configuration. Use the ``-r``
+parameter to provide the combined recipient keypair (PEM) generated above to
+SWUpdate. Alternativly use the parameter ``recip-keypair`` in the swupdate.cfg.
+
+
+Limitation
+----------
+
+- The encrypted AES file must be the first file in the SWU before
+ sw-description and sw-description.sig, if any.
+- The encrypted AES file must be present in all SWU's.
+- A Recipient Keypair (private key and cert) combined in one file (PEM) must be
+ provided at SWUpdate startup.
+
+
+Security considerations
+------------------------------------------
+- The AES file (AES key and iv) can and should always be rotated.
+- This feature should be used together with signature verification:
+ ``SIGNED_IMAGES``. Otherwise with the appropriate recipe certificate, an
+ attacker can create an SWU image that would be accepted.
+- Group keys should be considered for a larger number of devices, because the
+ size of the encrypted AES file and therefore the size of the SWU image grows
+ with each recipient device.
+- If a private recipient key is lost, only one device (or device group) is
+ affected.
@@ -1,6 +1,8 @@
.. SPDX-FileCopyrightText: 2013-2021 Stefano Babic <sbabic@denx.de>
.. SPDX-License-Identifier: GPL-2.0-only
+.. _sym-encrypted-images:
+
Symmetrically Encrypted Update Images
=====================================
@@ -41,6 +41,7 @@ SWUpdate Documentation
sw-description.rst
signed_images.rst
encrypted_images.rst
+ asym_encrypted_images.rst
handlers.rst
mongoose.rst
suricatta.rst
@@ -138,11 +138,6 @@ BTRFS supports subvolume and delta backup for volumes - supporting subvolumes is
to move the delta approach to filesystems, while SWUpdate should apply the deltas
generated by BTRFS utilities.
-Security
-========
-
-- add support for asymmetryc decryption
-
Support for evaluation boards
=============================
Signed-off-by: Michael Glembotzki <Michael.Glembotzki@iris-sensing.com> --- doc/source/asym_encrypted_images.rst | 121 +++++++++++++++++++++++++++ doc/source/encrypted_images.rst | 2 + doc/source/index.rst | 1 + doc/source/roadmap.rst | 5 -- 4 files changed, 124 insertions(+), 5 deletions(-) create mode 100644 doc/source/asym_encrypted_images.rst