1Runtime Security Engine (RSE) 2============================= 3 4Introduction 5------------ 6 7Runtime Security Engine (RSE) 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 13RSE initially boots from immutable code (BL1_1) in its internal ROM, before 14jumping to BL1_2, which is provisioned and hash-locked in RSE OTP. The updatable 15MCUBoot BL2 boot stage is loaded from host system flash into RSE SRAM, where it 16is authenticated. BL2 loads and authenticates the TF-M runtime into RSE SRAM 17from host flash. BL2 is also responsible for loading initial boot code into 18other subsystems within the host. 19 20The RSE 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/rse/<rse platform name>` 30 31For example for building RSE for Total Compute platforms: 32``-DTFM_PLATFORM=arm/rse/tc`` 33 34Signing host images 35------------------- 36 37RSE 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 0x2000 \ 53 --pad-header \ 54 -S 0x80000 \ 55 --pad \ 56 -L <load address> \ 57 <binary infile> \ 58 <signed binary outfile> 59 60The ``load address`` is the logical address in the RSE memory map to which BL2 61will load the image. RSE FW expects the first host image to be loaded to address 62``0x70000000`` (the beginning of the RSE ATU host access region), and each 63subsequent host image to be loaded at an offset of ``0x1000000`` from the 64previous image. The RSE ATU should be configured to map these logical addresses 65to the physical addresses in the host system that the images need to be loaded 66to. 67 68For more information on the ``imgtool`` parameters, see the MCUBoot 69`imgtool documentation <https://docs.mcuboot.com/imgtool.html>`_. 70 71.. warning:: 72 73 The TF-M development key must never be used in production. To generate a 74 production key, follow the imgtool documentation. 75 76Running the code 77---------------- 78 79To run the built images, first the ROM image must be created from the bl1_1 80binary and the ROM DMA Initial Command Sequence (ICS).:: 81 82 srec_cat \ 83 bl1_1.bin -Binary -offset 0x0 \ 84 rom_dma_ics.bin -Binary -offset 0x1F000 \ 85 -o rom.bin -Binary 86 87Then, the flash image must be created by concatenating the images that are 88output from the build. To create the flash image, the following ``fiptool`` 89command should be run. ``fiptool`` documentation can be found `here 90<https://trustedfirmware-a.readthedocs.io/en/latest/getting_started/tools-build.html?highlight=fiptool#building-and-using-the-fip-tool>`_. 91Note that an up-to-date fiptool that supports the RSE UUIDs must be used.:: 92 93 fiptool create \ 94 --align 8192 --rss-bl2 bl2_signed.bin \ 95 --align 8192 --rss-ns tfm_ns_signed.bin \ 96 --align 8192 --rss-s tfm_s_signed.bin \ 97 --align 8192 --rss-scp-bl1 <signed Host SCP BL1 image> \ 98 --align 8192 --rss-ap-bl1 <signed Host AP BL1 image> \ 99 fip.bin 100 101If you already have a ``fip.bin`` containing host firmware images, RSE FIP 102images can be patched in:: 103 104 fiptool update --align 8192 --rss-bl2 bl2_signed.bin fip.bin 105 fiptool update --align 8192 --rss-ns tfm_ns.bin fip.bin 106 fiptool update --align 8192 --rss-s tfm_s.bin fip.bin 107 108If XIP mode is enabled, the following ``fiptool`` command should be run to 109create the flash image:: 110 111 fiptool create \ 112 --align 8192 --rss-bl2 bl2_signed.bin \ 113 --align 8192 --rss-ns tfm_ns_encrypted.bin \ 114 --align 8192 --rss-s tfm_s_encrypted.bin \ 115 --align 8192 --rss-sic-tables-ns tfm_ns_sic_tables_signed.bin \ 116 --align 8192 --rss-sic-tables-s tfm_s_sic_tables_signed.bin \ 117 --align 8192 --rss-scp-bl1 <signed Host SCP BL1 image> \ 118 --align 8192 --rss-ap-bl1 <signed Host AP BL1 image> \ 119 fip.bin 120 121Once the FIP is prepared, a host flash image can be created using ``srec_cat``:: 122 123 srec_cat \ 124 fip.bin -Binary -offset 0x0 \ 125 -o host_flash.bin -Binary 126 127If GPT support is enabled, and a host ``fip.bin`` and ``fip_gpt.bin`` has been 128obtained, RSE images can be inserted by first patching the host FIP and then 129inserting that patched FIP into the GPT image:: 130 131 sector_size=$(gdisk -l fip_gpt.bin | grep -i "sector size (logical):" | \ 132 sed 's/.*logical): \([0-9]*\) bytes/\1/') 133 134 fip_label=" FIP_A$" 135 fip_start_sector=$(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $2}') 136 fip_sector_am=$(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $3 - $2}') 137 138 dd if=fip.bin of=fip_gpt.bin bs=$sector_size seek=$fip_start_sector \ 139 count=$fip_sector_am conv=notrunc 140 141 fip_label = " FIP_B$" 142 fip_start_sector = $(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $2}') 143 fip_sector_am = $(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $3 - $2}') 144 145 dd if=fip.bin of=fip_gpt.bin bs=$sector_size seek=$fip_start_sector \ 146 count=$fip_sector_am conv=notrunc 147 148To patch a ``fip_gpt.bin`` without having an initial ``fip.bin``, the FIP can be 149extracted from the GPT image using the following commands (and can then be 150patched and reinserted using the above commands):: 151 152 sector_size=$(gdisk -l fip_gpt.bin | grep -i "sector size (logical):" | \ 153 sed 's/.*logical): \([0-9]*\) bytes/\1/') 154 155 fip_label=" FIP_A$" 156 fip_start_sector=$(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $2}') 157 fip_sector_am=$(gdisk -l fip_gpt.bin | grep "$fip_label" | awk '{print $3 - $2}') 158 159 dd if=fip_gpt.bin of=fip.bin bs=$sector_size skip=$fip_start_sector \ 160 count=$fip_sector_am conv=notrunc 161 162Once the ``fip_gpt.bin`` is prepared, it is placed at the base of the host flash 163image:: 164 165 srec_cat \ 166 fip_gpt.bin -Binary -offset 0x0 \ 167 -o host_flash.bin -Binary 168 169The RSE ROM binary should be placed in RSE ROM at ``0x11000000`` and the host 170flash binary should be placed at the base of the host flash. For the TC 171platform, this is at ``0x80000000``. 172 173The RSE OTP must be provisioned. On a development platform with 174``TFM_DUMMY_PROVISIONING`` enabled, BL1_1 expects provisioning bundles to be 175preloaded into SRAM. Preload ``encrypted_cm_provisioning_bundle_0.bin`` to the 176base of VM0, and ``encrypted_dm_provisioning_bundle.bin`` to the base of VM1. 177 178If ``TFM_DUMMY_PROVISIONING`` is disabled and provisioning is required, then 179BL1_1 will first wait for the TP mode to be set by a debugger (setting the 180``tp_mode`` variable in the current stack frame is easiest). BL1_1 will then 181wait for provisioning bundles to be loaded to VM0 and VM1 in the same way as 182when ``TFM_DUMMY_PROVISIONING`` is enabled, except that it will not 183automatically perform the reset once each provisioning state is complete. For 184more details about provisioning flows, see 185:doc:`RSE provisioning </platform/arm/rse/rse_provisioning>`. 186 187-------------- 188 189*Copyright (c) 2022-2023, Arm Limited. All rights reserved.* 190
