pub struct SecretBox<T: Bytes> { /* private fields */ }Expand description
A type for protecting fixed-length secrets allocated on the heap.
Heap-allocated secrets have distinct security needs from stack-allocated ones. They provide the following guarantees:
- any attempt to access the memory without having been borrowed
appropriately will result in immediate program termination; the
memory is protected with
mprotect(2)as follows:PROT_NONEwhen theSecretBoxhas no outstanding borrowsPROT_READwhen it has outstanding immutable borrowsPROT_WRITEwhen it has an outstanding mutable borrow
- the allocated region has guard pages preceding and following
it—both set to
PROT_NONE—ensuring that overflows and (large enough) underflows cause immediate program termination - a canary is placed just before the memory location (and after the
guard page) in order to detect smaller underflows; if this memory
has been written to (and the canary modified), the program will
immediately abort when the
SecretBoxisdropped mlock(2)is called on the underlying memorymunlock(2)is called on the underlying memory when no longer in use- the underlying memory is zeroed when no longer in use
- they are best-effort compared in constant time
- they are best-effort prevented from being printed by
Debug. - they are best-effort protected from
Cloneing the interior data
To fulfill these guarantees, SecretBox uses an API similar to
(but not exactly like) that of RefCell. You must call
borrow to (immutably) borrow the protected
data inside and you must call borrow_mut
to access it mutably. Unlike RefCell which hides
interior mutability with immutable borrows, these two calls follow
standard borrowing rules: borrow_mut
takes a &mut self, so the borrow checker statically ensures the
exclusivity of mutable borrows.
These borrow and
borrow_mut calls return a wrapper around
the interior that ensures the memory is re-mprotected
when all active borrows leave scope. These wrappers Deref to the
underlying value so you can to work with them as if they were the
underlying type, with a few excepitons: they have specific
implementations for Clone, Debug, PartialEq, and Eq
that try to ensure that the underlying memory isn’t copied out of
protected area, that the contents are never printed, and that two
secrets are only ever compared in constant time.
Care must be taken not to over-aggressively dereference these wrappers, as once you’re working with the real underlying type, we can’t prevent direct calls to their implementations of these traits. Care must also be taken not to call any other methods on these types that introduce copying.
§Example: generate a cryptographically-random 128-bit SecretBox
Initialize a SecretBox with cryptographically random data:
let secret = SecretBox::<u128>::random();
assert_eq!(secret.size(), 16);§Example: move mutable data into a SecretBox
Existing data can be moved into a SecretBox. 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.
let mut value = 0x0011223344556677u128;
// the contents of `value` will be copied into the SecretBox before
// being zeroed out
let secret = SecretBox::from(&mut value);
// the contents of `value` have been zeroed
assert_eq!(value, 0);§Example: compilation failure from incompatible borrows
Unlike RefCell, which hides interior mutability behind
immutable borrows, a SecretBox can’t have an outstanding
borrow and
borrow_mut at the same time.
let mut secret = SecretBox::<u32>::zero(8);
let secret_r = secret.borrow();
// error[E0502]: cannot borrow `secret` as mutable because it is
// also borrowed as immutable
secret.borrow_mut();§Example: compilation failure from multiple mutable borrows
Unlike RefCell, which hides interior mutability behind
immutable borrows, a SecretBox can’t have multiple outstanding
borrow_muts at the same time.
let mut secret = SecretBox::<u32>::zero(8);
let secret_w = secret.borrow_mut();
// error[E0499]: cannot borrow `secret` as mutable more than once
// at a time
secret.borrow_mut();Implementations§
Source§impl<T: Bytes> SecretBox<T>
impl<T: Bytes> SecretBox<T>
Sourcepub fn new<F>(f: F) -> Self
pub fn new<F>(f: F) -> Self
Instantiates and returns a new SecretBox.
Accepts a callback function that is responsible for initializing its contents. The value yielded to the initialization callback will be filled with garbage bytes.
Example:
let secret = SecretBox::<u8>::new(|s| *s = 0x20);
assert_eq!(*secret.borrow(), 0x20);Sourcepub fn borrow(&self) -> Ref<'_, T>
pub fn borrow(&self) -> Ref<'_, T>
Immutably borrows the contents of the SecretBox. Returns a
wrapper that ensures the underlying memory is
mprotect(2)ed once all borrows exit scope.
Example:
let secret = SecretBox::<u8>::from(&mut 127);
let secret_r1 = secret.borrow();
let secret_r2 = secret.borrow();
assert_eq!(*secret_r1, 127);
assert_eq!(*secret_r2, 127);
assert_eq!(secret_r1, secret_r2);Sourcepub fn borrow_mut(&mut self) -> RefMut<'_, T>
pub fn borrow_mut(&mut self) -> RefMut<'_, T>
Mutably borrows the contents of the SecretBox. Returns a
wrapper that ensures the underlying memory is
mprotect(2)ed once this borrow exits scope.
Example:
let mut secret = SecretBox::<u8>::zero();
let mut secret_w = secret.borrow_mut();
*secret_w = 0xaa;
assert_eq!(*secret_w, 0xaa);