Argonautica

https://docs.rs/argonautica/0.2.0/argonautica/
Admin
Argonautica is a Rust crate for hashing passwords using the cryptographically-secure Argon2...
Tokens:33,033
Snippets:328
Trust Score:9.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Installation

Source: https://docs.rs/argonautica

Instructions on how to include the Argonautica crate in your Rust project and the necessary build dependencies.

```APIDOC
## Installation

To include **argonautica** in your Rust project:

1. Add `extern crate argonautica;` to your `lib.rs` or `main.rs`.
2. Configure your `Cargo.toml` under `[dependencies]`:

   * **For local builds:**
     - `argonautica = { version = "0.2", features = ["simd"] }`
     - `argonautica = { version = "0.2", features = ["serde", "simd"] }`

   * **For cross-compilation:**
     - `argonautica = "0.2"`
     - `argonautica = { version = "0.2", features = ["serde"] }`

**Build Dependencies:**

**argonautica** requires a C compiler (LLVM/Clang version 3.9 or higher) for building its C implementation. Installation varies by OS:

*   **Mac OS:** `brew install llvm` (requires Homebrew)
*   **Debian-based Linux:** `apt-get install clang llvm-dev libclang-dev`
*   **Arch Linux:** `pacman -S clang`
*   **Windows:** Download a pre-built binary.

**Rust Version:**

Requires stable Rust version 1.26.0 or greater.
```

--------------------------------

### Install LLVM/Clang on macOS

Source: https://docs.rs/argonautica/0.2.0/argonautica/index.html

Use Homebrew to install LLVM on macOS. This is a prerequisite for building Argonautica.

```bash
brew install llvm
```

--------------------------------

### Install LLVM/Clang on Arch Linux

Source: https://docs.rs/argonautica/0.2.0/argonautica/index.html

Install Clang on Arch Linux using pacman. This is a build dependency for Argonautica.

```bash
pacman -S clang
```

--------------------------------

### Install LLVM/Clang on Debian-based Linux

Source: https://docs.rs/argonautica/0.2.0/argonautica/index.html

Install Clang, LLVM development files, and libclang on Debian-based Linux distributions. Required for building Argonautica.

```bash
apt-get install clang llvm-dev libclang-dev
```

--------------------------------

### Hash Password with Salt

Source: https://docs.rs/argonautica/0.2.0/argonautica/index.html

Hash a password using a provided salt. This example assumes `opt_out_of_secret_key` has been explicitly set to `true` to allow hashing without a secret key.

```rust
let hash = hasher
        .with_password("P@ssw0rd")
        .with_salt("somesalt")
        .hash()
        .unwrap();
```

```rust
assert_eq!(
        &hash,
        "$argon2id$v=19$m=4096,t=192,p=2$c29tZXNhbHQ$sw41ZsxebJmOJ6vSHe6BGQ",
    );
```

--------------------------------

### Salt Constructors and Methods

Source: https://docs.rs/argonautica/0.2.0/argonautica/input/struct.Salt.html

Provides details on how to create and interact with Salt instances.

```APIDOC
## Implementations

### impl Salt

#### pub fn random(len: u32) -> Salt
Creates a new _random_ `Salt`. Initially, the random `Salt` has nothing in it, but every time you call `hash`, `hash_raw`, or their non-blocking equivalents on a `Hasher`, the `Salt` will update with new random bytes of the length specified generated using a cryptographically-secure random number generator (`EntropyRng`).

#### pub fn as_bytes(&self) -> &[u8]
Read-only access to the underlying byte buffer.

#### pub fn is_random(&self) -> bool
Returns `true` if the `Salt` is _random_; `false` if it is _deterministic_.

#### pub fn len(&self) -> usize
Read-only access to the underlying byte buffer’s length.

#### pub fn to_str(&self) -> Result<&str, Error>
Read-only access to the underlying byte buffer as a `&str` if its bytes are valid utf-8.

#### pub fn update(&mut self) -> Result<(), Error>
If you have a _random_ `Salt`, this method will generate new random bytes of the length of your `Salt`. If you have a _deterministic_ `Salt`, this method does nothing.
```

--------------------------------

### Verifier Initialization and Configuration

Source: https://docs.rs/argonautica/0.2.0/argonautica/struct.Verifier.html

This section covers the creation of a Verifier instance and its various configuration options.

```APIDOC
## Verifier Struct

**_One of the two main structs._** Use it to verify passwords against hashes.

```rust
pub struct Verifier<'a> { /* private fields */ }
```

### `new()`

Creates a new `Verifier` with default configuration.

```rust
pub fn new() -> Verifier<'a>
```

### `configure_backend()`

Allows you to configure `Verifier` with a custom backend. The default backend is `Backend::C`.

```rust
pub fn configure_backend(&mut self, backend: Backend) -> &mut Verifier<'a>
```

### `configure_cpu_pool()`

Allows you to configure `Verifier` with a custom `CpuPool`.

```rust
pub fn configure_cpu_pool(&mut self, cpu_pool: CpuPool) -> &mut Verifier<'a>
```

### `configure_password_clearing()`

Allows you to configure `Verifier` to erase the password bytes after each verification.

```rust
pub fn configure_password_clearing( &mut self, boolean: bool, ) -> &mut Verifier<'a>
```

### `configure_secret_key_clearing()`

Allows you to configure `Verifier` to erase the secret key bytes after each verification.

```rust
pub fn configure_secret_key_clearing( &mut self, boolean: bool, ) -> &mut Verifier<'a>
```

### `configure_threads()`

Allows you to configure `Verifier` to use a custom number of threads.

```rust
pub fn configure_threads(&mut self, threads: u32) -> &mut Verifier<'a>
```

### `to_owned()`

Clones the `Verifier`, returning a new `Verifier` with a `static` lifetime.

```rust
pub fn to_owned(&self) -> Verifier<'static>
```

### `with_additional_data()`

Allows you to provide `Verifier` with the additional data that was originally used to create the hash.

```rust
pub fn with_additional_data<AD>( &mut self, additional_data: AD, ) -> &mut Verifier<'a>
```

### `with_hash()`

Allows you to provide `Verifier` with the hash to verify against.

```rust
pub fn with_hash<S>(&mut self, hash: S) -> &mut Verifier<'a>
```
```

