Merge https://gitlab.denx.de/u-boot/custodians/u-boot-spi

[platform/kernel/u-boot.git] / doc / uefi / uefi.rst

diff --git a/doc/uefi/uefi.rst b/doc/uefi/uefi.rst
index cfe2d84..4fda00d 100644 (file)
--- a/doc/uefi/uefi.rst
+++ b/doc/uefi/uefi.rst
@@ -97,6 +97,97 @@ 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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The 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 the chain trust is defined by the following UEFI variables
+
+* PK - Platform Key
+* KEK - Key Exchange Keys
+* db - white list database
+* dbx - black list database
+
+An in depth description of UEFI secure boot is beyond the scope of this
+document. Please, refer to the UEFI specification and available online
+documentation. Here is a simple example that you can follow for your initial
+attempt (Please note that the actual steps will depend on your system and
+environment.):
+
+Install the required tools on your host
+
+* openssl
+* efitools
+* sbsigntool
+
+Create signing keys and the key database on your host:
+
+The platform key
+
+.. code-block:: bash
+
+    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
+
+The key exchange keys
+
+.. code-block:: bash
+
+    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
+
+The whitelist database
+
+.. code-block:: bash
+
+    $ 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 the \*.auth files to media, say mmc, that is accessible from U-Boot.
+
+Sign an image with one of the keys in "db" on your host
+
+.. code-block:: bash
+
+    sbsign --key db.key --cert db.crt helloworld.efi
+
+Now in U-Boot install the 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
+
+Set up boot parameters on your board::
+
+    efidebug boot add 1 HELLO mmc 0:1 /helloworld.efi.signed ""
+
+Now your board can run the signed image via the boot manager (see below).
+You can also try this sequence by running Pytest, test_efi_secboot,
+on the sandbox
+
+.. code-block:: bash
+
+    cd <U-Boot source directory>
+    pytest.py test/py/tests/test_efi_secboot/test_signed.py --bd sandbox
+
 Executing the boot manager
 ~~~~~~~~~~~~~~~~~~~~~~~~~~