Djam/arm-trusted-firmware
1
0
Fork 0
mirror of https://github.com/ARM-software/arm-trusted-firmware.git synced 2025-04-29 16:48:59 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: change all occurrences of RSS to RSE

Browse source 
Changes all occurrences of "RSS" and "rss" in the documentation
to "RSE" and "rse".

Signed-off-by: Tamas Ban <tamas.ban@arm.com>
Change-Id: Ia42078f5faa1db331b1e5a35f01faeaf1afacb5f
This commit is contained in:
Tamas Ban 2024-02-21 13:55:31 +01:00
parent b8245368cc
commit 624c9a0b38
14 changed files with 210 additions and 210 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/about/features.rst
View file

@ -128,7 +128,7 @@ Additionally the following libraries are marked experimental when included
in a platform: in a platform:
- MPU translation library ``lib/xlat_mpu`` - MPU translation library ``lib/xlat_mpu``
- RSS comms driver ``drivers/arm/rss`` - RSE comms driver ``drivers/arm/rse``
Still to come Still to come
------------- -------------

8
docs/about/maintainers.rst
View file

@ -337,12 +337,12 @@ Message Handling Unit (MHU) driver
:|F|: include/drivers/arm/mhu.h :|F|: include/drivers/arm/mhu.h
:|F|: drivers/arm/mhu :|F|: drivers/arm/mhu
Runtime Security Subsystem (RSS) comms driver Runtime Security Engine (RSE) comms driver
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
:|M|: David Vincze <david.vincze@arm.com> :|M|: David Vincze <david.vincze@arm.com>
:|G|: `davidvincze`_ :|G|: `davidvincze`_
:|F|: include/drivers/arm/rss_comms.h :|F|: include/drivers/arm/rse_comms.h
:|F|: drivers/arm/rss :|F|: drivers/arm/rse
Libfdt wrappers Libfdt wrappers
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^

2
docs/design_documents/index.rst
View file

@ -9,7 +9,7 @@ Design Documents
context_mgmt_rework context_mgmt_rework
measured_boot_poc measured_boot_poc
drtm_poc drtm_poc
rss rse
psci_osi_mode psci_osi_mode
measured_boot measured_boot

10
docs/design_documents/measured_boot.rst
View file

@ -91,10 +91,10 @@ The Measured Boot implementation in TF-A supports:
and the variable length crypto agile structure called TCG_PCR_EVENT2. Event and the variable length crypto agile structure called TCG_PCR_EVENT2. Event
Log driver implemented in TF-A covers later part. Log driver implemented in TF-A covers later part.
#. RSS #. RSE
It is one of physical backend to extend the measurements. Please refer this It is one of physical backend to extend the measurements. Please refer this
document :ref:`Runtime Security Subsystem (RSS)` for more details. document :ref:`Runtime Security Engine (RSE)` for more details.
Platform Interface Platform Interface
------------------ ------------------
@ -121,7 +121,7 @@ Responsibilities of these platform interfaces are -
void bl2_plat_mboot_init(void); void bl2_plat_mboot_init(void);
Initialise all Measured Boot backends supported by the platform Initialise all Measured Boot backends supported by the platform
(e.g. Event Log buffer, RSS). As these functions do not return any value, (e.g. Event Log buffer, RSE). As these functions do not return any value,
the platform should deal with error management, such as logging the error the platform should deal with error management, such as logging the error
somewhere, or panicking the system if this is considered a fatal error. somewhere, or panicking the system if this is considered a fatal error.
@ -147,7 +147,7 @@ Responsibilities of these platform interfaces are -
- If it is Event Log backend, then record the measurement in TCG Event Log - If it is Event Log backend, then record the measurement in TCG Event Log
format. format.
- If it is a secure crypto-processor (like RSS), then extend the designated - If it is a secure crypto-processor (like RSE), then extend the designated
PCR (or slot) with the given measurement. PCR (or slot) with the given measurement.
- This function must return 0 on success, a signed integer error code - This function must return 0 on success, a signed integer error code
otherwise. otherwise.
@ -223,7 +223,7 @@ Responsibilities of these platform interfaces are -
- This function must return 0 on success, a signed integer error code - This function must return 0 on success, a signed integer error code
otherwise. otherwise.
- In TC2 platform, this function is used to calculate the hash of the given - In TC2 platform, this function is used to calculate the hash of the given
key and forward this hash to RSS alongside the measurement of the image key and forward this hash to RSE alongside the measurement of the image
which the key signs. which the key signs.
-------------- --------------

148
docs/design_documents/rse.rst
View file

