[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