Secure Services

Secure Services are functions implemented in the Secure Firmware (Secure Partition Manager), but made available to be called from the Non-Secure Firmware.

Calling functions in this API requires that the service is enabled in the Secure Partition Manager. See CONFIG_SPM_SECURE_SERVICES in the Secure Partition Manager’s menuconfig. Some services are enabled by default.

By default CONFIG_SPM_BLOCK_NON_SECURE_RESET is disabled. This is to make sure that your debugger will be able to issue a system reset during the development stage and that devices which do not have pin-reset routed can do a re-flashing routine correctly. This option should be turned off when you are putting a product into production to increase the security of your device.

API documentation

Header file: include/secure_services.h
Source file: subsys/spm/secure_services.c (compiled into the Secure Partition Manager)
group secure_services

Secure services available to the Non-Secure Firmware.

The Secure Services provide access to functionality controlled by the Secure Firmware.

Defines

NRF_NSE(ret, name, ...)

Implement a wrapper function around a secure_service.

This function must reside in the non-secure binary. It makes the secure service thread safe by locking the scheduler while the service is running. The scheduler locking is done via TZ_THREAD_SAFE_NONSECURE_ENTRY_FUNC().

The macro implements of the wrapper function. The wrapper function has the same function signature as the secure service.

Parameters

  • ret: The return type of the secure service and the wrapper function.

  • name: The name of the wrapper function. The secure service is assumed to be named the same, but with the suffix ‘_nse’. E.g. the wrapper function foo() wraps the secure service foo_nse().

  • ...: The arguments of the secure service and the wrapper function, as they would appear in a function signature, i.e. type and name.

Functions

void spm_request_system_reboot(void)

Request a system reboot from the Secure Firmware.

Rebooting is not available from the Non-Secure Firmware.

int spm_request_random_number(uint8_t *output, size_t len, size_t *olen)

Request a random number from the Secure Firmware.

This provides a True Random Number from the on-board random number generator.

Note

Currently, the RNG hardware is run each time this is called. This spends significant time and power.

Parameters

  • [out] output: The random number. Must be at least len long.

  • [in] len: The length of the output array. Currently, len must be 144.

  • [out] olen: The length of the random number provided.

Return Value

  • 0: If successful.

  • -EINVAL: If len is invalid. Currently, len must be 144.

int spm_request_read(void *destination, uint32_t addr, size_t len)

Request a read operation to be executed from Secure Firmware.

Parameters

  • [out] destination: Pointer to destination array where the content is to be copied.

  • [in] addr: Address to be copied from.

  • [in] len: Number of bytes to copy.

Return Value

  • 0: If successful.

  • -EINVAL: If destination is NULL, or if len is <= 0.

  • -EPERM: If source is outside of allowed ranges.

int spm_s0_active(uint32_t s0_address, uint32_t s1_address, bool *s0_active)

Check if S0 is the active B1 slot.

Parameters

  • [in] s0_address: Address of s0 slot.

  • [in] s1_address: Address of s1 slot.

  • [out] s0_active: Set to ‘true’ if s0 is active slot, ‘false’ otherwise

Return Value

  • 0: If successful.

  • -EINVAL: If info for both slots are NULL.

int spm_firmware_info(uint32_t fw_address, struct fw_info *info)

Search for the fw_info structure in firmware image located at address.

Parameters

  • [in] fw_address: Address where firmware image is stored.

  • [out] info: Pointer to where found info is stored.

Return Value

  • 0: If successful.

  • -EINVAL: If info is NULL.

  • -EFAULT: If no info is found.

int spm_prevalidate_b1_upgrade(uint32_t dst_addr, uint32_t src_addr)

Prevalidate a B1 update

This is performed by the B0 bootloader.

Parameters

  • [in] dst_addr: Target location for the upgrade. This will typically be the start address of either S0 or S1.

  • [in] src_addr: Current location of the upgrade.

Return Value

  • 1: If the upgrade is valid.

  • 0: If the upgrade is invalid.

  • -ENOTSUP: If the functionality is unavailable.

void spm_busy_wait(uint32_t busy_wait_us)

Busy wait in secure mode (debug function)

This function is for writing tests that require the execution to be in secure mode

Parameters

  • [in] busy_wait_us: The number of microseconds to wait for.