[PATCH v9 08/10] doc: uefi: add anti-rollback documentation

[Masahisa Kojima]

On Wed, 7 Jun 2023 at 19:22, Takahiro Akashi <takahiro.akashi at linaro.org> wrote:
>
> On Wed, Jun 07, 2023 at 02:41:58PM +0900, Masahisa Kojima wrote:
> > This commit describe the procedure to configure lowest supported
> > version in the device tree for anti-rollback protection.
> >
> > Signed-off-by: Masahisa Kojima <masahisa.kojima at linaro.org>
> > ---
> > No update since v7
> >
> > Changes in v7:
> > - describe the usage
> >
> > Newly created in v6
> >
> >  doc/develop/uefi/uefi.rst | 39 +++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 39 insertions(+)
> >
> > diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
> > index 30b90a09d5..ffd13cebe9 100644
> > --- a/doc/develop/uefi/uefi.rst
> > +++ b/doc/develop/uefi/uefi.rst
> > @@ -537,6 +537,45 @@ where signature.dts looks like::
> >              };
> >      };
> >
> > +Anti-rollback Protection
> > +************************
> > +
> > +Anti-rollback prevents unintentional installation of outdated firmware.
> > +To enable anti-rollback, you must add the lowest-supported-version property
> > +to dtb and specify --fw-version when creating a capsule file with the
> > +mkeficapsule tool.
> > +When executing capsule update, U-Boot checks if fw_version is greater than
> > +or equal to lowest-supported-version. If fw_version is less than
> > +lowest-supported-version, the update will fail.
> > +For example, if lowest-supported-version is set to 7 and you run capsule
> > +update using a capsule file with --fw-version of 5, the update will fail.
> > +When the --fw-version in the capsule file is updated, lowest-supported-version
> > +in the dtb might be updated accordingly.
>               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> I think that you should explicitly mention that a user always needs to update dtb
> *manually* in order to enforce anti-rollback to *any* older version.
> Otherwise, people may recognize that dtb be updated by the system (U-Boot).

Sorry for the late reply.
I agree with this.
This series was already merged into u-boot/next, so I will send the
follow-up patch
to include this comment.

Thanks,
Masahisa Kojima

>
> -Takahiro Akashi
>
> > +
> > +To insert the lowest supported version into a dtb
> > +
> > +.. code-block:: console
> > +
> > +    $ dtc -@ -I dts -O dtb -o version.dtbo version.dts
> > +    $ fdtoverlay -i orig.dtb -o new.dtb -v version.dtbo
> > +
> > +where version.dts looks like::
> > +
> > +    /dts-v1/;
> > +    /plugin/;
> > +    &{/} {
> > +            firmware-version {
> > +                    image1 {
> > +                            image-type-id = "09D7CF52-0720-4710-91D1-08469B7FE9C8";
> > +                            image-index = <1>;
> > +                            lowest-supported-version = <3>;
> > +                    };
> > +            };
> > +    };
> > +
> > +The properties of image-type-id and image-index must match the value
> > +defined in the efi_fw_image array as image_type_id and image_index.
> > +
> >  Executing the boot manager
> >  ~~~~~~~~~~~~~~~~~~~~~~~~~~
> >
> > --
> > 2.34.1
> >