KMU — Key management unit

Key management unit (KMU) is a component of the NVMC for secure key handling. KMU uses a subset of the flash referred to as user information configuration register (UICR) for its secure storage. This UICR subset can be used for both establishing a device root of trust (RoT) during chip and OEM manufacturing, and for storage and use of any device specific keys.

Access and use of information stored in UICR is controlled through the KMU. Even though the KMU and UICR are tightly coupled, they do not share a common memory map:

Figure 1. Memory map overview

The KMU is mapped as a stand-alone peripheral on the APB bus, while UICR is addressable on AHB and is located in flash memory map. Access to the KMU and keys stored in UICR is only allowed in secure mode. Access to the UICR memory map is equivalent to any other flash page access, except that the KMU will enforce usage and read/write restrictions to different regions of the UICR memory map depending on configuration.

For more information about the user information configuration registers, see chapter UICR — User information configuration registers.

Functional view

From a functional view UICR is divided into two different regions:
  • One-time programmable (OTP) memory
  • Key storage

OTP

One-time programmable (OTP) memory is typically used for holding values that are written once, and then never to be changed throughout the life-time of the product. 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 for a total of 128 keys to be addressable inside the key storage region.

Note: 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 the flash is enforced by a hardware finite-state machine (FSM). FSM can allow or block transactions depending both on the security of the transaction (secure or non-secure) and 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 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. KMU FSM operates on only one key slot instance at a time, and the permissions and 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 UICR content

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 UICR, the procedure require an implementation defined 32-bit word to be written into the UICR->ERASEPROTECT register.

In case of field return handling it is still possible to erase UICR even if 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 describe specific KMU and UICR behavior in more detail, in order to help the reader to get a better overview of its features and intended usage.

OTP

The OTP region of UICR contains 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' can be written.

An OTP write transaction must consist of a full 32-bit word. Both halfwords can either be written simultaneously or individually. The KMU FSM will block any write to a halfword in the OTP region if the initial value of this half-word is not 0xFFFF. When writing halfwords individually, the non-active halfword must be masked as 0xFFFF else the request will be blocked. I.e. writing 0x1234XXXX to an OTP destination address which already contain 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 AHB write transactions into the OTP region of UICR if the transaction is secure. 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 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, and 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 one key slot instance consists of one key header and an associated key value. Each key header supports 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 write-only key register of a HW cryptograhic 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 is 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 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 acccess 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 KMU->SELECTKEYSLOT must be set back to '0'.

By default all KMU key slots will consist of a 128 bit key value of '1', 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.

  1. 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.
  2. 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.
  3. Write the 128-bit key value into KEYSLOT.KEY[ID-1].VALUE[0-3].
  4. Write the desired key slot permissions into KEYSLOT.CONFIG[ID-1].PERM, including any applicable usage restrictions.
  5. 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 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 UICR is a three-step process:
  1. Select the key slot which the KMU shall operate on by writing the desired key slot ID into KMU->SELECTKEYSLOT.
  2. 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.
  3. 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 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 2. Tasks and events pattern for key slots
Figure: Tasks and events pattern for key slots

Pushing a key slot over secure APB is a four-step process:
  1. Select the key slot on which the KMU shall operate by writing the desired key slot ID into KMU->SELECTKEYSLOT
  2. 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
  3. After completing the secure APB transaction, the 128-bit key value is ready for use by the peripheral and EVENTS_KEYSLOT_PUSHED is triggered
  4. 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 key slots

All key slots within the key storage area can be marked as revoked by writing to the STATE field in the KEYSLOT.CONFIG[ID-1].PERM register. The following rules apply to keys that have been revoked:

  1. Key values that are not readable by the CPU, and thus depend on the tasks/events pattern to be used by a peripheral, can no longer be pushed. If a revoked key slot is selected and task TASKS_PUSH_KEYSLOT is started, the event EVENTS_KEYSLOT_REVOKED will be triggered.
  2. Key values that are readable by the CPU can have their revoke bit set in order to instruct the KMU to block future read requests for this key value. Any subsequent read operation to a revoked key value will return word 0xDEADDEAD.
  3. Published keys 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 used by a peripheral for cryptographic operations, the secure code need to reset the device and thus prevent the revoked key slot from being published again.

STATUS register

The KMU uses a KMU->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, this indicate that code is using the KMU incorrectly.

The KMU->STATUS register is reset every time register KMU->SELECTKEYSLOT is written.

Registers

Table 3. Instances
Base address Peripheral Instance Secure mapping DMA security Description Configuration

0x50039000
0x40039000

KMU

KMU : S
KMU : NS

SPLIT

NA

Key management unit

   
Table 4. Register overview
Register Offset Security Description
TASKS_PUSH_KEYSLOT 0x0000  

Push a key slot over secure APB

 
EVENTS_KEYSLOT_PUSHED 0x100  

Key successfully pushed over secure APB

 
EVENTS_KEYSLOT_REVOKED 0x104  

Key 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 ID 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 Access 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 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 Access Field Value ID Value Description
A RW

EVENTS_KEYSLOT_PUSHED

   

Key successfully pushed over secure APB

     

NotGenerated

0

Event not generated

     

Generated

1

Event generated

EVENTS_KEYSLOT_REVOKED

Address offset: 0x104

Key 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 Access Field Value ID Value Description
A RW

EVENTS_KEYSLOT_REVOKED

   

Key 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 Access 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 Access 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 Access 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 Access 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 Access 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 Access 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 ID 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 Access 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 ID. The 0 ID should be used when the KMU is idle or not in use

NOTE: Note that index N in UICR->KEYSLOT.KEY[N] and UICR->KEYSLOT.CONFIG[N] corresponds to KMU keyslot ID=N+1