Provided by: libcrypt-saltedhash-perl_0.09-3_all 
NAME
Crypt::SaltedHash - Perl interface to functions that assist in working with salted hashes.
SYNOPSIS
use Crypt::SaltedHash;
my $csh = Crypt::SaltedHash->new(algorithm => 'SHA-1');
$csh->add('secret');
my $salted = $csh->generate;
my $valid = Crypt::SaltedHash->validate($salted, 'secret');
DESCRIPTION
The "Crypt::SaltedHash" module provides an object oriented interface to create salted (or
seeded) hashes of clear text data. The original formalization of this concept comes from
RFC-3112 and is extended by the use of different digital agorithms.
ABSTRACT
Setting the data
The process starts with 2 elements of data:
• a clear text string (this could represent a password for instance).
• the salt, a random seed of data. This is the value used to augment a hash in order to
ensure that 2 hashes of identical data yield different output.
For the purposes of this abstract we will analyze the steps within code that perform the
necessary actions to achieve the endresult hashes. Cryptographers call this hash a digest.
We will not however go into an explanation of a one-way encryption scheme. Readers of this
abstract are encouraged to get information on that subject by their own.
Theoretically, an implementation of a one-way function as an algorithm takes input, and
provides output, that are both in binary form; realistically though digests are typically
encoded and stored in a database or in a flat text or XML file. Take slappasswd5 for
instance, it performs the exact functionality described above. We will use it as a black
box compiled piece of code for our analysis.
In pseudocode we generate a salted hash as follows:
Get the source string and salt as separate binary objects
Concatenate the 2 binary values
Hash the concatenation into SaltedPasswordHash
Base64Encode(concat(SaltedPasswordHash, Salt))
We take a clear text string and hash this into a binary object representing the hashed
value of the clear text string plus the random salt. Then we have the Salt value, which
are typically 4 bytes of purely random binary data represented as hexadecimal notation
(Base16 as 8 bytes).
Using SHA-1 as the hashing algorithm, SaltedPasswordHash is of length 20 (bytes) in raw
binary form (40 bytes if we look at it in hex). Salt is then 4 bytes in raw binary form.
The SHA-1 algorithm generates a 160 bit hash string. Consider that 8 bits = 1 byte. So 160
bits = 20 bytes, which is exactly what the algorithm gives us.
The Base64 encoding of the binary result looks like:
{SSHA}B0O0XSYdsk7g9K229ZEr73Lid7HBD9DX
Take note here that the final output is a 32-byte string of data. The Base64 encoding
process uses bit shifting, masking, and padding as per RFC-3548.
A couple of examples of salted hashes using on the same exact clear-text string:
slappasswd -s testing123
{SSHA}72uhy5xc1AWOLwmNcXALHBSzp8xt4giL
slappasswd -s testing123
{SSHA}zmIAVaKMmTngrUi4UlS0dzYwVAbfBTl7
slappasswd -s testing123
{SSHA}Be3F12VVvBf9Sy6MSqpOgAdEj6JCZ+0f
slappasswd -s testing123
{SSHA}ncHs4XYmQKJqL+VuyNQzQjwRXfvu6noa
4 runs of slappasswd against the same clear text string each yielded unique endresult
hashes. The random salt is generated silently and never made visible.
Extracting the data
One of the keys to note is that the salt is dealt with twice in the process. It is used
once for the actual application of randomness to the given clear text string, and then it
is stored within the final output as purely Base64 encoded data. In order to perform an
authentication query for instance, we must break apart the concatenation that was created
for storage of the data. We accomplish this by splitting up the binary data we get after
Base64 decoding the stored hash.
In pseudocode we would perform the extraction and verification operations as such:
Strip the hash identifier from the Digest
Base64Decode(Digest, 20)
Split Digest into 2 byte arrays, one for bytes 0 20(pwhash), one for bytes 21 32 (salt)
Get the target string and salt as separate binary object
Concatenate the 2 binary values
SHA hash the concatenation into targetPasswordHash
Compare targetPasswordHash with pwhash
Return corresponding Boolean value
Our job is to split the original digest up into 2 distinct byte arrays, one of the left 20
(0 - 20 including the null terminator) bytes and the other for the rest of the data. The
left 0 20 bytes will represent the salted binary value we will use for a byte-by-byte
data match against the new clear text presented for verification. The string presented for
verification will have to be salted as well. The rest of the bytes (21 32) represent the
random salt which when decoded will show the exact hex characters that make up the once
randomly generated seed.
We are now ready to verify some data. Let's start with the 4 hashes presented earlier. We
will run them through our code to extract the random salt and then using that verify the
clear text string hashed by slappasswd. First, let's do a verification test with an
erroneous password; this should fail the matching test:
{SSHA}72uhy5xc1AWOLwmNcXALHBSzp8xt4giL Test123
Hash extracted (in hex): ef6ba1cb9c5cd4058e2f098d71700b1c14b3a7cc
Salt extracted (in hex): 6de2088b
Hash length is: 20 Salt length is: 4
Hash presented in hex: 256bc48def0ce04b0af90dfd2808c42588bf9542
Hashes DON'T match: Test123
The match failure test was successful as expected. Now let's use known valid data through
the same exact code:
{SSHA}72uhy5xc1AWOLwmNcXALHBSzp8xt4giL testing123
Hash extracted (in hex): ef6ba1cb9c5cd4058e2f098d71700b1c14b3a7cc
Salt extracted (in hex): 6de2088b
Hash length is: 20 Salt length is: 4
Hash presented in hex: ef6ba1cb9c5cd4058e2f098d71700b1c14b3a7cc
Hashes match: testing123
The process used for salted passwords should now be clear. We see that salting hashed data
does indeed add another layer of security to the clear text one-way hashing process. But
we also see that salted hashes should also be protected just as if the data was in clear
text form. Now that we have seen salted hashes actually work you should also realize that
in code it is possible to extract salt values and use them for various purposes. Obviously
the usage can be on either side of the colored hat line, but the data is there.
METHODS
new( [%options] )
Returns a new Crypt::SaltedHash object. Possible keys for %options are:
• algorithm: It's also possible to use common string representations of the
algorithm (e.g. "sha256", "SHA-384"). If the argument is missing, SHA-1 will be
used by default.
• salt: You can specify your on salt. You can either specify it as a sequence of
charactres or as a hex encoded string of the form "HEX{...}". If the argument is
missing, a random seed is provided for you (recommended).
• salt_len: By default, the module assumes a salt length of 4 bytes (or 8, if it is
encoded in hex). If you choose a different length, you have to tell the validate
function how long your seed was.
add( $data, ... )
Logically joins the arguments into a single string, and uses it to update the current
digest state. For more details see Digest.
clear()
Resets the digest.
salt_bin()
Returns the salt in binary form.
salt_hex()
Returns the salt in hexadecimal form ('HEX{...}')
generate()
Generates the seeded hash. Uses the clone-method of Digest before actually performing
the digest calculation, so adding more cleardata after a call of generate to an
instance of Crypt::SaltedHash has the same effect as adding the data before the call
of generate.
validate( $hasheddata, $cleardata, [$salt_len] )
Validates a hasheddata previously generated against cleardata. $salt_len defaults to 4
if not set. Returns 1 if the validation is successful, 0 otherwise.
obj()
Returns a handle to Digest object.
FUNCTIONS
none yet.
SEE ALSO
Digest, MIME::Base64
AUTHOR
Sascha Kiefer, esskar@cpan.org
ACKNOWLEDGMENTS
The author is particularly grateful to Andres Andreu for his article: Salted hashes
demystified - A Primer (<http://www.securitydocs.com/library/3439>)
COPYRIGHT AND LICENSE
Copyright (C) 2010 Sascha Kiefer
This library is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.