secrets 1.3.0

#![allow(missing_debug_implementations)]
#![allow(unsafe_code)]

use crate::ffi::sodium;
use crate::traits::*;

use std::borrow::BorrowMut;
use std::fmt::{self, Debug, Formatter};
use std::ops::{Deref, DerefMut};
use std::thread;

/// A type for protecting secrets allocated on the stack.
///
/// Stack-allocated secrets have distinct security needs from
/// heap-allocated secrets, and should be preferred when possible. They
/// provide the following guarantees:
///
/// * [`mlock(2)`][mlock] is called on the underlying memory
/// * [`munlock(2)`][mlock] is called on the underlying memory when no longer in use
/// * the underlying memory is zeroed out when no longer in use
/// * they are borrowed for their entire lifespan, so cannot be moved
/// * they are best-effort compared in constant time
/// * they are best-effort prevented from being printed by [`Debug`]
/// * they are best-effort prevented from being [`Clone`]d
///
/// To fulfill these guarantees, [`Secret`]s are constructed in an
/// atypical pattern. Rather than having [`new`](Secret::new) return a
/// newly-created instance, [`new`](Secret::new) accepts a callback
/// argument that is provided with a mutably borrowed wrapper around the
/// data in question. This wrapper [`Deref`]s into the desired type,
/// with replacement implementations of [`Debug`], [`PartialEq`], and
/// [`Eq`] to prevent accidental misuse.
///
/// Users *must* take care when dereferencing secrets as this will
/// provide direct access to the underlying type. If the bare type
/// implements traits like [`Clone`], [`Debug`], and [`PartialEq`],
/// those methods can be called directly and will not benefit from the
/// protections provided by this wrapper.
///
/// Users *must* also take care to avoid unintentionally invoking
/// [`Copy`] on the underlying data, as doing so will result in
/// secret data being copied out of the [`Secret`], thus losing the
/// protections provided by this library. Be careful not to invoke
/// methods that take ownership of `self` or functions that move
/// parameters with secret data, since doing so will implicitly create
/// copies.
///
/// # Example: generate a cryptographically-random 128-bit [`Secret`]
///
/// Initialize a [`Secret`] with cryptographically random data:
///
/// ```
/// # use secrets::Secret;
/// Secret::<[u8; 16]>::random(|s| {
///     // use `s` as if it were a `&mut [u8; 16]`
/// });
/// ```
///
/// # Example: move mutable data into a [`Secret`]
///
/// Existing data can be moved into a [`Secret`]. When doing so, we make
/// a best-effort attempt to zero out the data in the original location.
/// Any prior copies will be unaffected, so please exercise as much
/// caution as possible when handling data before it can be protected.
///
/// ```
/// # use secrets::Secret;
/// let mut value = [1u8, 2, 3, 4];
///
/// // the contents of `value` will be copied into the Secret before
/// // being zeroed out
/// Secret::from(&mut value, |s| {
///     assert_eq!(*s, [1, 2, 3, 4]);
/// });
///
/// // the contents of `value` have been zeroed
/// assert_eq!(value, [0, 0, 0, 0]);
/// ```
///
/// [mlock]: http://man7.org/linux/man-pages/man2/mlock.2.html
//
// Aligned to the target's memory page size so that no two `Secret`s
// can share a page; `munlock` operates on whole pages and would
// otherwise unlock a sibling secret's memory while it is still live.
// `repr(align)` requires a literal, so we dispatch on the target.
// `Secret::new` asserts at runtime that the chosen alignment is at
// least the page size reported by the OS, catching any target whose
// real page size exceeds what this table promises.
#[cfg_attr(any(target_arch = "x86",         target_arch   = "x86_64"), repr(align(4096)))]
#[cfg_attr(all(target_arch = "aarch64",     target_vendor = "apple"),  repr(align(16384)))]
#[cfg_attr(all(target_arch = "aarch64", not(target_vendor = "apple")), repr(align(65536)))]
#[cfg_attr(not(any(
    target_arch = "x86",
    target_arch = "x86_64",
    target_arch = "aarch64",
)),                                                                    repr(align(65536)))]
pub struct Secret<T: Bytes> {
    /// The internal protected memory for the [`Secret`].
    data: T,
}

/// A mutable [`Deref`]-wrapper around a [`Secret`]'s internal
/// contents that intercepts calls like [`Clone::clone`] and
/// [`Debug::fmt`] that are likely to result in the inadvertent
/// disclosure of secret data.
pub struct RefMut<'a, T: Bytes> {
    /// a reference to the underlying secret data that will be derefed
    data: &'a mut T,
}

