KMU — Key management unit

The key management unit (KMU) enforces access policies to a subset region of user information configuration register (UICR). This subset region is used for storing cryptographic key values inside the key slots, which the CPU has no access to.

In total there are 128 key slots available, where each key slot can store one 128-bit key value together with an access policy and a destination address for the key value. Multiple key slots can be combined in order to support key sizes larger than 128 bits. The access policy of a key slot governs if and how a key value can be used, while the destination address determines where in the memory map the KMU pushes the key value upon a request from the CPU.

Key slots can be configured to be pushed directly into write-only key registers in cryptographic accelerators, like e.g. CryptoCell, without exposing the key value itself to the CPU. This enables the CPU to use the key values stored inside the key slots for cryptographic operations without being exposed to the key value.

Access to the KMU, and the key slots in the UICR, is only allowed from secure mode.

Functional view

From a functional view the UICR is divided into two different regions, one-time programmable (OTP) memory and key storage.

OTP

One-time programmable (OTP) memory is typically used for holding values that are written once, and then never to be changed again throughout the product lifetime. The OTP region of UICR is emulated by placing a write-once per halfword limitation on registers defined here.

Key storage

The key storage region contains multiple key slots, where each slot consists of a key header and an associated key value. The key value is limited to 128 bits. Any key size greater than 128 bits must be divided and distributed over multiple key slot instances.

Key headers are allocated an address range of 0x400 in the UICR memory map, allowing a total of 128 keys to be addressable inside the key storage region.

Note: The use of the key storage region in UICR should be limited to keys with a certain life span, and not per-session derived keys where the CPU is involved in the key exchange.

Access control

Access control to the underlying UICR infopage in flash is enforced by a hardware finite-state machine (FSM). The FSM can allow or block transactions, depending both on the security of the transaction (secure or non-secure) and on the type of register being written and/or read.

Table 1. Access control
Access type	Key headers	Key values
Read	Allowed	Restricted
Write	Restricted	Restricted

Any restricted access requires an explicit key slot selection through the KMU register interface. Any illegal access to restricted key slot registers will be blocked and word 0xDEADDEAD will be returned on the AHB.

The OTP region has individual access control behavior, while access control to the key storage region is configured on a per key slot basis. The KMU FSM operates on only one key slot instance at a time, and the permissions and the usage restriction for a key value associated with a key slot can be configured individually.

Note: Even if the KMU can be configured as non-secure, all non-secure transactions will be blocked.

Protecting the UICR content

The UICR content can be protected against device-internal NVMC.ERASEALL requests, in addition to device-external ERASEALL requests, through the CTRL-AP interface. This feature is useful if the firmware designers want to prevent the OTP region from being erased.

Since enabling this step will permanently disable erase for the UICR, the procedure requires an implementation defined 32-bit word to be written into the UICR's ERASEPROTECT register.

In case of a field return handling, it is still possible to erase the UICR even if the ERASEPROTECT is set. If this functionality is desired, the secure boot code must implement a secure communication channel over the CTRL-AP mailbox interface. Upon successful authentication of the external party, the secure boot code can temporarily re-enable the CTRL-AP ERASEALL functionality.

Usage

This section describes the specific KMU and UICR behavior in more detail, to help the reader get a better overview of KMU's features and the intended usage.

OTP

The OTP region of the UICR contains a user-defined static configuration of the device. The KMU emulates the OTP functionality by placing a write-once per halfword limitation of registers defined in this region, i.e. only halfwords containing all '1's can be written.

An OTP write transaction must consist of a full 32-bit word. Both halfwords can either be written simultaneously or one at a time. The KMU FSM will block any write to a halfword in the OTP region, if the initial value of this halfword is not 0xFFFF. When writing halfwords one at a time, the non-active halfword must be masked as 0xFFFF, otherwise the request will be blocked. For example, writing 0x1234XXXX to an OTP destination address which already contains the value 0xFFFFAABB, must be configured as 0x1234FFFF. The OTP destination address will contain the value 0x1234AABB after both write transactions have been processed.

