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
Panic Safety
This library is explicitly not panic-safe. To ensure the safety of protected memory space, this library can and will panic if it is unable to enforce its advertised guarantees.
Similarly, this library will cause segmentation faults if (and only if) it detects certain safety violations. For example, this can happen if a process attempts to directly read or write to the contents of memory that hasn't been properly unlocked, or if canaries have been overwritten. This library has been written to ensure that such violations should be impossible to cause through well-formed Rust, and so should only occur as a result of a security vulnerability.
Examples
Example: generating cryptographic keys
Secret::<[u8; 16]>::random(|s| {
// use `s` as if it were a `&mut [u8; 16]`
//
// the memory is `mlock(2)`ed and will be zeroed when this closure
// exits
});
Example: load a master key from disk and generate subkeys from it
use std::fs::File;
use std::io::Read;
use libsodium_sys as sodium;
use secrets::SecretBox;
const KEY_LEN : usize = sodium::crypto_kdf_KEYBYTES as _;
const CTX_LEN : usize = sodium::crypto_kdf_CONTEXTBYTES as _;
const CONTEXT : &[u8; CTX_LEN] = b"example\0";
fn derive_subkey(
key: &[u8; KEY_LEN],
context: &[u8; CTX_LEN],
subkey_id: u64,
subkey: &mut [u8],
) {
unsafe {
libsodium_sys::crypto_kdf_derive_from_key(
subkey.as_mut_ptr(),
subkey.len(),
subkey_id,
context.as_ptr().cast(),
key.as_ptr()
);
}
}
let master_key = SecretBox::<[u8; KEY_LEN]>::try_new(|mut s| {
File::open("example/master_key/key")?.read_exact(s)
})?;
let subkey_0 = SecretBox::<[u8; 16]>::new(|mut s| {
derive_subkey(&master_key.borrow(), CONTEXT, 0, s);
});
let subkey_1 = SecretBox::<[u8; 16]>::new(|mut s| {
derive_subkey(&master_key.borrow(), CONTEXT, 1, s);
});
assert_ne!(
subkey_0.borrow(),
subkey_1.borrow(),
);
Example: securely storing a decrypted ciphertext in memory
use std::fs::File;
use std::io::Read;
use libsodium_sys as sodium;
use secrets::{SecretBox, SecretVec};
const KEY_LEN : usize = sodium::crypto_secretbox_KEYBYTES as _;
const NONCE_LEN : usize = sodium::crypto_secretbox_NONCEBYTES as _;
const MAC_LEN : usize = sodium::crypto_secretbox_MACBYTES as _;
let mut key = SecretBox::<[u8; KEY_LEN]>::zero();
let mut nonce = [0; NONCE_LEN];
let mut ciphertext = Vec::new();
File::open("example/decrypted_ciphertext/key")?
.read_exact(key.borrow_mut().as_mut())?;
File::open("example/decrypted_ciphertext/nonce")?
.read_exact(&mut nonce)?;
File::open("example/decrypted_ciphertext/ciphertext")?
.read_to_end(&mut ciphertext)?;
let plaintext = SecretVec::<u8>::new(ciphertext.len() - MAC_LEN, |mut s| {
if -1 == unsafe {
sodium::crypto_secretbox_open_easy(
s.as_mut_ptr(),
ciphertext.as_ptr(),
ciphertext.len() as _,
nonce.as_ptr(),
key.borrow().as_ptr(),
)
} {
panic!("failed to authenticate ciphertext during decryption");
}
});
assert_eq!(
*b"attack at dawn",
*plaintext.borrow(),
);
License
Licensed under either of
at your option.
914 Dec 30, 2022
![[ZenGo X]](https://avatars.githubusercontent.com/u/40664522?v=4&s=40)
42 Jan 4, 2023
19 Dec 14, 2022
63 Dec 26, 2022
20.3k Jan 1, 2023
2.3k Dec 26, 2022
2 Aug 31, 2022
1.1k Jan 4, 2023
0 Dec 24, 2021
253 Dec 31, 2022
35 Sep 24, 2022
548 Dec 26, 2022
3.6k Dec 30, 2022
427 Dec 24, 2022
26 Dec 4, 2022
43 Dec 17, 2022
1.5k Jan 1, 2023
26 Nov 28, 2022