--------------------------------

### Configure Hasher settings

Source: https://docs.rs/argonautica

Demonstrates how to customize Hasher parameters such as backend, CPU pool, hash length, iterations, lanes, and memory size.

```rust
extern crate argonautica;
extern crate futures_cpupool;

use argonautica::Hasher;
use argonautica::config::{Backend, Variant, Version};
use futures_cpupool::CpuPool;

fn main() {
    let mut hasher = Hasher::default();
    hasher
        .configure_backend(Backend::C) // Default is `Backend::C`
        // 👆 argonautica was designed to support multiple backends (meaning multiple
        // implementations of the underlying Argon2 algorithm). Currently only the C backend
        // is supported, which uses the cannonical Argon2 library written in C to actually
        // do the work. In the future hopefully a Rust backend will also be supported, but,
        // for the moment, you must use `Backend::C`, which is the default. Using
        // `Backend::Rust` will result in an error (again, for the moment).
        .configure_cpu_pool(CpuPool::new(2))
        // 👆 There are two non-blocking methods on `Hasher` that perform computation on
        // a separate thread and return a `Future` instead of a `Result` (`hash_non_blocking`
        // and `hash_raw_non_blocking`). These methods allow argonautica to play nicely with
        // futures-heavy code, but need a `CpuPool` in order to work. The blocking
        // methods `hash` and `hash_raw` do not use a 'CpuPool'; so if you are using only
        // these blocking methods you can ignore this configuration entirely. If, however,
        // you are using the non-blocking methods and would like to provide your own `CpuPool`
        // instead of using the default, which is a lazily created `CpuPool` with the number
        // of threads equal to the number of logical cores on your machine, you can
        // configure your `Hasher` with a custom `CpuPool` using this method. This
        // might be useful if, for example, you are writing code in an environment which
        // makes heavy use of futures, the code you are writing uses both a `Hasher` and
        // a `Verifier`, and you would like both of them to share the same underlying
        // `CpuPool`.
        .configure_hash_len(16) // Default is `32`
        // 👆 The hash length in bytes is configurable. The default is 32. This is probably
        // a good number to use. 16 is also probably fine. You probably shouldn't go below 16
        .configure_iterations(192) // Default is `192`
        // 👆 Argon2 has a notion of "iterations" or "time cost". All else equal and generally
        // speaking, the greater the number of iterations, the longer it takes to perform the
        // hash and the more secure the resulting hash. More iterations basically means more
        // CPU load. This and "memory size" (see below) are the two primary parameters to
        // adjust in order to increase or decrease the security of your hash. The default is
        // 192 iterations, which was chosen because, along with the default memory size of
        // 4096, this leads to a hashing time of approximately 300 milliseconds on the
        // early-2014 Macbook Air that is the developer's machine. If you're going to use
        // argonautica in production, you should probably tweak this parameter (and the memory
        // size parameter) in order to increase the time it takes to hash to the maximum you
        // can reasonably allow for your use-case (e.g. to probably about 300-500 milliseconds
        // for the use-case of hashing user passwords for a website)
        .configure_lanes(2) // Default is number of logical cores on your machine
        // 👆 Argon2 can break up its work into one or more "lanes" during some parts of
        // the hashing algorithm. If you configure it with multiple lanes and you also
        // use multiple threads (see below) the hashing algorithm will performed its
        // work in parallel in some parts, potentially speeding up the time it takes to
        // produce a hash without diminishing the security of the result. By default,
        // the number of lanes is set to the number of logical cores on your machine
        .configure_memory_size(4096) // Default is `4096`
        // 👆 Argon2 has a notion of "memory size" or "memory cost" (in kibibytes). All else
        // equal and generally speaking, the greater the memory size, the longer it takes to
        // perform the hash and the more secure the resulting hash. More memory size basically
        // means more memory used. This and "iterations" (see above) are, again, generally
```

--------------------------------

### Get Minimum of Two AdditionalData Values

Source: https://docs.rs/argonautica/0.2.0/argonautica/input/struct.AdditionalData.html

Compares two AdditionalData values and returns the minimum.

```rust
fn min(self, other: Self) -> Self where Self: Sized,
```

--------------------------------

### Create a new Hasher

Source: https://docs.rs/argonautica/0.2.0/argonautica/struct.Hasher.html

Initializes a Hasher with default settings suitable for typical hardware.

```rust
pub fn new() -> Hasher<'static>
```

--------------------------------

### Get Maximum of Two AdditionalData Values

Source: https://docs.rs/argonautica/0.2.0/argonautica/input/struct.AdditionalData.html

Compares two AdditionalData values and returns the maximum.

```rust
fn max(self, other: Self) -> Self where Self: Sized,
```

--------------------------------

### Get Password Length

Source: https://docs.rs/argonautica/0.2.0/argonautica/input/struct.Password.html

