Trusted runtime primitive interface. More...

#include <asylo/platform/primitives/trusted_primitives.h>

Static Public Member Functions
static void	BestEffortAbort (const char *message)
	Aborts the enclave on a best-effort basis. More...

static void	DebugPuts (const char *message)
	Writes a message to a stream suitable for debug output. More...

static bool	IsInsideEnclave (const void *addr, size_t size) ASYLO_MUST_USE_RESULT
	A predicate that decides if a region of memory is internal to the enclave. More...

static bool	IsOutsideEnclave (const void *addr, size_t size) ASYLO_MUST_USE_RESULT
	A predicate that decides if a region of memory is external to the enclave. More...

static void *	UntrustedLocalAlloc (size_t size) noexcept ASYLO_MUST_USE_RESULT
	Allocates `size` bytes of untrusted local memory. More...

static void	UntrustedLocalFree (void *ptr) noexcept
	Calls untrusted local counterpart to free memory allocated by malloc in local untrusted code or by calling UntrustedLocalAlloc. More...

static void *	UntrustedLocalMemcpy (void dest, const void src, size_t size) noexcept
	Copies `size` bytes of memory from `src` to `dest`. More...

static PrimitiveStatus	UntrustedCall (uint64_t untrusted_selector, MessageWriter input, MessageReader output) ASYLO_MUST_USE_RESULT
	Exits the enclave synchronously at an entry point to untrusted code designated by `untrusted_selector`. More...

static PrimitiveStatus	RegisterEntryHandler (uint64_t trusted_selector, const EntryHandler &handler) ASYLO_MUST_USE_RESULT
	Registers a callback as the handler routine for an enclave entry point trusted_selector. More...

static int	CreateThread ()
	Creates a new thread. More...

Detailed Description

Trusted runtime primitive interface.

This class declares the primitive API available to trusted application code running inside an Asylo enclave. Each Asylo backend is responsible for providing an implementation of this interface.

Member Function Documentation

◆ BestEffortAbort()

static void asylo::primitives::TrustedPrimitives::BestEffortAbort ( const char * message )

static

Aborts the enclave on a best-effort basis.

Since it may not be possible to destroy the enclave completely without the cooperation of untrusted code, the implementation should clearly document the behavior of aborting on a particular backend.

Parameters

message A message for the abort method to print or log. May be nullptr.

◆ CreateThread()

static int asylo::primitives::TrustedPrimitives::CreateThread ( )

static

Creates a new thread.

Depending on the backend, the implementation might or might not need to exit the enclave for thread creation. The created thread is responsible for making a callback for querying the thread manager to register itself and then execute the callback function provided by the thread manager.

Returns: 0 on success.

◆ DebugPuts()

static void asylo::primitives::TrustedPrimitives::DebugPuts ( const char * message )

static

Writes a message to a stream suitable for debug output.

This API is intended for low-level debugging and should:

Take as few dependencies as possible.
Make as few assumptions about the runtime as possible.
Flush as immediately as possible.
Not assume that the I/O or logging subsystems are usable.

Parameters

message The message to output.

◆ IsInsideEnclave()

static bool asylo::primitives::TrustedPrimitives::IsInsideEnclave	(	const void *	addr,
		size_t	size
	)

static

A predicate that decides if a region of memory is internal to the enclave.

Parameters

addr	A pointer to the start of the memory region.
size	The number of bytes that will be tested for enclave residence.

Returns: true if every byte of a size byte range at an address addr falls inside the TCB and may not be modified by untrusted code.

◆ IsOutsideEnclave()

static bool asylo::primitives::TrustedPrimitives::IsOutsideEnclave	(	const void *	addr,
		size_t	size
	)

static

A predicate that decides if a region of memory is external to the enclave.

Parameters

addr	A pointer to the start of the memory region.
size	The number of bytes that will be tested for enclave non-residence.

Returns: true if every byte of a size byte range at an address addr falls outside the TCB and may be modified by untrusted code.

◆ RegisterEntryHandler()

static PrimitiveStatus asylo::primitives::TrustedPrimitives::RegisterEntryHandler	(	uint64_t	trusted_selector,
		const EntryHandler &	handler
	)

static

Registers a callback as the handler routine for an enclave entry point trusted_selector.

Parameters

trusted_selector	A unique-to-this-enclave identification number which will be used to select the given EntryHandler.
handler	The representation of a callable enclave function.

Returns: an error status if a handler has already been registered for trusted_selector or if an invalid selector value is passed.

◆ UntrustedCall()

static PrimitiveStatus asylo::primitives::TrustedPrimitives::UntrustedCall	(	uint64_t	untrusted_selector,
		MessageWriter *	input,
		MessageReader *	output
	)

static

Exits the enclave synchronously at an entry point to untrusted code designated by untrusted_selector.

Inputs must be pushed into input. Results are returned in output. All extent data in input and output are owned by them and located in trusted memory.

Parameters

untrusted_selector	The identification number to select a registered handler in the untrusted space.
input	A pointer to a MessageWriter, into which all call inputs must be pushed.
output	A pointer to a MessageReader from which to read outputs from the call.

Returns: A status for the call action, since the call itself may fail.

◆ UntrustedLocalAlloc()

static void* asylo::primitives::TrustedPrimitives::UntrustedLocalAlloc ( size_t size )

staticnoexcept

Allocates size bytes of untrusted local memory.

The allocated memory must later be freed by calling UntrustedLocalFree or by free call in local untrusted code. Local untrusted memory may not be addressable by the enclave directly, as this is a backend-specific assumption. Untrusted memory contents are not secure. One must assume that an attacker can read and write it. Note that untrusted local memory is not the same as host memory, and that untrusted local memory is not expected to be addressable from the untrusted application. If a backend permits directly addressing untrusted memory, portable applications should not use that capability. Only local primitives should use direct addressibility.

Parameters

size	The number of bytes to allocate.

Returns: A pointer to the allocated memory.

◆ UntrustedLocalFree()

static void asylo::primitives::TrustedPrimitives::UntrustedLocalFree ( void * ptr )

staticnoexcept

Calls untrusted local counterpart to free memory allocated by malloc in local untrusted code or by calling UntrustedLocalAlloc.

Parameters

ptr	The pointer to untrusted memory to free.

◆ UntrustedLocalMemcpy()

static void* asylo::primitives::TrustedPrimitives::UntrustedLocalMemcpy	(	void *	dest,
		const void *	src,
		size_t	size
	)

staticnoexcept

Copies size bytes of memory from src to dest.

Backends seeking to access or copy untrusted local memory should not assume direct memory access, and instead use this function to copy to/from the untrusted local memory.

Parameters

dest	The trusted or untrusted local destination memory.
src	The trusted or untrusted local source memory.
size	The number of bytes to be copied.

Returns: The pointer to destination buffer where memory got copied.

The documentation for this class was generated from the following file:

asylo/platform/primitives/trusted_primitives.h

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ BestEffortAbort()

◆ CreateThread()

◆ DebugPuts()

◆ IsInsideEnclave()

◆ IsOutsideEnclave()

◆ RegisterEntryHandler()

◆ UntrustedCall()

◆ UntrustedLocalAlloc()

◆ UntrustedLocalFree()

◆ UntrustedLocalMemcpy()