NAME

       Crypt::Argon2 - Perl interface to the Argon2 key derivation functions

VERSION

       version 0.030

SYNOPSIS

        use Crypt::Argon2 qw/argon2id_pass argon2_verify/;

        sub add_pass {
          my ($user, $password) = @_;
          my $salt = get_random(16);
          my $encoded = argon2id_pass($password, $salt, 3, '32M', 1, 16);
          store_password($user, $encoded);
        }

        sub check_password {
          my ($user, $password) = @_;
          my $encoded = fetch_encoded($user);
          return argon2_verify($encoded, $password);
        }

DESCRIPTION

       This module implements the Argon2 key derivation function, which is suitable to convert any password into
       a cryptographic key. This is most often used to for secure storage of passwords but can also be used to
       derive a encryption key from a password. It offers variable time and memory costs as well as output size.

       To find appropriate parameters, the bundled program "argon2-calibrate" can be used.

FUNCTIONS

   argon2_pass($type, $password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)
       This function processes the $password with the given $salt and parameters. It encodes the resulting tag
       and the parameters as a password string (e.g.
       "$argon2id$v=19$m=65536,t=2,p=1$c29tZXNhbHQ$wWKIMhR9lyDFvRz9YTZweHKfbftvj+qf+YFY4NeBbtA").

       •   $type

           The argon2 type that is used. This must be one of 'argon2id', 'argon2i' or 'argon2d'.

       •   $password

           This is the password that is to be turned into a cryptographic key.

       •   $salt

           This is the salt that is used. It must be long enough to be unique.

       •   $t_cost

           This is the time-cost factor, typically a small integer that can be derived as explained above.

       •   $m_factor

           This  is  the  memory costs factor. This must be given as a integer followed by an order of magnitude
           ("k", "M" or "G" for kilobytes, megabytes or gigabytes respectively), e.g. '64M'.

       •   $parallelism

           This is the number of threads that are used in computing it.

       •   $tag_size

           This is the size of the raw result in bytes. Typical values are 16 or 32.

   argon2_verify($encoded, $password)
       This verifies that the $password matches $encoded. All parameters and the tag value  are  extracted  from
       $encoded, so no further arguments are necessary.

   argon2_raw($type, $password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)
       This  function  processes  the $password with the given $salt and parameters much like "argon2_pass", but
       returns the binary tag instead of a formatted string.

   argon2id_pass($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)
   argon2i_pass($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)
   argon2d_pass($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)
       This function processes the $password much like "argon2_pass" does, but the $type argument  is  set  like
       the function name.

   argon2id_verify($encoded, $password)
   argon2i_verify($encoded, $password)
   argon2d_verify($encoded, $password)
       This  verifies  that  the $password matches $encoded and the given type. All parameters and the tag value
       are extracted from $encoded, so no further arguments are necessary.

   argon2id_raw($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)
   argon2i_raw($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)
   argon2d_raw($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)
       This function processes the $password much like "argon2_raw" does, but the $type argument is set like the
       function name.

   argon2_needs_rehash($encoded, $type, $t_cost, $m_cost, $parallelism, $output_length, $salt_length)
       This function checks if a password-encoded string needs a rehash. It will return true if the $type (valid
       values are "argon2i",  "argon2id"  or  "argon2d"),  $t_cost,  $m_cost,  $parallelism,  $output_length  or
       $salt_length arguments mismatches any of the parameters of the password-encoded hash.

   argon2_types
       This returns all supported argon2 subtypes. Currently that's 'argon2id', 'argon2i' and 'argon2d'.

   ACKNOWLEDGEMENTS
       This    module    is    based    on    the    reference    implementation    as    can    be   found   at
       <https://github.com/P-H-C/phc-winner-argon2>.

   SEE ALSO
       You will also need a good source of randomness to generate good salts. Some possible solutions include:

       •   Net::SSLeay

           Its RAND_bytes function is OpenSSL's pseudo-randomness source.

       •   Crypt::URandom

           A minimalistic abstraction around OS-provided non-blocking (pseudo-)randomness.

       •   "/dev/random" / "/dev/urandom"

           A Linux/BSD specific pseudo-file that will allow you to read random bytes.

       Implementations of other similar algorithms include:

       •   Crypt::Bcrypt

           An implementation of bcrypt, a battle-tested algorithm that tries to  be  CPU  but  not  particularly
           memory intensive.

       •   Crypt::ScryptKDF

           An implementation of scrypt, a older scheme that also tries to be memory hard.

AUTHOR

       Leon Timmermans <leont@cpan.org>

COPYRIGHT AND LICENSE

       This  software  is Copyright (c) 2013 by Daniel Dinu, Dmitry Khovratovich, Jean-Philippe Aumasson, Samuel
       Neves, Thomas Pornin and Leon Timmermans.

       This is free software, licensed under:

         The Apache License, Version 2.0, January 2004

perl v5.40.1                                       2025-05-12                                 Crypt::Argon2(3pm)