Skip to main content

Crate argon2

Crate argon2 

Source
Expand description

§RustCrypto: Argon2

crate Docs Build Status Apache2/MIT licensed Rust Version Project Chat

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 implements the following three algorithmic variants:

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

Support is provided for embedded (i.e. no_std) environments, including ones without alloc support.

§License

Licensed under either of:

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

§Usage

§Password Hashing

This API hashes a password to a “PHC string” suitable for the purposes of password-based authentication. Do not use this API to derive cryptographic keys: see the “key derivation” usage example below.

// NOTE: example requires `getrandom` feature is enabled

use argon2::{
    password_hash::{PasswordHasher, PasswordVerifier, phc::PasswordHash},
    Argon2
};

let password = b"hunter42"; // Bad password; don't actually use!

// Argon2 with default params (Argon2id v19), generating a random salt
let argon2 = Argon2::default();

// Hash password to PHC string ($argon2id$v=19$...)
let password_hash = argon2.hash_password(password)?.to_string();

// Verify password against PHC string.
//
// NOTE: hash params from `parsed_hash` are used instead of what is configured in the
// `Argon2` instance.
let parsed_hash = PasswordHash::new(&password_hash)?;
assert!(Argon2::default().verify_password(password, &parsed_hash).is_ok());

To pepper as well as salt your passwords:

// NOTE: example requires `getrandom` feature is enabled

use argon2::{
    password_hash::{PasswordHasher, PasswordVerifier, phc::PasswordHash},
    Algorithm, Argon2, Params, Version
};

let password = b"hunter42"; // Bad password; don't actually use!

// Argon2 with default params (Argon2id v19) and pepper
let argon2 = Argon2::new_with_secret(
    b"secret pepper",
    Algorithm::default(),
    Version::default(),
    Params::default()
)?;

// Hash password to PHC string ($argon2id$v=19$...), generating a random salt
let password_hash = argon2.hash_password(password)?.to_string();

// Verify password against PHC string.
//
// NOTE: hash params from `parsed_hash` are used instead of what is configured in the
// `Argon2` instance.
let parsed_hash = PasswordHash::new(&password_hash)?;
let argon2 = Argon2::new_with_secret(
    b"secret pepper",
    Algorithm::default(),
    Version::default(),
    Params::default(),
)
.unwrap();
let res = argon2.verify_password(password, &parsed_hash);
assert!(res.is_ok());

§Key Derivation

This API is useful for transforming a password into cryptographic keys for e.g. password-based encryption.

use argon2::Argon2;

let password = b"hunter42"; // Bad password; don't actually use!
let salt = b"example salt"; // Salt should be unique per password

let mut output_key_material = [0u8; 32]; // Can be any desired size
Argon2::default().hash_password_into(password, salt, &mut output_key_material)?;

Re-exports§

pub use password_hash;

Modules§

algorithm 🔒
Argon2 algorithms (e.g. Argon2d, Argon2i, Argon2id).
avx2_cpuid 🔒
blake2b_long 🔒
The variable length hash function used in the Argon2 algorithm.
block 🔒
Argon2 memory block functions
error 🔒
Error type
memory 🔒
Views into Argon2 memory that can be processed in parallel.
params 🔒
Argon2 password hash parameters.
version 🔒
Version of the algorithm.

Structs§

Argon2
Argon2 context.
AssociatedData
Associated data
Block
Structure for the (1 KiB) memory block implemented as 128 64-bit words.
KeyId
Key identifier
Params
Argon2 password hash parameters.
ParamsBuilder
Builder for Argon2 Params.
PasswordHash
Password hash.

Enums§

Algorithm
Argon2 primitive type: variants of the algorithm.
Error
Error type.
Version
Version of the algorithm.

Constants§

ADDRESSES_IN_BLOCK 🔒
To generate reference block positions
ARGON2D_IDENT
Argon2d algorithm identifier
ARGON2ID_IDENT
Argon2id algorithm identifier
ARGON2I_IDENT
Argon2i algorithm identifier
MAX_PWD_LEN
Maximum password length in bytes.
MAX_SALT_LEN
Maximum salt length in bytes.
MAX_SECRET_LEN
Maximum secret key length in bytes.
MIN_SALT_LEN
Minimum salt length in bytes.
RECOMMENDED_SALT_LEN
Recommended salt length for password hashing in bytes.
SYNC_POINTS 🔒
Number of synchronization points between lanes per pass

Traits§

CustomizedPasswordHasher
Trait for password hashing functions which support customization.
PasswordHasher
High-level trait for password hashing functions.
PasswordVerifier
Trait for password verification.

Type Aliases§

Result
Result with argon2’s Error type.