blackwriter-server/doc/argon2.md

Crate Documentation

Version: 0.5.3

Format Version: 56

Module argon2

RustCrypto: Argon2

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

• Apache License, Version 2.0
• MIT license

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.

# fn main() -> Result<(), Box<dyn std::error::Error>> {
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());
# Ok(())
# }

Key Derivation

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

# fn main() -> Result<(), Box<dyn std::error::Error>> {
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)?;
# Ok(())
# }

Types

Struct Argon2

Argon2 context.

This is the primary type of this crate's API, and contains the following:

• Argon2 [Algorithm] variant to be used
• Argon2 [Version] to be used
• Default set of [Params] to be used
• (Optional) Secret key a.k.a. "pepper" to be used

pub struct Argon2<''key> {
    // Some fields omitted
}

Fields

Name	Type	Documentation
private fields	...	Some fields have been omitted

Implementations

Methods

• pub fn new(algorithm: Algorithm, version: Version, params: Params) -> Self { /* ... */ }
  

  Create a new Argon2 context.

• pub fn new_with_secret(secret: &''key [u8], algorithm: Algorithm, version: Version, params: Params) -> Result<Self> { /* ... */ }
  

  Create a new Argon2 context.

• pub fn hash_password_into(self: &Self, pwd: &[u8], salt: &[u8], out: &mut [u8]) -> Result<()> { /* ... */ }
  

  Hash a password and associated parameters into the provided output buffer.

• pub fn hash_password_into_with_memory</* synthetic */ impl AsMut<[Block]>: AsMut<[Block]>>(self: &Self, pwd: &[u8], salt: &[u8], out: &mut [u8], memory_blocks: impl AsMut<[Block]>) -> Result<()> { /* ... */ }
  

  Hash a password and associated parameters into the provided output buffer.

• pub fn fill_memory</* synthetic */ impl AsMut<[Block]>: AsMut<[Block]>>(self: &Self, pwd: &[u8], salt: &[u8], memory_blocks: impl AsMut<[Block]>) -> Result<()> { /* ... */ }
  

  Use a password and associated parameters only to fill the given memory blocks.

• pub const fn params(self: &Self) -> &Params { /* ... */ }
  

  Get default configured [Params].

Trait Implementations

• Any

  • fn type_id(self: &Self) -> TypeId { /* ... */ }
    

• Borrow

  • fn borrow(self: &Self) -> &T { /* ... */ }
    

• BorrowMut

  • fn borrow_mut(self: &mut Self) -> &mut T { /* ... */ }
    

• Clone

  • fn clone(self: &Self) -> Argon2<''key> { /* ... */ }
    

• CloneToUninit

  • unsafe fn clone_to_uninit(self: &Self, dest: *mut u8) { /* ... */ }
    

• Debug

  • fn fmt(self: &Self, fmt: &mut fmt::Formatter<''_>) -> fmt::Result { /* ... */ }
    

• Default

  • fn default() -> Self { /* ... */ }
    

• Freeze

• From

  • fn from(t: T) -> T { /* ... */ }
    

    Returns the argument unchanged.

  • fn from(params: Params) -> Self { /* ... */ }
    

  • fn from(params: &Params) -> Self { /* ... */ }
    

• Into

  • fn into(self: Self) -> U { /* ... */ }
    

    Calls U::from(self).

• PasswordHasher

  • fn hash_password<''a, /* synthetic */ impl Into<Salt<'a>>: Into<Salt<''a>>>(self: &Self, password: &[u8], salt: impl Into<Salt<''a>>) -> password_hash::Result<PasswordHash<''a>> { /* ... */ }
    

  • fn hash_password_customized<''a, /* synthetic */ impl Into<Salt<'a>>: Into<Salt<''a>>>(self: &Self, password: &[u8], alg_id: Option<Ident<''a>>, version: Option<Decimal>, params: Params, salt: impl Into<Salt<''a>>) -> password_hash::Result<PasswordHash<''a>> { /* ... */ }
    

• PasswordVerifier

  • fn verify_password(self: &Self, password: &[u8], hash: &PasswordHash<''_>) -> Result<(), Error> { /* ... */ }
    

