On Mon, 21 Dec 2020 at 23:21, Heinrich Schuchardt xypron.glpk@gmx.de wrote:
On 12/21/20 6:12 PM, Sughosh Ganu wrote:
On Mon, 21 Dec 2020 at 18:28, Heinrich Schuchardt xypron.glpk@gmx.de 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 sughosh.ganu@linaro.org
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 \
- <capsule_file_name> --fw-version <val> --lsv <val> --guid \
- e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose
--update-image-index
\
- <val> --verbose <u-boot.bin>
+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 <capsule_file_name>
- => 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::
- Install utility commands on your host
* opensslOpenSSL
* efitools
- 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 -outCRT.pub.pem
$ openssl pkcs12 -export -out CRT.pfx -inkey CRT.key -inCRT.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.
<capsule_file_name> --monotonic-count <val> --fw-version \<val> --lsv <val> --guid \e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose \--update-image-index <val> --signer-private-cert \/path/to/CRT.pem --trusted-public-cert \/path/to/CRT.pub.pem --other-public-cert /path/to/CRT.pub.pem \<u-boot.bin>+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::
- Generate a skeleton overlay dts file, with a single fragment
node and an empty __overlay__ nodeA typical user will be lost here. Please, provide the content of the file here.
- Convert the dts to a corresponding dtb with the following
command./scripts/dtc/dtc -@ -I dts -O dtb -o <ov_dtb_file_name> \<dts_file>
- Run the dtb file generated above through the mkeficapsule tool
in u-boot./tools/mkeficapsule -O <pub_key.esl> -D <ov_dtb>+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_TFABOOTEnable CONFIG_EFI_CAPSULE_AUTHENTICATEEnable all configs needed for capsule update(listed above)- $ make all
+Boot the platform and perform the following steps on the u-boot +command line::
- Enable capsule authentication by setting the following env
variable=> setenv capsule_authentication_enabled 1=> saveenv
- Load the overlay dtb to memory and merge it with the base fdt
=> fatload virtio 0:1 <$fdtovaddr> EFI/<ov_dtb_file>=> fdt addr $fdtcontroladdr=> fdt resize <size_of_ov_dtb_file>=> fdt apply <$fdtovaddr>
- 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 <capsule_file_name>=> efidebug boot next 0=> saveenv
- 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.