docs: Update docs with firmware encryption feature
Update documentation with optional firmware encryption feature.
Signed-off-by: Sumit Garg <sumit.garg@linaro.org>
Change-Id: I26691b18e1ee52a73090954260f26f2865c4e05a
diff --git a/docs/change-log-upcoming.rst b/docs/change-log-upcoming.rst
index c4e8bb0..15f39de 100644
--- a/docs/change-log-upcoming.rst
+++ b/docs/change-log-upcoming.rst
@@ -46,6 +46,7 @@
- Security
- Example: "UBSAN support and handlers"
+ - Add support for optional firmware encryption feature (experimental).
- Tools
- Example: "fiptool: Add support to build fiptool on Windows."
diff --git a/docs/design/auth-framework.rst b/docs/design/auth-framework.rst
index ae77391..1a53e22 100644
--- a/docs/design/auth-framework.rst
+++ b/docs/design/auth-framework.rst
@@ -934,7 +934,7 @@
based on mbed TLS, which can be found in
``drivers/auth/mbedtls/mbedtls_crypto.c``. This library is registered in the
authentication framework using the macro ``REGISTER_CRYPTO_LIB()`` and exports
-three functions:
+four functions:
.. code:: c
@@ -945,6 +945,11 @@
void *pk_ptr, unsigned int pk_len);
int verify_hash(void *data_ptr, unsigned int data_len,
void *digest_info_ptr, unsigned int digest_info_len);
+ int auth_decrypt(enum crypto_dec_algo dec_algo, void *data_ptr,
+ size_t len, const void *key, unsigned int key_len,
+ unsigned int key_flags, const void *iv,
+ unsigned int iv_len, const void *tag,
+ unsigned int tag_len)
The mbedTLS library algorithm support is configured by both the
``TF_MBEDTLS_KEY_ALG`` and ``TF_MBEDTLS_KEY_SIZE`` variables.
@@ -957,6 +962,9 @@
- ``TF_MBEDTLS_KEY_SIZE`` sets the supported RSA key size for TFA. Valid values
include 1024, 2048, 3072 and 4096.
+- ``TF_MBEDTLS_USE_AES_GCM`` enables the authenticated decryption support based
+ on AES-GCM algorithm. Valid values are 0 and 1.
+
.. note::
If code size is a concern, the build option ``MBEDTLS_SHA256_SMALLER`` can
be defined in the platform Makefile. It will make mbed TLS use an
diff --git a/docs/design/trusted-board-boot.rst b/docs/design/trusted-board-boot.rst
index 49e8adb..4802c97 100644
--- a/docs/design/trusted-board-boot.rst
+++ b/docs/design/trusted-board-boot.rst
@@ -229,6 +229,34 @@
Instructions for building and using the tool can be found at
:ref:`tools_build_cert_create`.
+Authenticated Encryption Framework
+----------------------------------
+
+The authenticated encryption framework included in TF-A provides support to
+implement the optional firmware encryption feature. This feature can be
+optionally enabled on platforms to implement the optional requirement:
+R060_TBBR_FUNCTION as specified in the `Trusted Board Boot Requirements (TBBR)`_
+document.
+
+Note that due to security considerations and complexity of this feature, it is
+marked as experimental.
+
+Firmware Encryption Tool
+------------------------
+
+The ``encrypt_fw`` tool is built and runs on the host machine as part of the
+TF-A build process when ``DECRYPTION_SUPPORT != none``. It takes the plain
+firmware image as input and generates the encrypted firmware image which can
+then be passed as input to the ``fiptool`` utility for creating the FIP.
+
+The encrypted firmwares are also stored individually in the output build
+directory.
+
+The tool resides in the ``tools/encrypt_fw`` directory. It uses OpenSSL SSL
+library version 1.0.1 or later to do authenticated encryption operation.
+Instructions for building and using the tool can be found in the
+:ref:`tools_build_enctool`.
+
--------------
*Copyright (c) 2015-2019, Arm Limited and Contributors. All rights reserved.*
diff --git a/docs/getting_started/build-options.rst b/docs/getting_started/build-options.rst
index af4895e..f138feb 100644
--- a/docs/getting_started/build-options.rst
+++ b/docs/getting_started/build-options.rst
@@ -263,6 +263,22 @@
platform hook needs to be implemented. The value is passed as the last
component of the option ``-fstack-protector-$ENABLE_STACK_PROTECTOR``.
+- ``ENCRYPT_BL31``: Binary flag to enable encryption of BL31 firmware. This
+ flag depends on ``DECRYPTION_SUPPORT`` build flag which is marked as
+ experimental.
+
+- ``ENCRYPT_BL32``: Binary flag to enable encryption of Secure BL32 payload.
+ This flag depends on ``DECRYPTION_SUPPORT`` build flag which is marked as
+ experimental.
+
+- ``ENC_KEY``: A 32-byte (256-bit) symmetric key in hex string format. It could
+ either be SSK or BSSK depending on ``FW_ENC_STATUS`` flag. This value depends
+ on ``DECRYPTION_SUPPORT`` build flag which is marked as experimental.
+
+- ``ENC_NONCE``: A 12-byte (96-bit) encryption nonce or Initialization Vector
+ (IV) in hex string format. This value depends on ``DECRYPTION_SUPPORT``
+ build flag which is marked as experimental.
+
- ``ERROR_DEPRECATED``: This option decides whether to treat the usage of
deprecated platform APIs, helper functions or drivers within Trusted
Firmware as error. It can take the value 1 (flag the use of deprecated
@@ -287,6 +303,18 @@
- ``FWU_FIP_NAME``: This is an optional build option which specifies the FWU
FIP filename for the ``fwu_fip`` target. Default is ``fwu_fip.bin``.
+- ``FW_ENC_STATUS``: Top level firmware's encryption numeric flag, values:
+
+ ::
+
+ 0: Encryption is done with Secret Symmetric Key (SSK) which is common
+ for a class of devices.
+ 1: Encryption is done with Binding Secret Symmetric Key (BSSK) which is
+ unique per device.
+
+ This flag depends on ``DECRYPTION_SUPPORT`` build flag which is marked as
+ experimental.
+
- ``GENERATE_COT``: Boolean flag used to build and execute the ``cert_create``
tool to create certificates as per the Chain of Trust described in
:ref:`Trusted Board Boot`. The build system then calls ``fiptool`` to
diff --git a/docs/getting_started/porting-guide.rst b/docs/getting_started/porting-guide.rst
index e8357b3..d634d2e 100644
--- a/docs/getting_started/porting-guide.rst
+++ b/docs/getting_started/porting-guide.rst
@@ -872,6 +872,35 @@
On success the function should return 0 and a negative error code otherwise.
+Function : plat_get_enc_key_info() [when FW_ENC_STATUS == 0 or 1]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ Arguments : enum fw_enc_status_t fw_enc_status, uint8_t *key,
+ size_t *key_len, unsigned int *flags, const uint8_t *img_id,
+ size_t img_id_len
+ Return : int
+
+This function provides a symmetric key (either SSK or BSSK depending on
+fw_enc_status) which is invoked during runtime decryption of encrypted
+firmware images. `plat/common/plat_bl_common.c` provides a dummy weak
+implementation for testing purposes which must be overridden by the platform
+trying to implement a real world firmware encryption use-case.
+
+It also allows the platform to pass symmetric key identifier rather than
+actual symmetric key which is useful in cases where the crypto backend provides
+secure storage for the symmetric key. So in this case ``ENC_KEY_IS_IDENTIFIER``
+flag must be set in ``flags``.
+
+In addition to above a platform may also choose to provide an image specific
+symmetric key/identifier using img_id.
+
+On success the function should return 0 and a negative error code otherwise.
+
+Note that this API depends on ``DECRYPTION_SUPPORT`` build flag which is
+marked as experimental.
+
Common optional modifications
-----------------------------
diff --git a/docs/getting_started/tools-build.rst b/docs/getting_started/tools-build.rst
index bb707cb..c050f58 100644
--- a/docs/getting_started/tools-build.rst
+++ b/docs/getting_started/tools-build.rst
@@ -135,6 +135,33 @@
./tools/cert_create/cert_create -h
+.. _tools_build_enctool:
+
+Building the Firmware Encryption Tool
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``encrypt_fw`` tool is built as part of the TF-A build process when the
+``fip`` make target is specified, DECRYPTION_SUPPORT and TBB are enabled, but
+it can also be built separately with the following command:
+
+.. code:: shell
+
+ make PLAT=<platform> [DEBUG=1] [V=1] enctool
+
+``DEBUG=1`` builds the tool in debug mode. ``V=1`` makes the build process more
+verbose. The following command should be used to obtain help about the tool:
+
+.. code:: shell
+
+ ./tools/encrypt_fw/encrypt_fw -h
+
+Note that the enctool in its current implementation only supports encryption
+key to be provided in plain format. A typical implementation can very well
+extend this tool to support custom techniques to protect encryption key.
+
+Also, a user may choose to provide encryption key or nonce as an input file
+via using ``cat <filename>`` instead of a hex string.
+
--------------
*Copyright (c) 2019, Arm Limited. All rights reserved.*