Basic configurations for PAL porting

This document describes the basic configuration of each PAL module, as well as default settings for various platforms. These basic configurations are the minimum required implementation to compile on your device.

Note: This document does not replace the full porting guide.

Security

Hardware Root of Trust (RoT)

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

• When set to 1, PAL uses the hardware RoT.

  • PAL fetches the RoT from the hardware with the pal_plat_osGetRoTFromHW(uint8_t * key,size_t keyLenBytes) function.
  • The RoT can't be injected to the device using factory configurator client (FCC).

• When set to 0, the RoT can be:

  • Generated by the platform's software random generator.
  • Injected to the device using factory configurator client (FCC). See the FCC documentation for more details.

  Note: If the RoT is not hardware-generated, the Trusted Internal Storage feature must be enabled to meet security requirements.

Internal flash configuration for security purposes

Note: You must not erase, modify, or overwrite these configurations when flashing a binary file to the device, whether during manufacturing or an upgrade procedure.

PAL_USE_INTERNAL_FLASH: Defines whether an internal flash exists on the platform controller. Default value: 1. You must define PAL_USE_INTERNAL_FLASH to use the following defines:

• PAL_INTERNAL_FLASH_NUM_#_SECTIONS: The number of sections allocated for security usage. Set to 0 if there are no available sections on the internal flash. Default value: 2. Maximum value: 2.
• PAL_INTERNAL_FLASH_SECTION_#_ADDRESS: The starting address for each section number (#) for security usage. The minimal size is 1 KiB per section.
  • If the size of a section is larger than a single sector size, the section must occupy consecutive sectors.
  • Set to 0 if there are no sections on the internal flash.
• PAL_INTERNAL_FLASH_SECTION_#_SIZE: The size of each section.
  • Set to 0 if there are no sections on the internal flash.

True random number generator (TRNG)

PAL_USE_HW_TRNG: Defines whether PAL uses hardware TRNG. Default Value: 1.

• When set to 0, entropy can be:

  • Injected to the device using factory configurator client (FCC). See the FCC documentation for more details.

  • Implemented under a software component and set on the device using the factory configurator client (FCC) API.

The following is a reference implementation that shows how to inject entropy directly through the application. It's a useful feature for quick development, but must not be used for production.

// These entropy values are example only. You must generate your own entropy values.

#define FCC_ENTROPY_SIZE   48
const uint8_t MBED_CLOUD_DEV_ENTROPY[FCC_ENTROPY_SIZE] = { 0xf6, 0xd6, 0xc0, 0x09, 0x9e, 0x6e, 0xf2, 0x37, 0xdc, 0x29, 0x88, 0xf1, 0x57, 0x32, 0x7d, 0xde, 0xac, 0xb3, 0x99, 0x8c, 0xb9, 0x11, 0x35, 0x18, 0xeb, 0x48, 0x29, 0x03, 0x6a, 0x94, 0x6d, 0xe8, 0x40, 0xc0, 0x28, 0xcc, 0xe4, 0x04, 0xc3, 0x1f, 0x4b, 0xc2, 0xe0, 0x68, 0xa0, 0x93, 0xe6, 0x3a };

   int status = fcc_entropy_set(MBED_CLOUD_DEV_ENTROPY, FCC_ENTROPY_SIZE);

Note: If the RoT is not hardware-generated, the Trusted Internal Storage feature must be enabled to meet security requirements.

File System

To port the File System module properly, note the following:

1. The chosen File System library may support multiple partitions and format functionality for redundancy purposes.
2. PAL_NUMBER_OF_PARTITIONS - defines the number of partitions created on the storage platform attached to the device.
3. PAL_FS_MOUNT_POINT_PRIMARY and PAL_FS_MOUNT_POINT_SECONDARY - defines the location of the mount point, for the primary and the secondary partitions respectively.
4. PAL_PRIMARY_PARTITION_PRIVATE and PAL_SECONDARY_PARTITION_PRIVATE - define whether the partition is dedicated to the client application. When set to true, you cannot store your data in the partition; otherwise, the partition is for public use.

For more information, see the Filesystem section in the porting guide.

Mbed OS

You can find an example of mounting and BlockDevice code in the FileSystemInit.c file under the initSDcardAndFileSystem() function.

Linux

You can find an example of mounting code in the FileSystemInit.c file under the fileSystemCreateRootFolders function.

Network

To port the Network module correctly, note the following:

• In every system, provide PAL with a network interface context. See the NetworkInit.c file for information for each system.

• You must configure a unique MAC address for each device.

• The Network library must support:

  • DNS.
  • TCP keepalive.
  • Send and receive timeout.
  • Loop back.

For more information, see the Networking section in the porting guide.

RTOS

PAL_USE_HW_RTC defines whether PAL uses a hardware real-time clock (RTC). Default value: 1. If the RTC has a backup battery, you must enable the (RTC) module at startup in board initialization.

See the boardInit.c file and the RTOS section of the porting guide for more information.

Default security configuration in reference devices

Minimum configuration settings

These minimum configuration settings are required to meet the security requirements, and are enforced during the compilation of the mbed-client-pal project.

Note: Mbed OS does not support PAL_USE_INTERNAL_FLASH=1.

FRDM-K64F

ODIN-W2 and NUCLEO-F429ZI

NUCLEO-F411RE