From patchwork Thu Jul 15 17:00:26 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Ilias Apalodimas X-Patchwork-Id: 477439 Delivered-To: patch@linaro.org Received: by 2002:a02:c94a:0:0:0:0:0 with SMTP id u10csp467870jao; Thu, 15 Jul 2021 10:01:20 -0700 (PDT) X-Google-Smtp-Source: ABdhPJwunRCKnKpz2WKDuXQ87pfwvj1XQDdgpvad+CFH1Gi9wpLoRj7eu7fkz0ON/VWF2XHU+hq+ X-Received: by 2002:a05:6402:100e:: with SMTP id c14mr8326654edu.51.1626368480189; Thu, 15 Jul 2021 10:01:20 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1626368480; cv=none; d=google.com; s=arc-20160816; b=FWWQXw2l81ajfUZvDnhDP/3Ow10/u0VSI/+GbKypO0aMZjEuEITXb7Sx9+gf6ObF8x hgW7P3nfK9ZCdb3Ghhdmam7CxMuJZTpppxQ3YpXtV6g4/IsYtsHaVdtelMEqfFuzmj80 nDm6BaHBJH1UbF9pSG8WDaXzPV/du7NWQZw5Zmn1dI3+vzDn92hj6Uik7rn9U4XvqA64 JJgXWmNgtmrt+WG39hL/U2rj0VSfRWngT6EIv04Ci5UIr3oAe2ettxh3/3F+T1e5iPmi kryR2jOItVCzwguKdQYcnDKtL0NmpxpplRBJbjSKwTx5CCxX3dZ9be8Ny0VlVVjkb7ht lvEQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from:dkim-signature; bh=f+D+CH7cp+dGwJcCQ+KVfWz741B/57KofsrhOVbDNFo=; b=AF1DUuTAQWYONZftAoobited7rvIrXkMxFzAsH74jPPHkDb0HDsIEznxYN1dtMFfuK JcyTb7fdHc1sIk0rx1ysKKKsktNneK6UWWQcZAw93s528cMqAVByv4cFxhkw95l/FTF0 Zbprx7JVpv5YUUPJWp3Tcan7V1/qX9/AtOUjbCJjhmHjJuLDnTUZkdSfMb8GwxXUgEtw dARkYLSc9dy7T4TO2vk3PVrH7XSkAJSCSEkJ5WE5P9w5nmpRA9mCYGvSjWtZ15yTq3hF MwcFTT0d3838MEJixQiOghhRC0a6ylYxyuKtU1r31/ng2Oj0vzI6+VIw2PbzDolqcu9c K34g== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=dtFHGRBA; spf=pass (google.com: domain of u-boot-bounces@lists.denx.de designates 85.214.62.61 as permitted sender) smtp.mailfrom=u-boot-bounces@lists.denx.de; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from phobos.denx.de (phobos.denx.de. [85.214.62.61]) by mx.google.com with ESMTPS id s10si3643606edd.151.2021.07.15.10.01.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 15 Jul 2021 10:01:20 -0700 (PDT) Received-SPF: pass (google.com: domain of u-boot-bounces@lists.denx.de designates 85.214.62.61 as permitted sender) client-ip=85.214.62.61; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=dtFHGRBA; spf=pass (google.com: domain of u-boot-bounces@lists.denx.de designates 85.214.62.61 as permitted sender) smtp.mailfrom=u-boot-bounces@lists.denx.de; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 9724382BC7; Thu, 15 Jul 2021 19:01:08 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=linaro.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.b="dtFHGRBA"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 9983F82A01; Thu, 15 Jul 2021 19:01:00 +0200 (CEST) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de X-Spam-Level: X-Spam-Status: No, score=-2.0 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,SPF_HELO_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from mail-ed1-x52a.google.com (mail-ed1-x52a.google.com [IPv6:2a00:1450:4864:20::52a]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id CC5FE82999 for ; Thu, 15 Jul 2021 19:00:47 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=linaro.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=ilias.apalodimas@linaro.org Received: by mail-ed1-x52a.google.com with SMTP id h8so9135666eds.4 for ; Thu, 15 Jul 2021 10:00:47 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=f+D+CH7cp+dGwJcCQ+KVfWz741B/57KofsrhOVbDNFo=; b=dtFHGRBA1+1U2r1GS7dbxucagcyPZjZnfX9bir65OTxefWTU4W1rPPfiQQrBeBEAj6 ULgZarnK14nsNcst2hpv6XgDAAR5uTK5HpX7mcpn3MdvHo+GuFQrth+OGzICZ/m6HF/7 h2IUzSavAXnzscoiyxDa86tymYO9j/yPlgDg8X9uLrCSbC3pgp16VZeX+EuyRUqvBpgy VmYDHW+mGmi7WdarE95i67jKDlf+LpLnDEhQga/m35kb1fUFpznjEDPbK15mPBqBxhN2 JJfLJhMP4xdFxnlt0dJMlaOLd1Ewd66nLdkuaNK+tlaOpmKmWiWZG91TMDQdLdHoc59Z yExA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=f+D+CH7cp+dGwJcCQ+KVfWz741B/57KofsrhOVbDNFo=; b=m9NOo0gby7kz/U7CVMae5KO+bxAtWk6BWIZvaYoAEUSk7M0oM9MCFpAXRDqMvC70c/ OsM09YzmZIJzqx3UOgy2ojfF0j3lhShC3700IKY+XeFz9F3gS4+7/hLfmingOiptnc/d OFvPhKjXqNbMxd6qh6gPkaQoMY83BkCeATbYbrznFfZhy3aRMCkdib5ZxwNqRPRh8X+/ TWuljy0v6puNctt2JnSeicjQqUS+YbPHP/69Jc6AjusLjJv2LHK4Emp0Ny5O8HXP7xAt H+AzG2WDo5KHokjTIcRZhb/McuUmX5RzdO0f8sRgKWpfPTPXcPKo9iQMQ6cCk9OFOy8g z2Og== X-Gm-Message-State: AOAM531mlbuxUvpVGJT684y/fZ6vP5E24a8uM+5wzuUYrkGPgOYU2V1k J9gxgWhHD3KZ5xqxY4fsMIuLzw== X-Received: by 2002:aa7:ccc1:: with SMTP id y1mr8326504edt.321.1626368447376; Thu, 15 Jul 2021 10:00:47 -0700 (PDT) Received: from localhost.localdomain (ppp-94-66-243-35.home.otenet.gr. [94.66.243.35]) by smtp.gmail.com with ESMTPSA id p3sm2129556ejy.20.2021.07.15.10.00.46 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 15 Jul 2021 10:00:47 -0700 (PDT) From: Ilias Apalodimas To: xypron.glpk@gmx.de Cc: masami.hiramatsu@linaro.org, takahiro.akashi@linaro.org, Ilias Apalodimas , Alexander Graf , Sughosh Ganu , Simon Glass , u-boot@lists.denx.de Subject: [PATCH 3/3] doc: Update CapsuleUpdate READMEs Date: Thu, 15 Jul 2021 20:00:26 +0300 Message-Id: <20210715170030.97758-3-ilias.apalodimas@linaro.org> X-Mailer: git-send-email 2.32.0.rc0 In-Reply-To: <20210715170030.97758-1-ilias.apalodimas@linaro.org> References: <20210715170030.97758-1-ilias.apalodimas@linaro.org> MIME-Version: 1.0 X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.34 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.2 at phobos.denx.de X-Virus-Status: Clean Since we removed embeddingg the capsule key into a .dtb and fixed authenticated capsule updates for all boards, move the relevant documentation in the efi file and update it accordingly Signed-off-by: Ilias Apalodimas --- doc/board/emulation/qemu_capsule_update.rst | 203 -------------------- doc/develop/uefi/uefi.rst | 125 ++++++++++++ 2 files changed, 125 insertions(+), 203 deletions(-) delete mode 100644 doc/board/emulation/qemu_capsule_update.rst -- 2.32.0.rc0 diff --git a/doc/board/emulation/qemu_capsule_update.rst b/doc/board/emulation/qemu_capsule_update.rst deleted file mode 100644 index 0a2286d039d9..000000000000 --- a/doc/board/emulation/qemu_capsule_update.rst +++ /dev/null @@ -1,203 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0+ -.. Copyright (C) 2020, Linaro Limited - -Enabling UEFI Capsule Update feature ------------------------------------- - -Support has been added for the UEFI capsule update feature which -enables updating the U-Boot image using the UEFI firmware management -protocol (fmp). The capsules are not passed to the firmware through -the UpdateCapsule runtime service. Instead, capsule-on-disk -functionality is used for fetching the capsule from the EFI System -Partition (ESP) by placing the capsule file under the -\EFI\UpdateCapsule directory. - -Currently, support has been added on the QEMU ARM64 virt platform for -updating the U-Boot binary as a raw image when the platform is booted -in non-secure mode, i.e. with CONFIG_TFABOOT disabled. For this -configuration, the QEMU platform needs to be booted with -'secure=off'. The U-Boot binary placed on the first bank of the NOR -flash at offset 0x0. The U-Boot environment is placed on the second -NOR flash bank at offset 0x4000000. - -The capsule update feature is enabled with the following configuration -settings:: - - CONFIG_MTD=y - CONFIG_FLASH_CFI_MTD=y - CONFIG_CMD_MTDPARTS=y - CONFIG_CMD_DFU=y - CONFIG_DFU_MTD=y - CONFIG_PCI_INIT_R=y - CONFIG_EFI_CAPSULE_ON_DISK=y - CONFIG_EFI_CAPSULE_FIRMWARE_MANAGEMENT=y - CONFIG_EFI_CAPSULE_FIRMWARE=y - CONFIG_EFI_CAPSULE_FIRMWARE_RAW=y - CONFIG_EFI_CAPSULE_FMP_HEADER=y - -In addition, the following config needs to be disabled(QEMU ARM specific):: - - CONFIG_TFABOOT - -The capsule file can be generated by using the tools/mkeficapsule:: - - $ mkeficapsule --raw --index 1 - -As per the UEFI specification, the capsule file needs to be placed on -the EFI System Partition, under the \EFI\UpdateCapsule directory. The -EFI System Partition can be a virtio-blk-device. - -Before initiating the firmware update, the efi variables BootNext, -BootXXXX and OsIndications need to be set. The BootXXXX variable needs -to be pointing to the EFI System Partition which contains the capsule -file. The BootNext, BootXXXX and OsIndications variables can be set -using the following commands:: - - => efidebug boot add -b 0 Boot0000 virtio 0:1 - => efidebug boot next 0 - => setenv -e -nv -bs -rt -v OsIndications =0x04 - => saveenv - -Finally, the capsule update can be initiated with the following -command:: - - => efidebug capsule disk-update - -The updated U-Boot image will be booted on subsequent boot. - -Enabling Capsule Authentication -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The UEFI specification defines a way of authenticating the capsule to -be updated by verifying the capsule signature. The capsule signature -is computed and prepended to the capsule payload at the time of -capsule generation. This signature is then verified by using the -public key stored as part of the X509 certificate. This certificate is -in the form of an efi signature list (esl) file, which is embedded as -part of the platform's device tree blob using the mkeficapsule -utility. - -On the QEMU virt platforms, the device-tree is generated on the fly -based on the devices configured. This device tree is then passed on to -the various software components booting on the platform, including -U-Boot. Therefore, on the QEMU virt platform, the signatute is -embedded on an overlay. This overlay is then applied at runtime to the -base platform device-tree. Steps needed for embedding the esl file in -the overlay are highlighted below. - -The capsule authentication feature can be enabled through the -following config, in addition to the configs listed above for capsule -update:: - - CONFIG_EFI_CAPSULE_AUTHENTICATE=y - -The public and private keys used for the signing process are generated -and used by the steps highlighted below:: - - 1. Install utility commands on your host - * OPENSSL - * efitools - - 2. Create signing keys and certificate files on your host - - $ openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=CRT/ \ - -keyout CRT.key -out CRT.crt -nodes -days 365 - $ cert-to-efi-sig-list CRT.crt CRT.esl - - $ openssl x509 -in CRT.crt -out CRT.cer -outform DER - $ openssl x509 -inform DER -in CRT.cer -outform PEM -out CRT.pub.pem - - $ openssl pkcs12 -export -out CRT.pfx -inkey CRT.key -in CRT.crt - $ openssl pkcs12 -in CRT.pfx -nodes -out CRT.pem - -The capsule file can be generated by using the GenerateCapsule.py -script in EDKII:: - - $ ./BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \ - --monotonic-count --fw-version \ - --lsv --guid \ - e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose \ - --update-image-index --signer-private-cert \ - /path/to/CRT.pem --trusted-public-cert \ - /path/to/CRT.pub.pem --other-public-cert /path/to/CRT.pub.pem \ - - -Place the capsule generated in the above step on the EFI System -Partition under the EFI/UpdateCapsule directory - -For embedding the public key certificate, the following steps need to -be followed:: - - 1. Generate a skeleton overlay dts file, with a single fragment - node and an empty __overlay__ node - - A typical skeleton overlay file will look like this - - /dts-v1/; - /plugin/; - - / { - fragment@0 { - target-path = "/"; - __overlay__ { - }; - }; - }; - - - 2. Convert the dts to a corresponding dtb with the following - command - ./scripts/dtc/dtc -@ -I dts -O dtb -o \ - - - 3. Run the dtb file generated above through the mkeficapsule tool - in U-Boot - ./tools/mkeficapsule -O -D - -Running the above command results in the creation of a 'signature' -node in the dtb, under which the public key is stored as a -'capsule-key' property. The '-O' option is to be used since the -public key certificate(esl) file is being embedded in an overlay. - -The dtb file embedded with the certificate is now to be placed on an -EFI System Partition. This would then be loaded and "merged" with the -base platform flattened device-tree(dtb) at runtime. - -Build U-Boot with the following steps(QEMU ARM64):: - - $ make qemu_arm64_defconfig - $ make menuconfig - Disable CONFIG_TFABOOT - Enable CONFIG_EFI_CAPSULE_AUTHENTICATE - Enable all configs needed for capsule update(listed above) - $ make all - -Boot the platform and perform the following steps on the U-Boot -command line:: - - 1. Enable capsule authentication by setting the following env - variable - - => setenv capsule_authentication_enabled 1 - => saveenv - - 2. Load the overlay dtb to memory and merge it with the base fdt - - => fatload virtio 0:1 <$fdtovaddr> EFI/ - => fdt addr $fdtcontroladdr - => fdt resize - => fdt apply <$fdtovaddr> - - 3. Set the following environment and UEFI boot variables - - => setenv -e -nv -bs -rt -v OsIndications =0x04 - => efidebug boot add -b 0 Boot0000 virtio 0:1 - => efidebug boot next 0 - => saveenv - - 4. Finally, the capsule update can be initiated with the following - command - - => efidebug capsule disk-update - -On subsequent reboot, the platform should boot the updated U-Boot binary. diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index 4f2b8b036db8..3d04228e8188 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -277,6 +277,131 @@ Enable ``CONFIG_OPTEE``, ``CONFIG_CMD_OPTEE_RPMB`` and ``CONFIG_EFI_MM_COMM_TEE` [1] https://optee.readthedocs.io/en/latest/building/efi_vars/stmm.html +Enabling UEFI Capsule Update feature +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Support has been added for the UEFI capsule update feature which +enables updating the U-Boot image using the UEFI firmware management +protocol (FMP). The capsules are not passed to the firmware through +the UpdateCapsule runtime service. Instead, capsule-on-disk +functionality is used for fetching the capsule from the EFI System +Partition (ESP) by placing the capsule file under the +\EFI\UpdateCapsule directory. + +The directory \EFI\UpdateCapsule is checked for capsules only within the +EFI system partition on the device specified in the active boot option +determine by reference to BootNext variable or BootOrder variable processing. +The active Boot Variable is the variable with highest priority BootNext or +within BootOrder that refers to a device found to be present. Boot variables +in BootOrder but referring to devices not present are ignored when determining +active boot variable. +Before starting a capsule update make sure your capsules are installed in the +correct ESP partition or set BootNext. + +Performing the update +********************* + +Since U-boot doesn't currently support SetVariable at runtime there's a Kconfig +option (CONFIG_EFI_IGNORE_OSINDICATIONS) to disable the OsIndications variable +check. If that option is enabled just copy your capsule to \EFI\UpdateCapsule. + +If that option is disabled, you'll need to set the OsIndications variable with:: + + => setenv -e -nv -bs -rt -v OsIndications =0x04 + +Finally, the capsule update can be initiated either by rebooting the board, +which is the preferred method, or by issuing the following command:: + + => efidebug capsule disk-update + +**The efidebug command is should only be used during debugging/development.** + +Enabling Capsule Authentication +******************************* + +The UEFI specification defines a way of authenticating the capsule to +be updated by verifying the capsule signature. The capsule signature +is computed and prepended to the capsule payload at the time of +capsule generation. This signature is then verified by using the +public key stored as part of the X509 certificate. This certificate is +in the form of an efi signature list (esl) file, which is embedded as +part of U-Boot. + +The capsule authentication feature can be enabled through the +following config, in addition to the configs listed above for capsule +update:: + + CONFIG_EFI_CAPSULE_AUTHENTICATE=y + CONFIG_EFI_CAPSULE_KEY_PATH= + +The public and private keys used for the signing process are generated +and used by the steps highlighted below:: + + 1. Install utility commands on your host + * OPENSSL + * efitools + + 2. Create signing keys and certificate files on your host + + $ openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=CRT/ \ + -keyout CRT.key -out CRT.crt -nodes -days 365 + $ cert-to-efi-sig-list CRT.crt CRT.esl + + $ openssl x509 -in CRT.crt -out CRT.cer -outform DER + $ openssl x509 -inform DER -in CRT.cer -outform PEM -out CRT.pub.pem + + $ openssl pkcs12 -export -out CRT.pfx -inkey CRT.key -in CRT.crt + $ openssl pkcs12 -in CRT.pfx -nodes -out CRT.pem + +The capsule file can be generated by using the GenerateCapsule.py +script in EDKII:: + + $ ./BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \ + --monotonic-count --fw-version \ + --lsv --guid \ + e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose \ + --update-image-index --signer-private-cert \ + /path/to/CRT.pem --trusted-public-cert \ + /path/to/CRT.pub.pem --other-public-cert /path/to/CRT.pub.pem \ + + +Place the capsule generated in the above step on the EFI System +Partition under the EFI/UpdateCapsule directory + +Testing on QEMU +*************** + +Currently, support has been added on the QEMU ARM64 virt platform for +updating the U-Boot binary as a raw image when the platform is booted +in non-secure mode, i.e. with CONFIG_TFABOOT disabled. For this +configuration, the QEMU platform needs to be booted with +'secure=off'. The U-Boot binary placed on the first bank of the NOR +flash at offset 0x0. The U-Boot environment is placed on the second +NOR flash bank at offset 0x4000000. + +The capsule update feature is enabled with the following configuration +settings:: + + CONFIG_MTD=y + CONFIG_FLASH_CFI_MTD=y + CONFIG_CMD_MTDPARTS=y + CONFIG_CMD_DFU=y + CONFIG_DFU_MTD=y + CONFIG_PCI_INIT_R=y + CONFIG_EFI_CAPSULE_ON_DISK=y + CONFIG_EFI_CAPSULE_FIRMWARE_MANAGEMENT=y + CONFIG_EFI_CAPSULE_FIRMWARE=y + CONFIG_EFI_CAPSULE_FIRMWARE_RAW=y + CONFIG_EFI_CAPSULE_FMP_HEADER=y + +In addition, the following config needs to be disabled(QEMU ARM specific):: + + CONFIG_TFABOOT + +The capsule file can be generated by using the tools/mkeficapsule:: + + $ mkeficapsule --raw --index 1 + Executing the boot manager ~~~~~~~~~~~~~~~~~~~~~~~~~~