impl<T: Bytes> Secret<T> {
    /// Creates a new [`Secret`] and invokes the provided callback with
    /// a wrapper to the protected memory. This memory will be filled
    /// with a well-defined, arbitrary byte pattern, and should be
    /// initialized to something meaningful before actual use.
    ///
    /// # Panics
    ///
    /// This function will panic if the underlying call to `mlock(2)`
    /// (`VirtualLock` on windows) fails.
    ///
    /// ```
    /// # use secrets::Secret;
    /// use std::fs::File;
    /// use std::io::prelude::*;
    ///
    /// Secret::<[u8; 32]>::new(|mut s| {
    ///     File::open("/dev/urandom")?.read_exact(&mut s[..])
    /// });
    /// ```
    #[allow(clippy::new_ret_no_self)]
    pub fn new<F, U>(f: F) -> U
    where
        F: FnOnce(RefMut<'_, T>) -> U,
    {
        tested!(size_of::<T>() == 0);

        assert!(
            align_of::<Self>() >= page_size::get(),
            "secrets: Secret alignment ({}) is smaller than the system page size ({}); \
             this target is not yet supported",
            align_of::<Self>(),
            page_size::get(),
        );

        let mut secret = Self {
            data: T::uninitialized(),
        };

        assert!(
            unsafe { sodium::mlock(&raw mut secret.data) },
            "secrets: unable to mlock memory for a Secret"
        );

        f(RefMut::new(&mut secret.data))
    }
}

impl<T: Bytes + Zeroable> Secret<T> {
    /// Creates a new [`Secret`] filled with zeroed bytes and invokes the
    /// callback with a wrapper to the protected memory.
    ///
    /// ```
    /// # use secrets::Secret;
    /// Secret::<u8>::zero(|s| {
    ///     assert_eq!(*s, 0);
    /// });
    /// ```
    pub fn zero<F, U>(f: F) -> U
    where
        F: FnOnce(RefMut<'_, T>) -> U,
    {
        Self::new(|mut s| {
            s.zero();
            f(s)
        })
    }

    /// Creates a new [`Secret`] from existing, unprotected data, and
    /// immediately zeroes out the memory of the data being moved in.
    /// Invokes the callback with a wrapper to the protected memory.
    ///
    /// ```
    /// # use secrets::Secret;
    /// let mut bytes : [u32; 4] = [1, 2, 3, 4];
    ///
    /// Secret::from(&mut bytes, |s| {
    ///     assert_eq!(*s, [1, 2, 3, 4]);
    /// });
    ///
    /// assert_eq!(bytes, [0, 0, 0, 0]);
    /// ```
    pub fn from<F, U>(v: &mut T, f: F) -> U
    where
        F: FnOnce(RefMut<'_, T>) -> U,
    {
        Self::new(|mut s| {
            let _ = &v; // ensure the entirety of `v` is closed over
            unsafe { v.transfer(s.borrow_mut()) };
            f(s)
        })
    }
}

impl<T: Bytes + Randomizable> Secret<T> {
    /// Creates a new [`Secret`] filled with random bytes and invokes
    /// the callback with a wrapper to the protected memory.
    ///
    /// ```
    /// # use secrets::Secret;
    /// Secret::<u128>::random(|s| {
    ///     // s is filled with random bytes
    /// })
    /// ```
    pub fn random<F, U>(f: F) -> U
    where
        F: FnOnce(RefMut<'_, T>) -> U,
    {
        Self::new(|mut s| {
            s.randomize();
            f(s)
        })
    }
}

impl<T: Bytes> Drop for Secret<T> {
    /// Ensures that the [`Secret`]'s underlying memory is `munlock`ed
    /// and zeroed when it leaves scope.
    fn drop(&mut self) {
        if unsafe { !sodium::munlock(&raw mut self.data) } {
            // [`Drop::drop`] is called during stack unwinding, so we
            // may be in a panic already.
            assert!(
                thread::panicking(),
                "secrets: unable to munlock memory for a Secret"
            );
        }
    }
}

impl<'a, T: Bytes> RefMut<'a, T> {
    /// Instantiates a new `RefMut`.
    pub(crate) const fn new(data: &'a mut T) -> Self {
        Self { data }
    }
}

impl<T: Bytes + Clone> Clone for RefMut<'_, T> {
    fn clone(&self) -> Self {
        panic!("secrets: a Secret may not be cloned")
    }
}

impl<T: Bytes> Debug for RefMut<'_, T> {
    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
        write!(f, "{{ {} bytes redacted }}", self.data.size())
    }
}

impl<T: Bytes> Deref for RefMut<'_, T> {
    type Target = T;

