aragorn2

Aragorn2 provides secure password hashing, powered by Argon2.

Argon2 is a password-hashing function that summarizes the state of the art in the design of memory-hard functions and can be used to hash passwords for credential storage, key derivation, or other applications.

It has a simple design aimed at the highest memory filling rate and effective use of multiple computing units, while still providing defense against tradeoff attacks (by exploiting the cache and memory organization of the recent processors).

Argon2 has three variants: Argon2i, Argon2d, and Argon2id. Argon2d is faster and uses data-depending memory access, which makes it highly resistant against GPU cracking attacks and suitable for applications with no threats from side-channel timing attacks (eg. cryptocurrencies). Argon2i instead uses data-independent memory access, which is preferred for password hashing and password-based key derivation, but it is slower as it makes more passes over the memory to protect from tradeoff attacks. Argon2id is a hybrid of Argon2i and Argon2d, using a combination of data-depending and data-independent memory accesses, which gives some of Argon2i’s resistance to side-channel cache timing attacks and much of Argon2d’s resistance to GPU cracking attacks.

Argon2i, Argon2d, and Argon2id are parametrized by:

A time cost, which defines the amount of computation realized and therefore the execution time, given in number of iterations

A memory cost, which defines the memory usage, given in kibibytes

A parallelism degree, which defines the number of parallel threads

Types

Algorithm

</>

An Argon2 hashing algorithm.

pub type Algorithm {
  Argon2d
  Argon2i
  Argon2id
}

Constructors

```
Argon2d
```
Argon2d is faster and uses data-depending memory access, which makes it highly resistant against GPU cracking attacks and suitable for applications with no threats from side-channel timing attacks (eg. cryptocurrencies).
```
Argon2i
```
Argon2i instead uses data-independent memory access, which is preferred for password hashing and password-based key derivation, but it is slower as it makes more passes over the memory to protect from tradeoff attacks.
```
Argon2id
```
Argon2id is a hybrid of Argon2i and Argon2d, using a combination of data-depending and data-independent memory accesses, which gives some of Argon2i’s resistance to side-channel cache timing attacks and much of Argon2d’s resistance to GPU cracking attacks.

This is the default algorithm.

Hasher

opaque </>

An Argon2 password hasher.

pub opaque type Hasher

Functions

hash_password

</>

pub fn hash_password(
  hasher: Hasher,
  password: BitArray,
) -> Result(String, Nil)

Returns the hash of the given password.

hasher

</>

pub fn hasher() -> Hasher

Returns the default Hasher.

verify_password

</>

pub fn verify_password(
  hasher: Hasher,
  candidate candidate_password: BitArray,
  hash hashed_password: BitArray,
) -> Result(Nil, Nil)

Returns whether the candidate password matches the given hashed password.

with_hash_length

</>

pub fn with_hash_length(
  hasher: Hasher,
  hash_length: Int,
) -> Hasher

Sets the output hash length of the Hasher.

This is the length of the output hash, in bytes.

Must be a value between 4 and (2^32) - 1.

The default value is 32.

with_memory_cost

</>

pub fn with_memory_cost(
  hasher: Hasher,
  memory_cost: Int,
) -> Hasher

Sets the memory cost of the Hasher.

This is the memory size, expressed in kibibytes (KiB).

Must be a value between 8 * parallelism and (2^32) - 1.

The default value is 19,456 (19KiB).

with_parallelism

</>

pub fn with_parallelism(
  hasher: Hasher,
  parallelism: Int,
) -> Hasher

Sets the parallelism of the Hasher.

This is the number of threads that will be used when hashing a password.

Must be a value between 1 and (2^32) - 1.

The default value is 1.

with_time_cost

</>

pub fn with_time_cost(hasher: Hasher, time_cost: Int) -> Hasher

Sets the time cost of the Hasher.

This is the number of iterations that will be performed when hashing a password.

Must be a value between 1 and (2^32) - 1.

The default value is 2.