[PATCH] efi_loader: add some description about UEFI secure boot

[Ilias Apalodimas]

On Fri, Feb 07, 2020 at 02:14:37PM +0900, AKASHI Takahiro wrote:
> A small text in docs/uefi/uefi.rst was added to explain how we can
> configure and utilise UEFI secure boot feature on U-Boot.
> 
> Signed-off-by: AKASHI Takahiro <takahiro.akashi at linaro.org>
> ---
>  doc/uefi/uefi.rst | 77 +++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 77 insertions(+)
> 
> diff --git a/doc/uefi/uefi.rst b/doc/uefi/uefi.rst
> index a8fd886d6b5e..98cd770aefe5 100644
> --- a/doc/uefi/uefi.rst
> +++ b/doc/uefi/uefi.rst
> @@ -97,6 +97,83 @@ Below you find the output of an example session starting GRUB::
>  
>  See doc/uImage.FIT/howto.txt for an introduction to FIT images.
>  
> +Configuring UEFI secure boot
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +UEFI specification[1] defines a secure way of executing UEFI images
> +by verifying a signature (or message digest) of image with certificates.
> +This feature on U-Boot is enabled with::
> +
> +    CONFIG_UEFI_SECURE_BOOT=y
> +
> +To make the boot sequence safe, you need to establish a chain of trust;
> +In UEFI secure boot, you can make it with the UEFI variables, "PK"
> +(Platform Key), "KEK" (Key Exchange Keys), "db" (white list database)
> +and "dbx" (black list database).
> +
> +There are many online documents that describe what UEFI secure boot is
> +and how it works. Please consult some of them for details.
> +
> +Here is a simple example that you can follow for your initial attempt
> +(Please note that the actual steps would absolutely depend on your system
> +and environment.):
> +
> +1. Install utility commands on your host
> +    * openssl
> +    * efitools
> +    * sbsigntool
> +
> +2. Create signing keys and key database files on your host
> +    for PK::
> +
> +        $ openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_PK/ \
> +                -keyout PK.key -out PK.crt -nodes -days 365
> +        $ cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \
> +                PK.crt PK.esl;
> +        $ sign-efi-sig-list -c PK.crt -k PK.key PK PK.esl PK.auth
> +
> +    for KEK::
> +
> +        $ openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_KEK/ \
> +                -keyout KEK.key -out KEK.crt -nodes -days 365
> +        $ cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \
> +                KEK.crt KEK.esl
> +        $ sign-efi-sig-list -c PK.crt -k PK.key KEK KEK.esl KEK.auth
> +
> +    for db::
> +
> +        $ openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=TEST_db/ \
> +                -keyout db.key -out db.crt -nodes -days 365
> +        $ cert-to-efi-sig-list -g 11111111-2222-3333-4444-123456789abc \
> +                db.crt db.esl
> +        $ sign-efi-sig-list -c KEK.crt -k KEK.key db db.esl db.auth
> +
> +    Copy \*.auth to media, say mmc, that is accessible from U-Boot.
> +
> +3. Sign an image with one key in "db" on your host::
> +
> +    $ sbsign --key db.key --cert db.crt helloworld.efi
> +
> +4. Install keys on your board::
> +
> +    ==> fatload mmc 0:1 <tmpaddr> PK.auth
> +    ==> setenv -e -nv -bs -rt -at -i <tmpaddr>,$filesize PK
> +    ==> fatload mmc 0:1 <tmpaddr> KEK.auth
> +    ==> setenv -e -nv -bs -rt -at -i <tmpaddr>,$filesize KEK
> +    ==> fatload mmc 0:1 <tmpaddr> db.auth
> +    ==> setenv -e -nv -bs -rt -at -i <tmpaddr>,$filesize db
> +
> +5. Set up boot parameters on your board::
> +
> +    ==> efidebug boot add 1 HELLO mmc 0:1 /helloworld.efi.signed ""
> +
> +Then your board runs that image from Boot manager (See below).
> +You can also try this sequence by running Pytest, test_efi_secboot,
> +on sandbox::
> +
> +    $ cd <U-Boot source directory>
> +    $ pytest.py test/py/tests/test_efi_secboot/test_signed.py --bd sandbox
> +
>  Executing the boot manager
>  ~~~~~~~~~~~~~~~~~~~~~~~~~~
>  
> -- 
> 2.24.0
> 

Acked-by: Ilias Apalodimas <ilias.apalodimas at linaro.org>