1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153

use refs::{Ref, RefMut};
use sec::Sec;

use std::borrow::BorrowMut;

/// A type that wraps allocated memory suitable for cryptographic
/// secrets.
///
/// When initialized with existing data, the memory of the existing
/// data is zeroed out. That said, this library cannot guarantee that
/// that memory has not been copied elsewhere, swapped to disk, or
/// otherwise handled insecurely so rely on this with caution.
///
/// # Examples
///
/// Random secrets:
///
/// ```
/// use secrets::Secret;
///
/// let secret   = Secret::random(32);
/// let secret_r = secret.borrow();
///
/// println!("{:?}", secret_r.as_slice());
/// ```
///
/// Secrets from existing mutable data:
///
/// ```
/// use secrets::Secret;
///
/// let mut string   = "string".to_string();
/// let     secret   = Secret::from(unsafe { string.as_mut_vec() });
/// let     secret_r = secret.borrow();
///
/// assert_eq!("\0\0\0\0\0\0", string);
/// assert_eq!(b"string",      secret_r.as_slice());
/// ```
///
/// Secrets as pointers:
///
/// ```
/// use secrets::Secret;
/// use std::ptr;
///
/// let mut secret   = Secret::bytes(4);
/// let mut secret_w = secret.borrow_mut();
///
/// unsafe { ptr::write_bytes(secret_w.as_mut_ptr(), 0xff, secret_w.len()) };
///
/// assert_eq!([0xff, 0xff, 0xff, 0xff], secret_w.as_slice());
/// ```
///
#[derive(Debug)]
pub struct Secret<T> {
    sec: Sec<T>,
}

impl<'a, T> From<&'a mut T> for Secret<u8> where T: BorrowMut<[u8]> {
    fn from(bytes: &'a mut T) -> Secret<u8> {
        Secret { sec: Sec::from(bytes.borrow_mut()) }
    }
}

impl<T> PartialEq for Secret<T> {
    fn eq(&self, other: &Secret<T>) -> bool {
        self.sec == other.sec
    }
}

impl<T> Eq for Secret<T> {}

impl Secret<u8> {
    /// Creates a new Secret capable of storing `len` bytes.
    ///
    /// By default, the allocated region is filled with 0xd0 bytes in
    /// order to help catch bugs due to uninitialized data.
    pub fn bytes(len: usize) -> Self {
        Secret::new(len)
    }

    /// Creates a new Secret filled with `len` bytes of
    /// cryptographically random data.
    pub fn random(len: usize) -> Self {
        Secret { sec: Sec::random(len) }
    }
}

impl<T> Secret<T> {
    /// Creates a new Secret capable of storing `len` elements of type
    /// `T`.
    ///
    /// By default, the allocated region is filled with 0xd0 bytes in
    /// order to help catch bugs due to uninitialized data.
    pub fn new(len: usize) -> Self {
        Secret { sec: Sec::new(len) }
    }

    /// Returns the number of elements in the Secret.
    pub fn len(&self) -> usize { self.sec.len() }

    /// Returns a `Ref<T>` from which elements in the `Secret` can be
    /// safely read from, via either pointer or slice semantics.
    pub fn borrow(&self) -> Ref<T> {
        Ref::new(&self.sec)
    }

    /// Returns a `Ref<T>` from which elements in the `Secret` can be
    /// safely read from or written to, via either pointer or slice
    /// semantics.
    pub fn borrow_mut(&mut self) -> RefMut<T> {
        RefMut::new(&mut self.sec)
    }
}

#[cfg(test)]
mod tests {
    #![allow(unsafe_code)]
    use super::Secret;

    #[test]
    fn it_creates_byte_buffers() {
        let secret = Secret::bytes(1397);

        assert_eq!(1397, secret.len());
    }

    #[test]
    fn it_creates_random_byte_buffers() {
        let secret_1 = Secret::random(128);
        let secret_2 = Secret::random(128);

        // if this ever fails, modern crypto is doomed
        assert!(secret_1 != secret_2);
    }

    #[test]
    fn it_copies_input_memory() {
        let mut string   = "string".to_string();
        let     secret   = Secret::from(unsafe { string.as_mut_vec() });
        let     secret_r = secret.borrow();

        assert_eq!(b"string", secret_r.as_slice());
    }

    #[test]
    fn it_zeroes_out_input_memory() {
        let mut string = "string".to_string();
        let     _      = Secret::from(unsafe { string.as_mut_vec() });

        assert_eq!("\0\0\0\0\0\0", string);
    }
}