secrets
=======
[![Build Status][badge-ci]][ci]
[![Cargo Crate][badge-package]][package]
[![License][badge-license]][license]
A library to help safely hold cryptographic secrets in memory.
Buffers allocated through this library:
* restrict themselves from being read from and written to by default
* allow access to their contents in explicit, limited scopes
* are never included in core dumps
* are never swapped to permanent storage (using `mlock`)
* are protected from overflows and underflows by inaccessible guard pages (using `mprotect`)
* are protected from underflows by a random canary
* immediately zero out the contents of the memory used to initialize them
* immediately zero out the contents of their allocated memory when they leave scope
Examples
--------
Generating cryptographic keys:
```
use secrets::Secret;
let secret = Secret::<[u8; 32]>::random();
let secret_r = secret.borrow();
println!("{:?}", secret_r);
```
Instantiating a SecretVec from existing mutable data:
```
use secrets::SecretVec;
let mut bytes = *b"\xfa\x12\x00\xd9";
let zeroes = *b"\x00\x00\x00\x00";
let secret = SecretVec::from(&mut bytes[..]);
assert_eq!(zeroes, bytes);
```
Documentation
-------------
[API documentation][docs] for the latest `master` is autogenerated using rustdoc.
License
-------
`secrets` is distributed under the [MIT license][license].
[ci]: https://travis-ci.org/stouset/secrets
[docs]: https://stouset.github.io/secrets
[license]: https://github.com/stouset/secrets/blob/master/LICENSE
[package]: https://crates.io/crates/secrets
[badge-ci]: https://img.shields.io/travis/stouset/secrets.svg
[badge-license]: https://img.shields.io/crates/l/secrets.svg
[badge-package]: https://img.shields.io/crates/v/secrets.svg