Merge "docs(security): update info on use of OpenSSL 3.0" into integration

docs/design/trusted-board-boot-build.rst

@@ -35,6 +35,13 @@ images with support for these features:
    By default, this will use the Chain of Trust described in the TBBR-client
    document. To select a different one, use the ``COT`` build option.
 
+   If using a custom build of OpenSSL, set the ``OPENSSL_DIR`` variable
+   accordingly so it points at the OpenSSL installation path, as explained in
+   :ref:`Build Options`. In addition, set the ``LD_LIBRARY_PATH`` variable
+   when running to point at the custom OpenSSL path, so the OpenSSL libraries
+   are loaded from that path instead of the default OS path. Export this
+   variable if necessary.
+
    In the case of Arm platforms, the location of the ROTPK hash must also be
    specified at build time. The following locations are currently supported (see
    ``ARM_ROTPK_LOCATION`` build option):
@@ -63,7 +70,7 @@ images with support for these features:
        make PLAT=<platform> TRUSTED_BOARD_BOOT=1 GENERATE_COT=1        \
        ARM_ROTPK_LOCATION=devel_rsa                                    \
        ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem        \
-       BL33=<path-to>/<bl33_image>                                     \
+       BL33=<path-to>/<bl33_image> OPENSSL_DIR=<path-to>/<openssl>     \
        all fip
 
    The result of this build will be the bl1.bin and the fip.bin binaries. This
@@ -87,7 +94,7 @@ images with support for these features:
        make PLAT=juno TRUSTED_BOARD_BOOT=1 GENERATE_COT=1              \
        ARM_ROTPK_LOCATION=devel_rsa                                    \
        ROT_KEY=plat/arm/board/common/rotpk/arm_rotprivk_rsa.pem        \
-       BL33=<path-to>/<bl33_image>                                     \
+       BL33=<path-to>/<bl33_image> OPENSSL_DIR=<path-to>/<openssl>     \
        SCP_BL2=<path-to>/<scp_bl2_image>                               \
        SCP_BL2U=<path-to>/<scp_bl2u_image>                             \
        NS_BL2U=<path-to>/<ns_bl2u_image>                               \
@@ -109,7 +116,7 @@ images with support for these features:
 
 --------------
 
-*Copyright (c) 2019-2020, Arm Limited. All rights reserved.*
+*Copyright (c) 2019-2022, Arm Limited. All rights reserved.*
 
 .. _mbed TLS Repository: https://github.com/ARMmbed/mbedtls.git
 .. _mbed TLS Security Center: https://tls.mbed.org/security

docs/getting_started/build-options.rst

@@ -974,9 +974,10 @@ Common build options
   bit, to trap access to the RAS ERR and RAS ERX registers from lower ELs.
   This flag is disabled by default.
 
-- ``OPENSSL_DIR``: This flag is used to provide the installed openssl directory
-  path on the host machine which is used to build certificate generation and
-  firmware encryption tool.
+- ``OPENSSL_DIR``: This option is used to provide the path to a directory on the
+  host machine where a custom installation of OpenSSL is located, which is used
+  to build the certificate generation, firmware encryption and FIP tools. If
+  this option is not set, the default OS installation will be used.
 
 - ``USE_SP804_TIMER``: Use the SP804 timer instead of the Generic Timer for
   functions that wait for an arbitrary time length (udelay and mdelay). The

docs/getting_started/prerequisites.rst

@@ -58,6 +58,12 @@ supporting tools:
 
    Required to build the cert_create tool.
 
+   .. note::
+
+    OpenSSL 3.0 has to be built from source code, as it's not available in
+    the default package repositories in recent Ubuntu versions. Please refer
+    to the OpenSSL project documentation for more information.
+
 The following libraries are required for Trusted Board Boot and Measured Boot
 support:
 
@@ -90,7 +96,7 @@ required packages with the following command:
 
 .. code:: shell
 
-    sudo apt install build-essential git libssl-dev
+    sudo apt install build-essential git
 
 The optional packages can be installed using:
 

docs/getting_started/tools-build.rst

@@ -1,6 +1,16 @@
 Building Supporting Tools
 =========================
 
+.. note::
+
+    OpenSSL 3.0 is needed in order to build the tools. A custom installation
+    can be used if not updating the OpenSSL version on the OS. In order to do
+    this, use the ``OPENSSL_DIR`` variable after the ``make`` command to
+    indicate the location of the custom OpenSSL build. Then, to run the tools,
+    use the ``LD_LIBRARY_PATH`` to indicate the location of the built
+    libraries. More info about ``OPENSSL_DIR`` can be found at
+    :ref:`Build Options`.
+
 Building and using the FIP tool
 -------------------------------
 
@@ -164,4 +174,4 @@ via using ``cat <filename>`` instead of a hex string.
 
 --------------
 
-*Copyright (c) 2019, Arm Limited. All rights reserved.*
+*Copyright (c) 2019-2022, Arm Limited. All rights reserved.*