infra/common: add user guide for uefi secure boot

Add a new document that explains the procedure to validate uefi secure
boot on the Neoverse reference design platforms.
Signed-off-by: Sayanta Pattanayak <sayanta.pattanayak@arm.com>
Change-Id: Ifb2d5e0225a0a448273c111dcfc96a6d5d06b2cb

docs/infra/common/secure-boot.rst

+UEFI Secure Boot on Neoverse RD platforms
+=========================================
+
+.. contents::
+
+What is UEFI Secure Boot
+------------------------
+
+Secure boot is a mechanism to build and maintain a complete chain of trust on
+all the software layers executed in a system and preventing malicious code to be
+stored and loaded in place of the authenticated one. When the device starts, the
+firmware checks the signature of each piece of boot software, including UEFI
+firmware drivers, EFI applications, and the operating system. If the signatures
+are valid, the device boots, and the firmware gives control to the operating
+system. Fundamental to the success of the secure boot is the ability to securely
+store (also referred to as secure storage) and access the keys used for
+authentication during the various stages of boot.
+
+Secure boot and Secure storage mechanisms are defined by the UEFI
+specifications. In short, the UEFI specifications define the use of two
+asymmetric key pairs, platform key (PK) and Key Exchange Key (KEK), and
+databases for valid and black listed signatures. These keys and databases are
+used during the secure boot phase which implies that the platform should provide
+a tamper proof mechanism to store these keys.
+
+
+Secure boot support for RD platforms
+------------------------------------
+
+The RD platform software allows validation of the secure boot process. This
+document explains the procedure to build the platform software stack and
+validate UEFI secure boot on the RD platforms.
+
+Though secure boot process have to be validated using a linux distribution as
+the target OS, the RD platform software stack currently limits this feature
+validation to boot of a signed busybox OS.
+
+
+Platform Names
+--------------
+
+Arm's Infra reference platforms are assigned names in order to allow the build
+and execute scripts to recognize the platform that has to be buit and executed.
+The names for the reference platforms are listed below. Please make a note
+of the name of the platform of your choice. This name is required to start the
+build and execute procedure. The names under 'Platform Name' column has to be
+used in place of the placeholder ``<platform>`` as mentioned in the commands
+listed below.
+
++--------------------------+-------------------------+
+| Reference Platform       | Platform Name           |
++==========================+=========================+
+| SGI-575                  | sgi575                  |
++--------------------------+-------------------------+
+| RD-N1-Edge (Single Chip) | rdn1edge                |
++--------------------------+-------------------------+
+| RD-N1-Edge (Dual Chip)   | rdn1edgex2              |
++--------------------------+-------------------------+
+| RD-E1-Edge               | rde1edge                |
++--------------------------+-------------------------+
+| RD-Daniel Config-M       | rddaniel                |
++--------------------------+-------------------------+
+| RD-Daniel Config-XLR     | rddanielxlr             |
++--------------------------+-------------------------+
+| RD-N2                    | rdn2                    |
++--------------------------+-------------------------+
+
+
+Download the platform software
+------------------------------
+
+Skip this section if the required sources have been downloaded.
+
+To obtain the required sources for the platform, follow the steps listed on the
+`Download sources`_ page. Ensure that the platform software is downloaded before
+proceeding with the steps listed below. Also, note the host machine requirements
+listed on that page which is essential to build and execute the platform
+software stack.
+
+
+Generate key pairs
+------------------
+
+The next step is to create key pairs required for secure boot. The one-time
+generation of the following key pairs are mandatory - PK, KEK, DB and DBX. The
+following commands can be used to generate these key pairs. *Note:* Execute the
+following commands from the workspace into which the platform software has been
+downloaded.
+
+- Key Pair Creation : PK, KEK, DB and DBX
+
+  ::
+
+        cd rd-workspace  
+        cd tools/efitools
+        openssl req -new -x509 -newkey rsa:2048 -subj "/CN=PK/" -keyout PK.key -out PK.crt -days 3650 -nodes -sha256
+        openssl req -new -x509 -newkey rsa:2048 -subj "/CN=KEK/" -keyout KEK.key -out KEK.crt -days 3650 -nodes -sha256
+        openssl req -new -x509 -newkey rsa:2048 -subj "/CN=DB_Key/" -keyout DB.key -out DB.crt -days 3650 -nodes -sha256
+        openssl req -new -x509 -newkey rsa:2048 -subj "/CN=DBX_Key/" -keyout DBX.key -out DBX.crt -days 3650 -nodes -sha256
+
+- Convert crt certificate to der format
+
+  ::
+
+        openssl x509 -in PK.crt -outform der -out PK.der
+        openssl x509 -in KEK.crt -outform der -out KEK.der
+        openssl x509 -in DB.crt -outform der -out DB.der
+        openssl x509 -in DBX.crt -outform der -out DBX.der
+
+The signing of the grub and linux images are performed as a part of build script
+“build-test-secureboot.sh”. There is no explicit user action required to sign
+these images.
+
+
+Build the platform software
+---------------------------
+
+The procedure to build the platform software stack for secure boot test is
+listed below.
+
+To build the software stack, the command to be used is
+
+::
+
+  ./build-scripts/rdinfra/build-test-secureboot.sh -p <plaform> <command>
+
+Supported command line options are listed below
+
+* <platform>
+
+  - Supported platforms are listed in `Platform Names`_.
+
+* <command>
+
+  - Supported commands are
+
+    - ``clean``
+    - ``build``
+    - ``package``
+    - ``all`` (all of the three above)
+
+
+Examples of the build command are
+
+- Command to clean, build and package the software stack needed for the secure
+  boot test for RD-N2 platform.
+
+  ::
+
+     ./build-scripts/rdinfra/build-test-secureboot.sh -p rdn2 all
+
+- Command to perform an incremental build of the software components included in
+  the software stack for the RD-N2 platform.
+  
+  *Note:* This command should be followed by the ``package`` command to complete
+  the preparation of the fip and the disk image.
+
+  ::
+
+    ./build-scripts/rdinfra/build-test-secureboot.sh -p rdn2 build
+
+- Command to package the previously built software stack and prepare the fip and
+  the disk image.
+
+  ::
+
+    ./build-scripts/rdinfra/build-test-secureboot.sh -p rdn2 package
+
+
+Securely boot upto Busybox
+--------------------------
+
+After the build of the platform software stack for UEFI secure boot is complete,
+the following command starts the execution of the *selected platform fastmodel*
+and the software boots up to the busybox prompt. Examples on how to use the
+command are listed below.
+
+*Note:* The steps to enroll signatures required to successfully secure boot the
+platform is listed as well. It is important to execute those steps atleast once
+to validate secure boot support.
+
+To boot up to the busybox prompt, the commands to be used are
+
+- Set ``MODEL`` path before launching the model:
+
+  ::
+
+    export MODEL=<absolute path to the platform FVP binary>
+
+- If platform is SGI-575:
+
+  ::
+
+    cd model-scripts/sgi
+
+- If platform is an RD:
+
+  ::
+
+    cd model-scripts/rdinfra
+
+- Launch busybox boot:
+
+  ::
+
+    ./secure_boot.sh -p <platform> -a <additional_params> -n [true|false]
+
+
+Supported command line options are listed below
+
+*  -p <platform>
+
+   - Supported platforms are listed in `Platform Names`_.
+
+*  -n [true|false] (optional)
+
+   - Controls the use of network ports by the model. If network ports have
+     to be enabled, use 'true' as the option. Default value is set to
+     'false'.
+
+*  -a <additional_params> (optional)
+
+   - Specify any additional model parameters to be passed. The model
+     parameters and the data to be passed to those parameters can be found
+     in the FVP documentation.
+
+
+Example commands to validate the secure boot functionality are as listed below.
+
+- Command to start the execution of the RD-N2 model to boot up to the
+  Busybox prompt with secure boot enabled:
+
+  ::
+
+    ./secure_boot.sh -p rdn2
+
+- Command to start the execution of the RD-N2 model to boot up to the
+  Busybox prompt with secure boot and network enabled. The model supports
+  virtio.net allowing the software running within the model to access the
+  network:
+
+  ::
+
+    ./secure_boot.sh -p rdn2 -n true
+
+- Command to start the execution of the RD-N2 model with networking
+  enabled and to boot up to the Busybox prompt with secure boot enabled.
+  Additional parameters to the model are supplied using the -a command
+  line parameter:
+
+  ::
+
+    ./secure_boot.sh -p rdn2 -n true -a "-C board.flash0.diagnostics=1"
+
+
+There are additional steps to be performed on the first boot to setup the secure
+boot process. These steps are listed below. Ensure that these steps are executed
+on the very first boot for validating the secure boot.
+
+- Interrupt the boot at EDK2 by pressing escape key and dropping into the EDK2
+  boot menu.
+- Select Device Manger -> Secure Boot Configuration -> Secure Boot Mode →
+  choose Custom mode and then press enter.
+- Select "Custom Secure Boot Options” and then press enter.
+- Select “DBX Options” -> "Enroll Signature" then press enter →
+  "Enroll Signature Using File" and the press enter → Select “NO VOLUME LEBEL”
+  and then press enter.
+- Select EFI and press enter -> select BOOT and press enter → now Select
+  “DBX.der” and press enter -> “Commit Changes and Exit”.
+- Repeat steps “d” and “e” for “DB options” for “DB.der”.
+- Repeat steps “d” and “e” for “KEK options” for “KEK.der”.
+- Repeat steps “d” and “e” for “PK options” for “PK.der”.
+- Press Escape and press F10 to save. Ensure that the “Current Secure Boot
+  State” is set as “Enabled”.
+- Press Escape and select the “continue” option.
+- Prompts the user to press the “Enter”. Press Enter key which then reboots the
+  system
+- Make sure to close the model using “Cross Mark” on the FVP UI window titled
+  'Fast Models - <platform_name>' after this. If model does not close then press
+  “ctrl-c” to close it. Here, <platform_name> is one of those listed in
+  `Platform Names`_.
+
+Relaunch the model again with repeat the steps listed above to perform a secure
+boot (but skip the steps to enroll the signatures). The platform boots up to
+busybox login prompt with secure boot enabled. If the authentication of the grub
+or the linux kernel fails, the boot fails and the user is notified about the
+authentication failure.
+
+To confirm that the boot is indeed a secure boot, the linux kernel messages
+can be looked up. The following messages would appear in the linux boot log in
+case of a secure linux kernel boot:
+
+   ::
+
+     Loading driver at 0x000F50A0000 EntryPoint=0x000F676A188
+     Loading driver at 0x000F50A0000 EntryPoint=0x000F676A188
+     EFI stub: Booting Linux Kernel...
+     EFI stub: EFI_RNG_PROTOCOL unavailable, KASLR will be disabled
+     EFI stub: UEFI Secure Boot is enabled.
+     EFI stub: Using DTB from configuration table
+     EFI stub: Exiting boot services and installing virtual address map...
+     [    0.000000] Booting Linux on physical CPU 0x0000000000 [0x410fd490]
+
+This completes the validation of the secure boot functionality.
+
+--------------
+
+*Copyright (c) 2021, Arm Limited. All rights reserved.*
+
+.. _Download sources: docs/infra/common/download-sources.rst