argon2_kdf/
lib.rs

1#![deny(missing_docs)]
2
3//! A library for hashing passwords and deriving encryption keys using
4//! [Argon2](https://en.wikipedia.org/wiki/Argon2). Argon2 is a memory-hard
5//! [key derivation function](https://en.wikipedia.org/wiki/Key_derivation_function) and was
6//! the winner of the [Password Hashing Competition](https://www.password-hashing.net). It can
7//! generate exceptionally strong hashes.
8//!
9//! This crate is an alternative to the
10//! [argon2 crate](https://docs.rs/rust-argon2/latest/argon2/). The argon2 crate is a pure Rust
11//! implementation, whereas this crate uses
12//! [the original C Argon2 library](https://github.com/P-H-C/phc-winner-argon2). The original C
13//! implementation usually benchmarks faster than the argon2 crate's implementation (though you
14//! really should test it on your own machine--performance benchmarks are rarely universally
15//! applicable).
16//!
17//! This crate was designed with simplicity and ease-of-use in mind. Just take a look at the
18//! examples!
19//!
20//! # Usage
21//!
22//! To use argon2-kdf, add the following to your Cargo.toml:
23//!
24//! ```toml
25//! [dependencies]
26//! argon2-kdf = "1.5.4"
27//! ```
28//! To pass build flags to the C compiler used to build the Argon2 library, you may add a
29//! semicolon-delimited list of flags to the `ARGON2_KDF_C_COMPILER_FLAGS` environment variable.
30//! For example, if you wish to disable the AVX optimizations that are on by default, you can
31//! build using the following command:
32//! `ARGON2_KDF_C_COMPILER_FLAGS="-mno-avx512f;-mno-avx2" cargo build`.
33//!
34//! # Examples
35//!
36//! Hash a password, then verify the hash:
37//!
38//! ```rust
39//! use argon2_kdf::Hasher;
40//!
41//! let password = b"password";
42//! let hash = Hasher::default().hash(password).unwrap();
43//! assert!(hash.verify(password));
44//! ```
45//!
46//! Change the parameters used for hashing:
47//!
48//! ```rust
49//! use argon2_kdf::{Algorithm, Hasher};
50//!
51//! let password = b"password";
52//!
53//! let hash = Hasher::new()
54//!         .algorithm(Algorithm::Argon2id)
55//!         .salt_length(24)
56//!         .hash_length(42)
57//!         .iterations(12)
58//!         .memory_cost_kib(125000)
59//!         .threads(2)
60//!         .hash(password)
61//!         .unwrap();
62//!
63//! assert!(hash.verify(password));
64//! assert_eq!(hash.as_bytes().len(), 42);
65//! assert_eq!(hash.salt_bytes().len(), 24);
66//! ```
67//!
68//! Verify a hash from a hash string:
69//!
70//! ```rust
71//! use argon2_kdf::{Hash, Hasher};
72//! use std::str::FromStr;
73//!
74//! let password = b"password";
75//! let hash_string = "$argon2id$v=19$m=128,t=2,p=1$VnZ3ZFNhZkc$djHLRc+4K/DqQL0f8DMAQQ";
76//!
77//! let hash = Hash::from_str(hash_string).unwrap();
78//! assert!(hash.verify(password));
79//! ```
80//!
81//! Generate a hash string:
82//!
83//! ```rust
84//! use argon2_kdf::{Hash, Hasher};
85//! use std::str::FromStr;
86//!
87//! let password = b"password";
88//! let hash = Hasher::default().hash(password).unwrap();
89//!
90//! let hash_string = hash.to_string();
91//!
92//! assert!(Hash::from_str(&hash_string).unwrap().verify(password));
93//! ```
94//!
95//! Use a secret (sometimes called a
96//! "[pepper](https://en.wikipedia.org/wiki/Pepper_(cryptography))") for hashing and
97//! verification:
98//!
99//! ```rust
100//! use argon2_kdf::{Hasher, Secret};
101//!
102//! let password = b"password";
103//! let secret = b"secret";
104//!
105//! let hash = Hasher::default()
106//!         .secret(secret.into())
107//!         .hash(password)
108//!         .unwrap();
109//!
110//! assert!(hash.verify_with_secret(password, secret.into()));
111//! ```
112//!
113//! Use your own salt (by default, the hasher will use a secure-random salt):
114//!
115//! ```rust
116//! use argon2_kdf::Hasher;
117//!
118//! let password = b"password";
119//! let salt = b"dontusethissalt";
120//!
121//! let hash = Hasher::default()
122//!         .custom_salt(salt)
123//!         .hash(password)
124//!         .unwrap();
125//!
126//! assert!(hash.verify(password));
127//! ```
128
129mod bindings;
130mod error;
131mod hasher;
132mod lexer;
133
134pub use error::Argon2Error;
135pub use hasher::{Algorithm, Hash, Hasher, Secret};
argon2_kdf/lib.rs

argon2_kdf/
lib.rs
