[PATCH 8/8] qemu: arm64: Add documentation for capsule update

[Sughosh Ganu]

On Fri, 1 May 2020 at 00:07, Heinrich Schuchardt <xypron.glpk at gmx.de> wrote:

> On 4/30/20 7:36 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 at linaro.org>
>
> UEFI capsule updates should be architecture independent. I would expect
> that the submitted code should work for x86, ARM, and RISC-V. Why does
> this documentation live under the ARM emulation tree?
>

While the implementation of the core capsule update functionality is indeed
architecture agnostic, this series is for implementing the routines of the
firmware management protocol, which is very much platform specific -- the
routines to perform the actual firmware update would be very much tied to
the platform for which the firmware is being updated. So Takahiro's patch
series, which adds the core capsule update changes is architecture
independent, while this series is adding the routines for the firmware
management protocol, which would be very much platform specific.

-sughosh


>
> Best regards
>
> Heinrich
>
> > ---
> >  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 \
> > +    <capsule_file_name> --fw-version <val> --lsv <val> --guid \
> > +    fb90808a-ba9a-4d42-b9a2-a7a937144aee --verbose --update-image-index
> \
> > +    <val> --verbose <u-boot.bin>
> > +
> > +
> > +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 <capsule_file_name>
> > +    => 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 <load_addr> EFI/CRT.esl
> > +        => setenv -e -nv -bs -rt -i <load_addr>,$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 \
> > +     <capsule_file_name> --monotonic-count <val> --fw-version \
> > +     <val> --lsv <val> --guid \
> > +     fb90808a-ba9a-4d42-b9a2-a7a937144aee --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>
> > +
> > +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.
> >
>
>