secure-string 0.3.0

A data type suitable for storing sensitive information such as passwords and private keys in memory, featuring constant time equality, mlock and zeroing out.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

# Secure String

[![crates.io](https://img.shields.io/crates/v/secure-string?logo=rust)](https://crates.io/crates/secure-string)
[![crates.io](https://img.shields.io/crates/d/secure-string)](https://crates.io/crates/secure-string)
[![API Docs](https://docs.rs/secure-string/badge.svg)](https://docs.rs/secure-string/)
[![unlicense](https://img.shields.io/badge/un-license-green.svg?style=flat)](https://unlicense.org)

A [Rust] library that implements a data type (wrapper around `Vec<u8>` and other types) suitable for storing sensitive information such as passwords and private keys in memory.
Inspired by Haskell [securemem] and .NET [SecureString].

Featuring:

- Supports various secure datatypes: `SecureVec`, `SecureBytes`, `SecureArray`, `SecureString`, `SecureBox`
- automatically zeroing out in the destructor using [zeroize]
- `mlock` and `madvise` protection if possible
- formatting as `***SECRET***` to prevent leaking into logs
- (optionally) de/serializable into anything [Serde] supports as a byte string
- (optionally) compile-time checked [preconditions] for the public `unsafe` API

This crate is based on [`secstr`](https://crates.io/crates/secstr) by Val Packett, but modified to be a bit more rusty and versatile.

[Rust]: https://www.rust-lang.org
[securemem]: https://hackage.haskell.org/package/securemem
[SecureString]: http://msdn.microsoft.com/en-us/library/system.security.securestring%28v=vs.110%29.aspx
[zeroize]: https://crates.io/crates/zeroize
[Serde]: https://serde.rs/
[preconditions]: https://crates.io/crates/pre

## Usage

```rust
use secure_string::*;

let pw = SecureString::from("correct horse battery staple");

// Compared in constant time:
// (Obviously, you should store hashes in real apps, not plaintext passwords)
let are_pws_equal = pw == SecureString::from("correct horse battery staple".to_string()); // true

// Formatting, printing without leaking secrets into logs
let text_to_print = format!("{}", SecureString::from("hello")); // "***SECRET***"

// Clearing memory
// THIS IS DONE AUTOMATICALLY IN THE DESTRUCTOR
// (but you can force it)
let mut my_sec = SecureString::from("hello");
my_sec.zero_out();
// (It also sets the length to 0)
assert_eq!(my_sec.unsecure(), "");
```

Be careful with `SecureString::from`: if you have a borrowed string, it will be copied.  
Use `SecureString::new` if you have a `Vec<u8>`.

## License

This is free and unencumbered software released into the public domain.  
For more information, please refer to the `UNLICENSE` file or [unlicense.org](https://unlicense.org).