Docs: Document RSS provisioning and key management
Change-Id: I078a740a07b9d0d580f15eaa0dcaf977d9b7e987
Signed-off-by: Raef Coles <raef.coles@arm.com>
diff --git a/docs/platform/arm/rss/index.rst b/docs/platform/arm/rss/index.rst
index a6ff830..63ec126 100644
--- a/docs/platform/arm/rss/index.rst
+++ b/docs/platform/arm/rss/index.rst
@@ -7,6 +7,8 @@
RSS introduction <readme.rst>
RSS communication design <rss_comms.rst>
+ RSS hardware key management <rss_key_management.rst>
+ RSS provisioning <rss_provisioning.rst>
RSS also includes the following extra partitions:
diff --git a/docs/platform/arm/rss/rss_key_management.rst b/docs/platform/arm/rss/rss_key_management.rst
new file mode 100644
index 0000000..7f57326
--- /dev/null
+++ b/docs/platform/arm/rss/rss_key_management.rst
@@ -0,0 +1,53 @@
+RSS key management
+==================
+
+The RSS has a set of hardware components that act together to prevent hardware
+protected keys being disclosed to compromised software. This chain involves the
+LifeCycle Manager "LCM", the Key Management Unit "KMU", and the cryptographic
+accelerator in the integration layer of the RSS (which in reference RSS builds
+is a CryptoCell-3XX series accelerator).
+
+Hardware protected keys (henceforth "Hardware Keys") are stored in the LCM, in
+protected keyslots. On production-mode "PCI" chips these slots are write-only.
+They are protected during provisioning from disclosure by Secure Provisioning
+"SP" mode disabling debug, and the encryption with either the RTL key or the CM
+provisioning key. On boot, the LCM checks the integrity of the stored hardware
+keys by comparing the amount of zeroes with a stored zero-count which, because
+of the property of the OTP that does not allow 1-bits to be set to 0-bits,
+allows detection of any changes in the keys. If the check succeeds it exports
+the keys to the KMU over a private memory bus (one that is not accessible
+programs running on the RSS' CPU or other controllers on the main bus such as
+the DMA).
+
+The KMU has between 2 and 32 hardware keyslots, which are 256 bit (32 byte) in
+size. Between 0 and 8 of these are hardware keyslots, and correspond to the
+hardware keyslots in the LCM. These slots are filled by the key export from the
+LCM, and have their permissions preconfigured so they are not readable or
+writable by software. Software KMU keyslots (keyslots that are not defined in
+hardware as hardware keyslots) can be read and written, and then subsequently
+locked to prevent reading and writing, so that they behave like hardware
+keyslots. This allows trusted immutable firmware to set up keys for less-trusted
+later stage code, which can be used but cannot be read. KMU keyslots can be
+exported over another private bus to the cryptographic accelerator. Hardware
+keyslots can be invalidated, making them unusable until a hard reset.
+
+The cryptographic accelerator receives the key into a write-only key register,
+and then can use it to perform cryptographic operations. For the CryptoCell-3XX
+series, this is limited to AES. As with the previous stages, software cannot
+retrieve the key, only use it. Note that currently this can only be used with
+the cc3xx_rom_lib driver, not the cryptocell-312-runtime driver, as the latter
+requires modification. Note that this path is the only way to use hardware
+protected keys on the RSS, they cannot be used by software cryptographic
+libraries that require key material to be accessible by software.
+
+The RSS uses this functionality to allow key derivation (based on NIST SP800-108
+with an RSA-based PRF that can utilise the hardware keys as described above)
+from the HUK and GUK. This allows the derivation of the CCA platform attestation
+key / delegated attestation root key without allowing access to the GUK
+directly. As a further security measure, these keys are derived by ROM/OTP code,
+and the HUK and GUK are then invalidated so they cannot be used by the runtime
+firmware and BL2.
+
+--------------
+
+*Copyright (c) 2022, Arm Limited. All rights reserved.*
diff --git a/docs/platform/arm/rss/rss_provisioning.rst b/docs/platform/arm/rss/rss_provisioning.rst
new file mode 100644
index 0000000..d5fc569
--- /dev/null
+++ b/docs/platform/arm/rss/rss_provisioning.rst
@@ -0,0 +1,43 @@
+RSS provisioning
+================
+
+The LifeCycle Manager controls access to the RSS OTP, and includes a
+state-machine that controls Lifecycle-state transitions. The LCM is derived from
+the OTP management and state machine components of the CryptoCell-3XX series
+accelerators, and will be familiar to those who have worked with them.
+
+When the chip hasn't been provisioned, the OTP is blank, which means the LCM is
+in "Virgin" Test/Production mode "TP mode" state. The first step for
+provisioning must be to set the LCM to either test-chip mode "TCI" or
+production-chip mode "PCI". In TCI mode the RTL key is masked to avoid
+disclosure, several OTP fields are changed from write-only to read-write, to aid
+in debugging, and debugging is not limited in secure provisioning mode.
+
+Once the TP mode has been set, the chip is then is Chip Manufacturer
+provisioning state "CM". This mode is intended for the provisioning of the HUK,
+GUK, CM provisioning key, CM code-encryption key, the root-of-trust public key
+and the CM config. To provision these fields, The firmware must first receive a
+provisioning bundle via a side-band channel (UART or debug interface). This
+bundle either contains just the keys, or more usually the keys and also
+provisioning code. The chip must then enter secure provisioning mode by setting
+the SP_ENABLE register. This causes a reset (but does not clear the RSS SRAMs),
+and allows access to the RTL key by exporting it to the KMU. The RSS must then
+decrypt and authenticate the bundle using the RTL key. Under TCI mode the RTL
+key is zeroed, so encryption and signing must use a zeroed key. Once the CM
+provisioning bundle has been unpacked, run if it contains code, and the CM
+values have been set. The RSS must be cold-reset.
+
+After the cold reset, the RSS will then be in Device Manufacturer provisioning
+state "DM". This state is designed to provision the DM provisioning key, the DM
+code-encryption key and the DM config. The procedure follows the same steps as
+the CM provisioning flow, with the exception that the bundle will now be
+encrypted and signed using the CM provisioning key. Once the provisioning bundle
+has been unpacked/run, the RSS must be cold-reset.
+
+After the cold reset, the device will now be in Secure Enable "SE" mode. Debug
+may be limited based on the hardware DCU mask for SE state. Provisioning will
+not be run on boot.
+
+--------------
+
+*Copyright (c) 2022, Arm Limited. All rights reserved.*