Provided by: libcrypt-saltedhash-perl_0.09-3_all bug

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.

perl v5.36.0                                       2022-10-13                             Crypt::SaltedHash(3pm)