From mboxrd@z Thu Jan 1 00:00:00 1970 From: Sughosh Ganu Date: Tue, 22 Dec 2020 11:40:38 +0530 Subject: [PATCH v2 14/14] qemu: arm64: Add documentation for capsule update In-Reply-To: References: <20201221114314.25588-1-sughosh.ganu@linaro.org> <20201221114314.25588-15-sughosh.ganu@linaro.org> <1e8d0f09-f073-2334-481e-8b201826d9cd@gmx.de> Message-ID: List-Id: MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit To: u-boot@lists.denx.de On Mon, 21 Dec 2020 at 23:21, Heinrich Schuchardt wrote: > On 12/21/20 6:12 PM, Sughosh Ganu wrote: > > On Mon, 21 Dec 2020 at 18:28, Heinrich Schuchardt > > wrote: > > > >> On 12/21/20 12:43 PM, Sughosh Ganu wrote: > >>> Add documentation highlighting the steps for using the uefi capsule > >>> update feature for updating the u-boot firmware image. > >>> > >>> Signed-off-by: Sughosh Ganu > >>> --- > >>> > >>> Changes since V1: > >>> * Change the documentation to reflect the usage of overlays for > >>> embedding the public key certs at runtime > >>> * Fix the build for 'make htmldocs' > >>> > >>> doc/board/emulation/qemu-arm.rst | 188 > +++++++++++++++++++++++++++++++ > >> > >> Why do you put the information into doc/board/emulation/qemu-arm.rst? > >> > >> Isn't the same applicable to RISC-V QEMU? > >> > > > > Where do you want me to put it. Currently, I do not see any common > document > > for qemu which can be shared between qemu-arm and qemu risc-v. Or do you > > think a new document should be created under doc/board/emulation/ > > directory. Moreover, my series is adding support for capsule update > feature > > on the qemu arm64 platform, and i have only tested this feature on the > qemu > > arm64 platform. If someone wants to extend this on the qemu > > risc-v platform, that work i think needs to be done separately, with > > whatever changes that may be needed to get capsule updates working on > qemu > > risc-v. If you so prefer, I can move the changes made for mtdparts and > > dfu(patches 4/14 and 5/14) under a common directory under > board/emulation. > > > I have started putting the documentation for shell commands into > doc/usage. This is where a description of efidebug could be placed. > > Equally I think we should put the documentation of tools like > mkeficapsule under doc/usage. > > The description on the usage of the UEFI firmware protocol would fit > into doc/uefi/uefi.rst. > > When it comes to things that are really QEMU specific > doc/board/emulation/ is the right folder. > Ok. I will create a Qemu specific file for capsule updates under the doc/board/emulation/ directory. > > See more comments below. > > > > > -sughosh > > > > > >> > >> Best regards > >> > >> Heinrich > >> > >>> 1 file changed, 188 insertions(+) > >>> > >>> diff --git a/doc/board/emulation/qemu-arm.rst > >> b/doc/board/emulation/qemu-arm.rst > >>> index 8d7fda10f1..11d91811b3 100644 > >>> --- a/doc/board/emulation/qemu-arm.rst > >>> +++ b/doc/board/emulation/qemu-arm.rst > >>> @@ -90,3 +90,191 @@ The debug UART on the ARM virt board uses these > >> settings:: > >>> CONFIG_DEBUG_UART_PL010=y > >>> CONFIG_DEBUG_UART_BASE=0x9000000 > >>> CONFIG_DEBUG_UART_CLOCK=0 > >>> + > >>> +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 > > %s/uefi/UEFI/ > > >>> +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). > > According to the UEFI spec the relevant directory is \EFI\UpdateCapsule. > I think you should mentions this path. > > >>> + > >>> +Currently, support has been added for updating the u-boot binary as a > > %s/u-boot/U-Boot/g > > >>> +raw image when the platform is booted in non-secure mode, i.e with > > %s/i.e/i.e./ > > >>> +CONFIG_TFABOOT disabled. For this configuration, the qemu platform > > %s/qemu/QEMU/ > > >>> +needs to be booted with 'secure=off'. The u-boot binary placed on the > > U-Boot > > >>> +first bank of the Nor Flash at offset 0x0. The u-boot environment is > > %s/Nor Flash/NOR flash/ > > U-Boot > > >>> +placed on the second Nor Flash bank at offset 0x4000000. > > NOR flash > > >>> + > >>> +The capsule update feature is enabled with the following configs:: > > %s/configs/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:: > >>> + > >>> + CONFIG_TFABOOT > >>> + > >>> +The capsule file can be generated by using the GenerateCapsule.py > >>> +script in edk2:: > > EDK II > > >>> + > >>> + $ ./BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \ > >>> + --fw-version --lsv --guid \ > >>> + e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose > --update-image-index > >> \ > >>> + --verbose > >>> + > >>> +As per the uefi specification, the capsule file needs to be placed on > > UEFI > > >>> +the EFI System Partition, under the EFI/UpdateCapsule/ directory. The > > \EFI\UpdateCapsule\ (see UEFI specification) > > >>> +EFI System Partition can be a virtio-blk-device. > >>> + > >>> +Before initiating the firmware update, the efi variables BootNext, > > %s/efi/UEFI/ > > >>> +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 > > Shouldn't OsIndications bit 2 be set by default when EFI capsule support > is enabled? How about bit 3 (EFI_OS_INDICATIONS_FMP_CAPSULE_SUPPORTED)? > The OsIndications bit 2(EFI_OS_INDICATIONS_FILE_CAPSULE_DELIEVERY_SUPPORTED) should be set by the OS through a SetVariable call. This is still work in progress though, hence, for now, we are setting the bit in u-boot before invoking the capsule update. As for the bit 3(EFI_OS_INDICATIONS_FMP_CAPSULE_SUPPORTED), this has no function in the OsIndications variable. This needs to be set in the variable OsIndicationsSupported, which is being done in the function efi_init_os_indications. -sughosh > >>> +using the following commands:: > >>> + > >>> + => efidebug boot add 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. > > U-Boot > > >>> + > >>> +Enabling Capsule Authentication > >>> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ > >>> + > >>> +The uefi specification defines a way of authenticating the capsule to > > UEFI > > >>> +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 > > QEMU > > >>> +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 > > QEMU > > >>> +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 > > 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 edk2:: > > EDK II > > >>> + > >>> + $ ./BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \ > > Above you wrote GenerateCapsule.py. I understand that the binary wrapper > shall be used. But somehow this should be explained. > > >>> + --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 user will be lost here. Please, provide the content of the > file here. > > >>> + > >>> + 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 fdt at runtime. > > %s/fdt/flattened device-tree (dtb)/ > > >>> + > >>> +Build u-boot with the following steps:: > > U-Boot > > >>> + > >>> + $ 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 env and efi Boot variables > > environment and UEFI boot variables > > >>> + > >>> + => setenv -e -nv -bs -rt -v OsIndications =0x04 > >>> + => efidebug boot add 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 > > U-Boot > > Best regards > > Heinrich > > >> binary. > >>> > >> > >> > > > >