Rust argon2-kdf

A library for hashing passwords and deriving encryption keys using Argon2. Argon2 is a memory-hard key derivation function and was the winner of the Password Hashing Competition. It can generate exceptionally strong hashes.

This crate is an alternative to the argon2 crate. The argon2 crate is a pure Rust implementation, whereas this crate uses the original C Argon2 library. The original C implementation usually benchmarks faster than the argon2 crate's implementation (though you really should test it on your own machine--performance benchmarks are rarely universally applicable).

This crate was designed with simplicity and ease-of-use in mind. Just take a look at the examples!

Usage

To use argon2-kdf, add the following to your Cargo.toml:

toml [dependencies] argon2-kdf = "1.0"

Examples

Hash a password, then verify the hash:

```rust use argon2_kdf::Hasher;

let password = "password"; let hash = Hasher::default().hash(&password).unwrap(); assert!(hash.verify(&password)); ```

Change the parameters used for hashing:

```rust use argon2_kdf::{Algorithm, Hasher};

let password = "password";

let hash = Hasher::new() .algorithm(Algorithm::Argon2id) .saltlength(24) .hashlength(42) .iterations(12) .memorycostkib(125000) .threads(2) .hash(&password) .unwrap();

assert!(hash.verify(&password)); asserteq!(hash.asbytes().len(), 42); assert_eq!(hash.salt().len(), 24); ```

Verify a hash from a hash string:

```rust use argon2_kdf::{Hash, Hasher}; use std::str::FromStr;

let password = "password"; let hash_string = "$argon2id$v=19$m=128,t=2,p=1$VnZ3ZFNhZkc$djHLRc+4K/DqQL0f8DMAQQ";

let hash = Hash::fromstr(hashstring).unwrap(); assert!(hash.verify(&password)); ```

Generate a hash string:

```rust use argon2_kdf::{Hash, Hasher}; use std::str::FromStr;

let password = "password"; let hash = Hasher::default().hash(&password).unwrap();

let hashstring = hash.tostring();

assert!(Hash::fromstr(&hashstring).unwrap().verify(&password)); ```

Use a secret (sometimes called a "pepper") for hashing and verification:

```rust use argon2_kdf::{Hasher, Secret};

let password = "password"; let secret = b"secret";

let hash = Hasher::default() .secret(Secret::using_bytes(secret)) .hash(&password) .unwrap();

assert!(hash.verifywithsecret(&password, Secret::using_bytes(secret))); ```

Use your own salt (by default, the hasher will use a secure-random salt):

```rust use argon2_kdf::Hasher;

let password = "password"; let salt = b"dontusethissalt";

let hash = Hasher::default() .custom_salt(salt) .hash(&password) .unwrap();

assert!(hash.verify(&password)); ```