@ -1,45 +1,45 @@
Runtime Security Subsystem (RSS) Runtime Security Engine (RSE)
================================ =============================
This document focuses on the relationship between the Runtime Security Subsystem This document focuses on the relationship between the Runtime Security Engine
(RSS) and the application processor (AP). According to the ARM reference design (RSE) and the application processor (AP). According to the ARM reference design
the RSS is an independent core next to the AP and the SCP on the same die. It the RSE is an independent core next to the AP and the SCP on the same die. It
provides fundamental security guarantees and runtime services for the rest of provides fundamental security guarantees and runtime services for the rest of
the system (e.g.: trusted boot, measured boot, platform attestation, the system (e.g.: trusted boot, measured boot, platform attestation,
key management, and key derivation). key management, and key derivation).
At power up RSS boots first from its private ROM code. It validates and loads At power up RSE boots first from its private ROM code. It validates and loads
its own images and the initial images of SCP and AP. When AP and SCP are its own images and the initial images of SCP and AP. When AP and SCP are
released from reset and their initial code is loaded then they continue their released from reset and their initial code is loaded then they continue their
own boot process, which is the same as on non-RSS systems. Please refer to the own boot process, which is the same as on non-RSE systems. Please refer to the
``RSS documentation`` [1]_ for more details about the RSS boot flow. ``RSE documentation`` [1]_ for more details about the RSE boot flow.
The last stage of the RSS firmware is a persistent, runtime component. Much The last stage of the RSE firmware is a persistent, runtime component. Much
like AP_BL31, this is a passive entity which has no periodical task to do and like AP_BL31, this is a passive entity which has no periodical task to do and
just waits for external requests from other subsystems. RSS and other just waits for external requests from other subsystems. RSE and other
subsystems can communicate with each other over message exchange. RSS waits subsystems can communicate with each other over message exchange. RSE waits
in idle for the incoming request, handles them, and sends a response then goes in idle for the incoming request, handles them, and sends a response then goes
back to idle. back to idle.
RSS communication layer RSE communication layer
----------------------- -----------------------
The communication between RSS and other subsystems are primarily relying on the The communication between RSE and other subsystems are primarily relying on the
Message Handling Unit (MHU) module. The number of MHU interfaces between RSS Message Handling Unit (MHU) module. The number of MHU interfaces between RSE
and other cores is IMPDEF. Besides MHU other modules also could take part in and other cores is IMPDEF. Besides MHU other modules also could take part in
the communication. RSS is capable of mapping the AP memory to its address space. the communication. RSE is capable of mapping the AP memory to its address space.
Thereby either RSS core itself or a DMA engine if it is present, can move the Thereby either RSE core itself or a DMA engine if it is present, can move the
data between memory belonging to RSS or AP. In this way, a bigger amount of data data between memory belonging to RSE or AP. In this way, a bigger amount of data
can be transferred in a short time. can be transferred in a short time.
The MHU comes in pairs. There is a sender and receiver side. They are connected The MHU comes in pairs. There is a sender and receiver side. They are connected
to each other. An MHU interface consists of two pairs of MHUs, one sender and to each other. An MHU interface consists of two pairs of MHUs, one sender and
one receiver on both sides. Bidirectional communication is possible over an one receiver on both sides. Bidirectional communication is possible over an
interface. One pair provides message sending from AP to RSS and the other pair interface. One pair provides message sending from AP to RSE and the other pair
from RSS to AP. The sender and receiver are connected via channels. There is an from RSE to AP. The sender and receiver are connected via channels. There is an
IMPDEF number of channels (e.g: 4-16) between a sender and a receiver module. IMPDEF number of channels (e.g: 4-16) between a sender and a receiver module.
The RSS communication layer provides two ways for message exchange: The RSE communication layer provides two ways for message exchange:
- ``Embedded messaging``: The full message, including header and payload, are - ``Embedded messaging``: The full message, including header and payload, are
exchanged over the MHU channels. A channel is capable of delivering a single exchanged over the MHU channels. A channel is capable of delivering a single
@ -55,16 +55,16 @@ The RSS communication layer provides two ways for message exchange:
- ``Pointer-access messaging``: The message header and the payload are - ``Pointer-access messaging``: The message header and the payload are
separated and they are conveyed in different ways. The header is sent separated and they are conveyed in different ways. The header is sent
over the channels, similar to the embedded messaging but the payload is over the channels, similar to the embedded messaging but the payload is
copied over by RSS core (or by DMA) between the sender and the receiver. This copied over by RSE core (or by DMA) between the sender and the receiver. This
could be useful in the case of long messages because transaction time is less could be useful in the case of long messages because transaction time is less
compared to the embedded messaging mode. Small payloads are copied by the RSS compared to the embedded messaging mode. Small payloads are copied by the RSE
core because setting up DMA would require more CPU cycles. The payload is core because setting up DMA would require more CPU cycles. The payload is
either copied into an internal buffer or directly read-written by RSS. Actual either copied into an internal buffer or directly read-written by RSE. Actual
behavior depends on RSS setup, whether the partition supports memory-mapped behavior depends on RSE setup, whether the partition supports memory-mapped
``iovec``. Therefore, the sender must handle both cases and prevent access to ``iovec``. Therefore, the sender must handle both cases and prevent access to
the memory, where payload data lives, while the RSS handles the request. the memory, where payload data lives, while the RSE handles the request.
The RSS communication layer supports both ways of messaging in parallel. It is The RSE communication layer supports both ways of messaging in parallel. It is
decided at runtime based on the message size which way to transfer the message. decided at runtime based on the message size which way to transfer the message.
.. code-block:: bash .. code-block:: bash
@ -93,25 +93,25 @@ decided at runtime based on the message size which way to transfer the message.
V | | | V V V | | | V V
+----------------------------------------------+ | | +-------------------+ +----------------------------------------------+ | | +-------------------+
| |--+-+ | | | |--+-+ | |
| RSS | | SRAM | | RSE | | SRAM |
| | | | | | | |
+----------------------------------------------+ +-------------------+ +----------------------------------------------+ +-------------------+
.. Note:: .. Note::
The RSS communication layer is not prepared for concurrent execution. The The RSE communication layer is not prepared for concurrent execution. The
current use case only requires message exchange during the boot phase. In current use case only requires message exchange during the boot phase. In
the boot phase, only a single core is running and the rest of the cores are the boot phase, only a single core is running and the rest of the cores are
in reset. in reset.
Message structure Message structure
^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^
A description of the message format can be found in the ``RSS communication A description of the message format can be found in the ``RSE communication
design`` [2]_ document. design`` [2]_ document.
Source files Source files
^^^^^^^^^^^^ ^^^^^^^^^^^^
- RSS comms: ``drivers/arm/rss`` - RSE comms: ``drivers/arm/rse``
- MHU driver: ``drivers/arm/mhu`` - MHU driver: ``drivers/arm/mhu``
@ -119,29 +119,29 @@ API for communication over MHU
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The API is defined in these header files: The API is defined in these header files:
- ``include/drivers/arm/rss_comms.h`` - ``include/drivers/arm/rse_comms.h``
- ``include/drivers/arm/mhu.h`` - ``include/drivers/arm/mhu.h``
RSS provided runtime services RSE provided runtime services
----------------------------- -----------------------------
RSS provides the following runtime services: RSE provides the following runtime services:
- ``Measured boot``: Securely store the firmware measurements which were - ``Measured boot``: Securely store the firmware measurements which were
computed during the boot process and the associated metadata (image computed during the boot process and the associated metadata (image
description, measurement algorithm, etc.). More info on measured boot service description, measurement algorithm, etc.). More info on measured boot service
in RSS can be found in the ``measured_boot_integration_guide`` [3]_ . in RSE can be found in the ``measured_boot_integration_guide`` [3]_ .
- ``Delegated attestation``: Query the platform attestation token and derive a - ``Delegated attestation``: Query the platform attestation token and derive a
delegated attestation key. More info on the delegated attestation service delegated attestation key. More info on the delegated attestation service
in RSS can be found in the ``delegated_attestation_integration_guide`` [4]_ . in RSE can be found in the ``delegated_attestation_integration_guide`` [4]_ .
- ``OTP assets management``: Public keys used by AP during the trusted boot - ``OTP assets management``: Public keys used by AP during the trusted boot
process can be requested from RSS. Furthermore, AP can request RSS to process can be requested from RSE. Furthermore, AP can request RSE to
increase a non-volatile counter. Please refer to the increase a non-volatile counter. Please refer to the
``RSS key management`` [5]_ document for more details. ``RSE key management`` [5]_ document for more details.
Runtime service API Runtime service API
^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^
The RSS provided runtime services implement a PSA aligned API. The parameter The RSE provided runtime services implement a PSA aligned API. The parameter
encoding follows the PSA client protocol described in the encoding follows the PSA client protocol described in the
``Firmware Framework for M`` [6]_ document in chapter 4.4. The implementation is ``Firmware Framework for M`` [6]_ document in chapter 4.4. The implementation is
restricted to the static handle use case therefore only the ``psa_call`` API is restricted to the static handle use case therefore only the ``psa_call`` API is
@ -168,7 +168,7 @@ Software and API layers
| | | |
V V V V
+------------------------------------------------+ +------------------------------------------------+
| RSS communication protocol | | RSE communication protocol |
+------------------------------------------------+ +------------------------------------------------+
| ^ | ^
| mhu_send_data() | mhu_receive_data() | mhu_send_data() | mhu_receive_data()
@ -188,7 +188,7 @@ Software and API layers
| |
V V
+------------------------------------------------+ +------------------------------------------------+
| MHU HW on RSS side | | MHU HW on RSE side |
+------------------------------------------------+ +------------------------------------------------+
| ^ | ^
| IRQ | Register access | IRQ | Register access
@ -204,17 +204,17 @@ Software and API layers
+---------------+ +------------------------+ +---------------+ +------------------------+
RSS based Measured Boot RSE based Measured Boot
----------------------- -----------------------
Measured Boot is the process of cryptographically measuring (computing the hash Measured Boot is the process of cryptographically measuring (computing the hash
value of a binary) the code and critical data used at boot time. The value of a binary) the code and critical data used at boot time. The
measurement must be stored in a tamper-resistant way, so the security state measurement must be stored in a tamper-resistant way, so the security state
of the device can be attested later to an external party. RSS provides a runtime of the device can be attested later to an external party. RSE provides a runtime
service which is meant to store measurements and associated metadata alongside. service which is meant to store measurements and associated metadata alongside.
Data is stored in internal SRAM which is only accessible by the secure runtime Data is stored in internal SRAM which is only accessible by the secure runtime
firmware of RSS. Data is stored in so-called measurement slots. A platform has firmware of RSE. Data is stored in so-called measurement slots. A platform has
IMPDEF number of measurement slots. The measurement storage follows extend IMPDEF number of measurement slots. The measurement storage follows extend
semantics. This means that measurements are not stored directly (as it was semantics. This means that measurements are not stored directly (as it was
taken) instead they contribute to the current value of the measurement slot. taken) instead they contribute to the current value of the measurement slot.
@ -236,7 +236,7 @@ Defined here:
.. code-block:: c .. code-block:: c
psa_status_t psa_status_t
rss_measured_boot_extend_measurement(uint8_t index, rse_measured_boot_extend_measurement(uint8_t index,
const uint8_t *signer_id, const uint8_t *signer_id,
size_t signer_id_size, size_t signer_id_size,
const uint8_t *version, const uint8_t *version,
@ -291,27 +291,27 @@ multiple times:
.. Note:: .. Note::
Extending multiple measurements in the same slot leads to some metadata Extending multiple measurements in the same slot leads to some metadata
information loss. Since RSS is not constrained on special HW resources to information loss. Since RSE is not constrained on special HW resources to
store the measurements and metadata, therefore it is worth considering to store the measurements and metadata, therefore it is worth considering to
store all of them one by one in distinct slots. However, they are one-by-one store all of them one by one in distinct slots. However, they are one-by-one
included in the platform attestation token. So, the number of distinct included in the platform attestation token. So, the number of distinct
firmware image measurements has an impact on the size of the attestation firmware image measurements has an impact on the size of the attestation
token. token.
The allocation of the measurement slot among RSS, Root and Realm worlds is The allocation of the measurement slot among RSE, Root and Realm worlds is
platform dependent. The platform must provide an allocation of the measurement platform dependent. The platform must provide an allocation of the measurement
slot at build time. An example can be found in slot at build time. An example can be found in
``tf-a/plat/arm/board/tc/tc_bl1_measured_boot.c`` ``tf-a/plat/arm/board/tc/tc_bl1_measured_boot.c``
Furthermore, the memory, which holds the metadata is also statically allocated Furthermore, the memory, which holds the metadata is also statically allocated
in RSS memory. Some of the fields have a static value (measurement algorithm), in RSE memory. Some of the fields have a static value (measurement algorithm),
and some of the values have a dynamic value (measurement value) which is updated and some of the values have a dynamic value (measurement value) which is updated
by the bootloaders when the firmware image is loaded and measured. The metadata by the bootloaders when the firmware image is loaded and measured. The metadata
structure is defined in structure is defined in
``include/drivers/measured_boot/rss/rss_measured_boot.h``. ``include/drivers/measured_boot/rse/rse_measured_boot.h``.
.. code-block:: c .. code-block:: c
struct rss_mboot_metadata { struct rse_mboot_metadata {
unsigned int id; unsigned int id;
uint8_t slot; uint8_t slot;
uint8_t signer_id[SIGNER_ID_MAX_SIZE]; uint8_t signer_id[SIGNER_ID_MAX_SIZE];
@ -328,24 +328,24 @@ Signer-ID API
^^^^^^^^^^^^^ ^^^^^^^^^^^^^
This function calculates the hash of a public key (signer-ID) using the This function calculates the hash of a public key (signer-ID) using the
``Measurement algorithm`` and stores it in the ``rss_mboot_metadata`` field ``Measurement algorithm`` and stores it in the ``rse_mboot_metadata`` field
named ``signer_id``. named ``signer_id``.
Prior to calling this function, the caller must ensure that the ``signer_id`` Prior to calling this function, the caller must ensure that the ``signer_id``
field points to the zero-filled buffer. field points to the zero-filled buffer.
Defined here: Defined here:
- ``include/drivers/measured_boot/rss/rss_measured_boot.h`` - ``include/drivers/measured_boot/rse/rse_measured_boot.h``
.. code-block:: c .. code-block:: c
int rss_mboot_set_signer_id(struct rss_mboot_metadata *metadata_ptr, int rse_mboot_set_signer_id(struct rse_mboot_metadata *metadata_ptr,
const void *pk_oid, const void *pk_oid,
const void *pk_ptr, const void *pk_ptr,
size_t pk_len) size_t pk_len)
- First parameter is the pointer to the ``rss_mboot_metadata`` structure. - First parameter is the pointer to the ``rse_mboot_metadata`` structure.
- Second parameter is the pointer to the key-OID of the public key. - Second parameter is the pointer to the key-OID of the public key.
- Third parameter is the pointer to the public key buffer. - Third parameter is the pointer to the public key buffer.
- Fourth parameter is the size of public key buffer. - Fourth parameter is the size of public key buffer.
@ -356,15 +356,15 @@ Build time config options
^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^
- ``MEASURED_BOOT``: Enable measured boot. It depends on the platform - ``MEASURED_BOOT``: Enable measured boot. It depends on the platform
implementation whether RSS or TPM (or both) backend based measured boot is implementation whether RSE or TPM (or both) backend based measured boot is
enabled. enabled.
- ``MBOOT_RSS_HASH_ALG``: Determine the hash algorithm to measure the images. - ``MBOOT_RSE_HASH_ALG``: Determine the hash algorithm to measure the images.
The default value is sha-256. The default value is sha-256.
Measured boot flow Measured boot flow
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
.. figure:: ../resources/diagrams/rss_measured_boot_flow.svg .. figure:: ../resources/diagrams/rse_measured_boot_flow.svg
:align: center :align: center
Sample console log Sample console log
@ -425,15 +425,15 @@ The detailed description of the delegated attestation service can be found in
the ``Delegated Attestation Service Integration Guide`` [4]_ document. the ``Delegated Attestation Service Integration Guide`` [4]_ document.
In the CCA use case, the Realm Management Monitor (RMM) relies on the delegated In the CCA use case, the Realm Management Monitor (RMM) relies on the delegated
attestation service of the RSS to get a realm attestation key and the CCA attestation service of the RSE to get a realm attestation key and the CCA
platform token. BL31 does not use the service for its own purpose, only calls platform token. BL31 does not use the service for its own purpose, only calls
it on behalf of RMM. The access to MHU interface and thereby to RSS is it on behalf of RMM. The access to MHU interface and thereby to RSE is
restricted to BL31 only. Therefore, RMM does not have direct access, all calls restricted to BL31 only. Therefore, RMM does not have direct access, all calls
need to go through BL31. The RMM dispatcher module of the BL31 is responsible need to go through BL31. The RMM dispatcher module of the BL31 is responsible
for delivering the calls between the two parties. for delivering the calls between the two parties.
.. Note:: .. Note::
Currently the connection between the RMM dispatcher and the PSA/RSS layer Currently the connection between the RMM dispatcher and the PSA/RSE layer
is not yet implemented. RMM dispatcher just returns hard coded data. is not yet implemented. RMM dispatcher just returns hard coded data.
Delegated Attestation API Delegated Attestation API
@ -445,7 +445,7 @@ Defined here:
.. code-block:: c .. code-block:: c
psa_status_t psa_status_t
rss_delegated_attest_get_delegated_key(uint8_t ecc_curve, rse_delegated_attest_get_delegated_key(uint8_t ecc_curve,
uint32_t key_bits, uint32_t key_bits,
uint8_t *key_buf, uint8_t *key_buf,
size_t key_buf_size, size_t key_buf_size,
@ -453,7 +453,7 @@ Defined here:
uint32_t hash_algo); uint32_t hash_algo);
psa_status_t psa_status_t
rss_delegated_attest_get_token(const uint8_t *dak_pub_hash, rse_delegated_attest_get_token(const uint8_t *dak_pub_hash,
size_t dak_pub_hash_size, size_t dak_pub_hash_size,
uint8_t *token_buf, uint8_t *token_buf,
size_t token_buf_size, size_t token_buf_size,
@ -462,7 +462,7 @@ Defined here:
Attestation flow Attestation flow
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
.. figure:: ../resources/diagrams/rss_attestation_flow.svg .. figure:: ../resources/diagrams/rse_attestation_flow.svg
:align: center :align: center
Sample attestation token Sample attestation token
@ -623,27 +623,27 @@ JSON format:
"CCA_PLATFORM_VERIFICATION_SERVICE": "www.trustedfirmware.org" "CCA_PLATFORM_VERIFICATION_SERVICE": "www.trustedfirmware.org"
} }
RSS OTP Assets Management RSE OTP Assets Management
------------------------- -------------------------
RSS provides access for AP to assets in OTP, which include keys for image RSE provides access for AP to assets in OTP, which include keys for image
signature verification and non-volatile counters for anti-rollback protection. signature verification and non-volatile counters for anti-rollback protection.
Non-Volatile Counter API Non-Volatile Counter API
^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^
AP/RSS interface for retrieving and incrementing non-volatile counters API is AP/RSE interface for retrieving and incrementing non-volatile counters API is
as follows. as follows.
Defined here: Defined here:
- ``include/lib/psa/rss_platform_api.h`` - ``include/lib/psa/rse_platform_api.h``
.. code-block:: c .. code-block:: c
psa_status_t rss_platform_nv_counter_increment(uint32_t counter_id) psa_status_t rse_platform_nv_counter_increment(uint32_t counter_id)
psa_status_t rss_platform_nv_counter_read(uint32_t counter_id, psa_status_t rse_platform_nv_counter_read(uint32_t counter_id,
uint32_t size, uint8_t *val) uint32_t size, uint8_t *val)
Through this service, we can read/increment any of the 3 non-volatile Through this service, we can read/increment any of the 3 non-volatile
@ -656,15 +656,15 @@ counters used on an Arm CCA platform:
Public Key API Public Key API
^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^
AP/RSS interface for reading the ROTPK is as follows. AP/RSE interface for reading the ROTPK is as follows.
Defined here: Defined here:
- ``include/lib/psa/rss_platform_api.h`` - ``include/lib/psa/rse_platform_api.h``
.. code-block:: c .. code-block:: c
psa_status_t rss_platform_key_read(enum rss_key_id_builtin_t key, psa_status_t rse_platform_key_read(enum rse_key_id_builtin_t key,
uint8_t *data, size_t data_size, size_t *data_length) uint8_t *data, size_t data_size, size_t *data_length)
Through this service, we can read any of the 3 ROTPKs used on an Through this service, we can read any of the 3 ROTPKs used on an
@ -677,11 +677,11 @@ Arm CCA platform:
References References
---------- ----------
.. [1] https://tf-m-user-guide.trustedfirmware.org/platform/arm/rss/readme.html .. [1] https://tf-m-user-guide.trustedfirmware.org/platform/arm/rse/readme.html
.. [2] https://tf-m-user-guide.trustedfirmware.org/platform/arm/rss/rss_comms.html .. [2] https://tf-m-user-guide.trustedfirmware.org/platform/arm/rse/rse_comms.html
.. [3] https://git.trustedfirmware.org/TF-M/tf-m-extras.git/tree/partitions/measured_boot/measured_boot_integration_guide.rst .. [3] https://git.trustedfirmware.org/TF-M/tf-m-extras.git/tree/partitions/measured_boot/measured_boot_integration_guide.rst
.. [4] https://git.trustedfirmware.org/TF-M/tf-m-extras.git/tree/partitions/delegated_attestation/delegated_attest_integration_guide.rst .. [4] https://git.trustedfirmware.org/TF-M/tf-m-extras.git/tree/partitions/delegated_attestation/delegated_attest_integration_guide.rst
.. [5] https://tf-m-user-guide.trustedfirmware.org/platform/arm/rss/rss_key_management.html .. [5] https://tf-m-user-guide.trustedfirmware.org/platform/arm/rse/rse_key_management.html
.. [6] https://developer.arm.com/-/media/Files/pdf/PlatformSecurityArchitecture/Architect/DEN0063-PSA_Firmware_Framework-1.0.0-2.pdf?revision=2d1429fa-4b5b-461a-a60e-4ef3d8f7f4b4&hash=3BFD6F3E687F324672F18E5BE9F08EDC48087C93 .. [6] https://developer.arm.com/-/media/Files/pdf/PlatformSecurityArchitecture/Architect/DEN0063-PSA_Firmware_Framework-1.0.0-2.pdf?revision=2d1429fa-4b5b-461a-a60e-4ef3d8f7f4b4&hash=3BFD6F3E687F324672F18E5BE9F08EDC48087C93
.. [7] https://developer.arm.com/documentation/DEN0096/A_a/?lang=en .. [7] https://developer.arm.com/documentation/DEN0096/A_a/?lang=en

6
docs/porting-guide.rst
View file

@ -256,10 +256,10 @@ likely to be suitable for all platform ports.
Defines the maximum address in secure RAM that the BL31 image can occupy. Defines the maximum address in secure RAM that the BL31 image can occupy.
- **#define : PLAT_RSS_COMMS_PAYLOAD_MAX_SIZE** - **#define : PLAT_RSE_COMMS_PAYLOAD_MAX_SIZE**
Defines the maximum message size between AP and RSS. Need to define if Defines the maximum message size between AP and RSE. Need to define if
platform supports RSS. platform supports RSE.
For every image, the platform must define individual identifiers that will be For every image, the platform must define individual identifiers that will be
used by BL1 or BL2 to load the corresponding image into memory from non-volatile used by BL1 or BL2 to load the corresponding image into memory from non-volatile

2
docs/resources/diagrams/plantuml/rse_attestation_flow.puml
View file

@ -5,7 +5,7 @@ box AP
participant RMM participant RMM
participant BL31 participant BL31
endbox endbox
box RSS box RSE
participant DelegAttest participant DelegAttest
participant InitAttest participant InitAttest
participant MeasuredBoot participant MeasuredBoot

96
docs/resources/diagrams/plantuml/rse_measured_boot_flow.puml
View file

@ -1,11 +1,11 @@
@startuml @startuml
skinparam ParticipantPadding 10 skinparam ParticipantPadding 10
skinparam BoxPadding 10 skinparam BoxPadding 10
box RSS box RSE
participant RSS_BL1_1 participant RSE_BL1_1
participant RSS_BL1_2 participant RSE_BL1_2
participant RSS_BL2 participant RSE_BL2
participant RSS_S participant RSE_S
endbox endbox
box SCP box SCP
participant SCP_BL1 participant SCP_BL1
@ -16,64 +16,64 @@ participant AP_BL2
participant AP_BL31 participant AP_BL31
endbox endbox
== RSS Boot phase == == RSE Boot phase ==
-> RSS_BL1_1: Reset -> RSE_BL1_1: Reset
Rnote over RSS_BL1_1: ROM code, XIP Rnote over RSE_BL1_1: ROM code, XIP
Rnote over RSS_BL1_2: OTP code, XIP Rnote over RSE_BL1_2: OTP code, XIP
Rnote over RSS_BL2, AP_BL31: Stored in flash, loaded and executed in RAM Rnote over RSE_BL2, AP_BL31: Stored in flash, loaded and executed in RAM
activate RSS_BL1_1 #Green activate RSE_BL1_1 #Green
RSS_BL1_1 -->> RSS_BL1_2: Validate, measure RSE_BL1_1 -->> RSE_BL1_2: Validate, measure
Rnote over RSS_BL1_1: BL1_2 measurement\n\ saved to a shared buffer Rnote over RSE_BL1_1: BL1_2 measurement\n\ saved to a shared buffer
RSS_BL1_1 -> RSS_BL1_2: Pass execution RSE_BL1_1 -> RSE_BL1_2: Pass execution
deactivate RSS_BL1_1 deactivate RSE_BL1_1
activate RSS_BL1_2 #Green activate RSE_BL1_2 #Green
RSS_BL1_2 -->> RSS_BL2: Validate, measure, load RSE_BL1_2 -->> RSE_BL2: Validate, measure, load
Rnote over RSS_BL1_2: RSS_BL2 measurement\n\ saved to a shared buffer Rnote over RSE_BL1_2: RSE_BL2 measurement\n\ saved to a shared buffer
RSS_BL1_2 -> RSS_BL2: Pass execution RSE_BL1_2 -> RSE_BL2: Pass execution
deactivate RSS_BL1_2 deactivate RSE_BL1_2
activate RSS_BL2 #Green activate RSE_BL2 #Green
RSS_BL2 -->> RSS_S: Validate, measure, load RSE_BL2 -->> RSE_S: Validate, measure, load
RSS_BL2 -->> SCP_BL1: Validate, measure, load RSE_BL2 -->> SCP_BL1: Validate, measure, load
Rnote over RSS_BL2: RSS_S and SCP_BL1\n\ measurements saved\n\ to a shared buffer Rnote over RSE_BL2: RSE_S and SCP_BL1\n\ measurements saved\n\ to a shared buffer
RSS_BL2 -> SCP_BL1: Release from reset RSE_BL2 -> SCP_BL1: Release from reset
activate SCP_BL1 #Green activate SCP_BL1 #Green
Rnote over RSS_BL2, SCP_BL1: MHU init between RSS and SCP Rnote over RSE_BL2, SCP_BL1: MHU init between RSE and SCP
Rnote over SCP_BL1: Configure memory Rnote over SCP_BL1: Configure memory
Rnote over RSS_BL2: Waits for SCP Rnote over RSE_BL2: Waits for SCP
SCP_BL1 --> RSS_BL2: Done SCP_BL1 --> RSE_BL2: Done
RSS_BL2 -->> AP_BL1: Validate, measure, load RSE_BL2 -->> AP_BL1: Validate, measure, load
Rnote over RSS_BL2: AP_BL1 measurement\n\ saved to a shared buffer Rnote over RSE_BL2: AP_BL1 measurement\n\ saved to a shared buffer
RSS_BL2 -> AP_BL1: Release from reset RSE_BL2 -> AP_BL1: Release from reset
activate AP_BL1 #Green activate AP_BL1 #Green
RSS_BL2 -> RSS_S: Pass execution RSE_BL2 -> RSE_S: Pass execution
deactivate RSS_BL2 deactivate RSE_BL2
activate RSS_S #Green activate RSE_S #Green
Rnote over RSS_S: Measurements read from\n\ shared buffer and saved by\n\ Rnote over RSE_S: Measurements read from\n\ shared buffer and saved by\n\
Measured Boot service to\n\ measurement slots. Measured Boot service to\n\ measurement slots.
== RSS Runtime / AP Boot phase == == RSE Runtime / AP Boot phase ==
Rnote over RSS_S, AP_BL1: MHU init between RSS and AP Rnote over RSE_S, AP_BL1: MHU init between RSE and AP
Rnote over AP_BL1: Measure and load:\n\ FW_CONFIG\n\ TB_FW_CONFIG Rnote over AP_BL1: Measure and load:\n\ FW_CONFIG\n\ TB_FW_CONFIG
AP_BL1 -> RSS_S: Extend measurement AP_BL1 -> RSE_S: Extend measurement
Rnote over RSS_S: Measured Boot:\n\ store measurement Rnote over RSE_S: Measured Boot:\n\ store measurement
AP_BL1 -->> AP_BL2: Validate, measure,load AP_BL1 -->> AP_BL2: Validate, measure,load
AP_BL1 -> RSS_S: Extend measurement AP_BL1 -> RSE_S: Extend measurement
Rnote over RSS_S: Measured Boot:\n\ store measurement Rnote over RSE_S: Measured Boot:\n\ store measurement
AP_BL1 -> AP_BL2: Pass execution AP_BL1 -> AP_BL2: Pass execution
deactivate AP_BL1 deactivate AP_BL1
activate AP_BL2 #Green activate AP_BL2 #Green
Rnote over AP_BL2: Measure and load:\n\ HW_CONFIG Rnote over AP_BL2: Measure and load:\n\ HW_CONFIG
AP_BL2 -> RSS_S: Extend measurement AP_BL2 -> RSE_S: Extend measurement
Rnote over RSS_S: Measured Boot:\n\ store measurement Rnote over RSE_S: Measured Boot:\n\ store measurement
AP_BL2 -->> AP_BL31: Validate, measure,load AP_BL2 -->> AP_BL31: Validate, measure,load
Rnote over AP_BL2: Measure and load:\n\ BL31 Rnote over AP_BL2: Measure and load:\n\ BL31
AP_BL2 -> RSS_S: Extend measurement AP_BL2 -> RSE_S: Extend measurement
Rnote over RSS_S: Measured Boot:\n\ store measurement Rnote over RSE_S: Measured Boot:\n\ store measurement
Rnote over AP_BL2: Measure and load:\n\ RMM Rnote over AP_BL2: Measure and load:\n\ RMM
AP_BL2 -> RSS_S: Extend measurement AP_BL2 -> RSE_S: Extend measurement
Rnote over RSS_S: Measured Boot:\n\ store measurement Rnote over RSE_S: Measured Boot:\n\ store measurement
AP_BL2 -> AP_BL31: Pass execution AP_BL2 -> AP_BL31: Pass execution
deactivate AP_BL2 deactivate AP_BL2
activate AP_BL31 #Green activate AP_BL31 #Green
== RSS / AP Runtime == == RSE / AP Runtime ==
@enduml @enduml

12
docs/resources/diagrams/plantuml/tfa_rse_dfd.puml
View file

@ -5,7 +5,7 @@
'/ '/
/' /'
TF-A Data Flow Diagram including RSS TF-A Data Flow Diagram including RSE
'/ '/
@startuml @startuml
@ -54,12 +54,12 @@ digraph tfa_dfd {
bl31 [label="TF-A Runtime\n(BL31)" fillcolor="#ddffb3"] bl31 [label="TF-A Runtime\n(BL31)" fillcolor="#ddffb3"]
} }
# RSS cluster # RSE cluster
subgraph cluster_rss{ subgraph cluster_rse{
label ="RSS"; label ="RSE";
graph [style=filled color="#000000" fillcolor="#faf9cd"] graph [style=filled color="#000000" fillcolor="#faf9cd"]
rss [label="Runtime Security\n\ Subsystem\n\ (RSS)" fillcolor="#ddffb3"] rse [label="Runtime Security\n\ Subsystem\n\ (RSE)" fillcolor="#ddffb3"]
} }
} }
@ -70,7 +70,7 @@ digraph tfa_dfd {
sec -> bl2 [dir="both" lhead=cluster_tfa label="DF4"] sec -> bl2 [dir="both" lhead=cluster_tfa label="DF4"]
nsec -> bl1 [dir="both" lhead=cluster_tfa, label="DF5"] nsec -> bl1 [dir="both" lhead=cluster_tfa, label="DF5"]
bl2 -> tzc [dir="both" ltail=cluster_tfa lhead=cluster_ip label="DF6" minlen=1] bl2 -> tzc [dir="both" ltail=cluster_tfa lhead=cluster_ip label="DF6" minlen=1]
bl31 -> rss [dir="both" ltail=cluster_tfa lhead=cluster_rss label="DF7" minlen=1] bl31 -> rse [dir="both" ltail=cluster_tfa lhead=cluster_rse label="DF7" minlen=1]
} }