The KMU will also only allow secure AHB write transactions into the OTP region of the UICR. Any AHB write transaction to this region that does not satisfy the above requirements will be ignored, and the STATUS.BLOCKED register will be set to '1'.

Key storage

The key storage region of the UICR can contain multiple keys of different type, including symmetrical keys, hashes, public/private key pairs and other device secrets. One of the key features of the KMU, is that these device secrets can be installed and made available for use in cryptographic operations without revealing the actual secret values.

Keys in this region will typically have a certain life span. The region is not designed to be used for per-session derived keys where the non-secure side (i.e. application) is participating in the key exchange.

All key storage is done through the concept of multiple key slots, where each key slot instance consists of one key header and an associated key value. Each key header supports the configuration of usage permissions and an optional secure destination address.

The key header secure destination address option enables the KMU to push the associated key value over a dedicated secure APB to a pre-configured secure location within the memory map. Such locations typically include a write-only key register of the hardware cryptographic accelerator, allowing the KMU to distribute keys within the system without compromising the key values.

One key slot instance can store a key value of maximum 128 bits. If a key size exceeds this limit, the key value itself must be split over multiple key slot instances.

The following usage and read permissions scheme is applicable for each key slot:

Table 2. Valid key slot permission schemes
State	Push	Read	Write	Description
Active (1)	Enabled (1)	Enabled (1)	Enabled (1)	Default flash erase value. Key slot cannot be pushed, write is enabled.
Active (1)	Enabled (1)	Enabled (1)	Disabled (0)	Key slot is active, push is enabled. Key slot VALUE registers can be read, but write is disabled.
Active (1)	Enabled (1)	Disabled (0)	Disabled (0)	Key slot is active, push is enabled. Read and write to key slot VALUE registers are disabled.
Active (1)	Disabled (0)	Enabled (1)	Disabled (0)	Key slot is active, push is disabled. Key slot VALUE registers can be read, but write is disabled.
Revoked (0)	-	-	-	Key slot is revoked. Cannot be read or pushed over secure APB regardless of the permission settings.

Selecting a key slot

The KMU FSM is designed to process only one key slot at a time, effectively operating as a memory protection unit for the key storage region. Whenever a key slot is selected, the KMU will allow access to writing, reading, and/or pushing the associated key value according to the selected slot configuration.

A key slot must be selected prior to use, by writing the key slot ID into the KMU SELECTKEYSLOT register. Because the reset value of this register is 0x00000000, there is no key slot associated with ID=0 and no slot is selected by default. All key slots are addressed using IDs from 1 to 128.

SELECTED status is set when a key slot is selected, and a read or write access to that keyslot occurs.

BLOCKED status is set when any illegal access to key slot registers is detected.

When the use of the particular key slot is stopped, the key slot selection in SELECTKEYSLOT must be set back to '0'.

By default, all KMU key slots will consist of a 128-bit key value of '1's, where the key headers have no secure destination address, or any usage and read restrictions.

Writing to a key slot

Writing a key slot into UICR is a five-step process.

Select which key slot the KMU shall operate on by writing the desired key slot ID into KMU->SELECTKEYSLOT. The selected key slot must be empty in order to add a new entry to UICR.
If the key value shall be pushable over secure APB, the destination address of the recipient must be configured in register KEYSLOT.CONFIG[ID-1].DEST.
Write the 128-bit key value into KEYSLOT.KEY[ID-1].VALUE[0-3].
Write the desired key slot permissions into KEYSLOT.CONFIG[ID-1].PERM, including any applicable usage restrictions.
Select key slot 0.

In case the total key size is greater than 128 bits, the key value itself must be split into 128-bit segments and written to multiple key slot instances. Steps 1 through 5 above must be repeated for the entire key size.

Note: If a key slot is configured as readable, and KEYSLOT.CONFIG[ID-1].DEST is not to be used, it is recommended to disable the push bit in KEYSLOT.CONFIG[ID-1].PERM when configuring key slot permissions.

