1Runtime Security Subsystem (RSS)
2================================
3
4Introduction
5------------
6
7Runtime Security Subsystem (RSS) is an Arm subsystem that provides a reference
8implementation of the HES Host in the
9`Arm Confidential Compute Architecture (CCA) <https://www.arm.com/architecture/security-features/arm-confidential-compute-architecture>`_.
10It is designed to be integrated into A-profile compute subsystems that implement
11Arm CCA, where it serves as the Root of Trust.
12
13RSS initially boots from immutable code (BL1_1) in its internal ROM, before
14jumping to BL1_2, which is provisioned and hash-locked in RSS OTP. The updatable
15MCUBoot BL2 boot stage is loaded from host system flash into RSS SRAM, where it
16is authenticated. BL2 loads and authenticates the TF-M runtime into RSS SRAM
17from host flash. BL2 is also responsible for loading initial boot code into
18other subsystems within the host.
19
20The RSS platform port supports the TF-M Crypto, TF-M Initial Attestation,
21Measured Boot and TF-M Platform services along with the corresponding
22regression tests. It supports the IPC model in multi-core topology with
23Isolation Level 1 and 2.
24
25Building TF-M
26-------------
27
28Follow the instructions in :doc:`Build instructions </building/tfm_build_instruction>`.
29Build TF-M with platform name: `arm/rss/<rss platform name>`
30
31For example for building RSS for Total Compute platforms:
32``-DTFM_PLATFORM=arm/rss/tc``
33
34Signing host images
35-------------------
36
37RSS BL2 can load boot images into other subsystems within the host system. It
38expects images to be signed, with the signatures attached to the images in the
39MCUBoot metadata format.
40
41The `imgtool Python package <https://pypi.org/project/imgtool/>`_ can be used to
42sign images in the required format. To sign a host image using the development
43key distributed with TF-M, use the following command::
44
45    imgtool sign \
46        -k <TF-M base directory>/bl2/ext/mcuboot/root-RSA-3072.pem \
47        --public-key-format full \
48        --max-align 8 \
49        --align 1 \
50        -v "0.0.1" \
51        -s 1 \
52        -H 0x1000 \
53        --pad-header \
54        -S 0x80000 \
55        --pad \
56        --boot-record "HOST" \
57        -L <load address> \
58        <binary infile> \
59        <signed binary outfile>
60
61The ``load address`` is the logical address in the RSS memory map to which BL2
62will load the image. RSS FW expects the first host image to be loaded to address
63``0x70000000`` (the beginning of the RSS ATU host access region), and each
64subsequent host image to be loaded at an offset of ``0x100000`` from the
65previous image. The RSS ATU should be configured to map these logical addresses
66to the physical addresses in the host system that the images need to be loaded
67to.
68
69For more information on the ``imgtool`` parameters, see the MCUBoot
70`imgtool documentation <https://docs.mcuboot.com/imgtool.html>`_.
71
72.. warning::
73
74    The TF-M development key must never be used in production. To generate a
75    production key, follow the imgtool documentation.
76
77Running the code
78----------------
79
80To run the built images, they need to be concatenated into binaries that can be
81placed in ROM and flash. To create the ROM image, navigate to the TF-M build
82directory and run the following ``srec_cat`` command::
83
84    srec_cat \
85        bl1_1.bin -Binary -offset 0x0 \
86        bl1_provisioning_bundle.bin -Binary -offset 0xE000 \
87        -o rom.bin -Binary
88
89For development purposes, the OTP image is included as a provisioning bundle in
90the ROM image and provisioned into OTP by BL1_1.
91
92To create the flash image, the following ``fiptool`` command should be run.
93``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>`_.
94Note that an up-to-date fiptool that supports the RSS UUIDs must be used.::
95
96    fiptool create \
97        --align 8192 --rss-bl2     bl2_signed.bin \
98        --align 8192 --rss-ns      tfm_ns_signed.bin \
99        --align 8192 --rss-s       tfm_s_signed.bin \
100        --align 8192 --rss-scp-bl1 <signed Host SCP BL1 image> \
101        --align 8192 --rss-ap-bl1  <signed Host AP BL1 image> \
102        fip.bin
103
104If you already have a ``fip.bin`` containing host firmware images, RSS FIP
105images can be patched in::
106
107    fiptool update --align 8192 --rss-bl2 bl2_signed.bin fip.bin
108    fiptool update --align 8192 --rss-ns  tfm_ns.bin fip.bin
109    fiptool update --align 8192 --rss-s   tfm_s.bin fip.bin
110
111If XIP mode is enabled, the following ``fiptool`` command should be run to
112create the flash image::
113
114    fiptool create \
115        --align 8192 --rss-bl2           bl2_signed.bin \
116        --align 8192 --rss-ns            tfm_ns.bin \
117        --align 8192 --rss-s             tfm_s.bin \
118        --align 8192 --rss-sic-tables-ns tfm_ns_sic_tables_signed.bin \
119        --align 8192 --rss-sic-tables-s  tfm_s_sic_tables_signed.bin \
120        --align 8192 --rss-scp-bl1       <signed Host SCP BL1 image> \
121        --align 8192 --rss-ap-bl1        <signed Host AP BL1 image> \
122        fip.bin
123
124Once the FIP is prepared, a host flash image can be created using ``srec_cat``::
125
126    srec_cat \
127            fip.bin -Binary -offset 0x0 \
128            -o host_flash.bin -Binary
129
130If GPT support is enabled, and a host ``fip.bin`` and ``fip_gpt.bin`` has been
131obtained, RSS images can be inserted by first patching the host FIP and then
132inserting that patched FIP into the GPT image::
133
134    sector_size=$(gdisk -l fip_gpt.bin | grep -i "sector size (logical):" | \
135                sed 's/.*logical): \([0-9]*\) bytes/\1/')
136
137    fip_label=" FIP_A$"
138    fip_start_sector=$(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $2}')
139    fip_sector_am=$(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $3 - $2}')
140
141    dd if=fip.bin of=fip_gpt.bin bs=$sector_size seek=$fip_start_sector \
142        count=$fip_sector_am conv=notrunc
143
144    fip_label = " FIP_B$"
145    fip_start_sector = $(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $2}')
146    fip_sector_am = $(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $3 - $2}')
147
148    dd if=fip.bin of=fip_gpt.bin bs=$sector_size seek=$fip_start_sector \
149        count=$fip_sector_am conv=notrunc
150
151To patch a ``fip_gpt.bin`` without having an initial ``fip.bin``, the FIP can be
152extracted from the GPT image using the following commands (and can then be
153patched and reinserted using the above commands)::
154
155    sector_size=$(gdisk -l fip_gpt.bin | grep -i "sector size (logical):" | \
156                sed 's/.*logical): \([0-9]*\) bytes/\1/')
157
158    fip_label=" FIP_A$"
159    fip_start_sector=$(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $2}')
160    fip_sector_am=$(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $3 - $2}')
161
162    dd if=fip_gpt.bin of=fip.bin bs=$sector_size skip=$fip_start_sector \
163        count=$fip_sector_am conv=notrunc
164
165Once the ``fip_gpt.bin`` is prepared, it is placed at the base of the host flash
166image::
167
168    srec_cat \
169            fip_gpt.bin -Binary -offset 0x0 \
170            -o host_flash.bin -Binary
171
172The ROM binary should be placed in RSS ROM at ``0x11000000`` and the host flash
173binary should be placed at the base of the host flash. For the TC platform,
174this is at ``0x80000000``.
175
176--------------
177
178*Copyright (c) 2022-2023, Arm Limited. All rights reserved.*
179