• RefUnwindSafe

• Same

• Send

• Sync

• ToOwned

  • fn to_owned(self: &Self) -> T { /* ... */ }
    

  • fn clone_into(self: &Self, target: &mut T) { /* ... */ }
    

• TryFrom

  • fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> { /* ... */ }
    

• TryInto

  • fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error> { /* ... */ }
    

• Unpin

• UnwindSafe

Constants and Statics

Constant MAX_PWD_LEN

Maximum password length in bytes.

pub const MAX_PWD_LEN: usize = 0xFFFFFFFF;

Constant MIN_SALT_LEN

Minimum salt length in bytes.

pub const MIN_SALT_LEN: usize = 8;

Constant MAX_SALT_LEN

Maximum salt length in bytes.

pub const MAX_SALT_LEN: usize = 0xFFFFFFFF;

Constant RECOMMENDED_SALT_LEN

Recommended salt length for password hashing in bytes.

pub const RECOMMENDED_SALT_LEN: usize = 16;

Constant MAX_SECRET_LEN

Maximum secret key length in bytes.

pub const MAX_SECRET_LEN: usize = 0xFFFFFFFF;

Re-exports

Re-export Algorithm

pub use crate::algorithm::Algorithm;

Re-export Block

pub use crate::block::Block;

Re-export Error

pub use crate::error::Error;

Re-export Result

pub use crate::error::Result;

Re-export AssociatedData

pub use crate::params::AssociatedData;

Re-export KeyId

pub use crate::params::KeyId;

Re-export Params

pub use crate::params::Params;

Re-export ParamsBuilder

pub use crate::params::ParamsBuilder;

Re-export Version

pub use crate::version::Version;

Re-export ARGON2D_IDENT

Attributes:

• Other("#[<cfg_trace>(feature = \"password-hash\")]")
• Other("#[<cfg_attr_trace>(docsrs, doc(cfg(feature = \"password-hash\")))]")
• Other("#[doc(cfg(feature = \"password-hash\"))]")

pub use crate::algorithm::ARGON2D_IDENT;

Re-export ARGON2ID_IDENT

Attributes:

• Other("#[<cfg_trace>(feature = \"password-hash\")]")
• Other("#[<cfg_attr_trace>(docsrs, doc(cfg(feature = \"password-hash\")))]")
• Other("#[doc(cfg(feature = \"password-hash\"))]")

pub use crate::algorithm::ARGON2ID_IDENT;

Re-export ARGON2I_IDENT

Attributes:

• Other("#[<cfg_trace>(feature = \"password-hash\")]")
• Other("#[<cfg_attr_trace>(docsrs, doc(cfg(feature = \"password-hash\")))]")
• Other("#[doc(cfg(feature = \"password-hash\"))]")

pub use crate::algorithm::ARGON2I_IDENT;

Re-export password_hash

Attributes:

• Other("#[<cfg_trace>(feature = \"password-hash\")]")
• Other("#[<cfg_attr_trace>(docsrs, doc(cfg(feature = \"password-hash\")))]")
• Other("#[doc(cfg(feature = \"password-hash\"))]")

pub use password_hash;

Re-export PasswordHash

Attributes:

• Other("#[<cfg_trace>(feature = \"password-hash\")]")
• Other("#[<cfg_attr_trace>(docsrs, doc(cfg(feature = \"password-hash\")))]")
• Other("#[doc(cfg(feature = \"password-hash\"))]")

pub use password_hash::PasswordHash;

Re-export PasswordHasher

Attributes:

• Other("#[<cfg_trace>(feature = \"password-hash\")]")
• Other("#[<cfg_attr_trace>(docsrs, doc(cfg(feature = \"password-hash\")))]")
• Other("#[doc(cfg(feature = \"password-hash\"))]")

pub use password_hash::PasswordHasher;

Re-export PasswordVerifier

Attributes:

• Other("#[<cfg_trace>(feature = \"password-hash\")]")
• Other("#[<cfg_attr_trace>(docsrs, doc(cfg(feature = \"password-hash\")))]")
• Other("#[doc(cfg(feature = \"password-hash\"))]")

pub use password_hash::PasswordVerifier;