[PATCH v6 8/8] doc: uefi: add anti-rollback documentation

[Masahisa Kojima]

On Mon, 22 May 2023 at 09:27, Takahiro Akashi
<takahiro.akashi at linaro.org> wrote:
>
> Hi Kojima-san,
>
> On Fri, May 19, 2023 at 07:32:14PM +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>
> > ---
> > Newly created in v6
> >
> >  doc/develop/uefi/uefi.rst | 32 ++++++++++++++++++++++++++++++++
> >  1 file changed, 32 insertions(+)
> >
> > diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst
> > index efab0fc7b1..f1f13bb993 100644
> > --- a/doc/develop/uefi/uefi.rst
> > +++ b/doc/develop/uefi/uefi.rst
> > @@ -539,6 +539,38 @@ since FMP protocol handles multiple image indexes.
> >        [--fit | --raw | --guid <guid-string] \
> >        <image_blob> <capsule_file_name>
> >
> > +Anti-rollback Protection
> > +~~~~~~~~~~~~~~~~~~~~~~~~
> > +
> > +The anti-rollback protection is implemented differently from firmware versioning.
> > +U-Boot implements the file-based EFI variable storage, it can be tampered
> > +and not the right place to store the lowest supported version.
> > +U-Boot uses device tree to store the lowest supported version, it is secured
> > +as long as dtb is authenticated together with U-Boot image by the authenticated
> > +capsule update, and the former stage boot loader verifies the image containing the dtb
> > +when the system boots.
>
> This is details of implementation.
> You should rather mention the usage, i.e. how "anti-rollback" can be managed
> and achieved using firmware-version and lowest-supported-version and that users
> should always update their device tree to enforce the protection.

OK, I will clearly describe how the lowest-supported-version interacts
with fw_version.

Thanks,
Masahisa Kojima

> (If the lowest-supported-version is kept the same even after the firmware update,
> anti-rollback won't work.)
>
> -Takahiro Akashi
>
> > +1. Insert the lowest supported version into a device tree
> > +
> > +.. 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>;
> > +                    };
> > +            };
> > +    };
> > +
> >  Executing the boot manager
> >  ~~~~~~~~~~~~~~~~~~~~~~~~~~
> >
> > --
> > 2.17.1
> >