1Crypt::Argon2(3pm) User Contributed Perl Documentation Crypt::Argon2(3pm)
2
6 Crypt::Argon2 - Perl interface to the Argon2 key derivation functions
7
9 version 0.019
10
12 use Crypt::Argon2 qw/argon2id_pass argon2_verify/;
13 sub add_pass {
15 my ($user, $password) = @_;
16 my $salt = get_random(16);
17 my $encoded = argon2id_pass($password, $salt, 3, '32M', 1, 16);
18 store_password($user, $encoded);
19 }
20 sub check_password {
22 my ($user, $password) = @_;
23 my $encoded = fetch_encoded($user);
24 return argon2_verify($encoded, $password);
25 }
26
28 This module implements the Argon2 key derivation function, which is
29 suitable to convert any password into a cryptographic key. This is most
30 often used to for secure storage of passwords but can also be used to
31 derive a encryption key from a password. It offers variable time and
32 memory costs as well as output size.
33 To find appropriate parameters, the bundled program "argon2-calibrate"
35 can be used.
36
38 argon2_pass($type, $password, $salt, $t_cost, $m_factor, $parallelism,
39 $tag_size)
40 This function processes the $password with the given $salt and
41 parameters. It encodes the resulting tag and the parameters as a
42 password string (e.g.
43 "$argon2id$v=19$m=65536,t=2,p=1$c29tZXNhbHQ$wWKIMhR9lyDFvRz9YTZweHKfbftvj+qf+YFY4NeBbtA").
44 • $type
46 The argon2 type that is used. This must be one of 'argon2id',
48 'argon2i' or 'argon2d'.
49 • $password
51 This is the password that is to be turned into a cryptographic key.
53 • $salt
55 This is the salt that is used. It must be long enough to be unique.
57 • $t_cost
59 This is the time-cost factor, typically a small integer that can be
61 derived as explained above.
62 • $m_factor
64 This is the memory costs factor. This must be given as a integer
66 followed by an order of magnitude ("k", "M" or "G" for kilobytes,
67 megabytes or gigabytes respectively), e.g. '64M'.
68 • $parallelism
70 This is the number of threads that are used in computing it.
72 • $tag_size
74 This is the size of the raw result in bytes. Typical values are 16
76 or 32.
77 argon2_verify($encoded, $password)
79 This verifies that the $password matches $encoded. All parameters and
80 the tag value are extracted from $encoded, so no further arguments are
81 necessary.
82 argon2_raw($type, $password, $salt, $t_cost, $m_factor, $parallelism,
84 $tag_size)
85 This function processes the $password with the given $salt and
86 parameters much like "argon2_pass", but returns the binary tag instead
87 of a formatted string.
88 argon2id_pass($password, $salt, $t_cost, $m_factor, $parallelism,
90 $tag_size)
91 argon2i_pass($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)
92 argon2d_pass($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)
93 This function processes the $password much like "argon2_pass" does, but
94 the $type argument is set like the function name.
95 argon2id_verify($encoded, $password)
97 argon2i_verify($encoded, $password)
98 argon2d_verify($encoded, $password)
99 This verifies that the $password matches $encoded and the given type.
100 All parameters and the tag value are extracted from $encoded, so no
101 further arguments are necessary.
102 argon2id_raw($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)
104 argon2i_raw($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)
105 argon2d_raw($password, $salt, $t_cost, $m_factor, $parallelism, $tag_size)
106 This function processes the $password much like "argon2_raw" does, but
107 the $type argument is set like the function name.
108 argon2_needs_rehash($encoded, $type, $t_cost, $m_cost, $parallelism,
110 $salt_length, $output_length)
111 This function checks if a password-encoded string needs a rehash. It
112 will return true if the $type (valid values are "argon2i", "argon2id"
113 or "argon2d"), $t_cost, $m_cost, $parallelism, $salt_length or
114 $output_length arguments mismatches or any of the parameters of the
115 password-encoded hash.
116 argon2_types
118 This returns all supported argon2 subtypes. Currently that's
119 'argon2id', 'argon2i' and 'argon2d'.
120 ACKNOWLEDGEMENTS
122 This module is based on the reference implementation as can be found at
123 <https://github.com/P-H-C/phc-winner-argon2>.
124 SEE ALSO
126 You will also need a good source of randomness to generate good salts.
127 Some possible solutions include:
128 • Net::SSLeay
130 Its RAND_bytes function is OpenSSL's pseudo-randomness source.
132 • Crypt::URandom
134 A minimalistic abstraction around OS-provided non-blocking
136 (pseudo-)randomness.
137 • "/dev/random" / "/dev/urandom"
139 A Linux/BSD specific pseudo-file that will allow you to read random
141 bytes.
142 Implementations of other similar algorithms include:
144 • Crypt::Bcrypt
146 An implementation of bcrypt, a battle-tested algorithm that tries
148 to be CPU but not particularly memory intensive.
149 • Crypt::ScryptKDF
151 An implementation of scrypt, a older scheme that also tries to be
153 memory hard.
154
156 Leon Timmermans <leont@cpan.org>
157
159 This software is Copyright (c) 2013 by Daniel Dinu, Dmitry
160 Khovratovich, Jean-Philippe Aumasson, Samuel Neves, Thomas Pornin and
161 Leon Timmermans.
162 This is free software, licensed under:
164 The Apache License, Version 2.0, January 2004
166perl v5.38.0 2023-09-17 Crypt::Argon2(3pm)