NAME

Crypt::Argon2 - Easy Argon2 password hashing

SYNOPSIS

Password hashing and verification are one function each, and utilze a crypt()-style output string:

> use Crypt::Argon2

> my $hash = argon2-hash("password")
$argon2i$v=19$m=65536,t=2,p=2$q5gCW1J92SNJPlPtoOsP1Q$BCGwLfZsfL7vyF69PhHsQA

> argon2-verify($hash, "password")
True

> argon2-verify($hash, "wrong")
False

> argon2-hash("password", :t_cost(4), :m_cost(2**18), :parallelism(4), :hashlen(24))
$argon2i$v=19$m=262144,t=4,p=4$Ou7t7DzIXXJnEIok0kr10A$0VC9/L+aXKI34i1FQHla4LxQz30/3G0H

# Other variants are supported:
> argon2-hash("password", :type(Argon2_id))
$argon2id$v=19$m=65536,t=2,p=2$Qj4oYwx2A1Hryw03ntMNRQ$mQc1Zn4oSIvH8gduU1xNtQ


Key generation returns `(Buf $key, Argon2-meta $meta)`, where `$key` can be regenerated by running the function again with `$meta` as its second parameter:

```raku
> use Crypt::Argon2::DeriveKey;

> my ($key, $meta) = argon2-derive-key("password", :hashlen(16))
(Buf:0x<02 78 d7 dc 29 4d 8b 9a fb 89 0d 91 be 09 64 d0> ... )

> argon2-derive-key("password", $meta)
Buf:0x<02 78 d7 dc 29 4d 8b 9a fb 89 0d 91 be 09 64 d0>

DESCRIPTION

Argon2 is the winner of the Password Hashing Competition. It is both memory- and compute-hard. This module is a NativeCall binding that defaults to the Argon2i variant, which is resistant to side-channel attacks.

Additionally, Argon2_d and Argon2_id variants are supported with the "type" parameter to argon2-hash.

COST PARAMETERS

Hashing takes three cost parameters: time cost as an iteration count, memory cost in KiB, and parallelism in thread count. By default, password hashing uses two iterations and 64 MiB of memory, and key generation uses three iterations and 128 MiB of memory. Both defaults use two threads.

Parameters that may better fit your environment can be tested with the included bin/argon2-benchmark.p6. As an example, doubling either memory use or iteration count will roughly double hashing time, meaning you can somewhat 'trade' these costs if need be:

$ perl6 -Ilib bin/argon2-benchmark.p6
Running 10 iterations of argon2-verify() with the following settings:
    Iterations: 2
    Memory cost: 65536 KiB
    Parallelism: 2 threads
    Hash length: 16 bytes
Time per verification: 122.20 ms

$ perl6 -Ilib bin/argon2-benchmark.p6 --m_cost=32768 --t_cost=4
Running 10 iterations of argon2-verify() with the following settings:
    Iterations: 4
    Memory cost: 32768 KiB
    Parallelism: 2 threads
    Hash length: 16 bytes
Time per verification: 110.47 ms

AUTHOR

Current Maintainer: Adrian Kreher avuserow@gmail.com

Original Author: skinkade https://github.com/skinkade

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.