blackwriter-server/doc/argon2.md

# Crate Documentation

**Version:** 0.5.3

**Format Version:** 56

# Module `argon2`

# RustCrypto: Argon2

[![crate][crate-image]][crate-link]
[![Docs][docs-image]][docs-link]
[![Build Status][build-image]][build-link]
![Apache2/MIT licensed][license-image]
![Rust Version][rustc-image]
[![Project Chat][chat-image]][chat-link]

Pure Rust implementation of the [Argon2] password hashing function.

[Documentation][docs-link]

# 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](http://www.apache.org/licenses/LICENSE-2.0)
 * [MIT license](http://opensource.org/licenses/MIT)

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.

[//]: # (badges)

[crate-image]: https://buildstats.info/crate/argon2
[crate-link]: https://crates.io/crates/argon2
[docs-image]: https://docs.rs/argon2/badge.svg
[docs-link]: https://docs.rs/argon2/
[license-image]: https://img.shields.io/badge/license-Apache2.0/MIT-blue.svg
[rustc-image]: https://img.shields.io/badge/rustc-1.65+-blue.svg
[chat-image]: https://img.shields.io/badge/zulip-join_chat-blue.svg
[chat-link]: https://rustcrypto.zulipchat.com/#narrow/stream/260046-password-hashes
[build-image]: https://github.com/RustCrypto/password-hashes/workflows/argon2/badge.svg?branch=master&event=push
[build-link]: https://github.com/RustCrypto/password-hashes/actions?query=workflow%3Aargon2

[//]: # (general links)

[Argon2]: https://en.wikipedia.org/wiki/Argon2
[key derivation function]: https://en.wikipedia.org/wiki/Key_derivation_function
[Password Hashing Competition]: https://www.password-hashing.net/
## 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

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

#### Fields

| Name | Type | Documentation |
|------|------|---------------|
| *private fields* | ... | *Some fields have been omitted* |

#### Implementations

##### Methods

- ```rust
  pub fn new(algorithm: Algorithm, version: Version, params: Params) -> Self { /* ... */ }
  ```
  Create a new Argon2 context.

- ```rust
  pub fn new_with_secret(secret: &''key [u8], algorithm: Algorithm, version: Version, params: Params) -> Result<Self> { /* ... */ }
  ```
  Create a new Argon2 context.

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

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

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

- ```rust
  pub const fn params(self: &Self) -> &Params { /* ... */ }
  ```
  Get default configured [`Params`].

##### Trait Implementations

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

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

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

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

- **CloneToUninit**
  - ```rust
    unsafe fn clone_to_uninit(self: &Self, dest: *mut u8) { /* ... */ }
    ```

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

- **Default**
  - ```rust
    fn default() -> Self { /* ... */ }
    ```

- **Freeze**
- **From**
  - ```rust
    fn from(t: T) -> T { /* ... */ }
    ```
    Returns the argument unchanged.

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

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

- **Into**
  - ```rust
    fn into(self: Self) -> U { /* ... */ }
    ```
    Calls `U::from(self)`.

- **PasswordHasher**
  - ```rust
    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>> { /* ... */ }
    ```

  - ```rust
    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**
  - ```rust
    fn verify_password(self: &Self, password: &[u8], hash: &PasswordHash<''_>) -> Result<(), Error> { /* ... */ }
    ```

- **RefUnwindSafe**
- **Same**
- **Send**
- **Sync**
- **ToOwned**
  - ```rust
    fn to_owned(self: &Self) -> T { /* ... */ }
    ```

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

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

- **TryInto**
  - ```rust
    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.

```rust
pub const MAX_PWD_LEN: usize = 0xFFFFFFFF;
```

### Constant `MIN_SALT_LEN`

Minimum salt length in bytes.

```rust
pub const MIN_SALT_LEN: usize = 8;
```

### Constant `MAX_SALT_LEN`

Maximum salt length in bytes.

```rust
pub const MAX_SALT_LEN: usize = 0xFFFFFFFF;
```

### Constant `RECOMMENDED_SALT_LEN`

Recommended salt length for password hashing in bytes.

```rust
pub const RECOMMENDED_SALT_LEN: usize = 16;
```

### Constant `MAX_SECRET_LEN`

Maximum secret key length in bytes.

```rust
pub const MAX_SECRET_LEN: usize = 0xFFFFFFFF;
```

## Re-exports

### Re-export `Algorithm`

```rust
pub use crate::algorithm::Algorithm;
```

### Re-export `Block`

```rust
pub use crate::block::Block;
```

### Re-export `Error`

```rust
pub use crate::error::Error;
```

### Re-export `Result`

```rust
pub use crate::error::Result;
```

### Re-export `AssociatedData`

```rust
pub use crate::params::AssociatedData;
```

### Re-export `KeyId`

```rust
pub use crate::params::KeyId;
```

### Re-export `Params`

```rust
pub use crate::params::Params;
```

### Re-export `ParamsBuilder`

```rust
pub use crate::params::ParamsBuilder;
```

### Re-export `Version`

```rust
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\"))]")`

```rust
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\"))]")`

```rust
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\"))]")`

```rust
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\"))]")`

```rust
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\"))]")`

```rust
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\"))]")`

```rust
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\"))]")`

```rust
pub use password_hash::PasswordVerifier;
```