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.6.1"
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//! Verify a hash from bytes:
82//!
83//! ```rust
84//! use argon2_kdf::{Algorithm, Hash};
85//! use std::str::FromStr;
86//!
87//! let salt = b"testsalt";
88//! let hash_bytes = [155, 147, 76, 205, 220, 49, 114, 102];
89//!
90//! let hash = Hash::from_parts(
91//!     &hash_bytes,
92//!     salt,
93//!     Algorithm::Argon2id,
94//!     16,
95//!     1,
96//!     1,
97//! );
98//! assert!(hash.verify(b"password"));
99//! ```
100//!
101//! Generate a hash string:
102//!
103//! ```rust
104//! use argon2_kdf::{Hash, Hasher};
105//! use std::str::FromStr;
106//!
107//! let password = b"password";
108//! let hash = Hasher::default().hash(password).unwrap();
109//!
110//! let hash_string = hash.to_string();
111//!
112//! assert!(Hash::from_str(&hash_string).unwrap().verify(password));
113//! ```
114//!
115//! Use a secret (sometimes called a
116//! "[pepper](https://en.wikipedia.org/wiki/Pepper_(cryptography))") for hashing and
117//! verification:
118//!
119//! ```rust
120//! use argon2_kdf::{Hasher, Secret};
121//!
122//! let password = b"password";
123//! let secret = b"secret";
124//!
125//! let hash = Hasher::default()
126//!         .secret(secret.into())
127//!         .hash(password)
128//!         .unwrap();
129//!
130//! assert!(hash.verify_with_secret(password, secret.into()));
131//! ```
132//!
133//! Use your own salt (by default, the hasher will use a secure-random salt):
134//!
135//! ```rust
136//! use argon2_kdf::Hasher;
137//!
138//! let password = b"password";
139//! let salt = b"dontusethissalt";
140//!
141//! let hash = Hasher::default()
142//!         .custom_salt(salt)
143//!         .hash(password)
144//!         .unwrap();
145//!
146//! assert!(hash.verify(password));
147//! ```
148
149mod bindings;
150mod error;
151mod hasher;
152mod lexer;
153
154pub use error::Argon2Error;
155pub use hasher::{Algorithm, Hash, Hasher, Secret};
argon2_kdf/lib.rs

argon2_kdf/
lib.rs
