Zephyr Integration
Process
1. Setup files
Place zephyr-eiv-integration repository into your project's root directory.
You can place the integration files in custom locations, but please make sure to setup the correct path of the package
2. Import package in CMakeLists
Find following line in your project's CMakeLists.txt:
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
and replace it with the snippet below.
if a custom path was selected for the package, please make sure to set STERNUM_DIR with the correct path.
set(STERNUM_DIR ${CMAKE_CURRENT_LIST_DIR}/zephyr-eiv-integration)
include(${STERNUM_DIR}/post_build_setup.cmake)
find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
add_subdirectory(${STERNUM_DIR}/src)
target_include_directories( app PRIVATE
${STERNUM_DIR}/src/include
)
3. Setup Kconfig
Source Kconfig.sternum from Kconfig file in the project main directory.
If your project contains Kconfig file, source Sternum options among other configs, using following line:
rsource "zephyr-eiv-integration/Kconfig.sternum"
If your project doesn't contain a Kconfig file, create it with following content:
mainmenu "Sternum"
rsource "zephyr-eiv-integration/Kconfig.sternum"
source "Kconfig.zephyr"
if a custom path was selected for the package, please make sure to set the correct path in rsource.
Next, append the following definitions to your project prj.conf
CONFIG_STERNUM=y
CONFIG_STERNUM_ADS=y
CONFIG_STERNUM_PROTECTION=y
CONFIG_STERNUM_LOG_LEVEL_ERR=y
# Temporary ID. Please take your valid ID from ADS
CONFIG_STERNUM_DEVICE_DEFINITION_ID=1234
# Temporary non secure random generator.
CONFIG_TEST_RANDOM_GENERATOR=y
Please modify the configurations according to your needs. Documentation is available at Configuration
4. TF-M protection Setup
This part is relevant only if your projects adds out-of-tree tfm partitions.
Duplicated CMake properties are not handled correctly, so if you are adding your own secure tfm partitions, you are overwriting properties added by Sternum. It will result n Sternum partition not being added. To fix the issue extend TFM_EXTRA_MANIFEST_LIST_FILES and TFM_EXTRA_PARTITION_PATHS with Sternum defined variables: STERNUM_TFM_EXTRA_MANIFEST_LIST_FILES and STERNUM_TFM_EXTRA_PARTITION_PATHS (example below).
Please note a list must be enclosed in double quote and arguments separated by \\\;.
set_property(TARGET zephyr_property_target
APPEND PROPERTY TFM_CMAKE_OPTIONS
-DTFM_EXTRA_MANIFEST_LIST_FILES="${CMAKE_CURRENT_BINARY_DIR}/custom_partition/tfm_manifest_list.yaml\\\;${STERNUM_TFM_EXTRA_MANIFEST_LIST_FILES}"
-DTFM_EXTRA_PARTITION_PATHS="${CMAKE_CURRENT_LIST_DIR}/custom_partition\\\;${STERNUM_TFM_EXTRA_PARTITION_PATHS}"
)
Now, by simply compiling using west, you should be able to protect and import Sternum's observability SDK
5. Ports adaptations
Random number generation
Function sternum_port_generate_random_number defined in sternum_eiv\src\zephyr\ports\heap_protection_port.c is using responsible for generating secure random numbers.
If TFM is used, random numbers are generated by TFM.
If not, default implementation is using sys_rand_get provided by TEST_RANDOM_GENERATOR. This function is not returning a cryptographically secure random number value and should be replaced with secure random generation, i.e. with sys_csrand_get, when real random generator is available on the target project.
Device ID generation
Device ID must be unique for every device that share the same device definition. Possible implementations are for example, returning device serial number or unique random number.
Network transmission implementation
In order to send traces to ADS, it is required to implement porting functions ( please see
/src/zephyr/ports/user_port.c and src/include/ports/user_abstract_api.h).
Specifically, sternum_port_network_write_all(const void *buf, size_t count) ,should send https
requests with binary data to https://sternum-gateway.sternum.cloud/v1/trace
Here are the needed HTTP headers:
POST /v1/trace HTTP/1.1
Host: sternum-gateway.sternum.cloud
Content-Type: application/octet-stream
Customizing the Attack Handler
It's possible to customize the attack handler using the following KConfig: CONFIG_STERNUM_PERMISSIVE_SECURITY_RESPONSE
If you'd like to performance advanced customization to the attack handler, please modify sternum_port_security_alert
in system_port.c
6. Adjust configurations
FLASH layout setup
Following features are performing read/write operations in flash memory:
CONFIG_STERNUM_PROTECTION_TFM_REPORTINGCONFIG_STERNUM_CRASH_DUMP
To use these features project must provide a valid flash memory configuration for Sternum module. This must be done with the use of the settings:
CONFIG_STERNUM_FLASH_AREA_OFFSETCONFIG_STERNUM_FLASH_AREA_SIZE
To configure it properly you must reach out to your hardware flash layout, which usually may be found in flash_layout.h file specified for your hardware (i.e. for NRF5340 this file can be found in modules\tee\tf-m\trusted-firmware-m\platform\ext\target\nordic_nrf\common\nrf5340\partition\flash_layout.h).
Both CONFIG_STERNUM_FLASH_AREA_OFFSET and CONFIG_STERNUM_FLASH_AREA_SIZE must be flash page size aligned. For NRF5340 the page size is 0x1000.
/* Sector size of the embedded flash hardware (erase/program) */
#define FLASH_AREA_IMAGE_SECTOR_SIZE (0x1000) /* 4 KB. Flash memory program/erase operations have a page granularity. */
For CONFIG_STERNUM_FLASH_AREA_OFFSET choose the offset belonging to flash area which is available for Non-secure image and is not already used by your application. For NRF5340 Application MCU with BL2 the STERNUM_FLASH_AREA_OFFSET can be set to the beginning of Non-secure image secondary area
which is 0x000c000 or this value may be shifted by multiplications of FLASH_AREA_IMAGE_SECTOR_SIZE.
/* Flash layout on NRF5340 Application MCU with BL2:
*
* 0x0000_0000 BL2 - MCUBoot (64 KB)
* 0x0001_0000 Primary image area (448 KB):
* 0x0001_0000 Secure image primary (256 KB)
* 0x0005_0000 Non-secure image primary (192 KB)
* 0x0008_0000 Secondary image area (448 KB):
* 0x0008_0000 Secure image secondary (256 KB)
* 0x000c_0000 Non-secure image secondary (192 KB)
* 0x000f_0000 Protected Storage Area (16 KB)
* 0x000f_4000 Internal Trusted Storage Area (8 KB)
* 0x000f_6000 OTP / NV counters area (8 KB)
* 0x000f_8000 Non-secure storage, used when built with NRF_NS_STORAGE=ON,
* otherwise unused (32 KB)
*/
CONFIG_STERNUM_FLASH_AREA_SIZE must be flash page size aligned and meet minimum size requirements:
16bytes allocated forCONFIG_STERNUM_PROTECTION_TFM_REPORTING512bytes allocated forCONFIG_STERNUM_CRASH_DUMP.
Knowledge
Configuration
For more details about EIV KConfig options, please refer to Kconfig.sternum.