Note: A key value distributed over multiple key slots should use the same key slot configuration in its key headers, but the secure destination address for each key slot instance must be incremented by 4 words (128 bits) for each key slot instance spanned.

Note: Write to flash must be enabled in NVMC->CONFIG prior to writing keys to flash, and subsequently disabled once writing is complete.

Steps 1 through 5 above will be blocked if any of the following violations are detected:

No key slot selected
Non-empty key slot selected
NVM destination address not empty
AHB write to KEYSLOT.KEY[ID-1].VALUE[0-3] registers not belonging to selected key slot

Reading a key value

Key slots that are configured as readable can have their key value read directly from the UICR memory map by the CPU.

Readable keys are typically used during the secure boot sequence, where the CPU is involved in falsifying or verifying the integrity of the system. Since the CPU is involved in this decision process, it makes little sense not to trust the CPU having access to the actual key value but ultimately trust the decision of the integrity check. Another use-case for readable keys is if the key type in question does not have a HW peripheral in the platform that is able to accept such keys over secure APB.

Reading a key value from the UICR is a three-step process:

Select the key slot which the KMU shall operate on by writing the desired key slot ID into KMU->SELECTKEYSLOT.
If STATE and READ permission requirements are fulfilled as defined in KEYSLOT.CONFIG[ID-1].PERM, the key value can be read from region KEYSLOT.KEY[ID-1].VALUE[0-3] for selected key slot.
Select key slot 0.

Step 2 will be blocked and word 0xDEADDEAD will be returned on AHB if any of the following violations are detected:

No key slot selected
Key slot not configured as readable
Key slot is revoked
AHB read to KEYSLOT.KEY[ID-1].VALUE[0-3] registers not belonging to selected key slot

Push over secure APB

Key slots that are configured as non-readable cannot be read by the CPU regardless of the mode the system is in and must be pushed over secure APB in order to use the key value for cryptographic operations.

The secure APB destination address is set in the key slot configuration DEST register. Such destination addresses are typically write-only key registers in a hardware cryptographic accelerators memory map. The secure APB allows key slots to be utilized by the software side, without exposing the key value itself.

Figure: Tasks and events pattern for key slots — Figure 2. Tasks and events pattern for key slots

Pushing a key slot over secure APB is a four-step process:

Select the key slot on which the KMU shall operate by writing the desired key slot ID into KMU->SELECTKEYSLOT.
Start TASKS_PUSH_KEYSLOT to initiate a secure APB transaction, writing the 128-bit key value associated with the selected key slot into address defined in KEYSLOT.CONFIG[ID-1].DEST.
After completing the secure APB transaction, the 128-bit key value is ready for use by the peripheral and EVENTS_KEYSLOT_PUSHED is triggered.
Select key slot 0.

Note: If a key value is distributed over multiple key slots due to its key size, exceeding the maximum 128-bit key value limitation, then each distributed key slot must be pushed individually in order to transfer the entire key value over secure APB.

Step 3 will trigger other events than EVENTS_KEYSLOT_PUSHED if the following violations are detected:

EVENTS_KEYSLOT_ERROR:
- If no key slot is selected
- If a key slot has no destination address configured
- If when pushing a key slot, flash, or peripheral returns an error
- If pushing a key slot when push permissions are disabled
- If attempting to push a key slot with default permissions
EVENTS_KEYSLOT_REVOKED if a key slot is marked as revoked in its key header configuration

Revoking the key slots

All key slots within the key storage area can be marked as revoked.

To revoke any key slots, write to the STATE field in the KEYSLOT.CONFIG[ID-1].PERM register. The following rules apply to keys that have been revoked:

Key slots that have the PUSH field enabled in PERM register can no longer be pushed. If a revoked key slot is selected and task TASKS_PUSH_KEYSLOT is started, the event EVENTS_KEYSLOT_REVOKED is triggered.
Key slots that have the READ field enabled in PERM register can no longer be read. Any read operation to a revoked key value will return word 0xDEADDEAD.
Previously pushed key values stored in a peripheral write-only key register are not affected by key revocation. If secure code wants to enforce that a revoked key is no longer usable by a peripheral for cryptographic operations, the secure code should disable or reset the peripheral in question.

