From patchwork Mon Dec 4 10:05:42 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Glembotzki X-Patchwork-Id: 1871483 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=googlegroups.com header.i=@googlegroups.com header.a=rsa-sha256 header.s=20230601 header.b=J3sLHkVL; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256 header.s=20230601 header.b=EUzvnwSB; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=googlegroups.com (client-ip=2a00:1450:4864:20::337; helo=mail-wm1-x337.google.com; envelope-from=swupdate+bncbdy5juxlviebbk6jw2vqmgqest7bxvi@googlegroups.com; receiver=patchwork.ozlabs.org) Received: from mail-wm1-x337.google.com (mail-wm1-x337.google.com [IPv6:2a00:1450:4864:20::337]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (secp384r1) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4SkK803cHGz1yST for ; Mon, 4 Dec 2023 21:06:40 +1100 (AEDT) Received: by mail-wm1-x337.google.com with SMTP id 5b1f17b1804b1-40b3dbe99d9sf34479795e9.1 for ; Mon, 04 Dec 2023 02:06:40 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1701684397; cv=pass; d=google.com; s=arc-20160816; b=SPissP26BrpnXWZXAovROd8BzgUciLOayKtNxX/KEgJHwjWt8pzHAJZ61Bl6ecm5p+ wB8jkwFF9iB5rjsfcRrFUUrCuKVQnXV5myDhgzWLhsp6tkJBK7So81/tX6WKXt4+8XhR ocqq8xylDwH2HRBcPcAWaSRK2WG05Rb7wtJQ9/vYEx4OlnXyEolaO/CgJ8PBIPDiXhww 9cBnR4asWR1/Zjxjk578lp+jRBI/mdtYO3kU2hG84KJx5j4mbRflAMTnUvLk15FDuDw7 tB0y+IPx/MKBAx7Q6TFAP+OGSPJvv8b5buYqNPOdl2A5i4RUz/D61WKRYZp9TAFEAwI0 EmFQ== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :list-id:mailing-list:precedence:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:sender:dkim-signature :dkim-signature; bh=yoXZTVeMxAtMalz60jEkth/JWskKEUE4+6cafea0Wf8=; fh=zydHuzCQWrku2OPQyZfraJZFcOpEXLQ/YBcu3QNiBd0=; b=bU0d+rZMJOJN10XQ3Lyt4jpM9kByWCFSyIzDvhyWPChogsbU0rDN4HuE0DH2bCJdWy G6cFrcydVxwAQvZRMnJQ+M30AveocJ8nhfpoqG9ewVairHVmRDHT3SaHkFJlTv/VprUo FxO7LaTMfbkJDCyYzCicw7PTm5lD6VFEmNAqcCOdXzLK+fbhAHZAA7DYmgPGl5PFEhBI pfu8ScLyuxQwaKALz82znLmdYy/ULurvAT1v/J66MCIdtJeJIx6KMtkPzAQTI4q7zC52 suqHA1Q8F22w6PMLBgIVDq1FTbp9GsrKw0Ln6oyGSjcKyZ62frexCyKQZfTB99OwNJKR ajYA== ARC-Authentication-Results: i=2; gmr-mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=QntKOSH4; spf=pass (google.com: domain of m.glembo@gmail.com designates 2a00:1450:4864:20::633 as permitted sender) smtp.mailfrom=m.glembo@gmail.com; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=googlegroups.com; s=20230601; t=1701684397; x=1702289197; darn=patchwork.ozlabs.org; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :list-id:mailing-list:precedence:x-original-authentication-results :x-original-sender:mime-version:references:in-reply-to:message-id :date:subject:cc:to:from:sender:from:to:cc:subject:date:message-id :reply-to; bh=yoXZTVeMxAtMalz60jEkth/JWskKEUE4+6cafea0Wf8=; b=J3sLHkVLvpFrinljpl0UoeWAMQqtamTcjyAnXvjqLeStYIB+8pW3ojcVy+u9u57W16 MMCqbXpsn6geuRr41oCZfrWUuIaILtKm3PFQ27RdWdHe6qFoshlFXKNXc7xKxbR3Qk3T UNzHiNkVma+yu8t5pAAZ9pj+h59xvC+B5racMHPDfNGsVHSFA9w8JfEytrdNtwlkwpT0 bIU66JUvDturyzWeqhfpUBt5RY7D09Fd/amZ9mE5vWaXnzwuLEJY9qeMDS2uOLeGNam8 TU7y73j7Apkautp/8/r1LpzRB1njjHOjJYllI489lnSsYkvCKK+Q7sKpO3IcCPYtVyBr kY6Q== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1701684397; x=1702289197; darn=patchwork.ozlabs.org; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :list-id:mailing-list:precedence:x-original-authentication-results :x-original-sender:mime-version:references:in-reply-to:message-id :date:subject:cc:to:from:from:to:cc:subject:date:message-id:reply-to; bh=yoXZTVeMxAtMalz60jEkth/JWskKEUE4+6cafea0Wf8=; b=EUzvnwSBdEUTcTv0FkBklGQN8TIhPXJgQdVR/luZi8yT+KxsdLO+axCCvs2PUxY/HH 43Ysfd+4XZUlySB+thIg0z/lFyJGKMGOJ3uwJaOGI/diLhbUnRWEf93A4EVpWEucd971 fMRNooUZy2wL/621DvKo1hys6JPCNPPVdVB/CG3pO0wVjRp58jerA8RZieHfCThZ4Vi1 XDQv0SiUP3doAqakJxsB2rFKRG+Wbxeg1ggrG84ZyKatEvRU+43uz6LAD4HeVRFj8k7E O1Jevr73JFoApo341Wbtmy/MMQSCmQ6xd0tq8Kgjhz2h4r7BqH5SLHnmNK5/E6vll3U5 GUyQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1701684397; x=1702289197; h=list-unsubscribe:list-subscribe:list-archive:list-help:list-post :x-spam-checked-in-group:list-id:mailing-list:precedence :x-original-authentication-results:x-original-sender:mime-version :references:in-reply-to:message-id:date:subject:cc:to:from :x-beenthere:x-gm-message-state:sender:from:to:cc:subject:date :message-id:reply-to; bh=yoXZTVeMxAtMalz60jEkth/JWskKEUE4+6cafea0Wf8=; b=V4vde5Kv2k6L0IanMxATkWIvAzHBrRbeYgO2qyazEJ5wkx7FjKEumKBiqn8lSYkRW/ eK/JAMLwP0r5wVEhPtLdQ6e+7ZOy+SfLhscvrOBik/739wsLxR0ay2g6tX2x3BSOt/pN oXDJzNkXhlUEWkmAaW/Z5ezxT6Xa+zgjB4H+NkwqzhvDZVftM3ckAdsKzdGKx5zbTouL 0NpywtN2vKg64wUqke+wVpyXiqVnMuWuNGqejO97cyuddsV1GzJ3mIvsPbbIii1V2mco UsBbGcBn+09Zs1xTWOve9C8k18oO17d4kI826jx8XvZ/0trLOCGMf/kxnBAZcRitb4Cr yFOQ== Sender: swupdate@googlegroups.com X-Gm-Message-State: AOJu0YwNcfp8G8TP4UZ04KC+susK/GHda+n8ltlswEyL6TvMqlGVmtU9 tVAkQML85PyzHKN/zcDfPqM= X-Google-Smtp-Source: AGHT+IF+Ue7oRyCersftruRa+GNVtJEUvk67HFZkFOQXXWYbkanuYpA8zZWCsjUxQsGoe+s4U/vhbw== X-Received: by 2002:a05:600c:3d8d:b0:40b:5e21:cc18 with SMTP id bi13-20020a05600c3d8d00b0040b5e21cc18mr2198601wmb.67.1701684396482; Mon, 04 Dec 2023 02:06:36 -0800 (PST) X-BeenThere: swupdate@googlegroups.com Received: by 2002:a05:600c:1e20:b0:40b:3148:1b7e with SMTP id ay32-20020a05600c1e2000b0040b31481b7els2640720wmb.2.-pod-prod-03-eu; Mon, 04 Dec 2023 02:06:34 -0800 (PST) X-Received: by 2002:a05:600c:929:b0:40b:5e59:b7c7 with SMTP id m41-20020a05600c092900b0040b5e59b7c7mr2308508wmp.164.1701684394224; Mon, 04 Dec 2023 02:06:34 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1701684394; cv=none; d=google.com; s=arc-20160816; b=Zkiszj7pRhLGY++duNBRGPtM6FAW0vm3n4pmSkb57y3UqfKvo5NhJs0OJlPATfvku4 YyAF/IOfTAE7ucYtzfz1YhSUpnAbCOMR8jKcg5VrLJjktXcc2j0txvBDXFw2MlgQ41kQ TSQylmFVcZD2Z2YRRMxpg7P/5rP04571VpXni59Aj0zUWN16/DdvtNzS9rEqRWgjcdHC PuUZDbmmxJIIHUqc8KhhfynQzLc9KxNZxNmCecj3VuLMULK3lkNXIUv2O1M50JEaqbVV eCZ3Qp5tOLXSGGnnPb0VNZlKjEgw9YvQVxqM8k6H8rJINh7AQCNsA16rO/phk4/3Xdn+ NWVQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:dkim-signature; bh=lfqyX1vuiekBtNRykJNUPF7eKuSnJrvo/3SPEagdkpI=; fh=zydHuzCQWrku2OPQyZfraJZFcOpEXLQ/YBcu3QNiBd0=; b=KmRs3frzKJKGgL6NdlaHh7IXrf7CzYmQYCEk1St+c8/RzaoAR2A6cY7j4saPtAkOoU KMRK+HP3jnJt3mM2n2Pic9AyiP0g7uQOQPTu0LYN/4psKYwabOcOIR6eyu70KJCNzZAa B+cpZaedQmEeMNtqVIdNd5VFNWSj5rxJOqEm7dOhrWJLJ8AZiCoJttag9m3xP3MwBNvH 2UaGk7HP5b0mXQLiB+uW7IbDlyaaABKZ5qd/2lG8wyFbfop7M03bK+10hUnrmL9dtp7U Pb0bARmiXnkg5JGssT+7QcEa/koJDyqF3huA91O0DAfwh/kJt+SXvUzFn1JgwfCx3Mpc nV+g== ARC-Authentication-Results: i=1; gmr-mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=QntKOSH4; spf=pass (google.com: domain of m.glembo@gmail.com designates 2a00:1450:4864:20::633 as permitted sender) smtp.mailfrom=m.glembo@gmail.com; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from mail-ej1-x633.google.com (mail-ej1-x633.google.com. [2a00:1450:4864:20::633]) by gmr-mx.google.com with ESMTPS id u20-20020a05600c139400b0040b47a6405bsi560676wmf.1.2023.12.04.02.06.34 for (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Mon, 04 Dec 2023 02:06:34 -0800 (PST) Received-SPF: pass (google.com: domain of m.glembo@gmail.com designates 2a00:1450:4864:20::633 as permitted sender) client-ip=2a00:1450:4864:20::633; Received: by mail-ej1-x633.google.com with SMTP id a640c23a62f3a-a186e5d1056so547042466b.0 for ; Mon, 04 Dec 2023 02:06:34 -0800 (PST) X-Received: by 2002:a17:906:208d:b0:a17:d9c8:d9d3 with SMTP id 13-20020a170906208d00b00a17d9c8d9d3mr3440790ejq.12.1701684393253; Mon, 04 Dec 2023 02:06:33 -0800 (PST) Received: from PC-2635.irisgmbh.local (dslb-002-203-161-041.002.203.pools.vodafone-ip.de. [2.203.161.41]) by smtp.gmail.com with ESMTPSA id js22-20020a17090797d600b00a1b32663d7csm2032919ejc.102.2023.12.04.02.06.32 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 04 Dec 2023 02:06:32 -0800 (PST) From: Michael Glembotzki To: swupdate@googlegroups.com Cc: Michael Glembotzki Subject: [swupdate] [V2][PATCH 10/10] doc: Add documentation for asymmetric decryption Date: Mon, 4 Dec 2023 11:05:42 +0100 Message-ID: <20231204100620.27789-11-Michael.Glembotzki@iris-sensing.com> X-Mailer: git-send-email 2.42.0 In-Reply-To: <20231204100620.27789-1-Michael.Glembotzki@iris-sensing.com> References: <20231204100620.27789-1-Michael.Glembotzki@iris-sensing.com> MIME-Version: 1.0 X-Original-Sender: m.glembo@gmail.com X-Original-Authentication-Results: gmr-mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=QntKOSH4; spf=pass (google.com: domain of m.glembo@gmail.com designates 2a00:1450:4864:20::633 as permitted sender) smtp.mailfrom=m.glembo@gmail.com; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Precedence: list Mailing-list: list swupdate@googlegroups.com; contact swupdate+owners@googlegroups.com List-ID: X-Spam-Checked-In-Group: swupdate@googlegroups.com X-Google-Group-Id: 605343134186 List-Post: , List-Help: , List-Archive: , List-Unsubscribe: , Signed-off-by: Michael Glembotzki --- doc/source/asym_encrypted_images.rst | 154 +++++++++++++++++++++++++++ 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, 168 insertions(+), 7 deletions(-) create mode 100644 doc/source/asym_encrypted_images.rst diff --git a/doc/source/asym_encrypted_images.rst b/doc/source/asym_encrypted_images.rst new file mode 100644 index 0000000..7906479 --- /dev/null +++ b/doc/source/asym_encrypted_images.rst @@ -0,0 +1,154 @@ +.. SPDX-FileCopyrightText: 2023 Michael Glembotzki +.. 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 a new + update image. +- 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 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 `. 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 -out -outform DER -recip + +Replace ```` with the plain `sw-description` (e.g. +`sw-description.in`) and the encrypted ```` with `sw-description`. +````, ````, [...] ```` 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 -out ```` -inform DER -inkey -recip + +Replace the encrypted ```` with `sw-description` and the +```` with plain `sw-description` (e.g. `sw-description.in`). +```` and ```` 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 supply the combined +recipient key pair (PEM) generated earlier to SWUpdate, use the ``-r`` +parameter. Alternatively, the ``recip-keypair`` parameter in the +``swupdate.cfg`` can be used. + + +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. +- Exchange the AES key with each update package. +- Refrain from encrypting new update images for compromised device. + diff --git a/doc/source/encrypted_images.rst b/doc/source/encrypted_images.rst index 2b7c1ee..bc23681 100644 --- a/doc/source/encrypted_images.rst +++ b/doc/source/encrypted_images.rst @@ -1,6 +1,8 @@ .. SPDX-FileCopyrightText: 2013-2021 Stefano Babic .. SPDX-License-Identifier: GPL-2.0-only +.. _sym-encrypted-images: + Symmetrically Encrypted Update Images ===================================== diff --git a/doc/source/index.rst b/doc/source/index.rst index c3a8e88..3ed531a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 diff --git a/doc/source/roadmap.rst b/doc/source/roadmap.rst index dc7d547..4e6caf4 100644 --- a/doc/source/roadmap.rst +++ b/doc/source/roadmap.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 ============================= diff --git a/doc/source/sw-description.rst b/doc/source/sw-description.rst index 480ff4d..ecc6405 100644 --- a/doc/source/sw-description.rst +++ b/doc/source/sw-description.rst @@ -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. |