[doc] document the ROM key slots and CREATOR_SW_CFG_SIGVERIFY_RSA_KEY_EN
This does not contains the exact order the key set, which will be
in a different document since it is specific to the chip.
Signed-off-by: Amaury Pouly <amaury.pouly@lowrisc.org>
diff --git a/doc/security/specs/secure_boot/README.md b/doc/security/specs/secure_boot/README.md
index 012025b..cdd54b0 100644
--- a/doc/security/specs/secure_boot/README.md
+++ b/doc/security/specs/secure_boot/README.md
@@ -77,13 +77,32 @@
Additionally, each key is restricted to one of three "roles", which determine in which device states the key can be used.
The roles are:
-* dev (development, only for devices in the `DEV` lifecycle state)
-* test (manufacturing and testing, only for devices in the `TEST_UNLOCK` lifecycle state)
-* prod (production, only for devices in the `PROD` or `PROD_END` lifecycle states)
+* `dev`: development, only for devices in the `DEV` lifecycle state.
+* `test`: manufacturing and testing, only for devices in the `TEST_UNLOCK` and `RMA` lifecycle states.
+* `prod`: production, intended for `PROD` or `PROD_END` lifecycle states but can be used in all states.
+
+The following table summarizes which role can be used in which lifecycle state:
+
+| Key Type | LC_TEST | LC_RMA | LC_DEV | LC_PROD |
+|----------|:-------:|:------:|:------:|:-------:|
+| `test` | X | X | | |
+| `dev` | | | X | |
+| `prod` | X | X | X | X |
If the key indicated in the manifest has a role that doesn't match the lifecycle state of the device, the boot fails.
All of these keys are 3072-bit RSA public keys with exponent e=65537 (the “F4 exponent”).
+The `ROM` has `N` key slots (the exact number depends on the `ROM`) numbered from `0` to `N-1`.
+The `CREATOR_SW_CFG_SIGVERIFY_RSA_KEY_EN` item in the [OTP](otp-mmap) can be used to invalidate a key at
+manufacturing time. This item consists of several little-endian 32-bit words. Each word contains four 8-bit hardened booleans
+(see `hardened_byte_bool_t` in `hardened.h`) that specifies whether the key is valid (`kHardenedByteBoolTrue`)
+or invalid (any value other that `kHardenedByteBoolTrue`). In order to verify that the key slot `i` contains
+a valid key, the `ROM` will:
+
+* read the `floor(i / 4)`-th word in `CREATOR_SW_CFG_SIGVERIFY_RSA_KEY_EN`,
+* extract the `(i % 4)`-th boolean from that word (the lower 8 bits correspond to the 0-th boolean and so on),
+* compare it to `kHardenedByteBoolTrue`.
+
# Terminology Quick Reference
## OpenTitan Logical Entities
@@ -191,6 +210,7 @@
[key-manager]: ../../../../hw/ip/keymgr/README.md
[manifest-format]: ../../../../sw/device/silicon_creator/rom_ext/doc/manifest.md
[rom-epmp]: ../../../../sw/device/silicon_creator/rom/doc/memory_protection.md
+[otp-mmap]: ../../../../hw/ip/otp_ctrl/README.md#direct-access-memory-map
[ot-flash]: #
[ot-unlock-flow]: #
[ownership-transfer]: ../ownership_transfer/README.md