Returns the length of the underlying byte buffer in bytes. This provides the size of the password data.

```rust
pub fn len(&self) -> usize
```

--------------------------------

### Convert Version Enum to String

Source: https://docs.rs/argonautica/0.2.0/argonautica/config/enum.Version.html

Converts a Version enum variant to its string representation. Use this to get the version number as a string.

```rust
pub fn as_str(&self) -> &'static str
```

--------------------------------

### Configure Hasher backend

Source: https://docs.rs/argonautica/0.2.0/argonautica/struct.Hasher.html

Sets the hashing backend. Currently, only Backend::C is supported.

```rust
pub fn configure_backend(&mut self, backend: Backend) -> &mut Hasher<'a>
```

--------------------------------

### Get Password Bytes

Source: https://docs.rs/argonautica/0.2.0/argonautica/input/struct.Password.html

Provides read-only access to the underlying byte buffer of the Password struct. Use this to inspect the password bytes without modification.

```rust
pub fn as_bytes(&self) -> &[u8]
```

--------------------------------

### HashRaw Struct Overview

Source: https://docs.rs/argonautica/0.2.0/argonautica/output/struct.HashRaw.html

Provides an overview of the HashRaw struct, its purpose, and how to obtain instances.

```APIDOC
## Struct HashRaw

### Summary
```
pub struct HashRaw { /* private fields */ }
```

### Description
Struct representing raw hash output. You typically won’t need this struct if all you’d like to produce is a string-encoded hash, which is what is returned from the regular `hash` method on `Hasher` (or it’s non-blocking equivalent).
That said, if you want to inspect each component of a hash more directly (e.g. pull out the raw hash bytes or the raw salt bytes individually), you can obtain an instance of this `HashRaw` struct, which will allows you do to those things, by either:
  * Parsing a string-encoded hash into a `HashRaw` via `let hash_raw = hash_str.parse::<HashRaw>()?;`,
  * Obtaining a `HashRaw` directly by calling `hash_raw` on a `Hasher` (or its non-blocking equivalent)
```

--------------------------------

### Hasher Configuration Methods

Source: https://docs.rs/argonautica/0.2.0/argonautica/struct.Hasher.html

Methods to customize the Hasher's behavior.

```APIDOC
### `Hasher::configure_backend(backend: Backend)`

Allows configuration of the hashing backend. The default is `Backend::C`. A Rust backend is planned but not yet available. Using `Backend::Rust` will result in an error.

### `Hasher::configure_cpu_pool(cpu_pool: CpuPool)`

Allows configuration of a custom `CpuPool`. A `CpuPool` is only necessary for non-blocking hashing methods (`hash_non_blocking`, `hash_raw_non_blocking`). If not provided, a default pool is created on the fly.

### `Hasher::configure_hash_len(hash_len: u32)`

Sets a custom hash length in bytes. The default is `32`.

### `Hasher::configure_iterations(iterations: u32)`

Sets a custom number of iterations for the hashing algorithm. The default is `192`.

### `Hasher::configure_lanes(lanes: u32)`

Sets a custom number of lanes for the hashing algorithm. The default is the number of physical cores on the machine.
```

--------------------------------

### Salt Comparison Methods

Source: https://docs.rs/argonautica/0.2.0/argonautica/input/struct.Salt.html

Methods for comparing Salt instances using standard ordering and relational operators.

```APIDOC
## Comparison Methods for Salt

### Description
Provides methods to compare Salt instances for ordering and equality.

### Methods
- **partial_cmp**: Returns an ordering between self and other.
- **lt**: Tests less than (<).
- **le**: Tests less than or equal to (<=).
- **gt**: Tests greater than (>).
- **ge**: Tests greater than or equal to (>=).

### Parameters
#### Path Parameters
- **other** (Salt/Rhs) - Required - The value to compare against.
```

--------------------------------

### Hasher Struct and Constructors

Source: https://docs.rs/argonautica/0.2.0/argonautica/struct.Hasher.html

Overview of the Hasher struct and its primary creation methods.

```APIDOC
## Struct Hasher

** _One of the two main structs._** Use it to turn passwords into hashes

### `Hasher::new()`

Creates a new `Hasher` with a sensible default configuration for the average machine.

**Note:** For production environments, it's recommended to tune `iterations` and `memory_size` for your specific hardware to achieve hashing times of approximately 300-500 milliseconds.

Default configuration options:
- `backend`: `Backend::C`
- `cpu_pool`: Lazily created `CpuPool` with threads equal to the number of logical cores.
- `hash_len`: `32` bytes
- `iterations`: `192`
- `lanes`: Number of logical cores on your machine
- `memory_size`: `4096` kibibytes
- `opt_out_of_secret_key`: `false`
- `password_clearing`: `false`
- `salt`: Random `Salt` of length 32 bytes.
- `secret_key_clearing`: `false`
- `threads`: Number of logical cores on your machine
- `variant`: `Variant::Argon2id`
- `version`: `Version::_0x13`

### `Hasher::fast_but_insecure()`

Creates a new `Hasher` with a configuration that is **fast but _highly_ insecure**. Use this only when security is not a concern.

Configuration:
- Hash length: 32 bytes
- Iterations: 1
- Memory size: Minimum of 8 * number of lanes
- Salt: Deterministic salt of minimum length 8 bytes
- Opts out of a secret key.
```

--------------------------------

### Hasher Configuration Methods

Source: https://docs.rs/argonautica/0.2.0/argonautica/struct.Hasher.html

Methods for configuring the Hasher with essential data for password hashing.

