From patchwork Mon Jan 15 19:26:45 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Glembotzki X-Patchwork-Id: 1886827 X-Patchwork-Delegate: sbabic@denx.de 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=nqNnV5Ha; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256 header.s=20230601 header.b=hxLXmh9F; 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+bncbdy5juxlviebbbeps2wqmgqel44xsly@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 4TDMdh3thdz23dm for ; Tue, 16 Jan 2024 06:29:12 +1100 (AEDT) Received: by mail-wm1-x337.google.com with SMTP id 5b1f17b1804b1-40e4caa37f5sf53140415e9.0 for ; Mon, 15 Jan 2024 11:29:12 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1705346949; cv=pass; d=google.com; s=arc-20160816; b=jFi18X/KJ3ZTGkcIAoPuOo6Cvzwc58hfYrgVcLyslP2j5s8KVC4WQD6zasIuj/r6Sb 53xM6eIsZLg9iYD3FcI/l6MSgsC+cKE+EQBBA1o1RmaI+pawqmSVv/BmYm/9exUTq6XF Kw1Dj03OK62pGmdcyvL1BfYUrAM29KNjuvZ9CzykRGOCLqe0aB5wcY7jSCVUlh8+sqp6 AUyaFHivU1sey4xET7tXgQ3RqkfzjJ6sWJQ5pKMIoV+TqWAnINwlp+XrshGC9l+rdOmJ RGBAC+wpXJojlAH8xAn5AdkQZGNLeFDDEHebVCb7EdZ+1pO43Hp6uhkyMIDEmQmXDWI/ NRvQ== 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=IKeUWx4WNMNGwY3rH9tdj4cxY+80mevxsCJ3XplJ4wI=; fh=zydHuzCQWrku2OPQyZfraJZFcOpEXLQ/YBcu3QNiBd0=; b=prk+rF1lG1lvyYUtzVkIaAfIz7VnfjGlYmuHbxX3qYClwwlKr4RCfENSL/UeeEqPHH xfmgs53SWUFoCjtDd/66zg8knnbYPctUuLDUId0PNlc/Zj0iXVvkrR/gCXTb6ICSwT5S NyjytxGIzRFpxzQV02XIcrnEV3PbqyptEpWbY3TV45AN8oHHUIuAPG2cTeZi9iHcesXD TIRUqX6xL1wUKgJ49BHFceD54m+MUpMnvFV/ZqHwoNU8uz/bfHr7HAo/09o/iWEBxel2 xDqoDuaEb8GrHBAIPDoONdhcJ5px4BTHPve0Z/9+lLfIX9H1k/tVjq0zimV3rgQfIdgK qqVg== ARC-Authentication-Results: i=2; gmr-mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=WvE4WsMz; spf=pass (google.com: domain of m.glembo@gmail.com designates 2a00:1450:4864:20::636 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=1705346949; x=1705951749; 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=IKeUWx4WNMNGwY3rH9tdj4cxY+80mevxsCJ3XplJ4wI=; b=nqNnV5HaS/i3EDj4VP6fd/BfV4/h2iOcqRmG42jT715fBB+DUUd9CT42XEO97Q0mxI dVjpRLmCc7/Gk9lbu83xjcnw5CeVsCWkZYdH8XoOwZwpAvQ7uqe1+9bX9+xiZ5IQ7MG7 umGI0PwXW2iGicV5himNkbGmhiKJ4CKgSu4xPZuq5oT1dEl2L2Mcrghrp2EA1mhLLStf I0gyu/X0ZQYNa9RVqBYmLvMC9ZYGHNKthG+TL7o+5uvfZNUtBUdQ4Uo0p0GfSEuEhgKk 1Ciqm2CRWojqIALDCvkg1TJQCEiWvLf9TmZ9xABuR2IYH0WkS3vN2VNwr2VAMai2+ebq DCgQ== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1705346949; x=1705951749; 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=IKeUWx4WNMNGwY3rH9tdj4cxY+80mevxsCJ3XplJ4wI=; b=hxLXmh9FxK+9Ax03yABX7EGkuTjXn+wupfd8A4Hvk+Ed/zy2yiPZLvEBYRhat8smtY bba7lWiKc3krJ9C2RlC/7fU3STB5fD7xUqt/FgwaNm2KqoZMOK1K6OwWmWc3fz9B8d90 ZscWxO51rvp9KYy8ZUELUNw3GsgqRxh1WSh+OChh6/e+INrZ81rpkGXaDUfk6E9+lAfM t6opHEpOv1UWs65W2+dZjf2Sn4y2mkKVRmk+i1tch9JFNDcV5x6wu9ZeW4lZRFLSTxGh 16FRWA37hBMZWIcZHlaDqZQMg9o6fMIEPVEYbIyFf6kLzL+hTwEc6NlFogpPBS0kOIGN sVag== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1705346949; x=1705951749; 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=IKeUWx4WNMNGwY3rH9tdj4cxY+80mevxsCJ3XplJ4wI=; b=TYwPQRTm6kJhlAYeYk0DRK9pRtnGppOT7eUaHdvBP39jh/kr1KInC342vKpmGbi/BW T35+0nlXsydIi0NR1nVn7VrJJn7V6QC3GQpuVeeO7xiMu4v54ixF8MpqPc/CHCiMGkgD eaeXRQR/QLn8jhSrGUqHsYMK43sSi8R05gS1f038BLtxFI2ZF1KOwxtPiyvD/7U27XXH 96trG3xkiA4MToAu70lJFJn9b4lDqEy1kuPRDO1OaSumc53DTE/HrfevEFC/aA1Nbi4e zaEpu5Zuh/4MUw7i/swCXRdtWfLz+2IOAZsB+ewIfAnH3ecArc+sJxEVGaKxBWqSbCzR GieA== Sender: swupdate@googlegroups.com X-Gm-Message-State: AOJu0YyeMKEt0ZiPy5aUwQYYQkI4xvWWBriv8xATJUa+71E70eOhbfp1 nw+OaHSJvf9KRyWIYBZT2aE= X-Google-Smtp-Source: AGHT+IGekKkNZA4DcQfXo7XFfHWsqUj4lYdwu7ERgJGEpNAFyQjEt6meANQB3lSEWPNYQapq9oGkXg== X-Received: by 2002:a05:600c:2a48:b0:40e:4dc1:fbc0 with SMTP id x8-20020a05600c2a4800b0040e4dc1fbc0mr2967819wme.60.1705346948783; Mon, 15 Jan 2024 11:29:08 -0800 (PST) X-BeenThere: swupdate@googlegroups.com Received: by 2002:a05:600c:3c88:b0:40d:839d:e5d6 with SMTP id bg8-20020a05600c3c8800b0040d839de5d6ls1318404wmb.1.-pod-prod-07-eu; Mon, 15 Jan 2024 11:29:07 -0800 (PST) X-Received: by 2002:a05:600c:468b:b0:40e:5118:5046 with SMTP id p11-20020a05600c468b00b0040e51185046mr3374937wmo.21.1705346946731; Mon, 15 Jan 2024 11:29:06 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1705346946; cv=none; d=google.com; s=arc-20160816; b=U4Qj1ALCkLIPLix8PDD8W9s3/trQFfB0mfLTOEpGIjmTt0IAUWKuU6xbp+1wJi2WPO AigUJ84hX0QSTGS6E/CL2ipelyAhazEjb2F7X5NCBYV9u2zzQNFJ6zr7GVInnlLNMez+ QjurfpRTb2ZHQ+/ad1/CCbz1ddALuUANFE4LjwCSBcsbr7e9TYAwACw47maeM+Yuph3n AceSe7LC5oUbx0krFv6xyDKc2SqjArhW4RPY6rS74qsh1jxtlF3rVxBESdxF9lYJ/ToH 2etRinJJIljFC5TNLFow9BmD7IrKMlay5//FRo9kvqYhkcPRVol6u7yruetNnkE8Gizp XovA== 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=aYuPuYseKS/b/sHB00vtpsf3DrPPtACcMQKcYREvtAU=; fh=zydHuzCQWrku2OPQyZfraJZFcOpEXLQ/YBcu3QNiBd0=; b=WMIBHPr9hFyOCmOnzLEG8xiOIXeKxzQSMSaJumxouC0J6o/JUofHc2N+1/MNsfq5zH iueH/yC1+0eLEZPeujex1dHWV4oZtM8fo2jtR+Xsug7U7wiiZu+1e9bm5znJQE70cNHZ k8PQe+fLpw4ubMQLcbuO9F+qw0N53D7KJqNYYJhupjbnRTE8xIT8QxqbJP6vaUbZiVB7 yUpfAn8dWuLkbvce97fZcPWZCrm5IUakF3M5iFa24ZOnuDLCBSr+y7SLlNQBmViABPQA qbZSPByYm35rPKpaQYfLXTjBfV0yajGABX4it76fSv4E/gMi2XDlY0XJg6GHBwDGuLAu dPmw== ARC-Authentication-Results: i=1; gmr-mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=WvE4WsMz; spf=pass (google.com: domain of m.glembo@gmail.com designates 2a00:1450:4864:20::636 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-x636.google.com (mail-ej1-x636.google.com. [2a00:1450:4864:20::636]) by gmr-mx.google.com with ESMTPS id k1-20020a05600c1c8100b0040e5a5b0b63si336441wms.0.2024.01.15.11.29.06 for (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Mon, 15 Jan 2024 11:29:06 -0800 (PST) Received-SPF: pass (google.com: domain of m.glembo@gmail.com designates 2a00:1450:4864:20::636 as permitted sender) client-ip=2a00:1450:4864:20::636; Received: by mail-ej1-x636.google.com with SMTP id a640c23a62f3a-a2d348d213dso231560666b.0 for ; Mon, 15 Jan 2024 11:29:06 -0800 (PST) X-Received: by 2002:a17:907:c209:b0:a2c:be05:92af with SMTP id ti9-20020a170907c20900b00a2cbe0592afmr3223744ejc.57.1705346945659; Mon, 15 Jan 2024 11:29:05 -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 tl7-20020a170907c30700b00a2de58581f6sm1289255ejc.74.2024.01.15.11.29.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 15 Jan 2024 11:29:05 -0800 (PST) From: Michael Glembotzki To: swupdate@googlegroups.com Cc: Michael Glembotzki Subject: [swupdate] [V4][PATCH 8/8] doc: Add documentation for asymmetric decryption Date: Mon, 15 Jan 2024 20:26:45 +0100 Message-ID: <20240115192845.51530-9-Michael.Glembotzki@iris-sensing.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240115192845.51530-1-Michael.Glembotzki@iris-sensing.com> References: <20240115192845.51530-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=WvE4WsMz; spf=pass (google.com: domain of m.glembo@gmail.com designates 2a00:1450:4864:20::636 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..aa7bc5c --- /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 decrypt images device specific. +The artifacts themselves are still encrypted symmetrically. An AES key can +optionally be provided in the sw-description, or the default AES key will be +used. Cryptographic Message Syntax (CMS) is used for decryption. + + +Use Cases +--------- + +- Asymmetrically encrypted update images, with individual device key pairs, are + inherently more secure than a purely symmetrical solution, because one + compromised private device key does not affect the security of the others. +- If ``CONFIG_SIGNED_IMAGES`` is enabled too and a device's private key is + compromised, the key pair can be excluded from the list of eligible devices + for receiving new update images. +- The AES key can be securely **exchanged** with each new update image, as it is + part of the sw-description, even in the absence of direct access to the + device. + + +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 devices. An RSA key pair +could be used in the same way. + +:: + + # 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 togther are used for encryption. + +:: + + # Encrypt sw-description for multiple 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 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 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 ``encrypted`` attribute is +necessary for encrypted artifacts. While it is strongly recommended to provide +the attributes ``aes-key`` (global) and ``ivt`` (artifact-specific), they are +not mandatory. If no ``aes-key`` or ``ivt`` is provided, the provided default +``aes-key``/``ivt`` will be used. + +:: + + software = + { + version = "0.0.1"; + aes-key = "ed73b9d3bf9c655d5a0b04836d8be48660a4a4bb6f4aa07c6778e00e342881ac"; + images: ({ + filename = "rootfs.ext4.enc"; + device = "/dev/mmcblk0p3"; + sha256 = "131159df3a4efaa890ff80173664a125c496c458dd432a8a6acae18872e35822"; + encrypted = true; + ivt = "ea34a55a0c3476ed78f238ac87a7970c"; + }); + } + + +Asymmetrically encrypt the `sw-description` for multiple 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 key pair +(PEM) generated earlier to SWUpdate, use the ``-a`` argument. Alternatively, +use the ``asym-decryption-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 should be preferred over larger ones. +- Exchange the AES key in the sw-description with each update package. +- Avoid encrypting new update packages for compromised devices, if there is no + direct access to the device or if unauthorized users have access to new update + packages. 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..6e7e9bb 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 | | Optional AES key for encrypted | + | | | | artefacts. It has no effect if not | + | | | | compiled with | + | | | | `CONFIG_ASYM_ENCRYPTED_SW_DESCRIPTION`| + | | | | or if attribute "encrypted" is not | + | | | | set. If no AES key is provided the | + | | | | default AES key is used. It is an | + | | | | ASCII hex string of 16/24/32 chars. | + +-------------+----------+------------+---------------------------------------+ + | ivt | string | images | Optional IVT for encrypted artefacts. | + | | | 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. |