diff mbox series

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

Message ID 20200430173630.15608-9-sughosh.ganu@linaro.org
State New
Headers show
Series qemu: arm64: Add support for uefi firmware management protocol routines | expand

Commit Message

Sughosh Ganu April 30, 2020, 5:36 p.m. UTC
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>
---
 doc/board/emulation/qemu-arm.rst | 112 +++++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)

Comments

Heinrich Schuchardt April 30, 2020, 6:37 p.m. UTC | #1
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?

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.
>
Sughosh Ganu April 30, 2020, 7:08 p.m. UTC | #2
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.
> >
>
>
Tom Rini April 30, 2020, 7:27 p.m. UTC | #3
On Fri, May 01, 2020 at 12:38:45AM +0530, Sughosh Ganu wrote:
> 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.

Since we're talking QEMU here, how much of this can be easily dropped in
to QEMU x86_64 and QEMU RISC-V?  If not almost all of it, why?  Can it
be reworked as such?
Sughosh Ganu May 1, 2020, 5:47 a.m. UTC | #4
On Fri, 1 May 2020 at 00:57, Tom Rini <trini at konsulko.com> wrote:

> On Fri, May 01, 2020 at 12:38:45AM +0530, Sughosh Ganu wrote:
> > 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.
>
> Since we're talking QEMU here, how much of this can be easily dropped in
> to QEMU x86_64 and QEMU RISC-V?  If not almost all of it, why?  Can it
> be reworked as such?
>

I don't think it would be too difficult to extend it on other
architectures, provided there is some mechanism to access and overwrite the
u-boot binary file from the qemu target. It is currently being done using
the semihosting interface for the arm architecture. I am not aware if there
is an interface like semihosting for accessing the u-boot binary on the
other architectures that you mentioned. Will check on this.

-sughosh
AKASHI Takahiro May 7, 2020, 2:10 a.m. UTC | #5
On Fri, May 01, 2020 at 11:17:27AM +0530, Sughosh Ganu wrote:
> On Fri, 1 May 2020 at 00:57, Tom Rini <trini at konsulko.com> wrote:
> 
> > On Fri, May 01, 2020 at 12:38:45AM +0530, Sughosh Ganu wrote:
> > > 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.
> >
> > Since we're talking QEMU here, how much of this can be easily dropped in
> > to QEMU x86_64 and QEMU RISC-V?  If not almost all of it, why?  Can it
> > be reworked as such?
> >
> 
> I don't think it would be too difficult to extend it on other
> architectures, provided there is some mechanism to access and overwrite the
> u-boot binary file from the qemu target. It is currently being done using
> the semihosting interface for the arm architecture. I am not aware if there
> is an interface like semihosting for accessing the u-boot binary on the
> other architectures that you mentioned. Will check on this.

Obviously, another choice would be my FIT-based FMP[1]
as it uses update_tftp(), more specifically dfu_tftp_write(),
internally.

[1] https://lists.denx.de/pipermail/u-boot/2020-April/408767.html

Thanks,
-Takahiro Akashi


> -sughosh
Heinrich Schuchardt May 7, 2020, 8:52 p.m. UTC | #6
On 5/7/20 4:10 AM, Akashi Takahiro wrote:
> On Fri, May 01, 2020 at 11:17:27AM +0530, Sughosh Ganu wrote:
>> On Fri, 1 May 2020 at 00:57, Tom Rini <trini at konsulko.com> wrote:
>>
>>> On Fri, May 01, 2020 at 12:38:45AM +0530, Sughosh Ganu wrote:
>>>> 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.
>>>
>>> Since we're talking QEMU here, how much of this can be easily dropped in
>>> to QEMU x86_64 and QEMU RISC-V?  If not almost all of it, why?  Can it
>>> be reworked as such?
>>>
>>
>> I don't think it would be too difficult to extend it on other
>> architectures, provided there is some mechanism to access and overwrite the
>> u-boot binary file from the qemu target. It is currently being done using
>> the semihosting interface for the arm architecture. I am not aware if there
>> is an interface like semihosting for accessing the u-boot binary on the
>> other architectures that you mentioned. Will check on this.
>
> Obviously, another choice would be my FIT-based FMP[1]
> as it uses update_tftp(), more specifically dfu_tftp_write(),
> internally.
>
> [1] https://lists.denx.de/pipermail/u-boot/2020-April/408767.html
>
> Thanks,
> -Takahiro Akashi

Please, try to align. We should avoid alternative implementations were
not needed. We could also have a chat on Zoom together.

Best regards

Heinrich

>
>
>> -sughosh
diff mbox series

Patch

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.