```APIDOC
## POST /api/hasher/configure

### Description
Configures the Hasher with password, salt, secret key, and additional data.

### Method
POST

### Endpoint
/api/hasher/configure

### Parameters
#### Request Body
- **password** (string) - Required - The password to be hashed.
- **salt** (string) - Optional - The salt to be used for hashing. If not provided, a random salt will be generated.
- **secret_key** (string) - Optional - The secret key to be used for hashing. This is required for verification later.
- **additional_data** (string) - Optional - Additional data to be hashed alongside the password. This is required for verification later.

### Request Example
```json
{
  "password": "mysecretpassword",
  "salt": "randomsalt123",
  "secret_key": "mysecretkey",
  "additional_data": "extra_info"
}
```

### Response
#### Success Response (200)
- **hash** (string) - The generated hash of the password.
- **config** (object) - The configuration used for hashing.
  - **salt** (string) - The salt used.
  - **secret_key** (string) - The secret key used (if provided).
  - **additional_data** (string) - The additional data used (if provided).

#### Response Example
```json
{
  "hash": "generated_hash_string",
  "config": {
    "salt": "randomsalt123",
    "secret_key": "mysecretkey",
    "additional_data": "extra_info"
  }
}
```
```

--------------------------------

### SecretKey Conversions (From)

Source: https://docs.rs/argonautica/0.2.0/argonautica/input/struct.SecretKey.html

Implementations for converting various types into a SecretKey.

