From patchwork Fri Dec 15 14:19:47 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Glembotzki X-Patchwork-Id: 1876658 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=SFIKq/r7; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256 header.s=20230601 header.b=XyZvAiTU; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=googlegroups.com (client-ip=2a00:1450:4864:20::43d; helo=mail-wr1-x43d.google.com; envelope-from=swupdate+bncbdy5juxlviebbugc6gvqmgqebgeyhda@googlegroups.com; receiver=patchwork.ozlabs.org) Received: from mail-wr1-x43d.google.com (mail-wr1-x43d.google.com [IPv6:2a00:1450:4864:20::43d]) (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 4SsBK05lbYz23nt for ; Sat, 16 Dec 2023 01:23:16 +1100 (AEDT) Received: by mail-wr1-x43d.google.com with SMTP id ffacd0b85a97d-33349915da3sf613794f8f.0 for ; Fri, 15 Dec 2023 06:23:16 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1702650193; cv=pass; d=google.com; s=arc-20160816; b=Cq59ATBkMpF63vfcipCIvUwzW+zY4oLWwVCHUyINwiGm1475JZDgugYizDw7EGO5FU MQHS0Q/QrXfKWszhTPgdWYCcHGfF9r8OZkORqOXyoQ9b9LbgP8tpvdZgZJlNbYKhQa8e 8lQL2faDf4dUfnMJarvB+LAk+V6JQr7+GS5LN8Kw6+RNt0DfJgGPHfuJM7LGB8dpm3Yx Osh1ZI5aDBehm33MdfAAgE+iP7CoRzZnpyAYwbVJVHAizjm/2XIqY/mgZlJYnsbsmyRg W52uJbuUy9C874NrQ7hik8i5gEXbvTKvQa+x3A+83oXvMyU4AxkqM3cUKS5z8xNVum9l TciA== 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=QJZjf67W/e6+rvAEo92J5cOxWoLozoJQzCQulqXZh/c=; fh=zydHuzCQWrku2OPQyZfraJZFcOpEXLQ/YBcu3QNiBd0=; b=VkI7bgwM1hZ5bZZsSFcP2Rt3D6B87u6dAatFpVtBedRHnnb9bh43yC2ygVXz4q4vdl uYBvBuL1tee/o9waNZHee5gf/45OrCurkcLbnG3Je6rxL4uAHU6Ywzq/dCcx0s5BLa+6 LwEQT9AV70trN/xB5yGElLFDbhhLdjj4IYAZI5UVJuqOWZXf7GRYeTLbCxU2PFcz08gu 5MMS+ra2bbQR2lJW0lX1IL5w6//kP6kWieNPXAltxrpVyBpoVpeyEi/+bOc65ha3K/7Y vU2CcCzw1vM2OI8VFqcvWq78TaCEUxeo6qloqKmYgYGh7eCg4QZKZ5HLXYUIx1H2cki7 JdTg== ARC-Authentication-Results: i=2; gmr-mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=bgn9SiGF; spf=pass (google.com: domain of m.glembo@gmail.com designates 2a00:1450:4864:20::632 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=1702650193; x=1703254993; 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=QJZjf67W/e6+rvAEo92J5cOxWoLozoJQzCQulqXZh/c=; b=SFIKq/r7q7XeR5fCl9TH5vI4GB3WvT76Ge7QqESzxxgHsGUfCpeVOSpQy39LyGKQFM Zc1xAl4frLbI5BfgiVxcKiYXDgYEMtmeKsRBYhBef0Vt/EyBfsOVoew9JVJ93D2BWObp 6SZjv/IiKh+G5sLz3AD2GXAphujav5oKkYkV1gC6cu5u9D/5BJzESQfdLdZBS9XyZAgC hPjn3WbR4f0IBDimN4/fB/1JIdfhJujhsHs5Pw45TQ4HFj/3Zcer9Gf162n2gAsrof7v AKPsaUlsfJQxpkoPjqELhw4eRYsphNgiOuVmjM/nN+CHxTslk8lTTjqlLeeeizfoxAtU U6XA== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1702650193; x=1703254993; 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=QJZjf67W/e6+rvAEo92J5cOxWoLozoJQzCQulqXZh/c=; b=XyZvAiTUWsfv9ozfimMAh1h70fbLfLetr1UmG7FuCrTFnaQL3nuSt3w6l6yYLqZ1yz RHOgo/vHTONLZLRRwTXGYNu5lfw5/KvcglVy30SilG1yUiUSPmoK44sh767nc84Sa7/N Q6C3p22vrAOp00O9J8VYj9uWSgpWQwn2FnTxosJBqxdQhPEsKyeF5sMcKMDbiVvlYOng 2Givfr3byEQIgaI3OFq5GDjLIhL5RBZIzRrCbkDAr8oU0KCSTh/OrdJzX5t/n7/VdPuo KONxQwI2xyNSUaZ13BqdGQzfVve+p3BsxfPTuLjt/fnDAFDJrcv2XKQpXLX6UN2LddrH BTAQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1702650193; x=1703254993; 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=QJZjf67W/e6+rvAEo92J5cOxWoLozoJQzCQulqXZh/c=; b=knY9EtmfxbaqlK3JnFHfXZkztvDGCDgaGsLsBIcFyTYy6mekjMkTm7O1yvptidX52V unrFb/RF3TMdXSeII3MuU+IUAZ0fxVj4zM+fnojv6YncRnBTkEwho3mwuIYcRGspYXjc RyxjAE8vCr8B9d7XiNzBRf255b/QvBa38qByUiujfWrtdNj7/Nc2SmfCmFoD6iE8UfOu DpUOSiHll1CIC3SC9RB4Uqrh09tKGAzRNFrFfXAtvXdDwMjALUVS/hivR0M3bTzQ1Hrl c10/4Dh3gdIcCdQcSiQknzsYiNT49pouc8cS+grm+WibLkZljBKK56o+6We6EXqa76uR HF4A== Sender: swupdate@googlegroups.com X-Gm-Message-State: AOJu0Yzpa8W2r+88CeEFn9Oi6cmJTjzB9o7beyRPutwSx7xnNVhfSHjH R1hspQWTKU5IS+jL4J9kDQ0= X-Google-Smtp-Source: AGHT+IFU+AD64Ev0zWPHsoJpYlI2bDeP6x5bIatmlywJEOrq/mp95WKoNpROTQf/g1nXmvKS2Lv/xQ== X-Received: by 2002:adf:eb4f:0:b0:333:2fc4:464 with SMTP id u15-20020adfeb4f000000b003332fc40464mr4080847wrn.93.1702650193112; Fri, 15 Dec 2023 06:23:13 -0800 (PST) X-BeenThere: swupdate@googlegroups.com Received: by 2002:a5d:45d1:0:b0:336:4ce1:c059 with SMTP id b17-20020a5d45d1000000b003364ce1c059ls340676wrs.0.-pod-prod-02-eu; Fri, 15 Dec 2023 06:23:11 -0800 (PST) X-Received: by 2002:adf:ec05:0:b0:336:5bc6:6c45 with SMTP id x5-20020adfec05000000b003365bc66c45mr10395wrn.110.1702650190948; Fri, 15 Dec 2023 06:23:10 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1702650190; cv=none; d=google.com; s=arc-20160816; b=0D35GpQTZctaQASo32hImELoNX7PFq/KWzCk8Z5z6FYNwgHkhMIPY2JqLPVc5BBE2V OmXdXpPuuDegMNLs/nAQwgZ9tmSDWaM5fdjUc65HBDBoCaMJtYytcDBV/tutUzz45ljB GI30ccfjwc0MO4cYKbGFh9T83IdaMHIEyr+MnPYz71fat/x+HctB5O53tfqKL5Qu2xca zPo16BQEBaBzP5DGrMtlT1o47nVVsDW3/Zzo4OJf/UYN9Oh4YmmonXWVcvIM+xsJi5lw TXk0Rg8SxC80ORrt6ab9Ls2FqhBqS4Tc6ZAhbXR2BlryqeGT8NsLlqguepUIFzhBazif ccJg== 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=y6CeVrOMEoqswMynIS3+QanQ2oj6jMDGEnhWsQlhlOU=; fh=zydHuzCQWrku2OPQyZfraJZFcOpEXLQ/YBcu3QNiBd0=; b=EE1XZOQoW07rpgkoguxzzB5hpxADr27gLRaRZDkCsBZe3vvrHoEBUbMbChkLmY01nK 1oomC5Fgc4VYmlMe9NkQqJQ+m1Y1HzRoTgv0tod5Tai6V71/pFABvcUwBfo1GU4LJzJw gSAFFWnLc16ot0G4dpDsxQZ375ZRJV8C6BoHss194UGgvATVsrMSVHa/weUvKnsFoJa3 g0Ouc1yNwuM6DVVawO+fWgepy45ALz4rD22Hce/ZjzhMC9WNpS9KIVj3/oKk8IBrlvhQ ij3L/jhohNxMycyZyFBn9c8bsWMpxieByKVBpUhgYJF3HVAqndlMTtPK8JXj0n5hqWMA zWFA== ARC-Authentication-Results: i=1; gmr-mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=bgn9SiGF; spf=pass (google.com: domain of m.glembo@gmail.com designates 2a00:1450:4864:20::632 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-x632.google.com (mail-ej1-x632.google.com. [2a00:1450:4864:20::632]) by gmr-mx.google.com with ESMTPS id t7-20020adfe107000000b0033636cd2db8si280947wrz.6.2023.12.15.06.23.10 for (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Fri, 15 Dec 2023 06:23:10 -0800 (PST) Received-SPF: pass (google.com: domain of m.glembo@gmail.com designates 2a00:1450:4864:20::632 as permitted sender) client-ip=2a00:1450:4864:20::632; Received: by mail-ej1-x632.google.com with SMTP id a640c23a62f3a-a1f5cb80a91so95183266b.3 for ; Fri, 15 Dec 2023 06:23:10 -0800 (PST) X-Received: by 2002:a17:906:14e:b0:a19:a19b:4231 with SMTP id 14-20020a170906014e00b00a19a19b4231mr3135241ejh.156.1702650189774; Fri, 15 Dec 2023 06:23:09 -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 vx6-20020a170907a78600b00a1e852ab3f0sm10944029ejc.15.2023.12.15.06.23.09 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 15 Dec 2023 06:23:09 -0800 (PST) From: Michael Glembotzki To: swupdate@googlegroups.com Cc: Michael Glembotzki Subject: [swupdate] [V3][PATCH 10/10] doc: Add documentation for asymmetric decryption Date: Fri, 15 Dec 2023 15:19:47 +0100 Message-ID: <20231215142251.52393-11-Michael.Glembotzki@iris-sensing.com> X-Mailer: git-send-email 2.42.0 In-Reply-To: <20231215142251.52393-1-Michael.Glembotzki@iris-sensing.com> References: <20231215142251.52393-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=bgn9SiGF; spf=pass (google.com: domain of m.glembo@gmail.com designates 2a00:1450:4864:20::632 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 | 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 diff --git a/doc/source/asym_encrypted_images.rst b/doc/source/asym_encrypted_images.rst new file mode 100644 index 0000000..7379357 --- /dev/null +++ b/doc/source/asym_encrypted_images.rst @@ -0,0 +1,153 @@ +.. 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 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 `. 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 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. 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. |