argus

Types

Argon2Algorithm

pub type Argon2Algorithm {
  Argon2d
  Argon2i
  Argon2id
}

Constructors

```
Argon2d
```
```
Argon2i
```
```
Argon2id
```

HashError

</>

All possible Argon2 hashing errors. Most are unlikely to occur, but it’s good to be aware of them.

pub type HashError {
  OutputPointerIsNull
  OutputTooShort
  OutputTooLong
  PasswordTooShort
  PasswordTooLong
  SaltTooShort
  SaltTooLong
  AssociatedDataTooShort
  AssociatedDataTooLong
  SecretTooShort
  SecretTooLong
  TimeCostTooSmall
  TimeCostTooLarge
  MemoryCostTooSmall
  MemoryCostTooLarge
  TooFewLanes
  TooManyLanes
  PasswordPointerMismatch
  SaltPointerMismatch
  SecretPointerMismatch
  AssociatedDataPointerMismatch
  MemoryAllocationError
  FreeMemoryCallbackNull
  AllocateMemoryCallbackNull
  IncorrectParameter
  IncorrectType
  InvalidAlgorithm
  OutputPointerMismatch
  TooFewThreads
  TooManyThreads
  NotEnoughMemory
  EncodingFailed
  DecodingFailed
  ThreadFailure
  DecodingLengthFailure
  VerificationFailure
  UnknownErrorCode
}

Constructors

```
OutputPointerIsNull
```
```
OutputTooShort
```
```
OutputTooLong
```
```
PasswordTooShort
```
```
PasswordTooLong
```
```
SaltTooShort
```
```
SaltTooLong
```
```
AssociatedDataTooShort
```
```
AssociatedDataTooLong
```
```
SecretTooShort
```
```
SecretTooLong
```
```
TimeCostTooSmall
```
```
TimeCostTooLarge
```
```
MemoryCostTooSmall
```
```
MemoryCostTooLarge
```
```
TooFewLanes
```
```
TooManyLanes
```
```
PasswordPointerMismatch
```
```
SaltPointerMismatch
```
```
SecretPointerMismatch
```
```
AssociatedDataPointerMismatch
```
```
MemoryAllocationError
```
```
FreeMemoryCallbackNull
```
```
AllocateMemoryCallbackNull
```
```
IncorrectParameter
```
```
IncorrectType
```
```
InvalidAlgorithm
```
```
OutputPointerMismatch
```
```
TooFewThreads
```
```
TooManyThreads
```
```
NotEnoughMemory
```
```
EncodingFailed
```
```
DecodingFailed
```
```
ThreadFailure
```
```
DecodingLengthFailure
```
```
VerificationFailure
```
```
UnknownErrorCode
```

HashOutput

</>

pub type HashOutput {
  HashOutput(raw_hash: BitArray, encoded_hash: String)
}

Constructors

HashOutput(raw_hash: BitArray, encoded_hash: String)

Hasher

opaque </>

pub opaque type Hasher

Salt

opaque </>

A value containing validated bytes for salting a password.

Usually produced via the gen_salt function.

pub opaque type Salt

Values

derive_encryption_key

</>

pub fn derive_encryption_key(
  hasher: Hasher,
  password: String,
  salt: Salt,
) -> Result(BitArray, HashError)

Derive an encryption key from a password.

You do not need to use this function for password hashing. If you’re using Argus for password hashing, prefer the hash function.

You only need this function if you’re using Argus to derive fixed-size cryptographic keys suitable for encryption, such as when encrypting a file.

In order to be able to re-derive an identical key, you must use the same salt and set of Argon2 parameters as when the original key was created. It’s recommended that you store these alongside the ciphertext.

gen_salt

</>

pub fn gen_salt() -> Salt

Generate a random 16-byte salt.

hash

</>

pub fn hash(
  hasher: Hasher,
  password: String,
) -> Result(HashOutput, HashError)

Hash a password using the provided hasher.

This will use gen_salt to generate a random salt.

Examples

import argus

let assert Ok(hash_output) =
  argus.hasher()
  |> argus.algorithm(argus.Argon2id)
  |> argus.time_cost(3)
  |> argus.memory_cost(12288)
  |> argus.parallelism(1)
  |> argus.hash_length(32)
  |> argus.hash("password")

let assert Ok(True) = argus.verify(hash_output.encoded_hash, "password")

hash_length

</>

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

Set the hash length to use for the hasher.

hasher

</>

pub fn hasher() -> Hasher

Create a new hasher with default settings based on the OWASP recommendations.

Note: if you change the algorithm to Argon2i, you will need to change the memory_cost to 12_288 (12 mebibytes) or less for performance reasons.

The hasher_argon2i function is provided with the recommended settings for Argon2i.

hasher_argon2i

</>

pub fn hasher_argon2i() -> Hasher

Create a new hasher with default settings based on the OWASP recommendations for Argon2i.

make_salt

</>

pub fn make_salt(from bytes: BitArray) -> Result(Salt, Nil)

Make a salt from a BitArray. You’ll only need to do this when using derive_encryption_key with a pre-existing stored salt. For most use cases, hash will generate a secure salt for you.

Returns Error(Nil) if the provided BitArray does not contain whole bytes.

memory_cost

</>

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

Set the memory cost to use for the hasher.

parallelism

</>

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

Set the parallelism to use for the hasher.

salt_bytes

</>

pub fn salt_bytes(salt: Salt) -> BitArray

Retrieve the raw bytes from a Salt value.

time_cost

</>

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

Set the time cost to use for the hasher.

verify

</>

pub fn verify(
  encoded_hash: String,
  password: String,
) -> Result(Bool, HashError)

Verify a password using the provided encoded hash.