secure_context.h File Reference

Caller-owned Secure context leases for a trusted NS kernel. More...

#include "nexus/core/status.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	nx_freertos_secure_context_t
	Explicit Secure metadata, never stored in Nonsecure RAM. More...

Macros
#define	NX_FREERTOS_SECURE_MIN_STACK_BYTES   64u
	Minimum context capacity excludes the eight-byte ARM stack seal.

Enumerations
enum	nx_freertos_secure_fault_t { NX_FREERTOS_SECURE_SEAL_FAILURE = 1 , NX_FREERTOS_SECURE_STACK_FAILURE }
	Secure-context integrity failures, distinct from normal rejection. More...

Functions
nx_result_t	nx_freertos_secure_context_prepare (nx_freertos_secure_context_t *context, void *stack, size_t bytes, void *task)
	Prepare exact Secure storage for one trusted task identity.
nx_result_t	nx_freertos_secure_context_rebind (nx_freertos_secure_context_t *context, void *task)
	Rebind retired metadata while preserving its epoch history.
nx_freertos_secure_context_t *	nx_freertos_secure_context_for_task (void *task)
	Resolve a trusted, statically composed Secure task record.
void	nx_freertos_secure_fault (nx_freertos_secure_fault_t fault)
	Fail stop after a loaded Secure stack integrity failure.

Detailed Description

Caller-owned Secure context leases for a trusted NS kernel.

Author

Nexus Team

Version

1.0.0

Date

2026-10-11

Copyright

Copyright (c) 2026 Nexus Team

Definition in file secure_context.h.

Macro Definition Documentation

NX_FREERTOS_SECURE_MIN_STACK_BYTES

#define NX_FREERTOS_SECURE_MIN_STACK_BYTES   64u

Minimum context capacity excludes the eight-byte ARM stack seal.

Definition at line 19 of file secure_context.h.

Enumeration Type Documentation

nx_freertos_secure_fault_t

enum nx_freertos_secure_fault_t

Secure-context integrity failures, distinct from normal rejection.

Enumerator
NX_FREERTOS_SECURE_SEAL_FAILURE
NX_FREERTOS_SECURE_STACK_FAILURE

Definition at line 81 of file secure_context.h.

Function Documentation

nx_freertos_secure_context_for_task()

nx_freertos_secure_context_t * nx_freertos_secure_context_for_task

(

void *

task

)

Resolve a trusted, statically composed Secure task record.

Parameters

[in]

task

Opaque identity supplied by the trusted NS kernel.

Returns

Prepared caller-owned metadata, or NULL when unauthorized.

Note

Secure application overrides the weak NULL default with an immutable mapping. Called with both PRIMASK states held; never dereference an NS-provided metadata pointer, allocate, block, discover objects, call a kernel or mutate mappings. The NS kernel and its SVC/PendSV are trusted: this mechanism does not authenticate an adversarial NS privileged kernel. NS Thread calls cannot spoof Handler origin.

nx_freertos_secure_context_prepare()

nx_result_t nx_freertos_secure_context_prepare	(	nx_freertos_secure_context_t *	context,
		void *	stack,
		size_t	bytes,
		void *	task )

Prepare exact Secure storage for one trusted task identity.

Parameters

[out]	context	Zero-initialized caller-owned Secure metadata.
[in]	stack	Eight-byte-aligned Secure writable stack allocation.
[in]	bytes	Whole allocation, including eight-byte upper seal.
[in]	task	Opaque NS task identity, never dereferenced here.

Returns

SUCCESS, INVALID, CONTEXT, STATE or BUSY.

Note

Secure privileged Thread startup/exclusive lifecycle owner. Both memory spans must be Secure, writable and disjoint. No NS task may run against this identity during prepare. Repeat prepare is rejected; epochs are never reset. No allocation, kernel operation or runtime registry is used.

nx_freertos_secure_context_rebind()

nx_result_t nx_freertos_secure_context_rebind	(	nx_freertos_secure_context_t *	context,
		void *	task )

Rebind retired metadata while preserving its epoch history.

Parameters

[in,out]	context	Prepared, unleased and unloaded Secure metadata.
[in]	task	New trusted NS task identity.

Returns

SUCCESS, INVALID, CONTEXT, STATE or BUSY.

Note

Secure lifecycle owner only after joining the previous task and stopping every observer. Existing stack is reused; stale handles remain invalid after the next allocation.

nx_freertos_secure_fault()

void nx_freertos_secure_fault

(

nx_freertos_secure_fault_t

fault

)

Fail stop after a loaded Secure stack integrity failure.

Parameters

[in]

fault

Seal or stack invariant violation.

Note

Secure application may override to record/reset safely. Called with both masks held; must not return, block, call a kernel or release retained storage. Default holds masks and spins. No transport or product recovery policy is imposed.