Struct UserRef 

pub struct UserRef<T: ?Sized>(/* private fields */);

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Available on Fortanix and SGX only.

A reference to some type in userspace memory. &UserRef<T> is equivalent to &T in enclave memory. Access to the memory is only allowed by copying to avoid TOCTTOU issues. After copying, code should make sure to completely check the value before use.

It is also possible to obtain a mutable reference &mut UserRef<T>. Unlike regular mutable references, these are not exclusive. Userspace may always write to the backing memory at any time, so it can’t be assumed that there the pointed-to memory is uniquely borrowed. The two different reference types are used solely to indicate intent: a mutable reference is for writing to user memory, an immutable reference for reading from user memory.

Implementations

impl<T> UserRef<T>

where T: UserSafe + ?Sized,

pub unsafe fn from_ptr<'a>(ptr: *const T) -> &'a Self

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Creates a &UserRef<[T]> from a raw pointer.

Safety

The caller must ensure ptr points to T.

Panics

This function panics if:

• The pointer is not aligned
• The pointer is null
• The pointed-to range is not in user memory

pub unsafe fn from_mut_ptr<'a>(ptr: *mut T) -> &'a mut Self

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Creates a &mut UserRef<[T]> from a raw pointer. See the struct documentation for the nuances regarding a &mut UserRef<T>.

Safety

The caller must ensure ptr points to T.

Panics

This function panics if:

• The pointer is not aligned
• The pointer is null
• The pointed-to range is not in user memory

pub fn copy_from_enclave(&mut self, val: &T)

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Copies val into user memory.

Panics

This function panics if the destination doesn’t have the same size as the source. This can happen for dynamically-sized types such as slices.

pub fn copy_to_enclave<U: ?Sized + UserSafeCopyDestination<T>>( &self, dest: &mut U, )

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Copies the value from user memory and place it into dest.

Panics

This function panics if the destination doesn’t have the same size as the source. This can happen for dynamically-sized types such as slices.

pub fn as_raw_ptr(&self) -> *const T

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Obtain a raw pointer from this reference.

pub fn as_raw_mut_ptr(&mut self) -> *mut T

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Obtain a raw pointer from this reference.

impl<T> UserRef<T>

where T: UserSafe,

pub fn to_enclave(&self) -> T

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Copies the value from user memory into enclave memory.

impl<T> UserRef<[T]>

where [T]: UserSafe,

pub unsafe fn from_raw_parts<'a>(ptr: *const T, len: usize) -> &'a Self

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Creates a &UserRef<[T]> from a raw thin pointer and a slice length.

Safety

The caller must ensure ptr points to n elements of T.

Panics

This function panics if:

• The pointer is not aligned
• The pointer is null
• The pointed-to range does not fit in the address space
• The pointed-to range is not in user memory

pub unsafe fn from_raw_parts_mut<'a>(ptr: *mut T, len: usize) -> &'a mut Self

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Creates a &mut UserRef<[T]> from a raw thin pointer and a slice length. See the struct documentation for the nuances regarding a &mut UserRef<T>.

Safety

The caller must ensure ptr points to n elements of T.

Panics

This function panics if:

• The pointer is not aligned
• The pointer is null
• The pointed-to range does not fit in the address space
• The pointed-to range is not in user memory

pub fn as_ptr(&self) -> *const T

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Obtain a raw pointer to the first element of this user slice.

pub fn as_mut_ptr(&mut self) -> *mut T

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Obtain a raw pointer to the first element of this user slice.

pub fn len(&self) -> usize

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Obtain the number of elements in this user slice.

pub fn append_to_enclave_vec(&self, dest: &mut Vec<T>)

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Copies the value from user memory and appends it to dest.

pub fn to_enclave(&self) -> Vec<T>

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Copies the value from user memory into a vector in enclave memory.

pub fn iter(&self) -> Iter<'_, T>

where T: UserSafe,

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Returns an iterator over the slice.

pub fn iter_mut(&mut self) -> IterMut<'_, T>

where T: UserSafe,

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Returns an iterator that allows modifying each value.

impl UserRef<ByteBuffer>

pub fn copy_user_buffer(&self) -> Vec<u8>

🔬This is a nightly-only experimental API. (sgx_platform #56975)

Copies the user memory range pointed to by the user ByteBuffer to enclave memory.

Panics

This function panics if, in the user ByteBuffer:

• The pointer is null
• The pointed-to range does not fit in the address space
• The pointed-to range is not in user memory

Trait Implementations

impl<T: CoerceUnsized<U>, U> CoerceUnsized<UserRef<U>> for UserRef<T>

impl<T, I> Index<I> for UserRef<[T]>

where [T]: UserSafe, I: SliceIndex<[T]>, I::Output: UserSafe,

type Output = UserRef<<I as SliceIndex<[T]>>::Output>

The returned type after indexing.

fn index(&self, index: I) -> &UserRef<I::Output>

Performs the indexing (container[index]) operation.

impl<T, I> IndexMut<I> for UserRef<[T]>

where [T]: UserSafe, I: SliceIndex<[T]>, I::Output: UserSafe,

fn index_mut(&mut self, index: I) -> &mut UserRef<I::Output>

Performs the mutable indexing (container[index]) operation.