```APIDOC
## From<&'a [u8]> for SecretKey<'a>

### Description
Converts a byte slice into a `SecretKey`.

### Method
`fn from(bytes: &'a [u8]) -> SecretKey<'a>`

## From<&'a SecretKey<'a>> for SecretKey<'a>

### Description
Creates a `SecretKey` from a reference to another `SecretKey`.

### Method
`fn from(sk: &'a SecretKey<'a>) -> SecretKey<'a>`

## From<&'a String> for SecretKey<'a>

### Description
Converts a string slice into a `SecretKey`.

### Method
`fn from(s: &'a String) -> SecretKey<'a>`

## From<&'a Vec<u8>> for SecretKey<'a>

### Description
Converts a byte vector slice into a `SecretKey`.

### Method
`fn from(bytes: &'a Vec<u8>) -> SecretKey<'a>`

## From<&'a mut [u8]> for SecretKey<'a>

### Description
Converts a mutable byte slice into a `SecretKey`.

### Method
`fn from(bytes: &'a mut [u8]) -> SecretKey<'a>`

## From<&'a mut SecretKey<'a>> for SecretKey<'a>

### Description
Creates a mutable `SecretKey` from a mutable reference to another `SecretKey`.

### Method
`fn from(sk: &'a mut SecretKey<'a>) -> SecretKey<'a>`

## From<&'a mut String> for SecretKey<'a>

### Description
Converts a mutable string slice into a `SecretKey`.

### Method
`fn from(s: &'a mut String) -> SecretKey<'a>`

## From<&'a mut str> for SecretKey<'a>

### Description
Converts a mutable string slice into a `SecretKey`.

### Method
`fn from(s: &'a mut str) -> SecretKey<'a>`

## From<&'a str> for SecretKey<'a>

### Description
Converts a string slice into a `SecretKey`.

### Method
`fn from(s: &'a str) -> SecretKey<'a>`

## From<String> for SecretKey<'a>

### Description
Converts an owned `String` into a `SecretKey` with a `'static` lifetime.

### Method
`fn from(s: String) -> SecretKey<'static>`

## From<Vec<u8>> for SecretKey<'a>

### Description
Converts an owned byte vector into a `SecretKey` with a `'static` lifetime.

### Method
`fn from(bytes: Vec<u8>) -> SecretKey<'static>`

```

--------------------------------

### Create an insecure Hasher

Source: https://docs.rs/argonautica/0.2.0/argonautica/struct.Hasher.html

Initializes a Hasher with minimal security settings for non-sensitive use cases.

```rust
pub fn fast_but_insecure() -> Hasher<'a>
```

--------------------------------

### Add Argonautica to Cargo.toml (Local with Serde)

Source: https://docs.rs/argonautica/0.2.0/argonautica/index.html

Include this in your Cargo.toml when building for your own machine, enabling both SIMD and Serde support.

```toml
argonautica = { version = "0.2", features = ["serde", "simd"] }
```

--------------------------------

### Add Argonautica to Cargo.toml (Cross-Machine with Serde)

Source: https://docs.rs/argonautica/0.2.0/argonautica/index.html

Include this in your Cargo.toml when building for a different machine, enabling Serde support.

```toml
argonautica = { version = "0.2", features = ["serde"] }
```

--------------------------------

### Default Version

Source: https://docs.rs/argonautica/0.2.0/argonautica/config/enum.Version.html

Provides the default Version, which is Version::_0x13.

```rust
fn default() -> Version
```

--------------------------------

### Verifier Configuration Methods

Source: https://docs.rs/argonautica/0.2.0/argonautica/struct.Verifier.html

Methods used to set the verification parameters for the Verifier instance.

```APIDOC
## with_hash_raw

### Description
Allows you to provide Verifier with the hash to verify against (in the form of a HashRaw).

### Parameters
- **hash_raw** (HashRaw) - Required - The raw hash to verify against.

## with_password

### Description
Allows you to provide Verifier with the password to verify against.

### Parameters
- **password** (P) - Required - The password to verify, must implement Into<Password>.

## with_secret_key

### Description
Allows you to provide Verifier with the secret key that was initially used to create the hash.

### Parameters
- **secret_key** (SK) - Required - The secret key, must implement Into<SecretKey>.
```

--------------------------------

### CloneToUninit Trait Implementation (Nightly)

Source: https://docs.rs/argonautica/0.2.0/argonautica/config/struct.HasherConfig.html

Nightly-only experimental API for copying data to an uninitialized memory location.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### HasherConfig Implementations

Source: https://docs.rs/argonautica/0.2.0/argonautica/config/struct.HasherConfig.html

Methods available on the HasherConfig struct.

```APIDOC
## Implementations

### impl HasherConfig

#### pub fn backend(&self) -> Backend

#### pub fn cpu_pool(&self) -> Option<CpuPool>

#### pub fn hash_len(&self) -> u32

#### pub fn iterations(&self) -> u32

#### pub fn lanes(&self) -> u32

#### pub fn memory_size(&self) -> u32

#### pub fn opt_out_of_secret_key(&self) -> bool

#### pub fn password_clearing(&self) -> bool

#### pub fn secret_key_clearing(&self) -> bool

#### pub fn threads(&self) -> u32

#### pub fn variant(&self) -> Variant

#### pub fn version(&self) -> Version
```

--------------------------------

### Verify a password against a hash

Source: https://docs.rs/argonautica/0.2.0/argonautica/index.html

Use the Verifier to compare a password and secret key against an existing Argon2 hash string.

```rust
extern crate argonautica;

use argonautica::Verifier;

fn main() {
    let mut verifier = Verifier::default();
    let is_valid = verifier
        .with_hash("
            $argon2id$v=19$m=4096,t=192,p=4$\
            o2y5PU86Vt+sr93N7YUGgC7AMpTKpTQCk4tNGUPZMY4$\
            yzP/ukZRPIbZg6PvgnUUobUMbApfF9RH6NagL9L4Xr4\
        ")
        .with_password("P@ssw0rd")
        .with_secret_key("\
            secret key that you should really store in a .env file \
            instead of in code, but this is just an example\
        ")
        .verify()
        .unwrap();

    assert!(is_valid);
}
```

--------------------------------

### Hasher Configuration API

Source: https://docs.rs/argonautica/0.2.0/argonautica/struct.Hasher.html

Methods for configuring the Hasher instance before hashing.

```APIDOC
## Hasher Configuration API

This section details the methods available for configuring the `Hasher` instance.

### `configure_memory_size`

Allows you to configure `Hasher` to use a custom memory size (in kibibytes). The default is `4096`.

#### Method
POST

#### Endpoint
`/configure/memory_size`

#### Parameters
##### Query Parameters
- **memory_size** (u32) - Required - The custom memory size in kibibytes.

### `configure_password_clearing`

Allows you to configure `Hasher` to erase the password bytes after each hashing operation. The default is `false`.

#### Method
POST

#### Endpoint
`/configure/password_clearing`

#### Parameters
##### Query Parameters
- **boolean** (bool) - Required - Set to `true` to enable password clearing.

### `configure_secret_key_clearing`

Allows you to configure `Hasher` to erase the secret key bytes after each hashing operation. The default is `false`.

#### Method
POST

#### Endpoint
`/configure/secret_key_clearing`

#### Parameters
##### Query Parameters
- **boolean** (bool) - Required - Set to `true` to enable secret key clearing.

### `configure_threads`

Allows you to configure `Hasher` to use a custom number of threads. The default is the number of physical cores.

#### Method
POST

#### Endpoint
`/configure/threads`

#### Parameters
##### Query Parameters
- **threads** (u32) - Required - The custom number of threads to use.

### `configure_variant`

Allows you to configure `Hasher` to use a custom Argon2 variant. The default is `Variant::Argon2id`.

#### Method
POST

#### Endpoint
`/configure/variant`

#### Parameters
##### Query Parameters
- **variant** (Variant) - Required - The Argon2 variant to use (e.g., `Argon2id`, `Argon2i`, `Argon2d`).

### `configure_version`

Allows you to configure `Hasher` to use a custom Argon2 version. The default is `Version::_0x13`.

#### Method
POST

#### Endpoint
`/configure/version`

#### Parameters
##### Query Parameters
- **version** (Version) - Required - The Argon2 version to use (e.g., `_0x13`).

### `opt_out_of_secret_key`

Explicitly declare the intention to hash without a secret key. This is not recommended.

#### Method
POST

#### Endpoint
`/configure/opt_out_of_secret_key`

#### Parameters
##### Query Parameters
- **boolean** (bool) - Required - Set to `true` to opt out of using a secret key.

### `to_owned`

Clones the `Hasher`, returning a new `Hasher` with a `'static` lifetime. Use this method if you would like to move a `Hasher` to another thread.

#### Method
GET

#### Endpoint
`/to_owned`

#### Response
##### Success Response (200)
- **Hasher<'static>** - A new `Hasher` instance with a static lifetime.
```

--------------------------------

### Verifier Methods

Source: https://docs.rs/argonautica/0.2.0/argonautica/struct.Verifier.html

Methods for configuring and executing password verification.

```rust
pub fn new() -> Verifier<'a>
```

```rust
pub fn configure_backend(&mut self, backend: Backend) -> &mut Verifier<'a>
```

```rust
pub fn configure_cpu_pool(&mut self, cpu_pool: CpuPool) -> &mut Verifier<'a>
```

```rust
pub fn configure_password_clearing( &mut self, boolean: bool, ) -> &mut Verifier<'a>
```

```rust
pub fn configure_secret_key_clearing( &mut self, boolean: bool, ) -> &mut Verifier<'a>
```

```rust
pub fn configure_threads(&mut self, threads: u32) -> &mut Verifier<'a>
```

```rust
pub fn to_owned(&self) -> Verifier<'static>
```

```rust
pub fn verify(&mut self) -> Result<bool, Error>
```

```rust
pub fn verify_non_blocking(&mut self) -> impl Future<Item = bool, Error = Error>
```

```rust
pub fn with_additional_data<AD>( &mut self, additional_data: AD, ) -> &mut Verifier<'a>
where AD: Into<AdditionalData>,
```

```rust
pub fn with_hash<S>(&mut self, hash: S) -> &mut Verifier<'a>
where S: AsRef<str>,
```

--------------------------------

### Constant DEFAULT_BACKEND

Source: https://docs.rs/argonautica/0.2.0/argonautica/config/constant.DEFAULT_BACKEND.html

The default backend configuration for the argonautica crate.

```APIDOC
## Constant DEFAULT_BACKEND

### Description
`Backend::C`

### Summary
`pub const DEFAULT_BACKEND: Backend;`

### Details
This constant represents the default backend, which is `Backend::C`.
```

--------------------------------

### Access DEFAULT_BACKEND constant

Source: https://docs.rs/argonautica/0.2.0/argonautica/config/constant.DEFAULT_BACKEND.html

Represents the default backend implementation, which defaults to Backend::C.

```rust
pub const DEFAULT_BACKEND: Backend;
```

--------------------------------

### Configure Hasher with Custom Options

Source: https://docs.rs/argonautica/0.2.0/argonautica/index.html

Use this to customize Argon2 hashing parameters. Configure the backend, CPU pool, hash length, iterations, lanes, and memory size for specific security and performance needs.

```rust
extern crate argonautica;
extern crate futures_cpupool;

use argonautica::Hasher;
use argonautica::config::{Backend, Variant, Version};
use futures_cpupool::CpuPool;

fn main() {
    let mut hasher = Hasher::default();
    hasher
        .configure_backend(Backend::C) // Default is `Backend::C`
        // 👆 argonautica was designed to support multiple backends (meaning multiple
        // implementations of the underlying Argon2 algorithm). Currently only the C backend
        // is supported, which uses the cannonical Argon2 library written in C to actually
        // do the work. In the future hopefully a Rust backend will also be supported, but,
        // for the moment, you must use `Backend::C`, which is the default. Using
        // `Backend::Rust` will result in an error (again, for the moment).
        .configure_cpu_pool(CpuPool::new(2))
        // 👆 There are two non-blocking methods on `Hasher` that perform computation on
        // a separate thread and return a `Future` instead of a `Result` (`hash_non_blocking`
        // and `hash_raw_non_blocking`). These methods allow argonautica to play nicely with
        // futures-heavy code, but need a `CpuPool` in order to work. The blocking
        // methods `hash` and `hash_raw` do not use a 'CpuPool'; so if you are using only
        // these blocking methods you can ignore this configuration entirely. If, however,
        // you are using the non-blocking methods and would like to provide your own `CpuPool`
        // instead of using the default, which is a lazily created `CpuPool` with the number
        // of threads equal to the number of logical cores on your machine, you can
        // configure your `Hasher` with a custom `CpuPool` using this method. This
        // might be useful if, for example, you are writing code in an environment which
        // makes heavy use of futures, the code you are writing uses both a `Hasher` and
        // a `Verifier`, and you would like both of them to share the same underlying
        // `CpuPool`.
        .configure_hash_len(16) // Default is `32`
        // 👆 The hash length in bytes is configurable. The default is 32. This is probably
        // a good number to use. 16 is also probably fine. You probably shouldn't go below 16
        .configure_iterations(192) // Default is `192`
        // 👆 Argon2 has a notion of "iterations" or "time cost". All else equal and generally
        // speaking, the greater the number of iterations, the longer it takes to perform the
        // hash and the more secure the resulting hash. More iterations basically means more
        // CPU load. This and "memory size" (see below) are the two primary parameters to
        // adjust in order to increase or decrease the security of your hash. The default is
        // 192 iterations, which was chosen because, along with the default memory size of
        // 4096, this leads to a hashing time of approximately 300 milliseconds on the
        // early-2014 Macbook Air that is the developer's machine. If you're going to use
        // argonautica in production, you should probably tweak this parameter (and the memory
        // size parameter) in order to increase the time it takes to hash to the maximum you
        // can reasonably allow for your use-case (e.g. to probably about 300-500 milliseconds
        // for the use-case of hashing user passwords for a website)
        .configure_lanes(2) // Default is number of logical cores on your machine
        // 👆 Argon2 can break up its work into one or more "lanes" during some parts of
        // the hashing algorithm. If you configure it with multiple lanes and you also
        // use multiple threads (see below) the hashing algorithm will performed its
        // work in parallel in some parts, potentially speeding up the time it takes to
        // produce a hash without diminishing the security of the result. By default,
        // the number of lanes is set to the number of logical cores on your machine
        .configure_memory_size(4096) // Default is `4096`
        // 👆 Argon2 has a notion of "memory size" or "memory cost" (in kibibytes). All else
        // equal and generally speaking, the greater the memory size, the longer it takes to
        // perform the hash and the more secure the resulting hash. More memory size basically
        // means more memory used. This and "iterations" (see above) are, again, generally
}

```

--------------------------------

### From Trait

Source: https://docs.rs/argonautica/0.2.0/argonautica/input/struct.Password.html

Enables conversion from one type to another.

```APIDOC
## impl<T> From<T> for T

### Description
Returns the argument unchanged. This is a basic implementation of the `From` trait.

### Method
`from`

### Parameters
- `t` (T) - The value to be converted.

### Request Body
None

### Response
#### Success Response (200)
- `T`: The argument `t` itself.

### Response Example
None provided
```

--------------------------------

### Add Argonautica to Cargo.toml (Local)

Source: https://docs.rs/argonautica/0.2.0/argonautica/index.html

Include this in your Cargo.toml when building for your own machine. Enables SIMD optimizations.

```toml
argonautica = { version = "0.2", features = ["simd"] }
```

--------------------------------

### Construct SecretKey from Base64 Encoded String with Custom Config

Source: https://docs.rs/argonautica/0.2.0/argonautica/input/struct.SecretKey.html

Constructs a `SecretKey` from a base64-encoded string using a custom configuration, allowing for non-standard base64 encodings like URL-safe.

```rust
pub fn from_base64_encoded_config<S>( s: S, config: Config, ) -> Result<SecretKey<'static>, Error>
where S: AsRef<str>,
```

--------------------------------

### SecretKey Creation

Source: https://docs.rs/argonautica/0.2.0/argonautica/input/struct.SecretKey.html

Methods for constructing a SecretKey from different sources, including base64 encoded strings.

```APIDOC
## SecretKey::from_base64_encoded

### Description
Constructs a `SecretKey` from a base64-encoded `&str` using standard base64 encoding.

### Method
`pub fn from_base64_encoded<S>(s: S) -> Result<SecretKey<'static>, Error>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **SecretKey<'static>** - The constructed SecretKey.

#### Response Example
None

## SecretKey::from_base64_encoded_config

### Description
Constructs a `SecretKey` from a base64-encoded `&str` using a custom base64 encoding configuration.

### Method
`pub fn from_base64_encoded_config<S>(s: S, config: Config) -> Result<SecretKey<'static>, Error>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **SecretKey<'static>** - The constructed SecretKey.

#### Response Example
None
```

--------------------------------

### CloneToUninit Trait

Source: https://docs.rs/argonautica/0.2.0/argonautica/struct.Error.html

The `CloneToUninit` trait is an experimental, nightly-only API that allows for copy-assignment from a value to an uninitialized memory location.

```APIDOC
## unsafe fn clone_to_uninit(&self, dest: *mut u8)

### Description
Performs copy-assignment from `self` to `dest`.

### Method
`unsafe fn clone_to_uninit`

### Parameters
- **self** (*const Self*) - The source value to copy from.
- **dest** (**mut u8*) - A mutable pointer to the destination memory location.

### Notes
This is a nightly-only experimental API.
```

--------------------------------

### Clone From Implementation for HasherConfig

Source: https://docs.rs/argonautica/0.2.0/argonautica/config/struct.HasherConfig.html

Enables copy-assignment from a source HasherConfig.

```rust
fn clone_from(&mut self, source: &Self)
```

--------------------------------

### VerifierConfig Methods

Source: https://docs.rs/argonautica/0.2.0/argonautica/config/struct.VerifierConfig.html

Methods available on the VerifierConfig struct to retrieve configuration details.

```APIDOC
## VerifierConfig Methods

### Description
Provides read-only access to the configuration parameters of a Verifier instance.

### Methods
- **backend() -> Backend**: Returns the configured backend.
- **cpu_pool() -> Option<CpuPool>**: Returns the configured CPU pool, if any.
- **password_clearing() -> bool**: Returns true if password clearing is enabled.
- **secret_key_clearing() -> bool**: Returns true if secret key clearing is enabled.
- **threads() -> u32**: Returns the number of threads configured.
```

--------------------------------

### Default Backend Value

Source: https://docs.rs/argonautica/0.2.0/argonautica/config/enum.Backend.html

Returns the default Backend variant, which is Backend::C. This is used when no specific backend is provided.

```rust
fn default() -> Backend
```

--------------------------------

### TryInto Trait Conversion

Source: https://docs.rs/argonautica/0.2.0/argonautica/enum.ErrorKind.html

Documentation for the TryInto trait and its associated error type and conversion method.

```APIDOC
## impl<T, U> TryInto<U> for T

### Description
Implementation of the TryInto trait for fallible conversion.

### Associated Types
- **Error** - The type returned in the event of a conversion error.

### Methods
#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
Performs the conversion from the current type to type U.
```

--------------------------------

### Create Password from Vec<u8> Reference

Source: https://docs.rs/argonautica/0.2.0/argonautica/input/struct.Password.html

Implements the From trait to create a Password from a reference to a Vec<u8> (`&'a Vec<u8>`). This allows initialization from a vector of bytes.

```rust
fn from(bytes: &'a Vec<u8>) -> Password<'a>
```

--------------------------------

### HashRaw Methods

Source: https://docs.rs/argonautica/0.2.0/argonautica/output/struct.HashRaw.html

Details the methods available on the HashRaw struct for accessing hash components and configuration.

```APIDOC
## Implementations

### impl HashRaw

#### pub fn to_string(&self) -> String
Converts the `HashRaw` to a string-encoded hash

#### pub fn iterations(&self) -> u32
Obtain the iterations configuration that was used to produce this hash

#### pub fn lanes(&self) -> u32
Obtain the lanes configuration that was used to produce this hash

#### pub fn memory_size(&self) -> u32
Obtain the memory size configuration that was used to produce this hash

#### pub fn raw_hash_bytes(&self) -> &[u8]
Read-only access to the raw hash bytes

#### pub fn raw_salt_bytes(&self) -> &[u8]
Read-only access to the raw salt bytes

#### pub fn variant(&self) -> Variant
Obtain the variant configuration that was used to produce this hash

#### pub fn version(&self) -> Version
Obtian the version configuration that was used to produce this hash
```

--------------------------------

### Configure Argon2 Hashing Parameters

Source: https://docs.rs/argonautica/0.2.0/argonautica/index.html

Set various parameters to control the security and performance of Argon2 hashing. Adjust memory cost, iterations, parallelism, and choose hashing variants. Ensure to set `opt_out_of_secret_key` to `true` if hashing without a secret key.

```rust
.configure_password_clearing(false) // Default is `false`
        .configure_secret_key_clearing(false) // Default is `false`
        .configure_threads(2) // Default is number of logical cores on your machine
        .configure_variant(Variant::Argon2id) // Default is `Variant::Argon2id`
        .configure_version(Version::_0x13) // Default is `Version::_0x13`
        .opt_out_of_secret_key(true);
```

--------------------------------

### HasherConfig Struct

Source: https://docs.rs/argonautica/0.2.0/argonautica/config/struct.HasherConfig.html

Provides read-only configuration for the Hasher. Obtainable via the `config` method on a Hasher instance.

```APIDOC
## Struct HasherConfig

### Summary
```rust
pub struct HasherConfig { /* private fields */ }
```

### Description
Read-only configuration for `Hasher`. Can be obtained by calling the `config` method on an instance of `Hasher`.
```

--------------------------------

### Salt Trait Implementations

Source: https://docs.rs/argonautica/0.2.0/argonautica/input/struct.Salt.html

Details on traits implemented by the Salt struct, such as Clone, Debug, Default, From, Hash, Ord, PartialEq, and PartialOrd.

```APIDOC
### Trait Implementations

### impl Clone for Salt
#### fn clone(&self) -> Salt
Returns a duplicate of the value.

#### fn clone_from(&mut self, source: &Self)
Performs copy-assignment from `source`.

### impl Debug for Salt
#### fn fmt(&self, f: &mut Formatter<'_>) -> Result
Formats the value using the given formatter.

### impl Default for Salt
#### fn default() -> Salt
Creates a new _random_ `Salt`. Initially, the random `Salt` has nothing in it, but every time you call `hash`, `hash_raw`, or their non-blocking equivalents on a `Hasher`, the `Salt` will update with `32` new random bytes generated using a cryptographically-secure random number generator (`EntropyRng`).

### impl<'a> From<&'a [u8]> for Salt
#### fn from(bytes: &[u8]) -> Salt
Converts to this type from the input type.

### impl<'a> From<&'a Salt> for Salt
#### fn from(salt: &Salt) -> Salt
Converts to this type from the input type.

### impl<'a> From<&'a String> for Salt
#### fn from(s: &String) -> Salt
Converts to this type from the input type.

### impl<'a> From<&'a Vec<u8>> for Salt
#### fn from(bytes: &Vec<u8>) -> Salt
Converts to this type from the input type.

### impl<'a> From<&'a str> for Salt
#### fn from(s: &str) -> Salt
Converts to this type from the input type.

### impl From<String> for Salt
#### fn from(s: String) -> Salt
Converts to this type from the input type.

### impl From<Vec<u8>> for Salt
#### fn from(bytes: Vec<u8>) -> Salt
Converts to this type from the input type.

### impl Hash for Salt
#### fn hash<__H: Hasher>(&self, state: &mut __H)
Feeds this value into the given `Hasher`.

#### fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,
Feeds a slice of this type into the given `Hasher`.

### impl Ord for Salt
#### fn cmp(&self, other: &Salt) -> Ordering
This method returns an `Ordering` between `self` and `other`.

#### fn max(self, other: Self) -> Self
where Self: Sized,
Compares and returns the maximum of two values.

#### fn min(self, other: Self) -> Self
where Self: Sized,
Compares and returns the minimum of two values.

#### fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized,
Restrict a value to a certain interval.

### impl PartialEq for Salt
#### fn eq(&self, other: &Salt) -> bool
Tests for `self` and `other` values to be equal, and is used by `==`.

#### fn ne(&self, other: &Rhs) -> bool
Tests for `!=`.

### impl PartialOrd for Salt
```

--------------------------------

### Construct SecretKey from Base64 Encoded String

Source: https://docs.rs/argonautica/0.2.0/argonautica/input/struct.SecretKey.html

Constructs a `SecretKey` from a base64-encoded string using standard encoding. Accepts any type that can be dereferenced into a base64-encoded `&str`.

```rust
pub fn from_base64_encoded<S>(s: S) -> Result<SecretKey<'static>, Error>
where S: AsRef<str>,
```

--------------------------------

### Create Password from Byte Slice

Source: https://docs.rs/argonautica/0.2.0/argonautica/input/struct.Password.html

Implements the From trait to create a Password from an immutable byte slice (`&[u8]`). This is a common way to initialize a Password with existing byte data.

```rust
fn from(bytes: &'a [u8]) -> Password<'a>
```

--------------------------------

### Configure Hasher CPU pool

Source: https://docs.rs/argonautica/0.2.0/argonautica/struct.Hasher.html

Sets a custom CPU pool for non-blocking hashing operations.

```rust
pub fn configure_cpu_pool(&mut self, cpu_pool: CpuPool) -> &mut Hasher<'a>
```
Tokens:
Raw