Raef Coles | aefbe08 | 2021-06-18 08:53:43 +0100 | [diff] [blame] | 1 | ##################### |
| 2 | Platform Provisioning |
| 3 | ##################### |
| 4 | |
| 5 | TF-M stores any data that should be provisioned at the factory in OTP memory. |
| 6 | The default is that this OTP memory is actually implemented using on-chip flash, |
| 7 | the same that is used to implement the ITS service. |
| 8 | |
| 9 | If the lifecycle state is in the ``TFM_SLC_ASSEMBLY_AND_TEST`` [1]_ state (which |
| 10 | is the default for non-provisioned boards), then TF-M will attempt to provision |
| 11 | the: |
| 12 | - HUK |
| 13 | instead of booting. It will read the data from the |
| 14 | ``assembly_and_test_prov_data`` struct, and will then provision it to OTP. The |
| 15 | lifecycle state will then transition to ``TFM_SLC_PSA_ROT_PROVISIONING`` [1]_. |
| 16 | |
| 17 | If the lifecycle state is in the ``TFM_SLC_PSA_ROT_PROVISIONING`` [1]_ state, |
| 18 | then TF-M will attempt to provision the: |
| 19 | |
| 20 | - IAK |
| 21 | - boot seed |
| 22 | - implementation id |
Tamas Ban | fc318d7 | 2022-06-22 14:23:52 +0200 | [diff] [blame] | 23 | - certification reference |
Raef Coles | aefbe08 | 2021-06-18 08:53:43 +0100 | [diff] [blame] | 24 | - bl2 ROTPKs (of which there are up to 4) |
| 25 | - entropy seed |
| 26 | |
| 27 | Once all of these have been loaded from the ``psa_rot_prov_data`` struct and |
| 28 | provisioned to OTP, the LCS will transition to ``TFM_SLC_SECURED`` [1]_. Note |
| 29 | that this provisioning step will be run immediately after the |
| 30 | ``TFM_SLC_ASSEMBLY_AND_TEST`` [1]_ provisioning stage if the lifecycle |
| 31 | transition completed successfully. |
| 32 | |
| 33 | Provisioning development hardware |
| 34 | ================================= |
| 35 | |
| 36 | If ``TFM_DUMMY_PROVISIONING`` is enabled in the cmake config (as it is by |
| 37 | default), a set of dummy keys / data will be provisioned. The dummy IAK matches |
| 38 | the IAK tested by the TF-M tests, and the dummy bl2 ROTPKs match the dummy bl2 |
| 39 | keys used by default. ``TFM_DUMMY_PROVISIONING`` _MUST_ not be used in |
| 40 | production hardware, as the keys are insecure. |
| 41 | |
| 42 | Provisioning production hardware |
| 43 | ================================ |
| 44 | |
| 45 | For provisioning of real hardware, firstly ``TFM_DUMMY_PROVISIONING`` must be |
| 46 | disabled. 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 |
| 48 | beginning of the TF-M boot. These structs each require a magic value to be set |
| 49 | to 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 | ************************************************ |
| 59 | Provisioning on CryptoCell-312 enabled platforms |
| 60 | ************************************************ |
| 61 | |
| 62 | On boards that have a CC312 accelerator, and that have the default flash-backed |
| 63 | OTP disabled by setting ``PLATFORM_DEFAULT_OTP=OFF`` in cmake, the CC312 OTP |
| 64 | will be used as a backing for the OTP HAL. |
| 65 | |
| 66 | Due to the CC312 requiring a power-cycle to transition LCS, you will be prompted |
| 67 | to manually power-cycle the board between provisioning stages. |
| 68 | |
| 69 | Boards with real OTP memory cannot be reprovisioned - care should be taken that |
| 70 | the data being provisioned is the desired data. |
| 71 | |
| 72 | ***************************** |
| 73 | Platform-specific OTP backing |
| 74 | ***************************** |
| 75 | |
| 76 | If 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, |
| 78 | then it can provide a backing for the OTP HAL by implementing the methods |
| 79 | described 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 | |
Tamas Ban | fc318d7 | 2022-06-22 14:23:52 +0200 | [diff] [blame] | 89 | *Copyright (c) 2020-2022, Arm Limited. All rights reserved.* |