1Crypt::SaltedHash(3) User Contributed Perl Documentation Crypt::SaltedHash(3)
2
6 Crypt::SaltedHash - Perl interface to functions that assist in working
7 with salted hashes.
8
10 use Crypt::SaltedHash;
11 my $csh = Crypt::SaltedHash->new(algorithm => 'SHA-1');
13 $csh->add('secret');
14 my $salted = $csh->generate;
16 my $valid = Crypt::SaltedHash->validate($salted, 'secret');
17
19 The "Crypt::SaltedHash" module provides an object oriented interface to
20 create salted (or seeded) hashes of clear text data. The original
21 formalization of this concept comes from RFC-3112 and is extended by
22 the use of different digital agorithms.
23
25 Setting the data
26 The process starts with 2 elements of data:
27 · a clear text string (this could represent a password for instance).
29 · the salt, a random seed of data. This is the value used to augment
31 a hash in order to ensure that 2 hashes of identical data yield
32 different output.
33 For the purposes of this abstract we will analyze the steps within code
35 that perform the necessary actions to achieve the endresult hashes.
36 Cryptographers call this hash a digest. We will not however go into an
37 explanation of a one-way encryption scheme. Readers of this abstract
38 are encouraged to get information on that subject by their own.
39 Theoretically, an implementation of a one-way function as an algorithm
41 takes input, and provides output, that are both in binary form;
42 realistically though digests are typically encoded and stored in a
43 database or in a flat text or XML file. Take slappasswd5 for instance,
44 it performs the exact functionality described above. We will use it as
45 a black box compiled piece of code for our analysis.
46 In pseudocode we generate a salted hash as follows:
48 Get the source string and salt as separate binary objects
50 Concatenate the 2 binary values
51 Hash the concatenation into SaltedPasswordHash
52 Base64Encode(concat(SaltedPasswordHash, Salt))
53 We take a clear text string and hash this into a binary object
55 representing the hashed value of the clear text string plus the random
56 salt. Then we have the Salt value, which are typically 4 bytes of
57 purely random binary data represented as hexadecimal notation (Base16
58 as 8 bytes).
59 Using SHA-1 as the hashing algorithm, SaltedPasswordHash is of length
61 20 (bytes) in raw binary form (40 bytes if we look at it in hex). Salt
62 is then 4 bytes in raw binary form. The SHA-1 algorithm generates a 160
63 bit hash string. Consider that 8 bits = 1 byte. So 160 bits = 20 bytes,
64 which is exactly what the algorithm gives us.
65 The Base64 encoding of the binary result looks like:
67 {SSHA}B0O0XSYdsk7g9K229ZEr73Lid7HBD9DX
69 Take note here that the final output is a 32-byte string of data. The
71 Base64 encoding process uses bit shifting, masking, and padding as per
72 RFC-3548.
73 A couple of examples of salted hashes using on the same exact clear-
75 text string:
76 slappasswd -s testing123
78 {SSHA}72uhy5xc1AWOLwmNcXALHBSzp8xt4giL
79 slappasswd -s testing123
81 {SSHA}zmIAVaKMmTngrUi4UlS0dzYwVAbfBTl7
82 slappasswd -s testing123
84 {SSHA}Be3F12VVvBf9Sy6MSqpOgAdEj6JCZ+0f
85 slappasswd -s testing123
87 {SSHA}ncHs4XYmQKJqL+VuyNQzQjwRXfvu6noa
88 4 runs of slappasswd against the same clear text string each yielded
90 unique endresult hashes. The random salt is generated silently and
91 never made visible.
92 Extracting the data
94 One of the keys to note is that the salt is dealt with twice in the
95 process. It is used once for the actual application of randomness to
96 the given clear text string, and then it is stored within the final
97 output as purely Base64 encoded data. In order to perform an
98 authentication query for instance, we must break apart the
99 concatenation that was created for storage of the data. We accomplish
100 this by splitting up the binary data we get after Base64 decoding the
101 stored hash.
102 In pseudocode we would perform the extraction and verification
104 operations as such:
105 Strip the hash identifier from the Digest
107 Base64Decode(Digest, 20)
108 Split Digest into 2 byte arrays, one for bytes 0 20(pwhash), one for bytes 21 32 (salt)
109 Get the target string and salt as separate binary object
110 Concatenate the 2 binary values
111 SHA hash the concatenation into targetPasswordHash
112 Compare targetPasswordHash with pwhash
113 Return corresponding Boolean value
114 Our job is to split the original digest up into 2 distinct byte arrays,
116 one of the left 20 (0 - 20 including the null terminator) bytes and the
117 other for the rest of the data. The left 0 20 bytes will represent
118 the salted binary value we will use for a byte-by-byte data match
119 against the new clear text presented for verification. The string
120 presented for verification will have to be salted as well. The rest of
121 the bytes (21 32) represent the random salt which when decoded will
122 show the exact hex characters that make up the once randomly generated
123 seed.
124 We are now ready to verify some data. Let's start with the 4 hashes
126 presented earlier. We will run them through our code to extract the
127 random salt and then using that verify the clear text string hashed by
128 slappasswd. First, let's do a verification test with an erroneous
129 password; this should fail the matching test:
130 {SSHA}72uhy5xc1AWOLwmNcXALHBSzp8xt4giL Test123
132 Hash extracted (in hex): ef6ba1cb9c5cd4058e2f098d71700b1c14b3a7cc
133 Salt extracted (in hex): 6de2088b
134 Hash length is: 20 Salt length is: 4
135 Hash presented in hex: 256bc48def0ce04b0af90dfd2808c42588bf9542
136 Hashes DON'T match: Test123
137 The match failure test was successful as expected. Now let's use known
139 valid data through the same exact code:
140 {SSHA}72uhy5xc1AWOLwmNcXALHBSzp8xt4giL testing123
142 Hash extracted (in hex): ef6ba1cb9c5cd4058e2f098d71700b1c14b3a7cc
143 Salt extracted (in hex): 6de2088b
144 Hash length is: 20 Salt length is: 4
145 Hash presented in hex: ef6ba1cb9c5cd4058e2f098d71700b1c14b3a7cc
146 Hashes match: testing123
147 The process used for salted passwords should now be clear. We see that
149 salting hashed data does indeed add another layer of security to the
150 clear text one-way hashing process. But we also see that salted hashes
151 should also be protected just as if the data was in clear text form.
152 Now that we have seen salted hashes actually work you should also
153 realize that in code it is possible to extract salt values and use them
154 for various purposes. Obviously the usage can be on either side of the
155 colored hat line, but the data is there.
156
158 new( [%options] )
159 Returns a new Crypt::SaltedHash object. Possible keys for %options
160 are:
161 · algorithm: It's also possible to use common string
163 representations of the algorithm (e.g. "sha256", "SHA-384"). If
164 the argument is missing, SHA-1 will be used by default.
165 · salt: You can specify your on salt. You can either specify it
167 as a sequence of charactres or as a hex encoded string of the
168 form "HEX{...}". If the argument is missing, a random seed is
169 provided for you (recommended).
170 · salt_len: By default, the module assumes a salt length of 4
172 bytes (or 8, if it is encoded in hex). If you choose a
173 different length, you have to tell the validate function how
174 long your seed was.
175 add( $data, ... )
177 Logically joins the arguments into a single string, and uses it to
178 update the current digest state. For more details see Digest.
179 clear()
181 Resets the digest.
182 salt_bin()
184 Returns the salt in binary form.
185 salt_hex()
187 Returns the salt in hexadecimal form ('HEX{...}')
188 generate()
190 Generates the seeded hash. Uses the clone-method of Digest before
191 actually performing the digest calculation, so adding more
192 cleardata after a call of generate to an instance of
193 Crypt::SaltedHash has the same effect as adding the data before the
194 call of generate.
195 validate( $hasheddata, $cleardata, [$salt_len] )
197 Validates a hasheddata previously generated against cleardata.
198 $salt_len defaults to 4 if not set. Returns 1 if the validation is
199 successful, 0 otherwise.
200 obj()
202 Returns a handle to Digest object.
203
205 none yet.
206
208 Digest, MIME::Base64
209
211 Sascha Kiefer, esskar@cpan.org
212
214 The author is particularly grateful to Andres Andreu for his article:
215 Salted hashes demystified - A Primer
216 (<http://www.securitydocs.com/library/3439>)
217
219 Copyright (C) 2010 Sascha Kiefer
220 This library is free software; you can redistribute it and/or modify it
222 under the same terms as Perl itself.
223perl v5.30.0 2019-07-26 Crypt::SaltedHash(3)