Add support for pointer authentication

The previous commit added the infrastructure to load and save
ARMv8.3-PAuth registers during Non-secure <-> Secure world switches, but
didn't actually enable pointer authentication in the firmware.

This patch adds the functionality needed for platforms to provide
authentication keys for the firmware, and a new option (ENABLE_PAUTH) to
enable pointer authentication in the firmware itself. This option is
disabled by default, and it requires CTX_INCLUDE_PAUTH_REGS to be
enabled.

Change-Id: I35127ec271e1198d43209044de39fa712ef202a5
Signed-off-by: Antonio Nino Diaz <antonio.ninodiaz@arm.com>

3 files changed, 29 insertions, 1 deletions

diff --git a/docs/firmware-design.rst b/docs/firmware-design.rst
index 808afeedb..ead7297d9 100644
--- a/docs/firmware-design.rst
+++ b/docs/firmware-design.rst
@@ -2566,6 +2566,11 @@ Armv8.3-A
    must be set to 1. This will add all pointer authentication system registers
    to the context that is saved when doing a world switch.
 
+   The Trusted Firmware itself has support for pointer authentication at runtime
+   that can be enabled by setting both options ``ENABLE_PAUTH`` and
+   ``CTX_INCLUDE_PAUTH_REGS`` to 1. This enables pointer authentication in BL1,
+   BL2, BL31, and the TSP if it is used.
+
 Armv7-A
 ~~~~~~~
 
diff --git a/docs/porting-guide.rst b/docs/porting-guide.rst
index 7a3963bda..c3df389f8 100644
--- a/docs/porting-guide.rst
+++ b/docs/porting-guide.rst
@@ -1792,6 +1792,22 @@ defined by the translation library, and can be found in the file
 On DynamIQ systems, this function must not use stack while enabling MMU, which
 is how the function in xlat table library version 2 is implemented.
 
+Function : plat_init_apiakey [optional]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Argument : void
+    Return   : uint64_t *
+
+This function populates the ``plat_apiakey`` array that contains the values used
+to set the ``APIAKey{Hi,Lo}_EL1`` registers. It returns a pointer to this array.
+
+The value should be obtained from a reliable source of randomness.
+
+This function is only needed if ARMv8.3 pointer authentication is used in the
+Trusted Firmware by building with ``ENABLE_PAUTH=1``.
+
 Function : plat_get_syscnt_freq2() [mandatory]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/user-guide.rst b/docs/user-guide.rst
index 70c1d5a91..b42012757 100644
--- a/docs/user-guide.rst
+++ b/docs/user-guide.rst
@@ -362,7 +362,7 @@ Common build options
    the ARMv8.3-PAuth registers to be included when saving and restoring the CPU
    context. Note that if the hardware supports this extension and this option is
    set to 0 the value of the registers will be leaked between Secure and
-   Non-secure worlds. The default is 0.
+   Non-secure worlds if PAuth is used on both sides. The default is 0.
 
 -  ``DEBUG``: Chooses between a debug and release build. It can take either 0
    (release) or 1 (debug) as values. 0 is the default.
@@ -411,6 +411,13 @@ Common build options
    partitioning in EL3, however. Platform initialisation code should configure
    and use partitions in EL3 as required. This option defaults to ``0``.
 
+-  ``ENABLE_PAUTH``: Boolean option to enable ARMv8.3 Pointer Authentication
+   (``ARMv8.3-PAuth``) support in the Trusted Firmware itself. Note that this
+   option doesn't affect the saving of the registers introduced with this
+   extension, they are always saved if they are detected regardless of the value
+   of this option. If enabled, it is needed to use a compiler that supports the
+   option ``-msign-return-address``. It defaults to 0.
+
 -  ``ENABLE_PIE``: Boolean option to enable Position Independent Executable(PIE)
    support within generic code in TF-A. This option is currently only supported
    in BL31. Default is 0.