File Coverage

blib/lib/Crypt/KeyDerivation.pm
Criterion Covered Total %
statement 12 12 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 16 16 100.0


line stmt bran cond sub pod time code
1             package Crypt::KeyDerivation;
2              
3 2     2   68840 use strict;
  2         11  
  2         55  
4 2     2   9 use warnings;
  2         4  
  2         307  
5             our $VERSION = '0.080_001';
6              
7             require Exporter; our @ISA = qw(Exporter); ### use Exporter 5.57 'import';
8             our %EXPORT_TAGS = ( all => [qw(pbkdf1 pbkdf2 hkdf hkdf_expand hkdf_extract)] );
9             our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );
10             our @EXPORT = qw();
11              
12 2     2   14 use Carp;
  2         4  
  2         135  
13             $Carp::Internal{(__PACKAGE__)}++;
14 2     2   416 use CryptX;
  2         5  
  2         110  
15              
16             1;
17              
18             =pod
19              
20             =head1 NAME
21              
22             Crypt::KeyDerivation - PBKDF1, PBKDF2 and HKDF key derivation functions
23              
24             =head1 SYNOPSIS
25              
26             use Crypt::KeyDerivation ':all';
27              
28             ### PBKDF1/2
29             $derived_key1 = pbkdf1($password, $salt, $iteration_count, $hash_name, $len);
30             $derived_key2 = pbkdf2($password, $salt, $iteration_count, $hash_name, $len);
31              
32             ### HKDF & co.
33             $derived_key3 = hkdf($keying_material, $salt, $hash_name, $len, $info);
34             $prk = hkdf_extract($keying_material, $salt, $hash_name);
35             $okm1 = hkdf_expand($prk, $hash_name, $len, $info);
36              
37             =head1 DESCRIPTION
38              
39             Provides an interface to Key derivation functions:
40              
41             =over
42              
43             =item * PBKDF1 and PBKDF according to PKCS#5 v2.0 L
44              
45             =item * HKDF (+ related) according to L
46              
47             =back
48              
49             =head1 FUNCTIONS
50              
51             =head2 pbkdf1
52              
53             B if you are not sure, do not use C but rather choose C.
54              
55             $derived_key = pbkdf1($password, $salt, $iteration_count, $hash_name, $len);
56             #or
57             $derived_key = pbkdf1($password, $salt, $iteration_count, $hash_name);
58             #or
59             $derived_key = pbkdf1($password, $salt, $iteration_count);
60             #or
61             $derived_key = pbkdf1($password, $salt);
62              
63             # $password ......... input keying material (password)
64             # $salt ............. salt/nonce (expected length: 8)
65             # $iteration_count .. optional, DEFAULT: 5000
66             # $hash_name ........ optional, DEFAULT: 'SHA256'
67             # $len .............. optional, derived key len, DEFAULT: 32
68              
69             =head2 pbkdf2
70              
71             $derived_key = pbkdf2($password, $salt, $iteration_count, $hash_name, $len);
72             #or
73             $derived_key = pbkdf2($password, $salt, $iteration_count, $hash_name);
74             #or
75             $derived_key = pbkdf2($password, $salt, $iteration_count);
76             #or
77             $derived_key = pbkdf2($password, $salt);
78              
79             # $password ......... input keying material (password)
80             # $salt ............. salt/nonce
81             # $iteration_count .. optional, DEFAULT: 5000
82             # $hash_name ........ optional, DEFAULT: 'SHA256'
83             # $len .............. optional, derived key len, DEFAULT: 32
84              
85             =head2 hkdf
86              
87             $okm2 = hkdf($password, $salt, $hash_name, $len, $info);
88             #or
89             $okm2 = hkdf($password, $salt, $hash_name, $len);
90             #or
91             $okm2 = hkdf($password, $salt, $hash_name);
92             #or
93             $okm2 = hkdf($password, $salt);
94              
95             # $password ... input keying material (password)
96             # $salt ....... salt/nonce, if undef defaults to HashLen zero octets
97             # $hash_name .. optional, DEFAULT: 'SHA256'
98             # $len ........ optional, derived key len, DEFAULT: 32
99             # $info ....... optional context and application specific information, DEFAULT: ''
100              
101             =head2 hkdf_extract
102              
103             $prk = hkdf_extract($password, $salt, $hash_name);
104             #or
105             $prk = hkdf_extract($password, $salt, $hash_name);
106              
107             # $password ... input keying material (password)
108             # $salt ....... salt/nonce, if undef defaults to HashLen zero octets
109             # $hash_name .. optional, DEFAULT: 'SHA256'
110              
111              
112             =head2 hkdf_expand
113              
114             $okm = hkdf_expand($pseudokey, $hash_name, $len, $info);
115             #or
116             $okm = hkdf_expand($pseudokey, $hash_name, $len);
117             #or
118             $okm = hkdf_expand($pseudokey, $hash_name);
119             #or
120             $okm = hkdf_expand($pseudokey);
121              
122             # $pseudokey .. input keying material
123             # $hash_name .. optional, DEFAULT: 'SHA256'
124             # $len ........ optional, derived key len, DEFAULT: 32
125             # $info ....... optional context and application specific information, DEFAULT: ''
126              
127             =cut