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).
- PAL fetches the RoT from the hardware with the
-
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 to0
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.
- Set to
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:
- The chosen File System library may support multiple partitions and format functionality for redundancy purposes.
PAL_NUMBER_OF_PARTITIONS
- defines the number of partitions created on the storage platform attached to the device.PAL_FS_MOUNT_POINT_PRIMARY
andPAL_FS_MOUNT_POINT_SECONDARY
- defines the location of the mount point, for the primary and the secondary partitions respectively.PAL_PRIMARY_PARTITION_PRIVATE
andPAL_SECONDARY_PARTITION_PRIVATE
- define whether the partition is dedicated to the client application. When set totrue
, 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.
Number of flash areas | 0 | 1 | 2 |
---|---|---|---|
PAL_USE_INTERNAL_FLASH |
1 |
1 |
1 |
PAL_USE_HW_ROT |
1 |
0 /1 |
0 /1 |
PAL_USE_HW_RTC |
1 |
1 |
0 /1 |
PAL_USE_HW_TRNG |
1 |
1 |
1 |
Note: Mbed OS does not support PAL_USE_INTERNAL_FLASH=1
.
FRDM-K64F
Definition | Default value | Notes |
---|---|---|
PAL_USE_INTERNAL_FLASH |
1 |
|
PAL_INT_FLASH_NUM_SECTIONS |
2 |
|
PAL_INTERNAL_FLASH_SECTION_1_ADDRESS |
0xFE000 |
|
PAL_INTERNAL_FLASH_SECTION_2_ADDRESS |
0xFF000 |
|
PAL_INTERNAL_FLASH_SECTION_1_SIZE |
0x1000 |
|
PAL_INTERNAL_FLASH_SECTION_2_SIZE |
0x1000 |
|
PAL_USE_HW_RTC |
0 |
Set to 1 only if a backup battery is connected. |
PAL_USE_HW_ROT |
0 |
Set to 1 only after implementing reading the RoT from a hardware function. |
PAL_USE_HW_TRNG |
1 |
Set to 1 only after implementing hardware TRNG. |
ODIN-W2 and NUCLEO-F429ZI
Definition | Default value | Notes |
---|---|---|
PAL_USE_INTERNAL_FLASH |
1 |
|
PAL_INT_FLASH_NUM_SECTIONS |
2 |
|
PAL_INTERNAL_FLASH_SECTION_1_ADDRESS |
0x080C0000 |
|
PAL_INTERNAL_FLASH_SECTION_2_ADDRESS |
0x080E0000 |
|
PAL_INTERNAL_FLASH_SECTION_1_SIZE |
0x20000 |
|
PAL_INTERNAL_FLASH_SECTION_2_SIZE |
0x20000 |
|
PAL_USE_HW_RTC |
0 |
Set to 1 only if a backup battery is connected. |
PAL_USE_HW_ROT |
0 |
Set to 1 only after implementing reading the RoT from a hardware function. |
PAL_USE_HW_TRNG |
1 |
Set to 1 only after implementing hardware TRNG. |
NUCLEO-F411RE
Definition | Default value | Notes |
---|---|---|
PAL_USE_INTERNAL_FLASH |
1 |
|
PAL_INT_FLASH_NUM_SECTIONS |
2 |
|
PAL_INTERNAL_FLASH_SECTION_1_ADDRESS |
0x080C0000 |
|
PAL_INTERNAL_FLASH_SECTION_2_ADDRESS |
0x080E0000 |
|
PAL_INTERNAL_FLASH_SECTION_1_SIZE |
0x1000 |
|
PAL_INTERNAL_FLASH_SECTION_2_SIZE |
0x1000 |
|
PAL_USE_HW_RTC |
0 |
Set to 1 only if a backup battery is connected. |
PAL_USE_HW_ROT |
0 |
Set to 1 only after implementing reading the RoT from a hardware function. |
PAL_USE_HW_TRNG |
0 |
Cannot be set to 1 because the board doesn't have hardware TRNG. |