blib/lib/Crypt/KeyDerivation.pm

filter: Statementstmt 100% 21 / 21 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 4 / 4 Podpod n/a totaltotal 100% 25 / 25 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« blib/lib/Crypt/Cipher/XTEA.pm ↑ Summary blib/lib/Crypt/Mac/BLAKE2b.pm »
1 package Crypt::KeyDerivation;
2  
3 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 3 our $VERSION = '0.091';
6  
7 3 require Exporter; our @ISA = qw(Exporter); ### use Exporter 5.57 'import';
8 3 our %EXPORT_TAGS = ( all => [qw(pbkdf1 pbkdf1_openssl pbkdf2 hkdf hkdf_expand hkdf_extract bcrypt_pbkdf scrypt_pbkdf argon2_pbkdf)] );
9 3 our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
10 3 our @EXPORT = qw();
11  
12 3 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
13 3 $Carp::Internal{(__PACKAGE__)}++;
14 3 ▶use CryptX;
Subroutine BEGIN: called CC=1 SCAR=0.0
15  
16 3 1;
17  
18 =pod
19  
20 =head1 NAME
21  
22 Crypt::KeyDerivation - PBKDF1, PBKDF2, HKDF, Bcrypt, Scrypt, Argon2 key derivation functions
23  
24 =head1 SYNOPSIS
25  
26 use Crypt::KeyDerivation ':all';
27  
28 my $password = 'secret';
29 my $salt = '12345678';
30 my $iteration_count = 5000;
31 my $hash_name = 'SHA256';
32 my $len = 32;
33 my $keying_material = 'input keying material';
34 my $info = 'context';
35 my $rounds = 16;
36 my $N = 1024;
37 my $r = 8;
38 my $p = 1;
39 my $type = 'argon2id';
40 my $t_cost = 3;
41 my $m_factor = 65536;
42 my $parallelism = 1;
43 my $secret = '';
44 my $ad = '';
45  
46 ### PBKDF1/2
47 my $pbkdf1_key = pbkdf1($password, $salt, $iteration_count, $hash_name, $len);
48 my $openssl_pbkdf1_key = pbkdf1_openssl($password, $salt, $iteration_count, $hash_name, $len);
49 my $pbkdf2_key = pbkdf2($password, $salt, $iteration_count, $hash_name, $len);
50  
51 ### HKDF & co.
52 my $hkdf_okm = hkdf($keying_material, $salt, $hash_name, $len, $info);
53 my $prk = hkdf_extract($keying_material, $salt, $hash_name);
54 my $expanded_okm = hkdf_expand($prk, $hash_name, $len, $info);
55  
56 ### bcrypt / scrypt / argon2
57 my $bcrypt_key = bcrypt_pbkdf($password, $salt, $rounds, $hash_name, $len);
58 my $scrypt_key = scrypt_pbkdf($password, $salt, $N, $r, $p, $len);
59 my $argon2_key = argon2_pbkdf($type, $password, $salt, $t_cost, $m_factor, $parallelism, $len, $secret, $ad);
60  
61 =head1 DESCRIPTION
62  
63 Provides an interface to key derivation functions:
64  
65 =over
66  
67 =item * PBKDF1 and PBKDF2 according to PKCS #5 v2.0
68 L<https://www.rfc-editor.org/rfc/rfc2898>
69  
70 =item * HKDF (+ related) according to
71 L<https://www.rfc-editor.org/rfc/rfc5869>
72  
73 =item * Bcrypt-PBKDF as defined by the OpenBSD project
74  
75 =item * Scrypt according to L<https://www.rfc-editor.org/rfc/rfc7914>
76  
77 =item * Argon2 according to L<https://www.rfc-editor.org/rfc/rfc9106>
78  
79 =back
80  
81 While primarily designed for key derivation, the functions PBKDF2, Bcrypt, Scrypt and Argon2
82 are also widely used for password hashing. In that use case the derived key serves as the
83 stored password hash.
84  
85 All functions return raw bytes. Passing an output length of C<0> returns an
86 empty string in this wrapper API. Argument validation still happens first:
87 required password / input-keying-material arguments reject C<undef>, invalid
88 hash names and invalid Argon2 type names are still rejected, and malformed
89 optional scalar arguments still return C<undef> where applicable.
90  
91 This zero-length behaviour is a C<Crypt::KeyDerivation> wrapper policy. The
92 underlying libtomcrypt functions do not all behave the same way: some accept
93 zero-length outputs, while others reject them with algorithm-specific checks.
94 Code calling libtomcrypt directly should not assume the wrapper behaviour.
95  
96 =head1 EXPORT
97  
98 Nothing is exported by default.
99  
100 You can export selected functions:
101  
102 use Crypt::KeyDerivation qw(
103 pbkdf1 pbkdf1_openssl pbkdf2
104 hkdf hkdf_expand hkdf_extract
105 bcrypt_pbkdf scrypt_pbkdf argon2_pbkdf
106 );
107  
108 Or all of them at once:
109  
110 use Crypt::KeyDerivation ':all';
111  
112 =head1 FUNCTIONS
113  
114 =head2 pbkdf1
115  
116 B<BEWARE:> If you are not sure, do not use C<pbkdf1> - choose C<pbkdf2> instead.
117  
118 my $derived_key = pbkdf1($password, $salt, $iteration_count, $hash_name, $len);
119 #or
120 my $derived_key = pbkdf1($password, $salt, $iteration_count, $hash_name);
121 #or
122 my $derived_key = pbkdf1($password, $salt, $iteration_count);
123 #or
124 my $derived_key = pbkdf1($password, $salt);
125  
126 # $password ......... [binary string] input keying material (password)
127 # $salt ............. [binary string] salt/nonce (expected length: 8 bytes)
128 # $iteration_count .. [integer] optional, DEFAULT: 5000
129 # $hash_name ........ [string] optional, DEFAULT: 'SHA256'
130 # $len .............. [integer] optional, derived key len in bytes, DEFAULT: 32
131  
132 In strict PKCS #5 v1 mode, the derived key length must not exceed the selected
133 hash output size. For example, C<SHA1> allows at most 20 bytes.
134  
135 The underlying algorithm uses only the first 8 bytes of C<$salt>. Shorter salts
136 are rejected; longer salts are accepted but truncated to 8 bytes.
137  
138 =head2 pbkdf1_openssl
139  
140 I<Since: CryptX-0.088>
141  
142 OpenSSL-compatible variant of PBKDF1 (implements C<EVP_BytesToKey>). Unlike strict
143 C<pbkdf1>, the output length is not limited to the hash size -- it can be arbitrarily
144 long by chaining hash blocks.
145  
146 B<Important:> this function implements the OpenSSL-compatible algorithm, but its
147 default parameters do B<not> match the historical C<openssl enc> defaults.
148 OpenSSL traditionally uses C<MD5> and C<iteration_count=1>, while this wrapper
149 defaults to C<SHA256> and C<5000>. If you need output compatible with the
150 traditional OpenSSL default behaviour, pass both values explicitly:
151  
152 my $derived_key = pbkdf1_openssl($password, $salt, 1, 'MD5', $len);
153  
154 my $derived_key = pbkdf1_openssl($password, $salt, $iteration_count, $hash_name, $len);
155 #or
156 my $derived_key = pbkdf1_openssl($password, $salt, $iteration_count, $hash_name);
157 #or
158 my $derived_key = pbkdf1_openssl($password, $salt, $iteration_count);
159 #or
160 my $derived_key = pbkdf1_openssl($password, $salt);
161  
162 # $password ......... [binary string] input keying material (password)
163 # $salt ............. [binary string] salt/nonce (expected length: 8 bytes)
164 # $iteration_count .. [integer] optional, DEFAULT: 5000
165 # $hash_name ........ [string] optional, DEFAULT: 'SHA256'
166 # $len .............. [integer] optional, derived key len in bytes, DEFAULT: 32
167  
168 The underlying algorithm uses only the first 8 bytes of C<$salt>. Shorter salts
169 are rejected; longer salts are accepted but truncated to 8 bytes.
170  
171 =head2 pbkdf2
172  
173 my $derived_key = pbkdf2($password, $salt, $iteration_count, $hash_name, $len);
174 #or
175 my $derived_key = pbkdf2($password, $salt, $iteration_count, $hash_name);
176 #or
177 my $derived_key = pbkdf2($password, $salt, $iteration_count);
178 #or
179 my $derived_key = pbkdf2($password, $salt);
180  
181 # $password ......... [binary string] input keying material (password)
182 # $salt ............. [binary string] salt/nonce (any length; longer is better)
183 # $iteration_count .. [integer] optional, DEFAULT: 5000
184 # $hash_name ........ [string] optional, DEFAULT: 'SHA256'
185 # $len .............. [integer] optional, derived key len in bytes, DEFAULT: 32
186  
187 =head2 hkdf
188  
189 my $okm = hkdf($password, $salt, $hash_name, $len, $info);
190 #or
191 my $okm = hkdf($password, $salt, $hash_name, $len);
192 #or
193 my $okm = hkdf($password, $salt, $hash_name);
194 #or
195 my $okm = hkdf($password, $salt);
196  
197 # $password ... [binary string] input keying material
198 # $salt ....... [binary string | undef] salt; if undef defaults to HashLen zero octets
199 # $hash_name .. [string] optional, DEFAULT: 'SHA256'
200 # $len ........ [integer] optional, derived key len in bytes, DEFAULT: 32
201 # $info ....... [binary string] optional context/application info, DEFAULT: ''
202  
203 Use C<hkdf> for one-shot extract+expand. For multi-step workflows, use
204 C<hkdf_extract> followed by C<hkdf_expand>.
205  
206 The input keying material / pseudokey arguments must be string or
207 stringifiable scalars. Optional C<$salt> and C<$info> may be C<undef>.
208  
209 =head2 hkdf_extract
210  
211 my $prk = hkdf_extract($password, $salt, $hash_name);
212 #or
213 my $prk = hkdf_extract($password, $salt);
214  
215 # $password ... [binary string] input keying material
216 # $salt ....... [binary string | undef] salt; if undef defaults to HashLen zero octets
217 # $hash_name .. [string] optional, DEFAULT: 'SHA256'
218  
219 Returns the pseudorandom key (PRK). Its length is the digest size of the
220 selected hash and it is intended to be passed to C<hkdf_expand>.
221  
222  
223 =head2 hkdf_expand
224  
225 my $okm = hkdf_expand($pseudokey, $hash_name, $len, $info);
226 #or
227 my $okm = hkdf_expand($pseudokey, $hash_name, $len);
228 #or
229 my $okm = hkdf_expand($pseudokey, $hash_name);
230 #or
231 my $okm = hkdf_expand($pseudokey);
232  
233 # $pseudokey .. [binary string] input keying material (normally from hkdf_extract)
234 # $hash_name .. [string] optional, DEFAULT: 'SHA256'
235 # $len ........ [integer] optional, derived key len in bytes, DEFAULT: 32
236 # $info ....... [binary string] optional context/application info, DEFAULT: ''
237  
238 C<$pseudokey> is normally the PRK returned by C<hkdf_extract>.
239  
240 =head2 bcrypt_pbkdf
241  
242 I<Since: CryptX-0.088>
243  
244 bcrypt-based key derivation as defined by the OpenBSD project.
245  
246 my $derived_key = bcrypt_pbkdf($password, $salt, $rounds, $hash_name, $len);
247 #or
248 my $derived_key = bcrypt_pbkdf($password, $salt, $rounds, $hash_name);
249 #or
250 my $derived_key = bcrypt_pbkdf($password, $salt, $rounds);
251 #or
252 my $derived_key = bcrypt_pbkdf($password, $salt);
253  
254 # $password ... [binary string] input keying material (password)
255 # $salt ....... [binary string] salt/nonce
256 # $rounds ..... [integer] optional, number of rounds, DEFAULT: 16
257 # $hash_name .. [string] optional, DEFAULT: 'SHA512'
258 # $len ........ [integer] optional, derived key len in bytes, DEFAULT: 32
259  
260 Larger C<$rounds> values increase CPU cost linearly.
261  
262 =head2 scrypt_pbkdf
263  
264 I<Since: CryptX-0.088>
265  
266 scrypt key derivation according to L<https://www.rfc-editor.org/rfc/rfc7914>.
267  
268 my $derived_key = scrypt_pbkdf($password, $salt, $N, $r, $p, $len);
269 #or
270 my $derived_key = scrypt_pbkdf($password, $salt, $N, $r, $p);
271 #or
272 my $derived_key = scrypt_pbkdf($password, $salt, $N);
273 #or
274 my $derived_key = scrypt_pbkdf($password, $salt);
275  
276 # $password ... [binary string] input keying material (password)
277 # $salt ....... [binary string] salt/nonce
278 # $N .......... [integer] optional, CPU/memory cost (must be power of 2), DEFAULT: 1024
279 # $r .......... [integer] optional, block size, DEFAULT: 8
280 # $p .......... [integer] optional, parallelization parameter, DEFAULT: 1
281 # $len ........ [integer] optional, derived key len in bytes, DEFAULT: 32
282  
283 Use only power-of-two values for C<$N>. Larger C<$N>, C<$r>, and C<$p>
284 increase resource usage substantially; invalid combinations croak.
285  
286 =head2 argon2_pbkdf
287  
288 I<Since: CryptX-0.088>
289  
290 Argon2 key derivation according to L<https://www.rfc-editor.org/rfc/rfc9106>.
291  
292 my $derived_key = argon2_pbkdf($type, $password, $salt, $t_cost, $m_factor, $parallelism, $len, $secret, $ad);
293 #or
294 my $derived_key = argon2_pbkdf($type, $password, $salt, $t_cost, $m_factor, $parallelism, $len);
295 #or
296 my $derived_key = argon2_pbkdf($type, $password, $salt, $t_cost, $m_factor, $parallelism);
297 #or
298 my $derived_key = argon2_pbkdf($type, $password, $salt);
299  
300 # $type ... [string] one of 'argon2d', 'argon2i', 'argon2id'
301 # $password ... [binary string] input keying material (password)
302 # $salt ... [binary string] salt/nonce (recommended: at least 16 bytes)
303 # $t_cost ... [integer] optional, time cost (number of iterations), DEFAULT: 3
304 # $m_factor ... [integer] optional, memory cost in kibibytes (1 KiB = 1024 B), DEFAULT: 65536 (= 64 MiB)
305 # $parallelism ... [integer] optional, degree of parallelism, DEFAULT: 1
306 # $len ... [integer] optional, derived key len in bytes, DEFAULT: 32
307 # $secret ... [binary string] optional, secret value, DEFAULT: ''
308 # $ad ... [binary string] optional, associated data, DEFAULT: ''
309  
310 Increasing C<$t_cost>, C<$m_factor>, or C<$parallelism> increases work and
311 memory requirements. Invalid combinations croak. Optional C<$secret> and
312 C<$ad> may be C<undef>; otherwise they must be string or stringifiable scalars.
313  
314 =head1 SEE ALSO
315  
316 =over
317  
318 =item * L<CryptX>
319  
320 =item * L<Crypt::Digest>, L<Crypt::Mac>, L<Crypt::PRNG>
321  
322 =item * L<https://www.rfc-editor.org/rfc/rfc2898>
323  
324 =item * L<https://www.rfc-editor.org/rfc/rfc5869>
325  
326 =item * L<https://www.rfc-editor.org/rfc/rfc7914>
327  
328 =item * L<https://www.rfc-editor.org/rfc/rfc9106>
329  
330 =back
331  
332 =cut
« blib/lib/Crypt/Cipher/XTEA.pm ↑ Summary blib/lib/Crypt/Mac/BLAKE2b.pm »