From patchwork Thu Oct 7 06:23:36 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: AKASHI Takahiro X-Patchwork-Id: 515433 Delivered-To: patch@linaro.org Received: by 2002:ac0:b5cc:0:0:0:0:0 with SMTP id x12csp1004406ime; Wed, 6 Oct 2021 23:26:17 -0700 (PDT) X-Google-Smtp-Source: ABdhPJxIp6gA+gtBNr1/AnNsOhe/0QsigO9JlWm86pjS49QuBOEoO1sEC7JJVliU/8Ajw+xo0JLm X-Received: by 2002:a17:906:1553:: with SMTP id c19mr3392157ejd.266.1633587977569; Wed, 06 Oct 2021 23:26:17 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1633587977; cv=none; d=google.com; s=arc-20160816; b=op2PUQwKrE+W/AQBC0JYrra1j2rclCIFbr9V8I7pbK8gJf69PNjaR3uFzriznswI1Z 7uESwVbgPCiVlqA00kWeYH5FIgr4bzDcSJHWBvzjXIT92c5S8P68A9ZG7NzrUKck2B9q bscdmVAyEn2I4LYEbu7wDz9hHzpq3soznzL5+fY0RfiSWtcZedwHkl4heFtozIpHLagc JefW4QrdVlH7E9RktrpQ/NJjy2iCYkHu1zelAWDGVPqNGJb8wtqNLN18lKD8Fmxd1qdV 86MiPw9cdkKixGDqLjaSJbOLjHAQn8fa3v6EYaqo98a1bT5JgG17NKW/6c17pG+pefIZ ru1w== 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=MmgudMx1S5LA/ce0O0uzj23yjaHZFq7L0ZVuN+gKpE4=; b=nEqyOL2CSgj+UFuFhVCVw3lP0ayieU9tqwdEamvGAjqV7K2YUM89abmEVosxqX5N48 KJpXMg+Fcqq7mw5lnOJu+Dy3rkuMmQ9XfU0Bpfal1RVEyPllaaNHkfOwsexWacsHAOsx F5DoZAtJDvDgvqLaScGovy9ioJZGd4dRr6lGZXoO4hww40FMRLjzY3QfECWvoryNzgVL fDaefD7roXdVBiHk06uGMx6a/lhyTXx3TjVkpTLDWDyzGwYD1MDOpW8CXbAPCmI3Edkq 8LLSSq5TNAMdccQW/aop1C+XcG79/taUbQi/ApkSxInLUsu169ItQBaAPN+ZENvbgc70 P2AQ== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=CrmgXLkv; 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 gq12si10124998ejb.168.2021.10.06.23.26.17 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 06 Oct 2021 23:26:17 -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=CrmgXLkv; 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 66D1D834B9; Thu, 7 Oct 2021 08:25:40 +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="CrmgXLkv"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 11731834B0; Thu, 7 Oct 2021 08:25:38 +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.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-pf1-x42c.google.com (mail-pf1-x42c.google.com [IPv6:2607:f8b0:4864:20::42c]) (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 881FD834A3 for ; Thu, 7 Oct 2021 08:25:30 +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=takahiro.akashi@linaro.org Received: by mail-pf1-x42c.google.com with SMTP id g14so4471749pfm.1 for ; Wed, 06 Oct 2021 23:25:30 -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=MmgudMx1S5LA/ce0O0uzj23yjaHZFq7L0ZVuN+gKpE4=; b=CrmgXLkvOb0j0myHM4avRQBVPbtqrjJ9BpsorWkW6SSVs7WnSZYVygleODKgznA108 rmk04ntVN5hOC3MeC7ObVnhF/ODzLrFkNoWhX7ox7Lt9kexUT2DodtdGEx28Z+uXYcRN cwOUGO+2K0zSNB3xBDYc7BYdGSyPv3FLojt1Frgy4I4Kx5LG6vVH/26CqqEhO4KNq0mI tM1Oh8sfIx4hW1KKRLR23H0kFIshA2btYyMKgfy67SymdMlRwwku4m2qxb07kH0Cb8z1 HTakNJScdrEdRXeb9TM1Tk/ebYznU5GN28p6bp6aPW+4oY89tr2w3emjWmZRDX2FZIyY JKJg== 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=MmgudMx1S5LA/ce0O0uzj23yjaHZFq7L0ZVuN+gKpE4=; b=U2ouNCWShCexrH/iOwaXtTFptvnYLwyhAsYKEO3+u42CJ782pv/k6bnUagr2OAuCD7 IPSI4nifU8Vyzkb3Fl7cON5J6CEWMhMksyZettdjXzkUKOm5vJCXHo1S6c7qr73FC97T NHf81WLzp86SUGhICzWAOk8mqCtKtaJURXFzg8DYFTf2xN/q/pMYr9VlMjA1+48GnNpR s0l6h7mXj6j9A67Tczqsgr9dnXehU7omXTCadwhKgp67T+l6MAGfg1NA6YznOEsX5pkR IKX8FVz8XdYFyCRvE4c2BhGps862w8tt2nxE1ccoY0ujP7EGiL2lT1mEuZgyp/VUD4lC 9wvg== X-Gm-Message-State: AOAM530g5MmdAVsUeiCsOi1xAw0kRpOYvDu2eyUYNSo7G182BzPHG3vq s6zgagFwoxVsg/e2AkBbM9tdRw== X-Received: by 2002:a63:6f42:: with SMTP id k63mr1967885pgc.358.1633587928707; Wed, 06 Oct 2021 23:25:28 -0700 (PDT) Received: from localhost.localdomain (122-100-26-39m5.mineo.jp. [122.100.26.39]) by smtp.gmail.com with ESMTPSA id b17sm22131859pgl.61.2021.10.06.23.25.25 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 06 Oct 2021 23:25:28 -0700 (PDT) From: AKASHI Takahiro To: xypron.glpk@gmx.de, agraf@csgraf.de Cc: ilias.apalodimas@linaro.org, sughosh.ganu@linaro.org, masami.hiramatsu@linaro.org, u-boot@lists.denx.de, AKASHI Takahiro Subject: [PATCH v4 07/11] doc: update UEFI document for usage of mkeficapsule Date: Thu, 7 Oct 2021 15:23:36 +0900 Message-Id: <20211007062340.72207-8-takahiro.akashi@linaro.org> X-Mailer: git-send-email 2.33.0 In-Reply-To: <20211007062340.72207-1-takahiro.akashi@linaro.org> References: <20211007062340.72207-1-takahiro.akashi@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 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 --- doc/develop/uefi/uefi.rst | 122 ++++++++++++++------------------------ 1 file changed, 46 insertions(+), 76 deletions(-) -- 2.33.0 diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst index f17138f5c765..6ae517e92c44 100644 --- a/doc/develop/uefi/uefi.rst +++ b/doc/develop/uefi/uefi.rst @@ -284,37 +284,52 @@ 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:: + + $ 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. - -If that option is disabled, you'll need to set the OsIndications variable with:: +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:: => 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 +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. -**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 ******************************* @@ -338,7 +353,7 @@ 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 + * openssl * efitools 2. Create signing keys and certificate files on your host @@ -347,59 +362,14 @@ and used by the steps highlighted below:: -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 - -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:: +Run the following command to create and sign the capsule file:: - $ mkeficapsule --raw --index 1 + $ mkeficapsule --monotonic-count 1 \ + --private-key CRT.key \ + --certificate CRT.crt \ + --index 1 --instance 0 \ + [--fit | --raw ] \ + Executing the boot manager ~~~~~~~~~~~~~~~~~~~~~~~~~~