From patchwork Tue Jan 18 04:39:49 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: AKASHI Takahiro X-Patchwork-Id: 532858 Delivered-To: patch@linaro.org Received: by 2002:ad5:544f:0:0:0:0:0 with SMTP id a15csp3352536imp; Mon, 17 Jan 2022 20:41:23 -0800 (PST) X-Google-Smtp-Source: ABdhPJxhtXVh9/qehkD82/zm/UdEE9XBJB0f7V+F5aWET9PG+x4AobuuP4REVfGEefQRLmUJ4fIL X-Received: by 2002:a17:906:519b:: with SMTP id y27mr19388324ejk.649.1642480883821; Mon, 17 Jan 2022 20:41:23 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1642480883; cv=none; d=google.com; s=arc-20160816; b=F3hp7cVJeNFm2yp6qe/cg/1FSawQe82r+6GkTD+GBlMJ9nv6AfWIJieijgdp4UeK9t pFxlaE1lAMJwIqN4IpgRoj7VDN/8mUSSre8BdUafAyvYc3EpbYGkrzbFfAjLfgjkbWgI 0VCp6Yw957EAhwvOBMnvWdruX6eNOA6u+pXtjP2KwwXa6acLG+NX+2YhB7rsDw23twE2 BQCTwQIhJYSuawpneZ6IB/f879BvENpIWps01zg4J7DEIsT9B0qoZt9mlicR3mE0ZwAK RwK3cIx/HxSKkkf4Il0viT9GDdTJtXUfLVzmR+5xNsaSKDwP6vWnPSE6z8cHOXF2fsqn A1DQ== 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=mR1pD8an10hL1eYSQk6y2hzUF/bKxUXs6pDb/LAKo0Q=; b=IMedt0mdDbp2d7K/IjR5l5Vj2I+n5eb5ALl3uS/rJheUi4Z8NsCSWnjzs2wgvizEZI XY2AD++8hL+vWytK0hjc8LB1Zx2Vf7plOkNpRNRtsVJwMr/9GhWhSFg5E1eU5vYRfr6h vBfJqEXykg53Od7dvNJJbhar0Omo+/Fvtg5I+buenZXaXPJ2V2/hajQsX+Z58ixRHcHk X0My9GoWHYHbw5I5jHpacHOc5PLgi6WkYZRHRPqg++HF/ZxFyMxXwHr+gR9d1QumQnoP OpRIK0yXY3z6zyJDm1UerIztjgmrbnXYWd+EtOkDPouVxt2xpWzPWRbjqUjcJhOaoFzs QI8w== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=gdT98dQg; spf=pass (google.com: domain of u-boot-bounces@lists.denx.de designates 2a01:238:438b:c500:173d:9f52:ddab:ee01 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. [2a01:238:438b:c500:173d:9f52:ddab:ee01]) by mx.google.com with ESMTPS id i22si2271340ejw.647.2022.01.17.20.41.23 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 17 Jan 2022 20:41:23 -0800 (PST) Received-SPF: pass (google.com: domain of u-boot-bounces@lists.denx.de designates 2a01:238:438b:c500:173d:9f52:ddab:ee01 as permitted sender) client-ip=2a01:238:438b:c500:173d:9f52:ddab:ee01; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=gdT98dQg; spf=pass (google.com: domain of u-boot-bounces@lists.denx.de designates 2a01:238:438b:c500:173d:9f52:ddab:ee01 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 71CDD8380E; Tue, 18 Jan 2022 05:40:54 +0100 (CET) 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="gdT98dQg"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 3BAA083214; Tue, 18 Jan 2022 05:40:42 +0100 (CET) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de X-Spam-Level: X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,SPF_HELO_NONE,SPF_PASS autolearn=ham autolearn_force=no version=3.4.2 Received: from mail-pj1-x102b.google.com (mail-pj1-x102b.google.com [IPv6:2607:f8b0:4864:20::102b]) (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 41FE8837DE for ; Tue, 18 Jan 2022 05:40:36 +0100 (CET) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=linaro.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=takahiro.akashi@linaro.org Received: by mail-pj1-x102b.google.com with SMTP id z17-20020a17090ab11100b001b4d8817e04so343401pjq.2 for ; Mon, 17 Jan 2022 20:40:36 -0800 (PST) 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=mR1pD8an10hL1eYSQk6y2hzUF/bKxUXs6pDb/LAKo0Q=; b=gdT98dQgGn2o+HJmsqxdZczgxsTADgQzEffcEkzYKtWI96V4p8zUHfAqJGtSv08O4e PshjaPYymGRDnab3JJF4kpy6Fihu4Nw7spELrh0/Q/qUqCxCPCO843hJJIDNjgxLg1dr 3GZVLK0PVeO6Ru21LikCDko6SW9qaTO+YtQaPj7xT2+nrwBn7lkctvHNhbGPWeTspMCQ k/wQqJ+m3n9yQlPe5G5jqJQ+kiniiLxSpYIcyUjhDpOTB2rR46pdNEg9lzXAqnP5p/sN V1xdY2LCAxXwvrolpeOr+k241lwrWhn2PnyoYpuyadRIPvbQcs50XtdNTzmwlRzObl0K vuLg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=mR1pD8an10hL1eYSQk6y2hzUF/bKxUXs6pDb/LAKo0Q=; b=NAU92rJT+Wwe1uhvpEWNurjYo90AfgAce6fxVBm+jgmgtPybPCKpQUL7Rtprvl+oXV ri1t0tgLhsrAAzjSEhnH1viONZ1o5x0GCzyH1JGYdsDU0VsGNOyubCzWiv8WQoYxkM4e Pa6ODfBIVd/dk/ARnf87BuLts5NEzA95vI/JfDW6s/v0XVTGZvkFa59BPigktnso4YFf 80nOGmyeYyiFtDFGvnlY+Qhlyz0kaDhiuaPK30xxDzhpGfePv6qD5Q8YesOoz43e5yfA 7fmKB5CIQ7QIXNXCV7QV6bVDV+fpO9p3rmU2U1D2oY/qiCfpkyxKefLGc9X9OF+/HLTD WCuw== X-Gm-Message-State: AOAM533uIm513RR51BhituPAOs1MZXy1aUETThLkC3dM+03fxTwlBNUR 1ADRdmXg71pr7nE20oLNpXQWjA== X-Received: by 2002:a17:90b:3ec5:: with SMTP id rm5mr9869519pjb.241.1642480834571; Mon, 17 Jan 2022 20:40:34 -0800 (PST) Received: from localhost.localdomain ([2400:4050:c3e1:100:bc1a:291e:ac91:be98]) by smtp.gmail.com with ESMTPSA id y69sm15670770pfg.171.2022.01.17.20.40.31 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 17 Jan 2022 20:40:34 -0800 (PST) From: AKASHI Takahiro To: xypron.glpk@gmx.de, agraf@csgraf.de, sjg@chromium.org Cc: ilias.apalodimas@linaro.org, sughosh.ganu@linaro.org, masami.hiramatsu@linaro.org, mark.kettenis@xs4all.nl, u-boot@lists.denx.de, AKASHI Takahiro Subject: [PATCH v9 06/11] doc: update UEFI document for usage of mkeficapsule Date: Tue, 18 Jan 2022 13:39:49 +0900 Message-Id: <20220118043954.55940-7-takahiro.akashi@linaro.org> X-Mailer: git-send-email 2.33.0 In-Reply-To: <20220118043954.55940-1-takahiro.akashi@linaro.org> References: <20220118043954.55940-1-takahiro.akashi@linaro.org> MIME-Version: 1.0 X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 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 Now we can use mkeficapsule command instead of EDK-II's script to create a signed capsule file. So update the instruction for capsule authentication. Signed-off-by: AKASHI Takahiro Reviewed-by: Simon Glass Acked-by: Ilias Apalodimas --- doc/develop/uefi/uefi.rst | 147 +++++++++++++++++++------------------- 1 file changed, 74 insertions(+), 73 deletions(-) diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index 43fb10f7978e..7e1eb8256259 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -284,37 +284,56 @@ 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 -determined 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. +functionality is used for fetching capsules from the EFI System +Partition (ESP) by placing capsule files under the directory:: + + \EFI\UpdateCapsule + +The directory is checked for capsules only within the +EFI system partition on the device specified in the active boot option, +which is determined by BootXXXX variable in BootNext, or if not, the highest +priority one within BootOrder. Any BootXXXX variables referring to devices +not present are ignored when determining the active boot option. + +Please note that capsules will be applied in the alphabetic order of +capsule file names. + +Creating a capsule file +*********************** + +A capsule file can be created by using tools/mkeficapsule. +To build this tool, enable:: + + CONFIG_TOOLS_MKEFICAPSULE=y + CONFIG_TOOLS_LIBCRYPTO=y + +Run the following command:: + +.. code-block:: console + + $ mkeficapsule \ + --index 1 --instance 0 \ + [--fit | --raw ] \ + 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. +Put capsule files under the directory mentioned above. +Then, following the UEFI specification, you'll need to set +the EFI_OS_INDICATIONS_FILE_CAPSULE_DELIVERY_SUPPORTED +bit in OsIndications variable with:: -If that option is disabled, you'll need to set the OsIndications variable with:: +.. code-block:: console => 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:: +Since U-boot doesn't currently support SetVariable at runtime, its value +won't be taken over across the reboot. If this is the case, you can skip +this feature check with the Kconfig option (CONFIG_EFI_IGNORE_OSINDICATIONS) +set. - => efidebug capsule disk-update - -**The efidebug command is should only be used during debugging/development.** +Finally, the capsule update can be initiated by rebooting the board. Enabling Capsule Authentication ******************************* @@ -324,82 +343,64 @@ 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. +in the form of an efi signature list (esl) file, which is embedded in +a device tree. 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:: +and used by the steps highlighted below. - 1. Install utility commands on your host - * OPENSSL +1. Install utility commands on your host + * openssl * efitools - 2. Create signing keys and certificate files on your host +2. Create signing keys and certificate files on your host:: + +.. code-block:: console $ 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 \ - +3. Run the following command to create and sign the capsule file:: -Place the capsule generated in the above step on the EFI System -Partition under the EFI/UpdateCapsule directory +.. code-block:: console -Testing on QEMU -*************** + $ mkeficapsule --monotonic-count 1 \ + --private-key CRT.key \ + --certificate CRT.crt \ + --index 1 --instance 0 \ + [--fit | --raw ] \ + -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. +4. Insert the signature list into a device tree in the following format:: -The capsule update feature is enabled with the following configuration -settings:: + { + signature { + capsule-key = [ ]; + } + ... + } - 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 + You can do this manually with:: -In addition, the following config needs to be disabled(QEMU ARM specific):: +.. code-block:: console - CONFIG_TFABOOT + $ dtc -@ -I dts -O dtb -o signature.dtbo signature.dts + $ fdtoverlay -i orig.dtb -o new.dtb -v signature.dtbo -The capsule file can be generated by using the tools/mkeficapsule:: + where signature.dts looks like:: - $ mkeficapsule --raw --index 1 + &{/} { + signature { + capsule-key = /incbin/("CRT.esl"); + }; + }; Executing the boot manager ~~~~~~~~~~~~~~~~~~~~~~~~~~