1#####################
2Platform Provisioning
3#####################
4
5TF-M stores any data that should be provisioned at the factory in OTP memory.
6The default is that this OTP memory is actually implemented using on-chip flash,
7the same that is used to implement the ITS service.
8
9If the lifecycle state is in the ``TFM_SLC_ASSEMBLY_AND_TEST`` [1]_ state (which
10is the default for non-provisioned boards), then TF-M will attempt to provision
11the:
12- HUK
13instead of booting. It will read the data from the
14``assembly_and_test_prov_data`` struct, and will then provision it to OTP. The
15lifecycle state will then transition to ``TFM_SLC_PSA_ROT_PROVISIONING`` [1]_.
16
17If the lifecycle state is in the ``TFM_SLC_PSA_ROT_PROVISIONING`` [1]_ state,
18then TF-M will attempt to provision the:
19
20- IAK
21- boot seed
22- implementation id
23- certification reference
24- bl2 ROTPKs (of which there are up to 4)
25- entropy seed
26
27Once all of these have been loaded from the ``psa_rot_prov_data`` struct and
28provisioned to OTP, the LCS will transition to ``TFM_SLC_SECURED`` [1]_. Note
29that this provisioning step will be run immediately after the
30``TFM_SLC_ASSEMBLY_AND_TEST`` [1]_ provisioning stage if the lifecycle
31transition completed successfully.
32
33Provisioning development hardware
34=================================
35
36If ``TFM_DUMMY_PROVISIONING`` is enabled in the cmake config (as it is by
37default), a set of dummy keys / data will be provisioned. The dummy IAK matches
38the IAK tested by the TF-M tests, and the dummy bl2 ROTPKs match the dummy bl2
39keys used by default. ``TFM_DUMMY_PROVISIONING`` _MUST_ not be used in
40production hardware, as the keys are insecure.
41
42Provisioning production hardware
43================================
44
45For provisioning of real hardware, firstly ``TFM_DUMMY_PROVISIONING`` must be
46disabled. Then it is required to inject the keys into RAM so they populate the
47``assembly_and_test_prov_data`` and ``psa_rot_prov_data`` structs, at the
48beginning of the TF-M boot. These structs each require a magic value to be set
49to be accepted by the provisioning code, which is detailed in
50``platform/ext/common/provisioning.c``. Two suggestions for how to do this are:
51
52- Attach a debugger, and inject the values into RAM.
53- Flash an image that contains the required data. Care must be taken with this
54  approach that the keys are not left in RAM after provisioning, so a different
55  image (without provisioning data embedded) must be flashed afterwards, without
56  erasing the OTP flash area.
57
58************************************************
59Provisioning on CryptoCell-312 enabled platforms
60************************************************
61
62On boards that have a CC312 accelerator, and that have the default flash-backed
63OTP disabled by setting ``PLATFORM_DEFAULT_OTP=OFF`` in cmake, the CC312 OTP
64will be used as a backing for the OTP HAL.
65
66Due to the CC312 requiring a power-cycle to transition LCS, you will be prompted
67to manually power-cycle the board between provisioning stages.
68
69Boards with real OTP memory cannot be reprovisioned - care should be taken that
70the data being provisioned is the desired data.
71
72*****************************
73Platform-specific OTP backing
74*****************************
75
76If a platform has a medium that is suitable for storing data with OTP semantics
77(Where a bit cannot transition from a 1 to a 0), such as physical OTP memory,
78then it can provide a backing for the OTP HAL by implementing the methods
79described in ``tfm_plat_otp.h``.
80
81--------------
82
83.. [1] For the definitions of these lifecycle states, please refer to the
84       Platform Security Model
85       https://developer.arm.com/documentation/den0128/0100/
86
87--------------
88
89*Copyright (c) 2020-2022, Arm Limited. All rights reserved.*
90