DrPeterVanNostrand
7 years ago
parent
b48a4b6812
commit
5f09f96345
@ -0,0 +1,187 @@ |
||||
//! Utilities for working with secret values. This module includes functionality for locking (and
|
||||
//! unlocking) memory into RAM and overwriting memory with zeros.
|
||||
|
||||
use std::env; |
||||
use std::mem::{size_of, size_of_val}; |
||||
use std::ops::{Deref, DerefMut}; |
||||
|
||||
use errno::errno; |
||||
use memsec::{memzero, mlock, munlock}; |
||||
use pairing::bls12_381::Fr; |
||||
|
||||
use error::{Error, Result}; |
||||
|
||||
lazy_static! { |
||||
/// Sets whether or not `mlock`ing is enabled. Memory locking is enabled by default; it can be
|
||||
/// disabled by setting the environment variable `MLOCK_SECRETS=false`. This is useful when you
|
||||
/// are running on a system where you do not have the ability to increase the systems locked
|
||||
/// memory limit (which can be found using the Unix command: `ulimit -l`). For example, we
|
||||
/// disable `mlock`ing of secrets when testing crates that depend on `threshold_crypto` when
|
||||
/// running in Travis CI because Travis has a locked memory limit of 64kb, which we may exceed
|
||||
/// while running `cargo test`. Disabling `mlock`ing for secret values allows secret keys to
|
||||
/// be swapped/core-dumped to disk, resulting in unmanaged copies of secrets to hang around in
|
||||
/// memory; this is significantly less secure than enabling memory locking (the default). Only
|
||||
/// set `MLOCK_SECRETS=false` in development/testing.
|
||||
pub(crate) static ref SHOULD_MLOCK_SECRETS: bool = match env::var("MLOCK_SECRETS") { |
||||
Ok(s) => s.parse().unwrap_or(true), |
||||
_ => true, |
||||
}; |
||||
|
||||
/// The size in bytes of a single field element.
|
||||
pub(crate) static ref FR_SIZE: usize = size_of::<Fr>(); |
||||
} |
||||
|
||||
/// Overwrites a single field element with zeros.
|
||||
pub(crate) fn clear_fr(fr_ptr: *mut u8) { |
||||
unsafe { memzero(fr_ptr, *FR_SIZE) }; |
||||
} |
||||
|
||||
pub(crate) struct MemRange { |
||||
pub ptr: *mut u8, |
||||
pub n_bytes: usize, |
||||
} |
||||
|
||||
/// Marks a type as containing some secret value.
|
||||
pub(crate) trait ContainsSecret { |
||||
/// Returns the range of memory marked as secret.
|
||||
fn secret_memory(&self) -> MemRange; |
||||
|
||||
/// Locks a region of memory marked as secret into RAM.
|
||||
///
|
||||
/// The region of memory marked as secret will not be copied to disk, for example, during a
|
||||
/// swap-to-disk or core dump. This method should be called upon instantiation of every type
|
||||
/// that implements `ContainsSecret`.
|
||||
///
|
||||
/// Operating systems set a limit on the ammount of memory that a process may lock into RAM.
|
||||
/// Due to this limitation, this method returns a `Result` in the event that memory locking
|
||||
/// fails.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// An `Error::MlockFailed` is returned if we reach the system's locked memory limit or if we
|
||||
/// attempt to lock an invalid region of memory.
|
||||
fn mlock_secret(&self) -> Result<()> { |
||||
if !*SHOULD_MLOCK_SECRETS { |
||||
return Ok(()); |
||||
} |
||||
let MemRange { ptr, n_bytes } = self.secret_memory(); |
||||
if n_bytes == 0 { |
||||
return Ok(()); |
||||
} |
||||
let mlock_succeeded = unsafe { mlock(ptr, n_bytes) }; |
||||
if mlock_succeeded { |
||||
Ok(()) |
||||
} else { |
||||
let e = Error::MlockFailed { |
||||
errno: errno(), |
||||
addr: format!("{:?}", ptr), |
||||
n_bytes, |
||||
}; |
||||
Err(e) |
||||
} |
||||
} |
||||
|
||||
/// Unlocks the memory lock for a region of memory marked as secret. If the secret region of
|
||||
/// memory had not previosly been locked via the `.mlock_secret()` method, then this method
|
||||
/// does nothing.
|
||||
///
|
||||
/// Once this method has been called, the secret region of memory will no longer be protected
|
||||
/// from being copied to disk. This method should be called upon destruction of every type that
|
||||
/// implements `ContainsSecret`.
|
||||
///
|
||||
/// # Errors
|
||||
///
|
||||
/// An `Error::MlockFailed` is returned if we attempt to lock an invalid region memory.
|
||||
fn munlock_secret(&self) -> Result<()> { |
||||
if !*SHOULD_MLOCK_SECRETS { |
||||
return Ok(()); |
||||
} |
||||
let MemRange { ptr, n_bytes } = self.secret_memory(); |
||||
if n_bytes == 0 { |
||||
return Ok(()); |
||||
} |
||||
let munlock_succeeded = unsafe { munlock(ptr, n_bytes) }; |
||||
if munlock_succeeded { |
||||
Ok(()) |
||||
} else { |
||||
let e = Error::MunlockFailed { |
||||
errno: errno(), |
||||
addr: format!("{:?}", ptr), |
||||
n_bytes, |
||||
}; |
||||
Err(e) |
||||
} |
||||
} |
||||
|
||||
/// Overwrites the secret region of memory with zeros.
|
||||
///
|
||||
/// This method should be called upon destruction of every type that implements `ContainsSecret`.
|
||||
fn zero_secret(&self) { |
||||
let MemRange { ptr, n_bytes } = self.secret_memory(); |
||||
unsafe { memzero(ptr, n_bytes) }; |
||||
} |
||||
} |
||||
|
||||
/// A wrapper around temporary values to ensuer that they are locked into RAM and cleared on drop.
|
||||
///
|
||||
/// `Safe<T>` is meant to be used a wrapper around `T`, where `T` is either an `&mut U` or
|
||||
/// `Box<U>`.
|
||||
pub(crate) struct Safe<T: DerefMut>(T); |
||||
|
||||
impl<T> Deref for Safe<T> |
||||
where |
||||
T: DerefMut, |
||||
{ |
||||
type Target = T::Target; |
||||
|
||||
fn deref(&self) -> &Self::Target { |
||||
&*(self.0) |
||||
} |
||||
} |
||||
|
||||
impl<T> DerefMut for Safe<T> |
||||
where |
||||
T: DerefMut, |
||||
{ |
||||
fn deref_mut(&mut self) -> &mut Self::Target { |
||||
&mut *(self.0) |
||||
} |
||||
} |
||||
|
||||
impl<T> Drop for Safe<T> |
||||
where |
||||
T: DerefMut, |
||||
{ |
||||
fn drop(&mut self) { |
||||
self.zero_secret(); |
||||
if let Err(e) = self.munlock_secret() { |
||||
panic!("Failed to drop `Safe`: {}", e); |
||||
} |
||||
} |
||||
} |
||||
|
||||
impl<T> ContainsSecret for Safe<T> |
||||
where |
||||
T: DerefMut, |
||||
{ |
||||
fn secret_memory(&self) -> MemRange { |
||||
let ptr = &*self.0 as *const T::Target as *mut u8; |
||||
let n_bytes = size_of_val(&*self.0); |
||||
MemRange { ptr, n_bytes } |
||||
} |
||||
} |
||||
|
||||
impl<T> Safe<T> |
||||
where |
||||
T: DerefMut, |
||||
{ |
||||
pub(crate) fn new(x: T) -> Self { |
||||
Safe::try_new(x).unwrap_or_else(|e| panic!("Failed to create `Safe`: {}", e)) |
||||
} |
||||
|
||||
pub(crate) fn try_new(x: T) -> Result<Self> { |
||||
let safe = Safe(x); |
||||
safe.mlock_secret()?; |
||||
Ok(safe) |
||||
} |
||||
} |
||||
Loading…
Reference in new issue