Docs: Rename RSS to RSE
Renames Runtime Security Subsytem (RSS) to Runtime Security Engine (RSE)
in the docs. This patch does not affect paths or code.
Signed-off-by: Jamie Fox <jamie.fox@arm.com>
Change-Id: Iecf170beef5ea694bd8eb682b877370a5eacda05
diff --git a/docs/platform/arm/index.rst b/docs/platform/arm/index.rst
index a02107b..3f0f383 100755
--- a/docs/platform/arm/index.rst
+++ b/docs/platform/arm/index.rst
@@ -11,7 +11,7 @@
Corstone-310 FPGA (AN555) and FVP <mps3/corstone310/README.rst>
Musca-B1 <musca_b1/readme.rst>
Musca-S1 <musca_s1/readme.rst>
- Runtime Security Subsystem <rss/index>
+ Runtime Security Engine <rss/index>
--------------
diff --git a/docs/platform/arm/rss/index.rst b/docs/platform/arm/rss/index.rst
index 63ec126..9aa236c 100644
--- a/docs/platform/arm/rss/index.rst
+++ b/docs/platform/arm/rss/index.rst
@@ -1,20 +1,22 @@
-################################
-Runtime Security Subsystem (RSS)
-################################
+#############################
+Runtime Security Engine (RSE)
+#############################
+
+Previously known as Runtime Security Subsystem (RSS).
.. toctree::
:maxdepth: 1
- RSS introduction <readme.rst>
- RSS communication design <rss_comms.rst>
- RSS hardware key management <rss_key_management.rst>
- RSS provisioning <rss_provisioning.rst>
+ RSE introduction <readme.rst>
+ RSE communication design <rss_comms.rst>
+ RSE hardware key management <rss_key_management.rst>
+ RSE provisioning <rss_provisioning.rst>
-RSS also includes the following extra partitions:
+RSE also includes the following extra partitions:
- `Measured boot partition <https://git.trustedfirmware.org/TF-M/tf-m-extras.git/tree/partitions/measured_boot/measured_boot_integration_guide.rst>`_
- `Delegated attestation partition <https://git.trustedfirmware.org/TF-M/tf-m-extras.git/tree/partitions/delegated_attestation/delegated_attest_integration_guide.rst>`_
--------------
-*Copyright (c) 2022, Arm Limited. All rights reserved.*
+*Copyright (c) 2022-2023, Arm Limited. All rights reserved.*
diff --git a/docs/platform/arm/rss/readme.rst b/docs/platform/arm/rss/readme.rst
index 5d0f373..562a0ee 100644
--- a/docs/platform/arm/rss/readme.rst
+++ b/docs/platform/arm/rss/readme.rst
@@ -1,23 +1,23 @@
-Runtime Security Subsystem (RSS)
-================================
+Runtime Security Engine (RSE)
+=============================
Introduction
------------
-Runtime Security Subsystem (RSS) is an Arm subsystem that provides a reference
+Runtime Security Engine (RSE) is an Arm subsystem that provides a reference
implementation of the HES Host in the
`Arm Confidential Compute Architecture (CCA) <https://www.arm.com/architecture/security-features/arm-confidential-compute-architecture>`_.
It is designed to be integrated into A-profile compute subsystems that implement
Arm CCA, where it serves as the Root of Trust.
-RSS initially boots from immutable code (BL1_1) in its internal ROM, before
-jumping to BL1_2, which is provisioned and hash-locked in RSS OTP. The updatable
-MCUBoot BL2 boot stage is loaded from host system flash into RSS SRAM, where it
-is authenticated. BL2 loads and authenticates the TF-M runtime into RSS SRAM
+RSE initially boots from immutable code (BL1_1) in its internal ROM, before
+jumping to BL1_2, which is provisioned and hash-locked in RSE OTP. The updatable
+MCUBoot BL2 boot stage is loaded from host system flash into RSE SRAM, where it
+is authenticated. BL2 loads and authenticates the TF-M runtime into RSE SRAM
from host flash. BL2 is also responsible for loading initial boot code into
other subsystems within the host.
-The RSS platform port supports the TF-M Crypto, TF-M Initial Attestation,
+The RSE platform port supports the TF-M Crypto, TF-M Initial Attestation,
Measured Boot and TF-M Platform services along with the corresponding
regression tests. It supports the IPC model in multi-core topology with
Isolation Level 1 and 2.
@@ -28,13 +28,13 @@
Follow the instructions in :doc:`Build instructions </building/tfm_build_instruction>`.
Build TF-M with platform name: `arm/rss/<rss platform name>`
-For example for building RSS for Total Compute platforms:
+For example for building RSE for Total Compute platforms:
``-DTFM_PLATFORM=arm/rss/tc``
Signing host images
-------------------
-RSS BL2 can load boot images into other subsystems within the host system. It
+RSE BL2 can load boot images into other subsystems within the host system. It
expects images to be signed, with the signatures attached to the images in the
MCUBoot metadata format.
@@ -57,11 +57,11 @@
<binary infile> \
<signed binary outfile>
-The ``load address`` is the logical address in the RSS memory map to which BL2
-will load the image. RSS FW expects the first host image to be loaded to address
-``0x70000000`` (the beginning of the RSS ATU host access region), and each
+The ``load address`` is the logical address in the RSE memory map to which BL2
+will load the image. RSE FW expects the first host image to be loaded to address
+``0x70000000`` (the beginning of the RSE ATU host access region), and each
subsequent host image to be loaded at an offset of ``0x1000000`` from the
-previous image. The RSS ATU should be configured to map these logical addresses
+previous image. The RSE ATU should be configured to map these logical addresses
to the physical addresses in the host system that the images need to be loaded
to.
@@ -88,7 +88,7 @@
output from the build. To create the flash image, the following ``fiptool``
command should be run. ``fiptool`` documentation can be found `here
<https://trustedfirmware-a.readthedocs.io/en/latest/getting_started/tools-build.html?highlight=fiptool#building-and-using-the-fip-tool>`_.
-Note that an up-to-date fiptool that supports the RSS UUIDs must be used.::
+Note that an up-to-date fiptool that supports the RSE UUIDs must be used.::
fiptool create \
--align 8192 --rss-bl2 bl2_signed.bin \
@@ -98,7 +98,7 @@
--align 8192 --rss-ap-bl1 <signed Host AP BL1 image> \
fip.bin
-If you already have a ``fip.bin`` containing host firmware images, RSS FIP
+If you already have a ``fip.bin`` containing host firmware images, RSE FIP
images can be patched in::
fiptool update --align 8192 --rss-bl2 bl2_signed.bin fip.bin
@@ -125,7 +125,7 @@
-o host_flash.bin -Binary
If GPT support is enabled, and a host ``fip.bin`` and ``fip_gpt.bin`` has been
-obtained, RSS images can be inserted by first patching the host FIP and then
+obtained, RSE images can be inserted by first patching the host FIP and then
inserting that patched FIP into the GPT image::
sector_size=$(gdisk -l fip_gpt.bin | grep -i "sector size (logical):" | \
@@ -166,11 +166,11 @@
fip_gpt.bin -Binary -offset 0x0 \
-o host_flash.bin -Binary
-The RSS ROM binary should be placed in RSS ROM at ``0x11000000`` and the host
+The RSE ROM binary should be placed in RSE ROM at ``0x11000000`` and the host
flash binary should be placed at the base of the host flash. For the TC
platform, this is at ``0x80000000``.
-The RSS OTP must be provisioned. On a development platform with
+The RSE OTP must be provisioned. On a development platform with
``TFM_DUMMY_PROVISIONING`` enabled, BL1_1 expects provisioning bundles to be
preloaded into SRAM. Preload ``encrypted_cm_provisioning_bundle_0.bin`` to the
base of VM0, and ``encrypted_dm_provisioning_bundle.bin`` to the base of VM1.
@@ -182,7 +182,7 @@
when ``TFM_DUMMY_PROVISIONING`` is enabled, except that it will not
automatically perform the reset once each provisioning state is complete. For
more details about provisioning flows, see
-:doc:`RSS provisioning </platform/arm/rss/rss_provisioning>`.
+:doc:`RSE provisioning </platform/arm/rss/rss_provisioning>`.
--------------
diff --git a/docs/platform/arm/rss/rss_comms.rst b/docs/platform/arm/rss/rss_comms.rst
index 964b896..bca8b7b 100644
--- a/docs/platform/arm/rss/rss_comms.rst
+++ b/docs/platform/arm/rss/rss_comms.rst
@@ -1,8 +1,8 @@
########################
-RSS communication design
+RSE communication design
########################
-The RSS communication protocol is designed to be a lightweight serialization of
+The RSE communication protocol is designed to be a lightweight serialization of
the psa_call() API through a combination of in-band MHU (Message Handling Unit)
transport and parameter-passing through shared memory.
@@ -10,12 +10,12 @@
Message format
**************
-To call an RSS service, the client must send a message in-band over the MHU
-sender link to RSS and wait for a reply message on the MHU receiver (either by
+To call an RSE service, the client must send a message in-band over the MHU
+sender link to RSE and wait for a reply message on the MHU receiver (either by
polling the MHU or waiting for interrupt). The messages are defined as packed C
structs, which are serialized in byte-order over the MHU links.
-Messages encoding a psa_call() to RSS take the form::
+Messages encoding a psa_call() to RSE take the form::
__PACKED_STRUCT serialized_psa_msg_t {
struct serialized_rss_comms_header_t header;
@@ -25,7 +25,7 @@
} msg;
};
-Replies from RSS take the form::
+Replies from RSE take the form::
__PACKED_STRUCT serialized_psa_reply_t {
struct serialized_rss_comms_header_t header;
@@ -44,7 +44,7 @@
};
The ``client_id`` can be used by the caller to identify different clients at the
-endpoint for access control purposes. It is combined with an RSS-internal
+endpoint for access control purposes. It is combined with an RSE-internal
identifier for the endpoint to create the PSA Client ID for the call.
The sequence number, ``seq_num``, is returned in the reply message to allow the
@@ -126,7 +126,7 @@
The ``return_val`` and ``out_size`` have the same meaning as in the embed
protocol.
-RSS writes the outvec data to the pointers supplied in the call message prior to
+RSE writes the outvec data to the pointers supplied in the call message prior to
sending the MHU reply message, so no further payload is sent in the reply
message.
@@ -134,23 +134,23 @@
Implementation structure
************************
-The RSS side of the communication implementation is located in
+The RSE side of the communication implementation is located in
``platform/ext/target/arm/rss/common/rss_comms``. The implementation is
structured as follows:
-- ``rss_comms.c``: Implements the TF-M RPC layer using RSS comms implementation.
+- ``rss_comms.c``: Implements the TF-M RPC layer using RSE comms implementation.
- ``rss_comms_hal.c``: Abstracts MHU message sending and receiving.
-- ``rss_comms_protocol.c``: The common part of the RSS comms protocol.
-- ``rss_comms_protocol_embed.c``: The embed RSS comms protocol.
-- ``rss_comms_protocol_protocol_access.c``: The pointer access RSS comms protocol.
+- ``rss_comms_protocol.c``: The common part of the RSE comms protocol.
+- ``rss_comms_protocol_embed.c``: The embed RSE comms protocol.
+- ``rss_comms_protocol_protocol_access.c``: The pointer access RSE comms protocol.
- ``rss_comms_atu.c``: Allocates and frees ATU regions for host pointer access.
- ``rss_comms_permissions_hal.c``: Checks service access permissions and pointer validity.
-A reference implementation of the client side of the RSS comms is available in
+A reference implementation of the client side of the RSE comms is available in
the Trusted Firmware-A repository.
--------------
-*Copyright (c) 2022, Arm Limited. All rights reserved.*
+*Copyright (c) 2022-2023, Arm Limited. All rights reserved.*
diff --git a/docs/platform/arm/rss/rss_key_management.rst b/docs/platform/arm/rss/rss_key_management.rst
index 7f57326..8ce261b 100644
--- a/docs/platform/arm/rss/rss_key_management.rst
+++ b/docs/platform/arm/rss/rss_key_management.rst
@@ -1,10 +1,10 @@
-RSS key management
+RSE key management
==================
-The RSS has a set of hardware components that act together to prevent hardware
+The RSE 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
+accelerator in the integration layer of the RSE (which in reference RSE builds
is a CryptoCell-3XX series accelerator).
Hardware protected keys (henceforth "Hardware Keys") are stored in the LCM, in
@@ -16,7 +16,7 @@
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
+programs running on the RSE' 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
@@ -37,10 +37,10 @@
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
+protected keys on the RSE, 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
+The RSE 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
@@ -50,4 +50,4 @@
--------------
-*Copyright (c) 2022, Arm Limited. All rights reserved.*
+*Copyright (c) 2022-2023, Arm Limited. All rights reserved.*
diff --git a/docs/platform/arm/rss/rss_provisioning.rst b/docs/platform/arm/rss/rss_provisioning.rst
index fc66386..065fd52 100644
--- a/docs/platform/arm/rss/rss_provisioning.rst
+++ b/docs/platform/arm/rss/rss_provisioning.rst
@@ -1,10 +1,10 @@
-RSS provisioning
+RSE provisioning
================
Provisioning theory
-------------------
-The LifeCycle Manager (LCM) controls access to the RSS OTP, and includes a
+The LifeCycle Manager (LCM) controls access to the RSE OTP, and includes a
state-machine that controls Lifecycle-state (LCS) transitions. The LCM is
derived from the OTP management and state machine subsystems of the
CryptoCell-3XX series accelerators, and will be familiar to those who have
@@ -29,37 +29,37 @@
VM0. This bundle contains the keys and also code to perform the provisioning
such as a driver for the LCM, and a function to randomly generate the HUK via
the CryptoCell TRNG. The chip must then enter secure provisioning mode by
-setting the SP_ENABLE register. This causes a reset (but does not clear the RSS
+setting the SP_ENABLE register. This causes a reset (but does not clear the RSE
SRAMs), and allows access to the RTL key by exporting it to the KMU, though in
-secure provisioning mode the ability to debug the RSS is disabled, to prevent
-disclosure of the decrypted provisioning bundle values. The RSS will then
+secure provisioning mode the ability to debug the RSE is disabled, to prevent
+disclosure of the decrypted provisioning bundle values. The RSE will then
decrypt and authenticate the bundle using the RTL key. Under TCI mode the RTL
key is zeroed, the bundle generation tool must use a zeroed key to encrypt and
-sign the bundle. Once the CM provisioning bundle has been unpacked, the RSS will
-execute the code which will provision the CM provisioning data into OTP. The RSS
+sign the bundle. Once the CM provisioning bundle has been unpacked, the RSE will
+execute the code which will provision the CM provisioning data into OTP. The RSE
must be cold-reset, which will disable secure provisioning mode. If
``TFM_DUMMY_PROVISIONING`` is enabled the reset will happen automatically, else
the external provisioning device should read the provisioning state from the
GPIO/PSI (which is set via the ``rss_sysctrl`` register) and perform the reset.
-After the cold reset, the RSS will automatically transition to Device
+After the cold reset, the RSE will automatically transition to Device
Manufacturer provisioning state "DM" as the LCM hardware state-machine reads the
values of the cm_config_1 and cm_config_2 fields as non-zero. 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 and must be placed at the base of VM1. As before, once the
-provisioning bundle has been unpacked/run, the RSS must either be cold-reset or
+provisioning bundle has been unpacked/run, the RSE must either be cold-reset or
will perform this automatically.
After the cold reset, the device will now be in Secure Enable "SE" mode, due to
the dm_config_1 field being non-zero. Debug may be limited based on the hardware
DCU mask for SE state. Provisioning will not be run on boot.
-Practical RSS provisioning
+Practical RSE provisioning
--------------------------
-The RSS buildsystem produces two provisioning bundles (containing both code and
+The RSE buildsystem produces two provisioning bundles (containing both code and
data), and then encrypts and signs them with the RTL key to produce
``encrypted_cm_provisioning_bundle.bin`` and
``encrypted_dm_provisioning_bundle.bin``.
@@ -70,24 +70,24 @@
encrypted_*_provisioning_bundle.bin files should still be used, but note that
their contents are not encrypted.
-On first boot, the RSS is in Virgin state. If the RSS firmware was built with
+On first boot, the RSE is in Virgin state. If the RSE firmware was built with
``TFM_DUMMY_PROVISIONING`` enabled then it will automatically set the chip to
TCI mode and cold-reset. Production ROM implementations must disable
-``TFM_DUMMY_PROVISIONING``, which will cause RSS to loop in the ROM until either
+``TFM_DUMMY_PROVISIONING``, which will cause RSE to loop in the ROM until either
TCI or PCI mode is set with a debugger. It is possible to set the TP mode in the
LCS registers directly, however it may be easier to set the ``tp_mode`` variable
-in the frame where RSS is looping, at which point the loop will exit and the TP
+in the frame where RSE is looping, at which point the loop will exit and the TP
mode will be set by the ROM code.
-On non-virgin boot in CM lifecycle state, RSS checks the start of VM0 for the
+On non-virgin boot in CM lifecycle state, RSE checks the start of VM0 for the
magic constant ``0xC0DEFEED``, which is required to be the first word in the CM
provisioning bundle. There is also a second check for a constant at the end of
-the bundle to ensure the bundle has finished writing. The RSS will perform this
+the bundle to ensure the bundle has finished writing. The RSE will perform this
check in a loop until a bundle is found.
This procedure is repeated for DM LCS, except that the magic constant is
``0xBEEFFEED`` and the bundle must be loaded to the base of VM1. Note that the
-size of RSS memory may vary depending on implementation, so the load address of
+size of RSE memory may vary depending on implementation, so the load address of
the DM bundle may change.
In production systems it is intended that these bundles are loaded by a
@@ -99,9 +99,9 @@
once, and then to save the state of the OTP in SE LCS and then preload that on
subsequent boots.
-RSS provisioning GPIO signalling
+RSE provisioning GPIO signalling
--------------------------------
-The state of the RSS ROM boot/provisioning flow is signalled outside of the RSS
+The state of the RSE ROM boot/provisioning flow is signalled outside of the RSE
subsystem via the GPIOs as part of the Persistent State Interface (PSI). The PSI
signals the lifecycle state as a hardware signal, but additionally the software
can signal over the PSI by setting the ``rss_sysctrl`` register.
@@ -112,7 +112,7 @@
+--------+------------------------------------------------------------------+
| Signal | State |
+========+==================================================================+
-| 0x0 | RSS cold boot default |
+| 0x0 | RSE cold boot default |
+--------+------------------------------------------------------------------+
| 0x1 | Virgin chip idle, ready to set PCI/TCI mode |
+--------+------------------------------------------------------------------+