Crate bonsaidb::local::argon2[]

Expand description

RustCrypto: Argon2

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

Pure Rust implementation of the Argon2 password hashing function.

Documentation

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 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.

Minimum Supported Rust Version

Rust 1.57 or higher.

Minimum supported Rust version can be changed in the future, but it will be done with a minor version bump.

SemVer Policy

  • All on-by-default features of this library are covered by SemVer
  • MSRV is considered exempt from SemVer as noted above

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 (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.3"
rand_core = { version = "0.6", features = ["std"] }

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

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

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(password, &salt)?.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());

Modules

RustCrypto: Password Hashing Traits

Structs

Argon2 context.

Structure for the (1KB) memory block implemented as 128 64-bit words.

Argon2 password hash parameters.

Builder for Argon2 Params.

Password hash.

Enums

Argon2 primitive type: variants of the algorithm.

Error type.

Version of the algorithm.

Constants

Argon2d algorithm identifier

Argon2id algorithm identifier

Argon2i algorithm identifier

Maximum password length in bytes.

Maximum salt length in bytes.

Maximum secret key length in bytes.

Minimum and maximum salt length in bytes.

Traits

Trait for password hashing functions.

Trait for password verification.

Type Definitions

Result with argon2’s Error type.