RoT

Module scope

The Root of Trust (RoT) is a secret key that the secure storage uses to encrypt data on the target.

Your target uses one of two secure storage types:

• The target's secure storage.
• Device Management Client's secure storage - if the target does not have its own secure storage.

The pal_plat_rot.h header declares the RoT functions.

You must implement the relevant RoT functions based on your secure storage type and RoT configuration, as detailed in the Porting notes section below.

You must port the RoT module regardless of which secure storage type you use.

Prerequisites for this porting stage

For a successful port, the target must have a random number generator source.

Porting result

After successfully porting the RoT module, all PAL RoT tests need to pass. Please see the Tests section for more information.

Porting notes

This section covers non-trivial functionality that the target needs for a successful port.

RoT configuration

PAL_USE_HW_ROT: Defines whether PAL uses the hardware RoT. Default value: 1.

Porting for various secure storage types

Below is a detailed explanation about which module functions you must port for each of the secure storage types.

Device Management Client's secure storage

If the target uses Device Management Client's secure storage:

• If the target does not have a hardware RoT (PAL_USE_HW_ROT is set to 0), porting is not required.
• If the target has a hardware RoT ()PAL_USE_HW_ROT is set to 1):
  • Implement pal_plat_osGetRoTFromHW - This function gets the RoT key to the keyBuf out buffer.

    palStatus_t pal_plat_osGetRoTFromHW(uint8_t *keyBuf, size_t keyLenBytes);
    

    The size of the keyLenBytes buffer must be exactly 128 bits (16 bytes).
  • Compile the Source/Port/Reference-Impl/Generic/ROT/External/pal_plat_rot_hw.c file, which implements the pal_plat_osGetRoT function and calls pal_plat_osGetRoTFromHW.
  • You do not have to port pal_plat_osSeTRoT.

Target's secure storage

If the target has its own secure storage, you must implement the following functions:

• If the target does not have a hardware RoT (PAL_USE_HW_ROT is set to 0), implement:

  • pal_plat_osGetRoT - This function gets the RoT to the keyBuf out buffer.

    palStatus_t pal_plat_osGetRoT(uint8_t *keyBuf, size_t keyLenBytes);
    

    The size of the keyLenBytes buffer must be exactly 128 bits (16 bytes).

  • pal_plat_osSeTRoT - This function sets an RoT key.

    palStatus_t pal_plat_osSetRoT(uint8_t *keyBuf, size_t keyLenBytes);
    

    The size of the key must be exactly 128 bits (16 bytes).

• If the target has a hardware RoT (PAL_USE_HW_ROT is set to 1):

  • Implement pal_plat_osGetRoTFromHW - This function gets the RoT key to the keyBuf out buffer.

    palStatus_t pal_plat_osGetRoTFromHW(uint8_t *keyBuf, size_t keyLenBytes);
    

    The size of the keyLenBytes buffer must be exactly 128 bits (16 bytes).

  • Compile the Source/Port/Reference-Impl/Generic/ROT/External/pal_plat_rot_hw.c, which implements the pal_plat_osGetRoT function and calls pal_plat_osGetRoTFromHW.

  • You do not have to port pal_plat_osSeTRoT.

Reference implementations

PAL provides reference implementations for the following targets and operating systems:

Mbed OS

• Main generic RoT functionality: pal_plat_rot.cpp.
  Located in the Source/Port/Reference-Impl/OS_Specific/mbedOS/ROT folder.