new file mode 100644
@@ -0,0 +1,153 @@
+.. SPDX-FileCopyrightText: 2023 Michael Glembotzki <michael.glembotzki@iris-sensing.com>
+.. SPDX-License-Identifier: GPL-2.0-only
+
+Asymmetrically Encrypted Update Images
+======================================
+
+Asymmetrically encrypted update images are realized by an asymmetrical
+encrypted sw-description, making it possible to encrypt images device specific.
+The artifacts persist in being symmetrically encrypted by retrieving an AES key
+from the sw-description, which may be the same or distinct for each artifact.
+Cryptographic Message Syntax (CMS) with OpenSSL is used for encryption.
+
+
+Use Cases
+---------
+
+- Asymmetrically encrypted update images, with individual device key pairs, are
+ inherently more secure than a purely symmetrical solution, because one
+ compromised device does not affect the security of the other devices.
+- If a device with its private key has been compromised, the key pair can be
+ removed from the list of devices (in the new CMS) eligible to receive new
+ update images.
+- The AES key can be exchanged with each new update image, because it is part
+ of the sw-description.
+- The AES key may be the same or distinct for each artifact in the
+ sw-description.
+
+
+Create a Self-Signed Device Key Pair
+------------------------------------
+
+As an example, an elliptic curve key pair (PEM) is generated for a single
+device. These steps must be repeated for all other recipient devices. An RSA
+key pair functions equally effectively.
+
+::
+
+ # Create a private key and a self-signed certificate
+ openssl ecparam -name secp521r1 -genkey -noout -out device-key-001.pem
+ openssl req -new -x509 -key device-key-001.pem -out device-cert-001.pem -subj "/O=SWUpdate /CN=target"
+
+ # Combine the private key and the certificate into a single file
+ cat device-key-001.pem device-cert-001.pem > device-001.pem
+
+
+Symmetric Encryption of Artifacts
+---------------------------------
+
+Generate an AES key and IV, as familiar from
+:ref:`symmetric image encryption <sym-encrypted-images>`. The encryption
+process for the artifacts remains unchanged.
+
+
+Encryption of sw-description for Multiple Devices
+-------------------------------------------------
+
+All device certificates are used for encryption.
+
+::
+
+ # Encrypt sw-description for multiple recipient devices
+ openssl cms -encrypt -aes-256-cbc -in <INFILE> -out <OUTFILE> -outform DER -recip <CERT_1> <CERT_2> <CERT_X>
+
+Replace ``<INFILE>`` with the plain `sw-description` (e.g.
+`sw-description.in`) and the encrypted ``<OUTFILE>`` with `sw-description`.
+``<CERT_1>``, ``<CERT_2>``, [...] ``<CERT_X>`` constitute the comprehensive
+list of recipient devices intended for encryption.
+
+
+Decryption of sw-description for a Single Device
+------------------------------------------------
+
+The combined key pair (private key and certificate) is used for decryption.
+SWUpdate handles the decryption process autonomously. Manually executing this
+step is not necessary and is provided here solely for development purposes.
+
+::
+
+ # Decrypt sw-description for a single recipient device
+ openssl cms -decrypt -in <INFILE> -out ``<OUTFILE>`` -inform DER -inkey <PRIVATE_KEY_1> -recip <CERT_1>
+
+Replace the encrypted ``<INFILE>`` with `sw-description` and the
+``<OUTFILE>`` with plain `sw-description` (e.g. `sw-description.in`).
+``<PRIVATE_KEY_1>`` and ``<CERT_1>`` are used for the decryption.
+
+
+
+
+Example Asymmetrically Encrypted Image
+--------------------------------------
+
+The image artifacts should be symmetrically encrypted and signed in advance.
+Now, create a plain `sw-description.in` file. The attributes ``encrypted``,
+``aes-key`` and ``ivt`` are required for encrypted artifacts.
+
+::
+
+ software =
+ {
+ version = "0.0.1";
+ images: ( {
+ filename = "rootfs.ext4.enc";
+ device = "/dev/mmcblk0p3";
+ sha256 = "131159df3a4efaa890ff80173664a125c496c458dd432a8a6acae18872e35822";
+ encrypted = true;
+ aes-key = "ed73b9d3bf9c655d5a0b04836d8be48660a4a4bb6f4aa07c6778e00e342881ac";
+ ivt = "ea34a55a0c3476ed78f238ac87a7970c";
+ });
+ }
+
+
+Asymmetrically encrypt the `sw-description` for multiple recipient devices:
+::
+
+ openssl cms -encrypt -aes-256-cbc -in sw-description.in -out sw-description -outform DER -recip device-cert-001.pem device-cert-002.pem device-cert-003.pem
+
+
+
+Create the new update image (SWU):
+
+::
+
+ #!/bin/sh
+
+ FILES="sw-description sw-description.sig rootfs.ext4.enc"
+
+ for i in $FILES; do
+ echo $i;done | cpio -ov -H crc > firmware.swu
+
+
+Running SWUpdate with Asymmetrically Encrypted Images
+-----------------------------------------------------
+
+Asymmetric encryption support can be enabled by configuring the compile-time
+option ``CONFIG_ASYM_ENCRYPTED_SW_DESCRIPTION``. To pass the combined
+recipient key pair (PEM) generated earlier to SWUpdate, use the ``-r``
+argument. Alternatively, use the ``recip-keypair`` parameter in the
+``swupdate.cfg``.
+
+
+Security Considerations
+-----------------------
+- Ideally, generate the private key on the device during factory provisioning,
+ ensuring it never leaves the device. Only the public certificate leaves the
+ device for encrypting future update packages.
+- This feature should be used in conjunction with signature verification
+ (``CONFIG_SIGNED_IMAGES``) to ensure data integrity. In principle, anyone
+ with the corresponding device certificate can create update packages.
+- As a side effect, the size of the update package may significantly increase
+ in a large-scale deployment. To enhance scalability, consider using group
+ keys. Smaller groups are better than larger ones.
+- Exchange the AES key with each update package.
+- Refrain from encrypting new update packages for compromised devices.
@@ -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
=============================
@@ -1441,8 +1441,17 @@ There are 4 main sections inside sw-description:
| | | scripts | and must be decrypted before |
| | | | installing. |
+-------------+----------+------------+---------------------------------------+
- | ivt | string | images | IVT in case of encrypted artefact |
- | | | files | It has no value if "encrypted" is not |
+ | aes-key | string | images | AES key in case of an encrypted |
+ | | | files | artefact. It has no effect if not |
+ | | | scripts | compiled with |
+ | | | | `CONFIG_ASYM_ENCRYPTED_SW_DESCRIPTION`|
+ | | | | or if attribute "encrypted" is not |
+ | | | | set. Each artefact can have an own |
+ | | | | AES key. It is an ASCII hex string |
+ | | | | of 16/24/32 chars. |
+ +-------------+----------+------------+---------------------------------------+
+ | ivt | string | images | IVT in case of an encrypted artefact. |
+ | | | files | It has no effect if "encrypted" is not|
| | | scripts | set. Each artefact can have an own |
| | | | IVT to avoid attacker can guess the |
| | | | the key. |
Signed-off-by: Michael Glembotzki <Michael.Glembotzki@iris-sensing.com> --- doc/source/asym_encrypted_images.rst | 153 +++++++++++++++++++++++++++ doc/source/encrypted_images.rst | 2 + doc/source/index.rst | 1 + doc/source/roadmap.rst | 5 - doc/source/sw-description.rst | 13 ++- 5 files changed, 167 insertions(+), 7 deletions(-) create mode 100644 doc/source/asym_encrypted_images.rst