STATUS register

The KMU uses a STATUS register to indicate its status of operation. The SELECTED bit will be asserted whenever the currently selected key slot is successfully read from or written to.

All read or write operations to other key slots than what is currently selected in KMU->SELECTKEYSLOT will assert the BLOCKED bit. The BLOCKED bit will also be asserted if the KMU fails to select a key slot, or if a request has been blocked due to an access violation. Normal operation using the KMU should never trigger the BLOCKED bit. If this bit is triggered during the development phase, it indicates that the code is using the KMU incorrectly.

The STATUS register is reset every time register SELECTKEYSLOT is written.

Registers

Instances


Instance	Base address	TrustZone			Split access	Description
Instance	Base address	Map	Att	DMA	Split access	Description
KMU : S KMU : NS	0x50039000 0x40039000	HF	NS	NA	Yes	Key management unit

Register overview


Register	Offset	Description
TASKS_PUSH_KEYSLOT	0x0000	Push a key slot over secure APB
EVENTS_KEYSLOT_PUSHED	0x100	Key slot successfully pushed over secure APB
EVENTS_KEYSLOT_REVOKED	0x104	Key slot has been revoked and cannot be tasked for selection
EVENTS_KEYSLOT_ERROR	0x108	No key slot selected, no destination address defined, or error during push operation
INTEN	0x300	Enable or disable interrupt
INTENSET	0x304	Enable interrupt
INTENCLR	0x308	Disable interrupt
INTPEND	0x30C	Pending interrupts
STATUS	0x40C	Status bits for KMU operation
SELECTKEYSLOT	0x500	Select key slot to be read over AHB or pushed over secure APB when TASKS_PUSH_KEYSLOT is started

TASKS_PUSH_KEYSLOT

Address offset: 0x0000

Push a key slot over secure APB


Bit number				31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
ID																																			A
Reset 0x00000000				0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
ID	R/W	Field	Value ID	Value								Description
A	W	TASKS_PUSH_KEYSLOT										Push a key slot over secure APB
			Trigger	1								Trigger task

EVENTS_KEYSLOT_PUSHED

Address offset: 0x100

Key slot successfully pushed over secure APB


Bit number				31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
ID																																			A
Reset 0x00000000				0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
ID	R/W	Field	Value ID	Value								Description
A	RW	EVENTS_KEYSLOT_PUSHED										Key slot successfully pushed over secure APB
			NotGenerated	0								Event not generated
			Generated	1								Event generated

EVENTS_KEYSLOT_REVOKED

Address offset: 0x104

Key slot has been revoked and cannot be tasked for selection


Bit number				31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
ID																																			A
Reset 0x00000000				0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
ID	R/W	Field	Value ID	Value								Description
A	RW	EVENTS_KEYSLOT_REVOKED										Key slot has been revoked and cannot be tasked for selection
			NotGenerated	0								Event not generated
			Generated	1								Event generated

EVENTS_KEYSLOT_ERROR

Address offset: 0x108

No key slot selected, no destination address defined, or error during push operation


Bit number				31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
ID																																			A
Reset 0x00000000				0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
ID	R/W	Field	Value ID	Value								Description
A	RW	EVENTS_KEYSLOT_ERROR										No key slot selected, no destination address defined, or error during push operation
			NotGenerated	0								Event not generated
			Generated	1								Event generated

INTEN

Address offset: 0x300

Enable or disable interrupt


Bit number				31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
ID																																	C	B	A
Reset 0x00000000				0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
ID	R/W	Field	Value ID	Value								Description
A	RW	KEYSLOT_PUSHED										Enable or disable interrupt for event KEYSLOT_PUSHED
			Disabled	0								Disable
			Enabled	1								Enable
B	RW	KEYSLOT_REVOKED										Enable or disable interrupt for event KEYSLOT_REVOKED
			Disabled	0								Disable
			Enabled	1								Enable
