Hardware unique key

This sample shows how to use a hardware unique key (HUK) to derive an encryption key through psa_crypto APIs.

Overview

The sample goes through the following steps to derive a key and use it to encrypt a string:

  1. Initializing the hardware, if applicable.

    When TF-M is enabled, the hardware is initialized automatically when booting.

  2. Generating HUKs, if applicable.

    The sample generates a random HUK and writes it to KMU or flash. When no KMU is present, the device reboots to allow the immutable bootloader to feed the key into CryptoCell. When TF-M is enabled, the HUKs are generated automatically when booting TF-M, and no action is needed in the sample.

  3. Generating a random initialization vector (IV).

  4. Deriving a key used for encryption.

    When TF-M is enabled, the key is derived using the psa_crypto APIs. Otherwise, the native nrf_cc3xx_platform APIs are used, and the key is imported into psa_crypto.

  5. Encrypting a sample string using the key_id received from the psa_crypto.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Build target

nRF5340 DK

PCA10095

nrf5340dk_nrf5340

nrf5340dk_nrf5340_cpuapp

nRF5340 DK

PCA10095

nrf5340dk_nrf5340

nrf5340dk_nrf5340_cpuapp_ns

nRF9160 DK

PCA10090

nrf9160dk_nrf9160

nrf9160dk_nrf9160

nRF9160 DK

PCA10090

nrf9160dk_nrf9160

nrf9160dk_nrf9160_ns

nRF52840 DK

PCA10056

nrf52840dk_nrf52840

nrf52840dk_nrf52840

Building and running

This sample can be found under samples/keys/hw_unique_key in the nRF Connect SDK folder structure.

See Building and programming an application for information about how to build and program the application.

Testing

After programming the sample to your development kit, test it by performing the following steps:

  1. Connect to the kit that runs this sample with a terminal emulator (for example, PuTTY). See How to connect with PuTTY for the required settings.

  2. Reset the kit.

  3. If not using TF-M, observe the following output:

    Writing random keys to KMU
    Success!
    
  4. Observe the following output (the values for IV, key, and ciphertext will vary randomly):

    Generating random IV
    IV:
    ab8e7c595d6de7d297a00b6c
    
    Deriving key
    Key:
    8d6e8ad32f5dffc10df1de38a2556ba0e01cf4ed56ac1294b9c57965cddc519a
    Key ID: 0x7fffffe0
    
    Encrypting
    Plaintext:
    "Lorem ipsum dolor sit amet. This will be encrypted."
    4c6f72656d20697073756d20646f6c6f722073697420616d65742e2054686973
    2077696c6c20626520656e637279707465642e
    Ciphertext (with authentication tag):
    ea696bf71e106f7c74adfc3296556f4f25ac2c999e453e28c52fb41085ef7b89
    3cbadee1a505cf3ce1901f4bc2fcca4fb86ec68e4b5f1344bb66ef5ce733f47a
    33788a
    

    If an error occurs, the sample will print a message and raise a kernel panic.

Dependencies

This sample uses the following libraries: