Crate argon2[][src]

Pure Rust implementation of the Argon2 password hashing function.

About

Argon2 is a memory-hard key derivation function chosen as the winner of the Password Hashing Competition in July 2015.

It provides three algorithmic variants (chosen via the Algorithm enum):

  • Argon2d: maximizes resistance to GPU cracking attacks
  • Argon2i: optimized to resist side-channel attacks
  • Argon2id: (default) hybrid version

Usage (simple with default params)

Note: this example requires the rand_core crate with the std feature enabled for rand_core::OsRng (embedded platforms can substitute their own RNG)

Add the following to your crate's Cargo.toml to import it:

[dependencies]
argon2 = "0.1"
rand_core = { version = "0.6", features = ["std"] }

The following example demonstrates the high-level password hashing API:

use argon2::{
    password_hash::{PasswordHash, PasswordHasher, PasswordVerifier, SaltString},
    Argon2
};
use rand_core::OsRng;

let password = b"hunter42"; // Bad password; don't actually use!
let salt = SaltString::generate(&mut OsRng);

// Argon2 with default params (Argon2id v19)
let argon2 = Argon2::default();

// Hash password to PHC string ($argon2id$v=19$...)
let password_hash = argon2.hash_password_simple(password, salt.as_ref()).unwrap().to_string();

// Verify password against PHC string
let parsed_hash = PasswordHash::new(&password_hash).unwrap();
assert!(argon2.verify_password(password, &parsed_hash).is_ok());

Notes

Multithreading has not yet been implemented.

Increasing the parallelism factor will still compute the correct results, but there will be no associated performance improvement.

Re-exports

pub use password_hash;

Structs

Argon2

Argon2 context.

Paramspassword-hash

Argon2 password hash parameters.

PasswordHashpassword-hash

Password hash.

Enums

Algorithm

Argon2 primitive type: variants of the algorithm.

Error

Error type.

Version

Version of the algorithm.

Constants

ARGON2D_IDENTpassword-hash

Argon2d algorithm identifier

ARGON2ID_IDENTpassword-hash

Argon2id algorithm identifier

ARGON2I_IDENTpassword-hash

Argon2i algorithm identifier

BLOCK_SIZE

Memory block size in bytes

MAX_AD_LENGTH

Minimum and maximum associated data length in bytes

MAX_LANES

Minimum and maximum number of lanes (degree of parallelism)

MAX_MEMORY

Maximum number of memory blocks (each of BLOCK_SIZE bytes)

MAX_OUTLEN

Maximum digest size in bytes

MAX_PWD_LENGTH

Maximum password length in bytes

MAX_SALT_LENGTH

Maximum salt length in bytes

MAX_SECRET

Maximum key length in bytes

MAX_THREADS

Minimum and maximum number of threads

MAX_TIME

Maximum number of passes

MIN_LANES

Minimum and maximum number of lanes (degree of parallelism)

MIN_MEMORY

Minimum number of memory blocks (each of BLOCK_SIZE bytes)

MIN_OUTLEN

Minimum digest size in bytes

MIN_SALT_LENGTH

Minimum and maximum salt length in bytes

MIN_THREADS

Minimum and maximum number of threads

MIN_TIME

Minimum number of passes

Traits

PasswordHasherpassword-hash

Trait for password hashing functions.

PasswordVerifierpassword-hash

Trait for password verification.