secrets

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:

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

Holding a decrypted plaintext (pseudocode):

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

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

let ciphertextrw = ciphertext.borrowmut();

crypto::secretbox::opendetached( &ciphertextrw[..], tag, nonce, key ); ```

License

Licensed under either of

at your option.