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
59
60
61
62
63
64
65
66
67
68

//! Password Hashing
//!
//! Secret keys used to encrypt or sign confidential data have to be chosen from
//! a very large keyspace. However, passwords are usually short, human-generated
//! strings, making dictionary attacks practical.
//!
//! The pwhash operation derives a secret key of any size from a password and a
//! salt.
//!
//! - The generated key has the size defined by the application, no matter what
//!   the password length is.
//! - The same password hashed with same parameters will
//!   always produce the same key.
//! - The same password hashed with different salts
//!   will produce different keys.
//! - The function deriving a key from a password
//!   and a salt is CPU intensive and intentionally requires a fair amount of
//!   memory. Therefore, it mitigates brute-force attacks by requiring a
//!   significant effort to verify each password.
//!
//! Common use cases:
//!
//! - Protecting an on-disk secret key with a password,
//! - Password storage, or rather: storing what it takes to verify a password
//!   without having to store the actual password.
//!
//! # Example (key derivation)
//! ```
//! use sodiumoxide::crypto::secretbox;
//! use sodiumoxide::crypto::pwhash;
//!
//! let passwd = b"Correct Horse Battery Staple";
//! let salt = pwhash::gen_salt();
//! let mut k = secretbox::Key([0; secretbox::KEYBYTES]);
//! {
//!     let secretbox::Key(ref mut kb) = k;
//!     pwhash::derive_key(kb, passwd, &salt,
//!                        pwhash::OPSLIMIT_INTERACTIVE,
//!                        pwhash::MEMLIMIT_INTERACTIVE).unwrap();
//! }
//! ```
//!
//! # Example (password hashing)
//! ```
//! use sodiumoxide::crypto::pwhash;
//! let passwd = b"Correct Horse Battery Staple";
//! let pwh = pwhash::pwhash(passwd,
//!                          pwhash::OPSLIMIT_INTERACTIVE,
//!                          pwhash::MEMLIMIT_INTERACTIVE).unwrap();
//! let pwh_bytes = &pwh[..];
//! //store pwh_bytes somewhere
//! ```
//!
//! # Example (password verification)
//! ```
//! use sodiumoxide::crypto::pwhash;
//!
//! let passwd = b"Correct Horse Battery Staple";
//! // in reality we want to load the password hash from somewhere
//! // and we might want to create a `HashedPassword` from it using
//! // `HashedPassword::from_slice(pwhash_bytes).unwrap()`
//! let pwh = pwhash::pwhash(passwd,
//!                          pwhash::OPSLIMIT_INTERACTIVE,
//!                          pwhash::MEMLIMIT_INTERACTIVE).unwrap();
//! assert!(pwhash::pwhash_verify(&pwh, passwd));
//! ```
pub use self::scryptsalsa208sha256::*;
pub mod scryptsalsa208sha256;