C	RW	KEYSLOT_ERROR										Enable or disable interrupt for event KEYSLOT_ERROR
			Disabled	0								Disable
			Enabled	1								Enable

INTENSET

Address offset: 0x304

Enable interrupt


Bit number				31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
ID																																	C	B	A
Reset 0x00000000				0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
ID	R/W	Field	Value ID	Value								Description
A	RW	KEYSLOT_PUSHED										Write '1' to enable interrupt for event KEYSLOT_PUSHED
			Set	1								Enable
			Disabled	0								Read: Disabled
			Enabled	1								Read: Enabled
B	RW	KEYSLOT_REVOKED										Write '1' to enable interrupt for event KEYSLOT_REVOKED
			Set	1								Enable
			Disabled	0								Read: Disabled
			Enabled	1								Read: Enabled
C	RW	KEYSLOT_ERROR										Write '1' to enable interrupt for event KEYSLOT_ERROR
			Set	1								Enable
			Disabled	0								Read: Disabled
			Enabled	1								Read: Enabled

INTENCLR

Address offset: 0x308

Disable interrupt


Bit number				31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
ID																																	C	B	A
Reset 0x00000000				0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
ID	R/W	Field	Value ID	Value								Description
A	RW	KEYSLOT_PUSHED										Write '1' to disable interrupt for event KEYSLOT_PUSHED
			Clear	1								Disable
			Disabled	0								Read: Disabled
			Enabled	1								Read: Enabled
B	RW	KEYSLOT_REVOKED										Write '1' to disable interrupt for event KEYSLOT_REVOKED
			Clear	1								Disable
			Disabled	0								Read: Disabled
			Enabled	1								Read: Enabled
C	RW	KEYSLOT_ERROR										Write '1' to disable interrupt for event KEYSLOT_ERROR
			Clear	1								Disable
			Disabled	0								Read: Disabled
			Enabled	1								Read: Enabled

INTPEND

Address offset: 0x30C

Pending interrupts


Bit number				31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
ID																																	C	B	A
Reset 0x00000000				0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
ID	R/W	Field	Value ID	Value								Description
A	R	KEYSLOT_PUSHED										Read pending status of interrupt for event KEYSLOT_PUSHED
			NotPending	0								Read: Not pending
			Pending	1								Read: Pending
B	R	KEYSLOT_REVOKED										Read pending status of interrupt for event KEYSLOT_REVOKED
			NotPending	0								Read: Not pending
			Pending	1								Read: Pending
C	R	KEYSLOT_ERROR										Read pending status of interrupt for event KEYSLOT_ERROR
			NotPending	0								Read: Not pending
			Pending	1								Read: Pending

STATUS

Address offset: 0x40C

Status bits for KMU operation

This register is reset and re-written by the KMU whenever SELECTKEYSLOT is written


Bit number				31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
ID																																		B	A
Reset 0x00000000				0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
ID	R/W	Field	Value ID	Value								Description
A	R	SELECTED										Key slot ID successfully selected by the KMU
			Disabled	0								No key slot ID selected by KMU
			Enabled	1								Key slot ID successfully selected by KMU
B	R	BLOCKED										Violation status
			Disabled	0								No access violation detected
			Enabled	1								Access violation detected and blocked

SELECTKEYSLOT

Address offset: 0x500

Select key slot to be read over AHB or pushed over secure APB when TASKS_PUSH_KEYSLOT is started


Bit number				31	30	29	28	27	26	25	24	23	22	21	20	19	18	17	16	15	14	13	12	11	10	9	8	7	6	5	4	3	2	1	0
ID																												A	A	A	A	A	A	A	A
Reset 0x00000000				0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0
ID	R/W	Field	Value ID	Value								Description
A	RW	ID										Select key slot ID to be read over AHB, or pushed over secure APB, when TASKS_PUSH_KEYSLOT is started. NOTE: ID=0 is not a valid key slot ID. The 0 ID should be used when the KMU is idle or not in use. NOTE: Index N in UICR->KEYSLOT.KEY[N] and UICR->KEYSLOT.CONFIG[N] corresponds to KMU key slot ID=N+1.