4
docs/resources/diagrams/rse_attestation_flow.svg
View file

File diff suppressed because one or more lines are too long
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 18 KiB

After

Width:  |  Height:  |  Size: 18 KiB

98
docs/resources/diagrams/rse_measured_boot_flow.svg
View file

File diff suppressed because one or more lines are too long
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 29 KiB

After

Width:  |  Height:  |  Size: 29 KiB

2
docs/threat_model/firmware_threat_model/index.rst
View file

@ -30,7 +30,7 @@ data flow diagram, as well as a list of threats we have identified using the
threat_model threat_model
threat_model_el3_spm threat_model_el3_spm
threat_model_fvp_r threat_model_fvp_r
threat_model_rss_interface threat_model_rse_interface
threat_model_arm_cca threat_model_arm_cca
threat_model_fw_update_and_recovery threat_model_fw_update_and_recovery

28
docs/threat_model/firmware_threat_model/threat_model_rse_interface.rst
View file

@ -1,41 +1,41 @@
Threat Model for RSS - AP interface Threat Model for RSE - AP interface
*********************************** ***********************************
************ ************
Introduction Introduction
************ ************
This document is an extension for the general TF-A threat-model. It considers This document is an extension for the general TF-A threat-model. It considers
those platforms where a Runtime Security Subsystem (RSS) is included in the SoC those platforms where a Runtime Security Engine (RSE) is included in the SoC
next to the Application Processor (AP). next to the Application Processor (AP).
******************** ********************
Target of Evaluation Target of Evaluation
******************** ********************
The scope of this threat model only includes the interface between the RSS and The scope of this threat model only includes the interface between the RSE and
AP. Otherwise, the TF-A :ref:`Generic Threat Model` document is applicable for AP. Otherwise, the TF-A :ref:`Generic Threat Model` document is applicable for
the AP core. The threat model for the RSS firmware will be provided by the RSS the AP core. The threat model for the RSE firmware will be provided by the RSE
firmware project in the future. firmware project in the future.
Data Flow Diagram Data Flow Diagram
================= =================
This diagram is different only from the general TF-A data flow diagram in that This diagram is different only from the general TF-A data flow diagram in that
it includes the RSS and highlights the interface between the AP and the RSS it includes the RSE and highlights the interface between the AP and the RSE
cores. The interface description only focuses on the AP-RSS interface the rest cores. The interface description only focuses on the AP-RSE interface the rest
is the same as in the general TF-A threat-model document. is the same as in the general TF-A threat-model document.
.. uml:: ../../resources/diagrams/plantuml/tfa_rss_dfd.puml .. uml:: ../../resources/diagrams/plantuml/tfa_rse_dfd.puml
:caption: Figure 1: TF-A Data Flow Diagram including RSS :caption: Figure 1: TF-A Data Flow Diagram including RSE
.. table:: Table 1: TF-A - RSS data flow diagram .. table:: Table 1: TF-A - RSE data flow diagram
+-----------------+--------------------------------------------------------+ +-----------------+--------------------------------------------------------+
| Diagram Element | Description | | Diagram Element | Description |
+=================+========================================================+ +=================+========================================================+
| DF7 | | Boot images interact with RSS over a communication | | DF7 | | Boot images interact with RSE over a communication |
| | channel to record boot measurements and get image | | | channel to record boot measurements and get image |
| | verification keys. At runtime, BL31 obtains the | | | verification keys. At runtime, BL31 obtains the |
| | realm world attestation signing key from RSS. | | | realm world attestation signing key from RSE. |
+-----------------+--------------------------------------------------------+ +-----------------+--------------------------------------------------------+
Threat Assessment Threat Assessment
@ -44,12 +44,12 @@ For this section, please reference the Threat Assessment under the general TF-A
threat-model document, :ref:`Generic Threat Model`. All the threats listed there threat-model document, :ref:`Generic Threat Model`. All the threats listed there
are applicable for the AP core, here only the differences are highlighted. are applicable for the AP core, here only the differences are highlighted.
- ID 11: The access to the communication interface between AP and RSS is - ID 11: The access to the communication interface between AP and RSE is
allowed only for firmware running at EL3. Accidentally exposing this allowed only for firmware running at EL3. Accidentally exposing this
interface to NSCode can allow malicious code to interact with RSS and interface to NSCode can allow malicious code to interact with RSE and
gain access to sensitive data. gain access to sensitive data.
- ID 13: Relevant in the context of the realm attestation key, which can be - ID 13: Relevant in the context of the realm attestation key, which can be
retrieved by BL31 through DF7. The RSS communication protocol layer retrieved by BL31 through DF7. The RSE communication protocol layer
mitigates against this by clearing its internal buffer when reply is mitigates against this by clearing its internal buffer when reply is
received. The caller of the API must do the same if data is not needed received. The caller of the API must do the same if data is not needed
anymore. anymore.

2
docs/threat_model/supply_chain_threat_model.rst
View file

@ -115,7 +115,7 @@ description of each component and where they are sourced from.
- *EDK2 UEFI*: Normal world bootloader from the EDK2 project [7]_. We use EDK2 - *EDK2 UEFI*: Normal world bootloader from the EDK2 project [7]_. We use EDK2
UEFI binaries hosted on tf.org servers for testing [8]_. UEFI binaries hosted on tf.org servers for testing [8]_.
Other software components used to test TF-A include U-Boot, Linux kernel, RSS, Other software components used to test TF-A include U-Boot, Linux kernel, RSE,
MCP, and file systems, all sourced from the Arm Reference Platforms teams. MCP, and file systems, all sourced from the Arm Reference Platforms teams.
TF-A Toolchain TF-A Toolchain