From patchwork Thu Apr 30 17:36:30 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sughosh Ganu X-Patchwork-Id: 239031 List-Id: U-Boot discussion From: sughosh.ganu at linaro.org (Sughosh Ganu) Date: Thu, 30 Apr 2020 23:06:30 +0530 Subject: [PATCH 8/8] qemu: arm64: Add documentation for capsule update In-Reply-To: <20200430173630.15608-1-sughosh.ganu@linaro.org> References: <20200430173630.15608-1-sughosh.ganu@linaro.org> Message-ID: <20200430173630.15608-9-sughosh.ganu@linaro.org> Add documentation highlighting the steps for using the uefi capsule update feature for updating the u-boot firmware image. Signed-off-by: Sughosh Ganu --- doc/board/emulation/qemu-arm.rst | 112 +++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/doc/board/emulation/qemu-arm.rst b/doc/board/emulation/qemu-arm.rst index ca751d4af4..8649d593ed 100644 --- a/doc/board/emulation/qemu-arm.rst +++ b/doc/board/emulation/qemu-arm.rst @@ -80,3 +80,115 @@ can be enabled with the following command line parameters: -drive if=none,file=disk.img,id=mydisk -device nvme,drive=mydisk,serial=foo These have been tested in QEMU 2.9.0 but should work in at least 2.5.0 as well. + +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). Currently, support has been added for the arm64 +target booting with arm trusted firmware. The This feature is enabled +with the following configs:: + + CONFIG_EFI_CAPSULE_ON_DISK=y + CONFIG_EFI_FIRMWARE_MANAGEMENT_PROTOCOL=y + CONFIG_CMD_EFIDEBUG=y + +The capsule file can be generated by using the GenerateCapsule.py +script in edk2:: + + $ ./BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \ + --fw-version --lsv --guid \ + fb90808a-ba9a-4d42-b9a2-a7a937144aee --verbose --update-image-index \ + --verbose + + +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 and +BootXXXX need to be set. The BootXXXX variable needs to be pointing to +the EFI System Partition which contains the capsule file. The +BootNext and BootXXXX variables can be set using the efidebug +command:: + + => efidebug boot add 0 Boot0000 virtio 0:1 + => efidebug boot next 0 + +The OsIndications efi variable needs to be set with the +EFI_OS_INDICATIONS_FILE_CAPSULE_DELIVERY_SUPPORTED flag set:: + + => setenv -e -nv -bs -rt OsIndications =0x04 + => saveenv + +The capsule update function will be invoked on subsequent boot as part +of the main_loop function. 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 stored as an +efi variable. + +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 esl file can be generated as follows: + +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 + +3. Store the esl file generated above as an efi variable:: + + => fatload virtio 0:1 EFI/CRT.esl + => setenv -e -nv -bs -rt -i ,$filesize CRT + + => setenv capsule_authentication_enabled 1 + => setenv -e -nv -bs -rt OsIndication =0x04 + => saveenv + +Setting the environment variable capsule_authentication_enabled +enables the capsule authentication. + +4. The capsule file can be generated by using the GenerateCapsule.py + script in edk2:: + + $ ./BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \ + --monotonic-count --fw-version \ + --lsv --guid \ + fb90808a-ba9a-4d42-b9a2-a7a937144aee --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 \ + + +Once the capsule has been generated, use the same instructions as +mentioned above for placing the capsule on the EFI System Partition +and subsequently to initiate the update.