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.

Typedefs

typedef void (*spm_ns_on_fatal_error_t)(void)

Prototype of the function that is called in non-secure context from secure fault handler context.

Function can be used to print pending logging data before reboot.

Functions

void before_nse(void)
void after_nse(void)
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 CTR_DRBG number from the CC3XX platform libraries.

Parameters

  • output – [out] The CTR_DRBG number. Must be at least len long.

  • len – [in] The length of the output array.

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

Returns

non-negative on success, negative errno code on fail

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

Request a read operation to be executed from Secure Firmware.

Parameters

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

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

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

Return values

  • 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

  • s0_address – [in] Address of s0 slot.

  • s1_address – [in] Address of s1 slot.

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

Return values

  • 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

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

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

Return values

  • 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

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

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

Return values

  • 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

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

int spm_set_ns_fatal_error_handler(spm_ns_on_fatal_error_t handler)

Set handler which is called by the SPM fault handler.

Handler can be used to print out any pending log data before reset.

Note

It is only for debugging purposes!

Parameters

  • handler – Handler.

Return values

  • -ENOTSUP – if feature is disabled.

  • 0 – on success.

void z_spm_ns_fatal_error_handler(void)

Call non-secure fatal error handler.

Must be called from fatal error handler.