1RSE provisioning
2================
3
4Provisioning theory
5-------------------
6
7The LifeCycle Manager (LCM) controls access to the RSE OTP, and includes a
8state-machine that controls Lifecycle-state (LCS) transitions. The LCM is
9derived from the OTP management and state machine subsystems of the
10CryptoCell-3XX series accelerators, and will be familiar to those who have
11worked with them.
12
13When the chip hasn't been provisioned, the OTP is blank, which means the LCM is
14in "Virgin" Test/Production mode "TP mode" state. The first step for
15provisioning must be to set the LCM to either test-chip mode "TCI" or
16production-chip mode "PCI". In TCI mode the RTL key is masked to avoid
17disclosure, several OTP fields are changed from write-only to read-write, to aid
18in debugging, and debugging is not limited in secure provisioning mode (though
19the RTL key reads as zero). If ``TFM_DUMMY_PROVISIONING`` is enabled in cmake
20(which it is by default) then the chip will be set to TCI mode. If this option
21is not enabled, execution will pause to allow the setting to be set by a
22debugger.
23
24Once the TP mode has been set, the chip is then is Chip Manufacturer
25provisioning state "CM". This mode is intended for the provisioning of the HUK,
26GUK, CM provisioning key, CM code-encryption key, the root-of-trust public key
27and the CM config. To provision these fields, The firmware must first receive a
28provisioning bundle via a debugger. This bundle must be placed at the start of
29VM0 + an offset the size of the OTP DMA ICS (usually 0x400). This bundle
30contains the keys and also code to perform the provisioning such as a driver for
31the LCM, and a function to randomly generate the HUK via the CryptoCell TRNG.
32The chip must then enter secure provisioning mode by setting the SP_ENABLE
33register. This causes a reset (but does not clear the RSE SRAMs), and allows
34access to the RTL key by exporting it to the KMU, though in secure provisioning
35mode the ability to debug the RSE is disabled, to prevent disclosure of the
36decrypted provisioning bundle values. The RSE will then decrypt and authenticate
37the bundle using the RTL key. Under TCI mode the RTL key is zeroed, the bundle
38generation tool must use a zeroed key to encrypt and sign the bundle. Once the
39CM provisioning bundle has been unpacked, the RSE will execute the code which
40will provision the CM provisioning data into OTP. The RSE must be cold-reset,
41which will disable secure provisioning mode. If ``TFM_DUMMY_PROVISIONING`` is
42enabled the reset will happen automatically, else the external provisioning
43device should read the provisioning state from the GPIO/PSI (which is set via
44the ``rse_sysctrl`` register) and perform the reset.
45
46After the cold reset, the RSE will automatically transition to Device
47Manufacturer provisioning state "DM" as the LCM hardware state-machine reads the
48values of the cm_config_1 and cm_config_2 fields as non-zero. This state is
49designed to provision the DM provisioning key, the DM code-encryption key and
50the DM config. The procedure follows the same steps as the CM provisioning flow,
51with the exception that the bundle will now be encrypted and signed using the CM
52provisioning key and must be placed at the base of VM1. As before, once the
53provisioning bundle has been unpacked/run, the RSE must either be cold-reset or
54will perform this automatically.
55
56After the cold reset, the device will now be in Secure Enable "SE" mode, due to
57the dm_config_1 field being non-zero. Debug may be limited based on the hardware
58DCU mask for SE state. Provisioning will not be run on boot.
59
60Practical RSE provisioning
61--------------------------
62
63The RSE buildsystem produces two provisioning bundles (containing both code and
64data), and then encrypts and signs them with the RTL key to produce
65``encrypted_cm_provisioning_bundle.bin`` and
66``encrypted_dm_provisioning_bundle.bin``.
67
68.. Note::
69   Currently encrypted provisioning bundles are not supported due to a lack of
70   AEAD encryption support in the cc312-rom-lib driver. The
71   encrypted_*_provisioning_bundle.bin files should still be used, but note that
72   their contents are not encrypted.
73
74On first boot, the RSE is in Virgin state. If the RSE firmware was built with
75``TFM_DUMMY_PROVISIONING`` enabled then it will automatically set the chip to
76TCI mode and cold-reset. Production ROM implementations must disable
77``TFM_DUMMY_PROVISIONING``, which will cause RSE to loop in the ROM until either
78TCI or PCI mode is set with a debugger. It is possible to set the TP mode in the
79LCS registers directly, however it may be easier to set the ``tp_mode`` variable
80in the frame where RSE is looping, at which point the loop will exit and the TP
81mode will be set by the ROM code.
82
83On non-virgin boot in CM lifecycle state, RSE checks the start of VM0 for the
84magic constant ``0xC0DEFEED``, which is required to be the first word in the CM
85provisioning bundle. There is also a second check for a constant at the end of
86the bundle to ensure the bundle has finished writing. The RSE will perform this
87check in a loop until a bundle is found.
88
89This procedure is repeated for DM LCS, except that the magic constant is
90``0xBEEFFEED`` and the bundle must be loaded to the base of VM1. Note that the
91size of RSE memory may vary depending on implementation, so the load address of
92the DM bundle may change.
93
94In production systems it is intended that these bundles are loaded by a
95debugger, but for development systems it may be too onerous to perform this
96procedure, particularly if the system is one that has ephemeral OTP such as an
97FVP. The preferred solution is to preload to the provisioning bundles into VM0
98and VM1 as part of the image loading, which is supported on FVPs but may not be
99on other systems. An alternative solution is to perform provisioning manually
100once, and then to save the state of the OTP in SE LCS and then preload that on
101subsequent boots.
102
103RSE provisioning GPIO signalling
104--------------------------------
105The state of the RSE ROM boot/provisioning flow is signalled outside of the RSE
106subsystem via the GPIOs as part of the Persistent State Interface (PSI). The PSI
107signals the lifecycle state as a hardware signal, but additionally the software
108can signal over the PSI by setting the ``rse_sysctrl`` register.
109
110The boot state is encoded in the lowest 4 bits of the ``rse_sysctrl`` register,
111and has meaning as follows:
112
113+--------+------------------------------------------------------------------+
114| Signal | State                                                            |
115+========+==================================================================+
116| 0x0    | RSE cold boot default                                            |
117+--------+------------------------------------------------------------------+
118| 0x1    | Virgin chip idle, ready to set PCI/TCI mode                      |
119+--------+------------------------------------------------------------------+
120| 0x2    | CM LCS idle, waiting for CM provisioning bundle                  |
121+--------+------------------------------------------------------------------+
122| 0x3    | RMA LCS idle                                                     |
123+--------+------------------------------------------------------------------+
124| 0x4    | CM secure provisioning started, secure provisioning mode enabled |
125+--------+------------------------------------------------------------------+
126| 0x5    | CM secure provisioning failed due to bundle authentication error |
127+--------+------------------------------------------------------------------+
128| 0x6    | CM secure provisioning failed due to other error                 |
129+--------+------------------------------------------------------------------+
130| 0x7    | CM secure provisioning succeeded                                 |
131+--------+------------------------------------------------------------------+
132| 0x8    | DM LCS idle, waiting for CM provisioning bundle                  |
133+--------+------------------------------------------------------------------+
134| 0x9    | DM secure provisioning started, secure provisioning mode enabled |
135+--------+------------------------------------------------------------------+
136| 0xa    | DM secure provisioning failed due to bundle authentication error |
137+--------+------------------------------------------------------------------+
138| 0xb    | DM secure provisioning failed due to other error                 |
139+--------+------------------------------------------------------------------+
140| 0xc    | DM secure provisioning succeeded                                 |
141+--------+------------------------------------------------------------------+
142| 0xd    | SE LCS standard boot                                             |
143+--------+------------------------------------------------------------------+
144
145--------------
146
147*Copyright (c) 2022-2024, Arm Limited. All rights reserved.*
148