| 1 |
NAME |
| 2 |
PBKDF2::Tiny - Minimalist PBKDF2 (RFC 2898) with HMAC-SHA1 or HMAC-SHA2 |
| 3 |
|
| 4 |
VERSION |
| 5 |
version 0.005 |
| 6 |
|
| 7 |
SYNOPSIS |
| 8 |
use PBKDF2::Tiny qw/derive verify/; |
| 9 |
|
| 10 |
my $dk = derive( 'SHA-1', $pass, $salt, $iters ); |
| 11 |
|
| 12 |
if ( verify( $dk, 'SHA-1', $pass, $salt, $iters ) ) { |
| 13 |
# password is correct |
| 14 |
} |
| 15 |
|
| 16 |
DESCRIPTION |
| 17 |
This module provides an RFC 2898 <https://tools.ietf.org/html/rfc2898> |
| 18 |
compliant PBKDF2 implementation using HMAC-SHA1 or HMAC-SHA2 in under |
| 19 |
100 lines of code. If you are using Perl 5.10 or later, it uses only |
| 20 |
core Perl modules. If you are on an earlier version of Perl, you need |
| 21 |
Digest::SHA or Digest::SHA::PurePerl. |
| 22 |
|
| 23 |
All documented functions are optionally exported. No functions are |
| 24 |
exported by default. |
| 25 |
|
| 26 |
FUNCTIONS |
| 27 |
derive |
| 28 |
$dk = derive( $type, $password, $salt, $iterations, $dk_length ) |
| 29 |
|
| 30 |
The "derive" function outputs a binary string with the derived key. The |
| 31 |
first argument indicates the digest function to use. It must be one of: |
| 32 |
SHA-1, SHA-224, SHA-256, SHA-384, or SHA-512. |
| 33 |
|
| 34 |
If a password or salt are not provided, they default to the empty |
| 35 |
string, so don't do that! RFC 2898 recommends |
| 36 |
<https://tools.ietf.org/html/rfc2898#section-4.1> a random salt of at |
| 37 |
least 8 octets. If you need a cryptographically strong salt, consider |
| 38 |
Crypt::URandom. |
| 39 |
|
| 40 |
The password and salt should encoded as octet strings. If not (i.e. if |
| 41 |
Perl's internal 'UTF8' flag is on), then an exception will be thrown. |
| 42 |
|
| 43 |
The number of iterations defaults to 1000 if not provided. If the |
| 44 |
derived key length is not provided, it defaults to the output size of |
| 45 |
the digest function. |
| 46 |
|
| 47 |
derive_hex |
| 48 |
Works just like "derive" but outputs a hex string. |
| 49 |
|
| 50 |
verify |
| 51 |
$bool = verify( $dk, $type, $password, $salt, $iterations, $dk_length ); |
| 52 |
|
| 53 |
The "verify" function checks that a given derived key (in binary form) |
| 54 |
matches the password and other parameters provided using a constant-time |
| 55 |
comparison function. |
| 56 |
|
| 57 |
The first parameter is the derived key to check. The remaining |
| 58 |
parameters are the same as for "derive". |
| 59 |
|
| 60 |
verify_hex |
| 61 |
Works just like "verify" but the derived key must be a hex string |
| 62 |
(without a leading "0x"). |
| 63 |
|
| 64 |
digest_fcn |
| 65 |
($fcn, $block_size, $digest_length) = digest_fcn('SHA-1'); |
| 66 |
$digest = $fcn->($data); |
| 67 |
|
| 68 |
This function is used internally by PBKDF2::Tiny, but made available in |
| 69 |
case it's useful to someone. |
| 70 |
|
| 71 |
Given one of the valid digest types, it returns a function reference |
| 72 |
that digests a string of data. It also returns block size and digest |
| 73 |
length for that digest type. |
| 74 |
|
| 75 |
hmac |
| 76 |
$key = $digest_fcn->($key) if length($key) > $block_size; |
| 77 |
$hmac = hmac( $data, $key, $digest_fcn, $block_size ); |
| 78 |
|
| 79 |
This function is used internally by PBKDF2::Tiny, but made available in |
| 80 |
case it's useful to someone. |
| 81 |
|
| 82 |
The first two arguments are the data and key inputs to the HMAC |
| 83 |
function. Both should be encoded as octet strings, as underlying |
| 84 |
HMAC/digest functions may croak or may give unexpected results if Perl's |
| 85 |
internal UTF-8 flag is on. |
| 86 |
|
| 87 |
Note: if the key is longer than the digest block size, it must be |
| 88 |
preprocessed using the digesting function. |
| 89 |
|
| 90 |
The third and fourth arguments must be a digesting code reference (from |
| 91 |
"digest_fcn") and block size. |
| 92 |
|
| 93 |
SEE ALSO |
| 94 |
* Crypt::PBKDF2 |
| 95 |
|
| 96 |
* Digest::PBDKF2 |
| 97 |
|
| 98 |
SUPPORT |
| 99 |
Bugs / Feature Requests |
| 100 |
Please report any bugs or feature requests through the issue tracker at |
| 101 |
<https://github.com/dagolden/PBKDF2-Tiny/issues>. You will be notified |
| 102 |
automatically of any progress on your issue. |
| 103 |
|
| 104 |
Source Code |
| 105 |
This is open source software. The code repository is available for |
| 106 |
public review and contribution under the terms of the license. |
| 107 |
|
| 108 |
<https://github.com/dagolden/PBKDF2-Tiny> |
| 109 |
|
| 110 |
git clone https://github.com/dagolden/PBKDF2-Tiny.git |
| 111 |
|
| 112 |
AUTHOR |
| 113 |
David Golden <[email protected]> |
| 114 |
|
| 115 |
COPYRIGHT AND LICENSE |
| 116 |
This software is Copyright (c) 2014 by David Golden. |
| 117 |
|
| 118 |
This is free software, licensed under: |
| 119 |
|
| 120 |
The Apache License, Version 2.0, January 2004 |
| 121 |
|