1Crypt::ScryptKDF(3)   User Contributed Perl Documentation  Crypt::ScryptKDF(3)
2
3
4

NAME

6       Crypt::ScryptKDF - Scrypt password based key derivation function
7

SYNOPSIS

9       Creating / verifying scrypt-based password hash:
10
11        use Crypt::ScryptKDF qw(scrypt_hash scrypt_hash_verify);
12
13        my $hash1 = scrypt_hash("secret password");
14        # .. later
15        die "Invalid password" unless scrypt_hash_verify("secret password", $hash1);
16
17        #or by specifying Scrypt parameters
18        my $hash2 = scrypt_hash("secret password", \32, 16384, 8, 1, 32);
19        # .. later
20        die "Invalid password" unless scrypt_hash_verify("secret password", $hash2);
21
22       Creating raw scrypt-based derived key:
23
24        use Crypt::ScryptKDF qw(scrypt_raw scrypt_hex scrypt_b64);
25
26        my $binary_buffer = scrypt_raw($password, $salt, $N, $r, $p, $len);
27        my $hexadecimal_string = scrypt_hex($password, $salt, $N, $r, $p, $len);
28        my $base64_string = scrypt_b64($password, $salt, $N, $r, $p, $len);
29

DESCRIPTION

31       Scrypt is a password-based key derivation function (like for example
32       PBKDF2). Scrypt was designed to be "memory-hard" algorithm in order to
33       make it expensive to perform large scale custom hardware attacks.
34
35       It can be used for:
36
37       •   deriving cryptographic keys from low-entropy password (like PBKDF2)
38
39       •   creating (+validating) password hashes (like PBKDF2 or Bcrypt)
40
41       More details about Scrypt: <http://www.tarsnap.com/scrypt/scrypt.pdf>
42       and <https://tools.ietf.org/html/draft-josefsson-scrypt-kdf>
43
44       IMPORTANT: This module needs a cryptographically strong random number
45       generator. It tries to use one of the following:
46
47       •   Crypt::PRNG - random_bytes()
48
49       •   Crypt::OpenSSL::Random - random_bytes()
50
51       •   Net::SSLeay - RAND_bytes()
52
53       •   Crypt::Random - makerandom_octet()
54
55       •   Bytes::Random::Secure - random_bytes()
56
57       •   As an unsecure fallback it uses built-in rand()
58

FUNCTIONS

60       •   scrypt_raw
61
62           Derive a key from given "password" and "salt" (+ optional params).
63
64            my $derived_key_raw_bytes = scrypt_raw($password, $salt, $N, $r, $p, $len);
65            #or
66            my $derived_key_raw_bytes = scrypt_raw($password, $salt);
67
68            #  $password - low-entropy secret (bytes)
69            #  $salt - raw octects (bytes) with a salt
70            #  $N - CPU/memory cost (has to be power of 2 and >1) DEFAULT: 2^14 = 16384
71            #  $r - block size parameter                          DEFAULT: 8
72            #  $p - parallelization parameter                     DEFAULT: 1
73            #  $len - length of derived key (in bytes)            DEFAULT: 32
74            #returns:
75            #  $derived_key .. raw bytes of length $len
76
77       •   scrypt_hex
78
79           Similar to scrypt_raw only the return value is encoded as
80           hexadecimal value.
81
82            my $derived_key_hex_string = scrypt_hex($password, $salt, $N, $r, $p, $len);
83            #or
84            my $derived_key_hex_string = scrypt_hex($password, $salt);
85
86       •   scrypt_b64
87
88           Similar to scrypt_raw only the return value is BASE64 encoded.
89
90            my $derived_key_base64_string = scrypt_b64($password, $salt, $N, $r, $p, $len);
91            #or
92            my $derived_key_base64_string = scrypt_b64($password, $salt);
93
94       •   scrypt_hash
95
96           Create a password hash for given "password".
97
98            my $hash = scrypt_hash($password, $salt, $N, $r, $p, $len);
99
100            #  params same as by scrypt_raw, the $salt can also be a scalar ref with salt
101            #  length e.g. $salt=\24 means that salt will be 24 randomly generated bytes
102            #returns:
103            #  string with password hash (suitable for storing in DB) e.g.
104            #  'SCRYPT:16384:8:1:BK8jkrqgm3BEtMh/g+WGL+k8ZeoAo=:YsEnQWld4UK8EqRZ9JuGbQnnlkXaM='
105
106           Some of the parameters are optional:
107
108            # 1 arg variant
109            my $hash = scrypt_hash($password); # generate random salt (32 bytes)
110
111            # 2 args variant
112            my $hash = scrypt_hash($password, $salt); # use given $salt
113            my $hash = scrypt_hash($password, \20);   # generate random salt (20 bytes)
114
115            # 5 args variant
116            my $hash = scrypt_hash($password, $N, $r, $p, $len); # random salt (32 bytes)
117
118       •   scrypt_hash_verify
119
120           Verify a password hash created with scrypt_hash()
121
122            my $is_valid = scrypt_hash_verify($password, $hash);
123            #  $password - password to be verified
124            #  $hash - hash previously created via scrypt_hash
125            #returns:
126            #  1 (ok) or 0 (fail)
127
128       •   random_bytes
129
130           Generate random bytes of given length.
131
132            my $salt = random_bytes($len);
133            #  $len - number of random bytes
134            #returns:
135            #  $len random octets
136

LICENSE

138       This program is free software; you can redistribute it and/or modify it
139       under the same terms as Perl itself.
140

142       Copyright (c) 2013-2015 DCIT, a.s. <http://www.dcit.cz> / Karel Miko
143
144
145
146perl v5.36.0                      2023-01-20               Crypt::ScryptKDF(3)
Impressum