view release on metacpan or  search on metacpan

lib/Authen/Passphrase/SaltedSHA512.pm  view on Meta::CPAN

It adds two features to make your life a little easier and safer.  First, it
simplifies the user interface by selecting reasonable (and secure) defaults.
Second, in generating salt, it uses the high quality, CSPRNG provided by
L<Bytes::Random::Secure|http://search.cpan.org/perldoc?Bytes::Random::Secure>.

Some examples:

    use Authen::Passphrase::SaltedSHA512;

    # Generate a salt and hash from a passphrase.
    my $gen = Authen::Passphrase::SaltedSHA512->new( passphrase => 'Sneaky!' );
    my $hash = $gen->hash_hex;
    my $salt = $gen->salt_hex;
    # Store the hash and the salt in your user database.


    # Later....
    # Challenge a passphrase to authenticate a user login.
    # First, retrieve the user's hash and salt from your user database.
    # Then generate a challenge object:
    my $challenge = Authen::Passphrase::SaltedSHA512->new(
        salt_hex    => $salt,
        hash_hex    => $hash
    );

    # And challenge the passphrase supplied for the current session's login.
    if( $challenge->match( 'Sneaky!' ) ) {
        print "You are a winner!\n";
    }

    # Or for the ultimate in ease and simplicity:
    use Authen::Passphrase::SaltedSHA512 qw(
        generate_salted_sha512      validate_salted_sha512
    );
    my ( $salt_hex, $hash_hex ) = generate_salted_sha512( $passphrase );
    my $is_valid = validate_salted_sha512( $passphrase, $salt_hex, $hash_hex );



=head1 DESCRIPTION

Authen::Passhprase::SaltedSHA512 is designed to simplify the process of
generating random salt for, and a salted hash of a user supplied passphrase.

It is also designed to easily authenticate a user supplied passphrase against
a given salt and hash.

The presumed use-case is for user authentication where a salt and a password
hash will be stored in a database of user logins.  The simple interface should
fit into a broad range of authentication systems with minimal clutter.

Authen::Passphrase::SaltedSHA512 is a subclass of
L<Authen::Passphrase::SaltedDigest|http://search.cpan.org/perldoc?Authen::Passphrase::SaltedDigest>
that overrides the constructor to provide reasonable defaults so that you
don't have to spend a week reading articles on which algorithm to use, and how
to generate a good salt.

The hashing algorithm chosen is the SHA-512 hash function from the SHA-2
family.  Currently SHA-512 is a leading edge standard in strong hashing.

The salt generated when creating authentication credentials is a 512 bit
random string.  The random number generating algorithm used comes from
L<Bytes::Random::Secure|http://search.cpan.org/perldoc?Bytes::Random::Secure>.
That module uses Math::Random::ISAAC, "I<...a cryptographically-strong random
number generator with no known serious weaknesses.>"  Bytes::Random::Secure
obtains its seed using Crypt::Random::Seed.  The reason that
Bytes::Random::Secure was chosen over other random number generators is because
that module has a light-weight dependency chain, a cryptographically strong
random number generator, strong seeding (the hardest part of the CSPRNG problem)
across a wide variety of platforms, and useful hex output.

By using a 512 bit random salt, a maximum degree of entropy is achieved in the
hashes generated by the SHA-512 algorithm.  Every time the constructor is
called you will get a new random salt, so every user has his own salt.  The
advantage of using a fresh random salt for each user is that it eliminates the
rainbow table attack vector, by guaranteeing that if one user's password is
compromised through brute force (or cosmic good luck) all of your other users
with their own random salts are still secure.

By selecting secure defaults for hashing algorithm, random number generation,
and salt bit-length, much of the guesswork can be eliminated from devising
an authentication scheme, and a simpler user interface results.

=head1 EXPORT

This is primarily an Object Oriented Interface module.  However, for even
greater simplicity, a standard functions interface is provided upon request.
Nothing is exported by default.  By supplying an export list, the following
subroutines are available:

=over 4

=item * generate_salted_sha512

=item * validate_salted_sha512

=back



=head1 SUBROUTINES/METHODS

=head2 METHODS

The following section describes the methods available through the module's
Object Oriented interface.

=head3 new

B<The constructor> will create an object that can either be used to generate
a salt and a hash for later use, or to challenge a supplied salt and hash
by a passphrase supplied to C<match>.

Instantiate a salt and hash generator object.

    my $auth_gen = Authen::Passphrase::SaltedSHA512->new(
        passphrase => 'All your base are belong to us.'
    );

Instantiate a challenge object.