3 use crate::cell::UnsafeCell;
5 use crate::ops::{CoerceUnsized, Deref, DerefMut, Index, IndexMut};
6 use crate::ptr::{self, NonNull};
8 use crate::slice::SliceIndex;
10 use super::super::mem::is_user_range;
11 use fortanix_sgx_abi::*;
13 /// A type that can be safely read from or written to userspace.
15 /// Non-exhaustive list of specific requirements for reading and writing:
16 /// * **Type is `Copy`** (and therefore also not `Drop`). Copies will be
17 /// created when copying from/to userspace. Destructors will not be called.
18 /// * **No references or Rust-style owned pointers** (`Vec`, `Arc`, etc.). When
19 /// reading from userspace, references into enclave memory must not be
20 /// created. Also, only enclave memory is considered managed by the Rust
21 /// compiler's static analysis. When reading from userspace, there can be no
22 /// guarantee that the value correctly adheres to the expectations of the
23 /// type. When writing to userspace, memory addresses of data in enclave
24 /// memory must not be leaked for confidentiality reasons. `User` and
25 /// `UserRef` are also not allowed for the same reasons.
26 /// * **No fat pointers.** When reading from userspace, the size or vtable
27 /// pointer could be automatically interpreted and used by the code. When
28 /// writing to userspace, memory addresses of data in enclave memory (such
29 /// as vtable pointers) must not be leaked for confidentiality reasons.
31 /// Non-exhaustive list of specific requirements for reading from userspace:
32 /// * **Any bit pattern is valid** for this type (no `enum`s). There can be no
33 /// guarantee that the value correctly adheres to the expectations of the
34 /// type, so any value must be valid for this type.
36 /// Non-exhaustive list of specific requirements for writing to userspace:
37 /// * **No pointers to enclave memory.** Memory addresses of data in enclave
38 /// memory must not be leaked for confidentiality reasons.
39 /// * **No internal padding.** Padding might contain previously-initialized
40 /// secret data stored at that memory location and must not be leaked for
41 /// confidentiality reasons.
42 #[unstable(feature = "sgx_platform", issue = "56975")]
43 pub unsafe trait UserSafeSized: Copy + Sized {}
45 #[unstable(feature = "sgx_platform", issue = "56975")]
46 unsafe impl UserSafeSized for u8 {}
47 #[unstable(feature = "sgx_platform", issue = "56975")]
48 unsafe impl<T> UserSafeSized for FifoDescriptor<T> {}
49 #[unstable(feature = "sgx_platform", issue = "56975")]
50 unsafe impl UserSafeSized for ByteBuffer {}
51 #[unstable(feature = "sgx_platform", issue = "56975")]
52 unsafe impl UserSafeSized for Usercall {}
53 #[unstable(feature = "sgx_platform", issue = "56975")]
54 unsafe impl UserSafeSized for Return {}
55 #[unstable(feature = "sgx_platform", issue = "56975")]
56 unsafe impl<T: UserSafeSized> UserSafeSized for [T; 2] {}
58 /// A type that can be represented in memory as one or more `UserSafeSized`s.
59 #[unstable(feature = "sgx_platform", issue = "56975")]
60 pub unsafe trait UserSafe {
61 /// Equivalent to `mem::align_of::<Self>`.
62 fn align_of() -> usize;
64 /// Construct a pointer to `Self` given a memory range in user space.
66 /// N.B., this takes a size, not a length!
70 /// The caller must ensure the memory range is in user memory, is the
71 /// correct size and is correctly aligned and points to the right type.
72 unsafe fn from_raw_sized_unchecked(ptr: *mut u8, size: usize) -> *mut Self;
74 /// Construct a pointer to `Self` given a memory range.
76 /// N.B., this takes a size, not a length!
80 /// The caller must ensure the memory range points to the correct type.
84 /// This function panics if:
86 /// * the pointer is not aligned.
87 /// * the pointer is null.
88 /// * the pointed-to range does not fit in the address space.
89 /// * the pointed-to range is not in user memory.
90 unsafe fn from_raw_sized(ptr: *mut u8, size: usize) -> NonNull<Self> {
91 assert!(ptr.wrapping_add(size) >= ptr);
92 // SAFETY: The caller has guaranteed the pointer is valid
93 let ret = unsafe { Self::from_raw_sized_unchecked(ptr, size) };
96 NonNull::new_unchecked(ret as _)
100 /// Checks if a pointer may point to `Self` in user memory.
104 /// The caller must ensure the memory range points to the correct type and
105 /// length (if this is a slice).
109 /// This function panics if:
111 /// * the pointer is not aligned.
112 /// * the pointer is null.
113 /// * the pointed-to range is not in user memory.
114 unsafe fn check_ptr(ptr: *const Self) {
115 let is_aligned = |p| -> bool { 0 == (p as usize) & (Self::align_of() - 1) };
117 assert!(is_aligned(ptr as *const u8));
118 assert!(is_user_range(ptr as _, mem::size_of_val(unsafe { &*ptr })));
119 assert!(!ptr.is_null());
123 #[unstable(feature = "sgx_platform", issue = "56975")]
124 unsafe impl<T: UserSafeSized> UserSafe for T {
125 fn align_of() -> usize {
129 unsafe fn from_raw_sized_unchecked(ptr: *mut u8, size: usize) -> *mut Self {
130 assert_eq!(size, mem::size_of::<T>());
135 #[unstable(feature = "sgx_platform", issue = "56975")]
136 unsafe impl<T: UserSafeSized> UserSafe for [T] {
137 fn align_of() -> usize {
142 /// Behavior is undefined if any of these conditions are violated:
143 /// * `ptr` must be [valid] for writes of `size` many bytes, and it must be
144 /// properly aligned.
146 /// [valid]: core::ptr#safety
149 /// This function panics if:
151 /// * the element size is not a factor of the size
152 unsafe fn from_raw_sized_unchecked(ptr: *mut u8, size: usize) -> *mut Self {
153 let elem_size = mem::size_of::<T>();
154 assert_eq!(size % elem_size, 0);
155 let len = size / elem_size;
156 // SAFETY: The caller must uphold the safety contract for `from_raw_sized_unchecked`
157 unsafe { slice::from_raw_parts_mut(ptr as _, len) }
161 /// A reference to some type in userspace memory. `&UserRef<T>` is equivalent
162 /// to `&T` in enclave memory. Access to the memory is only allowed by copying
163 /// to avoid TOCTTOU issues. After copying, code should make sure to completely
164 /// check the value before use.
166 /// It is also possible to obtain a mutable reference `&mut UserRef<T>`. Unlike
167 /// regular mutable references, these are not exclusive. Userspace may always
168 /// write to the backing memory at any time, so it can't be assumed that there
169 /// the pointed-to memory is uniquely borrowed. The two different reference types
170 /// are used solely to indicate intent: a mutable reference is for writing to
171 /// user memory, an immutable reference for reading from user memory.
172 #[unstable(feature = "sgx_platform", issue = "56975")]
173 pub struct UserRef<T: ?Sized>(UnsafeCell<T>);
174 /// An owned type in userspace memory. `User<T>` is equivalent to `Box<T>` in
175 /// enclave memory. Access to the memory is only allowed by copying to avoid
176 /// TOCTTOU issues. The user memory will be freed when the value is dropped.
177 /// After copying, code should make sure to completely check the value before
179 #[unstable(feature = "sgx_platform", issue = "56975")]
180 pub struct User<T: UserSafe + ?Sized>(NonNull<UserRef<T>>);
182 trait NewUserRef<T: ?Sized> {
183 unsafe fn new_userref(v: T) -> Self;
186 impl<T: ?Sized> NewUserRef<*mut T> for NonNull<UserRef<T>> {
187 unsafe fn new_userref(v: *mut T) -> Self {
188 // SAFETY: The caller has guaranteed the pointer is valid
189 unsafe { NonNull::new_unchecked(v as _) }
193 impl<T: ?Sized> NewUserRef<NonNull<T>> for NonNull<UserRef<T>> {
194 unsafe fn new_userref(v: NonNull<T>) -> Self {
195 // SAFETY: The caller has guaranteed the pointer is valid
196 unsafe { NonNull::new_userref(v.as_ptr()) }
200 #[unstable(feature = "sgx_platform", issue = "56975")]
201 impl<T: ?Sized> User<T>
205 // This function returns memory that is practically uninitialized, but is
206 // not considered "unspecified" or "undefined" for purposes of an
207 // optimizing compiler. This is achieved by returning a pointer from
208 // from outside as obtained by `super::alloc`.
209 fn new_uninit_bytes(size: usize) -> Self {
211 // Mustn't call alloc with size 0.
212 let ptr = if size > 0 {
213 rtunwrap!(Ok, super::alloc(size, T::align_of())) as _
215 T::align_of() as _ // dangling pointer ok for size 0
217 if let Ok(v) = crate::panic::catch_unwind(|| T::from_raw_sized(ptr, size)) {
218 User(NonNull::new_userref(v))
220 rtabort!("Got invalid pointer from alloc() usercall")
225 /// Copies `val` into freshly allocated space in user memory.
226 pub fn new_from_enclave(val: &T) -> Self {
228 let ret = Self::new_uninit_bytes(mem::size_of_val(val));
230 val as *const T as *const u8,
231 ret.0.as_ptr() as *mut u8,
232 mem::size_of_val(val),
238 /// Creates an owned `User<T>` from a raw pointer.
241 /// The caller must ensure `ptr` points to `T`, is freeable with the `free`
242 /// usercall and the alignment of `T`, and is uniquely owned.
245 /// This function panics if:
247 /// * The pointer is not aligned
248 /// * The pointer is null
249 /// * The pointed-to range is not in user memory
250 pub unsafe fn from_raw(ptr: *mut T) -> Self {
251 // SAFETY: the caller must uphold the safety contract for `from_raw`.
252 unsafe { T::check_ptr(ptr) };
253 User(unsafe { NonNull::new_userref(ptr) })
256 /// Converts this value into a raw pointer. The value will no longer be
257 /// automatically freed.
258 pub fn into_raw(self) -> *mut T {
265 #[unstable(feature = "sgx_platform", issue = "56975")]
270 /// Allocate space for `T` in user memory.
271 pub fn uninitialized() -> Self {
272 Self::new_uninit_bytes(mem::size_of::<T>())
276 #[unstable(feature = "sgx_platform", issue = "56975")]
281 /// Allocate space for a `[T]` of `n` elements in user memory.
282 pub fn uninitialized(n: usize) -> Self {
283 Self::new_uninit_bytes(n * mem::size_of::<T>())
286 /// Creates an owned `User<[T]>` from a raw thin pointer and a slice length.
289 /// The caller must ensure `ptr` points to `len` elements of `T`, is
290 /// freeable with the `free` usercall and the alignment of `T`, and is
294 /// This function panics if:
296 /// * The pointer is not aligned
297 /// * The pointer is null
298 /// * The pointed-to range does not fit in the address space
299 /// * The pointed-to range is not in user memory
300 pub unsafe fn from_raw_parts(ptr: *mut T, len: usize) -> Self {
302 NonNull::new_userref(<[T]>::from_raw_sized(ptr as _, len * mem::size_of::<T>()))
307 #[unstable(feature = "sgx_platform", issue = "56975")]
308 impl<T: ?Sized> UserRef<T>
312 /// Creates a `&UserRef<[T]>` from a raw pointer.
315 /// The caller must ensure `ptr` points to `T`.
318 /// This function panics if:
320 /// * The pointer is not aligned
321 /// * The pointer is null
322 /// * The pointed-to range is not in user memory
323 pub unsafe fn from_ptr<'a>(ptr: *const T) -> &'a Self {
324 // SAFETY: The caller must uphold the safety contract for `from_ptr`.
325 unsafe { T::check_ptr(ptr) };
326 unsafe { &*(ptr as *const Self) }
329 /// Creates a `&mut UserRef<[T]>` from a raw pointer. See the struct
330 /// documentation for the nuances regarding a `&mut UserRef<T>`.
333 /// The caller must ensure `ptr` points to `T`.
336 /// This function panics if:
338 /// * The pointer is not aligned
339 /// * The pointer is null
340 /// * The pointed-to range is not in user memory
341 pub unsafe fn from_mut_ptr<'a>(ptr: *mut T) -> &'a mut Self {
342 // SAFETY: The caller must uphold the safety contract for `from_mut_ptr`.
343 unsafe { T::check_ptr(ptr) };
344 unsafe { &mut *(ptr as *mut Self) }
347 /// Copies `val` into user memory.
350 /// This function panics if the destination doesn't have the same size as
351 /// the source. This can happen for dynamically-sized types such as slices.
352 pub fn copy_from_enclave(&mut self, val: &T) {
354 assert_eq!(mem::size_of_val(val), mem::size_of_val(&*self.0.get()));
356 val as *const T as *const u8,
357 self.0.get() as *mut T as *mut u8,
358 mem::size_of_val(val),
363 /// Copies the value from user memory and place it into `dest`.
366 /// This function panics if the destination doesn't have the same size as
367 /// the source. This can happen for dynamically-sized types such as slices.
368 pub fn copy_to_enclave(&self, dest: &mut T) {
370 assert_eq!(mem::size_of_val(dest), mem::size_of_val(&*self.0.get()));
372 self.0.get() as *const T as *const u8,
373 dest as *mut T as *mut u8,
374 mem::size_of_val(dest),
379 /// Obtain a raw pointer from this reference.
380 pub fn as_raw_ptr(&self) -> *const T {
381 self as *const _ as _
384 /// Obtain a raw pointer from this reference.
385 pub fn as_raw_mut_ptr(&mut self) -> *mut T {
390 #[unstable(feature = "sgx_platform", issue = "56975")]
395 /// Copies the value from user memory into enclave memory.
396 pub fn to_enclave(&self) -> T {
397 unsafe { ptr::read(self.0.get()) }
401 #[unstable(feature = "sgx_platform", issue = "56975")]
406 /// Creates a `&UserRef<[T]>` from a raw thin pointer and a slice length.
409 /// The caller must ensure `ptr` points to `n` elements of `T`.
412 /// This function panics if:
414 /// * The pointer is not aligned
415 /// * The pointer is null
416 /// * The pointed-to range does not fit in the address space
417 /// * The pointed-to range is not in user memory
418 pub unsafe fn from_raw_parts<'a>(ptr: *const T, len: usize) -> &'a Self {
419 // SAFETY: The caller must uphold the safety contract for `from_raw_parts`.
421 &*(<[T]>::from_raw_sized(ptr as _, len * mem::size_of::<T>()).as_ptr() as *const Self)
425 /// Creates a `&mut UserRef<[T]>` from a raw thin pointer and a slice length.
426 /// See the struct documentation for the nuances regarding a
427 /// `&mut UserRef<T>`.
430 /// The caller must ensure `ptr` points to `n` elements of `T`.
433 /// This function panics if:
435 /// * The pointer is not aligned
436 /// * The pointer is null
437 /// * The pointed-to range does not fit in the address space
438 /// * The pointed-to range is not in user memory
439 pub unsafe fn from_raw_parts_mut<'a>(ptr: *mut T, len: usize) -> &'a mut Self {
440 // SAFETY: The caller must uphold the safety contract for `from_raw_parts_mut`.
442 &mut *(<[T]>::from_raw_sized(ptr as _, len * mem::size_of::<T>()).as_ptr() as *mut Self)
446 /// Obtain a raw pointer to the first element of this user slice.
447 pub fn as_ptr(&self) -> *const T {
451 /// Obtain a raw pointer to the first element of this user slice.
452 pub fn as_mut_ptr(&mut self) -> *mut T {
456 /// Obtain the number of elements in this user slice.
457 pub fn len(&self) -> usize {
458 unsafe { (*self.0.get()).len() }
461 /// Copies the value from user memory and place it into `dest`. Afterwards,
462 /// `dest` will contain exactly `self.len()` elements.
465 /// This function panics if the destination doesn't have the same size as
466 /// the source. This can happen for dynamically-sized types such as slices.
467 pub fn copy_to_enclave_vec(&self, dest: &mut Vec<T>) {
468 if let Some(missing) = self.len().checked_sub(dest.capacity()) {
469 dest.reserve(missing)
471 // SAFETY: We reserve enough space above.
472 unsafe { dest.set_len(self.len()) };
473 self.copy_to_enclave(&mut dest[..]);
476 /// Copies the value from user memory into a vector in enclave memory.
477 pub fn to_enclave(&self) -> Vec<T> {
478 let mut ret = Vec::with_capacity(self.len());
479 self.copy_to_enclave_vec(&mut ret);
483 /// Returns an iterator over the slice.
484 pub fn iter(&self) -> Iter<'_, T>
486 T: UserSafe, // FIXME: should be implied by [T]: UserSafe?
488 unsafe { Iter((&*self.as_raw_ptr()).iter()) }
491 /// Returns an iterator that allows modifying each value.
492 pub fn iter_mut(&mut self) -> IterMut<'_, T>
494 T: UserSafe, // FIXME: should be implied by [T]: UserSafe?
496 unsafe { IterMut((&mut *self.as_raw_mut_ptr()).iter_mut()) }
500 /// Immutable user slice iterator
502 /// This struct is created by the `iter` method on `UserRef<[T]>`.
503 #[unstable(feature = "sgx_platform", issue = "56975")]
504 pub struct Iter<'a, T: 'a + UserSafe>(slice::Iter<'a, T>);
506 #[unstable(feature = "sgx_platform", issue = "56975")]
507 impl<'a, T: UserSafe> Iterator for Iter<'a, T> {
508 type Item = &'a UserRef<T>;
511 fn next(&mut self) -> Option<Self::Item> {
512 unsafe { self.0.next().map(|e| UserRef::from_ptr(e)) }
516 /// Mutable user slice iterator
518 /// This struct is created by the `iter_mut` method on `UserRef<[T]>`.
519 #[unstable(feature = "sgx_platform", issue = "56975")]
520 pub struct IterMut<'a, T: 'a + UserSafe>(slice::IterMut<'a, T>);
522 #[unstable(feature = "sgx_platform", issue = "56975")]
523 impl<'a, T: UserSafe> Iterator for IterMut<'a, T> {
524 type Item = &'a mut UserRef<T>;
527 fn next(&mut self) -> Option<Self::Item> {
528 unsafe { self.0.next().map(|e| UserRef::from_mut_ptr(e)) }
532 #[unstable(feature = "sgx_platform", issue = "56975")]
533 impl<T: ?Sized> Deref for User<T>
537 type Target = UserRef<T>;
539 fn deref(&self) -> &Self::Target {
540 unsafe { &*self.0.as_ptr() }
544 #[unstable(feature = "sgx_platform", issue = "56975")]
545 impl<T: ?Sized> DerefMut for User<T>
549 fn deref_mut(&mut self) -> &mut Self::Target {
550 unsafe { &mut *self.0.as_ptr() }
554 #[unstable(feature = "sgx_platform", issue = "56975")]
555 impl<T: ?Sized> Drop for User<T>
561 let ptr = (*self.0.as_ptr()).0.get();
562 super::free(ptr as _, mem::size_of_val(&mut *ptr), T::align_of());
567 #[unstable(feature = "sgx_platform", issue = "56975")]
568 impl<T: CoerceUnsized<U>, U> CoerceUnsized<UserRef<U>> for UserRef<T> {}
570 #[unstable(feature = "sgx_platform", issue = "56975")]
571 impl<T, I> Index<I> for UserRef<[T]>
574 I: SliceIndex<[T], Output: UserSafe>,
576 type Output = UserRef<I::Output>;
579 fn index(&self, index: I) -> &UserRef<I::Output> {
581 if let Some(slice) = index.get(&*self.as_raw_ptr()) {
582 UserRef::from_ptr(slice)
584 rtabort!("index out of range for user slice");
590 #[unstable(feature = "sgx_platform", issue = "56975")]
591 impl<T, I> IndexMut<I> for UserRef<[T]>
594 I: SliceIndex<[T], Output: UserSafe>,
597 fn index_mut(&mut self, index: I) -> &mut UserRef<I::Output> {
599 if let Some(slice) = index.get_mut(&mut *self.as_raw_mut_ptr()) {
600 UserRef::from_mut_ptr(slice)
602 rtabort!("index out of range for user slice");
608 #[unstable(feature = "sgx_platform", issue = "56975")]
609 impl UserRef<super::raw::ByteBuffer> {
610 /// Copies the user memory range pointed to by the user `ByteBuffer` to
614 /// This function panics if, in the user `ByteBuffer`:
616 /// * The pointer is null
617 /// * The pointed-to range does not fit in the address space
618 /// * The pointed-to range is not in user memory
619 pub fn copy_user_buffer(&self) -> Vec<u8> {
621 let buf = self.to_enclave();
623 User::from_raw_parts(buf.data as _, buf.len).to_enclave()
625 // Mustn't look at `data` or call `free` if `len` is `0`.
626 Vec::with_capacity(0)