    fn deref(&self) -> &Self::Target {
        self.data
    }
}
impl<T: Bytes> DerefMut for RefMut<'_, T> {
    fn deref_mut(&mut self) -> &mut Self::Target {
        self.data
    }
}

impl<T: Bytes> PartialEq for RefMut<'_, T> {
    fn eq(&self, rhs: &Self) -> bool {
        self.data.constant_eq(rhs.data)
    }
}

impl<T: Bytes> Eq for RefMut<'_, T> {}

// LCOV_EXCL_START

#[cfg(test)]
mod tests {
    use super::*;
    use std::ptr;

    #[test]
    fn it_defaults_to_garbage_data() {
        Secret::<u16>::new(|s| assert_eq!(*s, 0xdbdb));
    }

    #[test]
    fn it_aligns_to_at_least_the_page_size() {
        let page = page_size::get();
        assert!(align_of::<Secret<u8>>()       >= page);
        assert!(align_of::<Secret<[u8; 32]>>() >= page);
        assert!(align_of::<Secret<[u64; 4]>>() >= page);
    }

    #[test]
    fn it_does_not_share_a_page_between_secrets() {
        // Regression test for #109: two stack-allocated `Secret`s
        // could land on the same page, so dropping one would `munlock`
        // the other's still-live memory.
        Secret::<u64>::zero(|a| {
            let addr_a = &raw const *a as usize;
            let addr_b = Secret::<u64>::zero(|b| &raw const *b as usize);
            let page   = page_size::get();
            assert_ne!(addr_a / page, addr_b / page);
        });
    }

    #[test]
    fn it_zeroes_when_leaving_scope() {
        unsafe {
            let mut ptr: *const _ = ptr::null();

            Secret::<u128>::new(|mut s| {
                // Funnily enough, this test also fails (in release
                // mode) if we set `s` to since the Rust compiler
                // rightly determines that this entire block does
                // nothing and can be optimized away.
                //
                // So we use `sodium::memrandom` which `rustc` doesn't
                // get to perform analysis on to force the compiler to
                // not optimize this whole thing away.
                sodium::memrandom(s.as_mut_bytes());

                // Assign to a pointer that outlives this, which is
                // totally undefined behavior but there's no real other
                // way to test that this works.
                ptr = &*s;
            });

            // This is extremely brittle. It works with integers because
            // they compare equality directly but it doesn't work with
            // arrays since they compare using a function call which
            // clobbers the value of `ptr` since it's pointing to the
            // stack.
            //
            // Still, a test here is better than no test here. It would
            // just be nice if we could also test with arrays, but the
            // logic should work regardless. This was spot-checked in a
            // debugger as well.
            assert_eq!(*ptr, 0);
        }
    }

    #[test]
    fn it_initializes_from_values() {
        Secret::from(&mut 5, |s| assert_eq!(*s, 5_u8));
    }

    #[test]
    fn it_zeroes_values_when_initializing_from() {
        let mut value = 5_u8;

        Secret::from(&mut value, |_| {});

        assert_eq!(value, 0);
    }

    #[test]
    fn it_compares_equality() {
        Secret::<u32>::from(&mut 0x0123_4567, |a| {
            Secret::<u32>::from(&mut 0x0123_4567, |b| {
                assert_eq!(a, b);
            });
        });
    }

    #[test]
    fn it_compares_inequality() {
        Secret::<[u64; 4]>::random(|a| {
            Secret::<[u64; 4]>::random(|b| {
                assert_ne!(a, b);
            });
        });
    }

    #[test]
    fn it_preserves_secrecy() {
        Secret::<[u64; 2]>::zero(|s| {
            assert_eq!(
                format!("{{ {} bytes redacted }}", 16),
                format!("{:?}", s),
            );
        });
    }

    #[test]
    #[should_panic(expected = "secrets: a Secret may not be cloned")]
    fn it_panics_when_cloned() {
        #[allow(clippy::redundant_clone)]
        Secret::<u16>::zero(|s| {
            let _ = s.clone();
        });
    }

    #[test]
    #[should_panic(expected = "secrets: unable to mlock memory for a Secret")]
    fn it_detects_sodium_mlock_failure() {
        sodium::fail();
        Secret::<u8>::zero(|_| {});
    }

    #[test]
    #[should_panic(expected = "secrets: unable to munlock memory for a Secret")]
    fn it_detects_sodium_munlock_failure() {
        Secret::<u8>::zero(|_| sodium::fail());
    }
}

// LCOV_EXCL_STOP