secrets 0.12.0

Protected-access memory for cryptographic secrets
Documentation

secrets

Build Status Test Coverage Cargo Crate License

secrets is a library to help Rust programmers safely held cryptographic secrets in memory.

It is mostly an ergonomic wrapper around the memory-protection utilities provided by libsodium.

Fixed-size buffers allocated on the stack gain the following protections:

  • mlock(2) is called on the underlying memory
  • the underlying memory is zeroed out when no longer in use
  • they are borrowed for their entire lifespan, so cannot be moved
  • they are compared in constant time
  • they are prevented from being printed by Debug
  • they are prevented from being Cloned

Fixed and variable-sized buffers can be allocated on the heap and gain the following protections:

  • the underlying memory is protected from being read from or written to with mprotect(2) unless an active borrow is in scope
  • mlock(2) is called on the allocated memory
  • the underlying memory is zeroed out when no longer in use
  • overflows and underflows are detected using inaccessible guard pages, causing an immediate segmentation fault and program termination
  • short underflows that write to memory are detected when memory is freed using canaries, and will result in a segmentation fault and program termination

Examples

Generating cryptographic keys:

Secret::<[u8; 16]>::random(|s| {
     // use `s` as if it were a `&mut [u8; 16]`
});

Holding a decrypted plaintext (pseudocode):

let key = SecretBox::<[u8; 16]>::new(|mut s| {
    /// initialized from some preexisting key
});

let mut ciphertext = SecretVec::<u8>::from(&mut b"..."); // some ciphertext
let     nonce      = b"..."; // some nonce
let     tag        = b"..."; // some authentication tag

let ciphertext_rw = ciphertext.borrow_mut();

crypto::secretbox::open_detached(
    &ciphertext_rw[..],
    tag, nonce, key
);

License

Licensed under either of

at your option.