view release on metacpan or  search on metacpan

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

## no critic (RCS,VERSION)
package Authen::Passphrase::SaltedSHA512;

use 5.008;
use strict;
use warnings;

our $VERSION = '0.07';

# $VERSION = eval $VERSION;    ## no critic (eval)

use Exporter;
use Authen::Passphrase::SaltedDigest;
use Bytes::Random::Secure qw( random_bytes_hex );

our @ISA = qw( Exporter Authen::Passphrase::SaltedDigest );   ## no critic (ISA)
our @EXPORT_OK = qw( generate_salted_sha512 validate_salted_sha512 );

use constant NUM_BYTES => 64;    ## no critic (constant)

sub new {
    my ( $class, %args ) = @_;
    $args{algorithm} = 'SHA-512';

    # We're doing our own random salt generation.
    delete $args{salt_random};

    # If there is no hash supplied, and a passphrase is supplied, this must be
    # a passphrase hash/salt generation object.
    if (   !exists $args{hash}
        && !exists $args{hash_hex}
        && exists $args{passphrase} )
    {

        # Generate a 512 bit random salt using a secure random generator.
        # 64 bytes is 512 bits, or 128 hex characters.
        my $salt = random_bytes_hex(NUM_BYTES);

        # We're generating our own salt.  Don't accept others.
        delete $args{$_} for qw( salt salt_hash );

        $args{salt_hex} = $salt;
    }

    # Let the super-class instantiate and handle our preprocessed args.
    return $class->SUPER::new(%args);
}

sub generate_salted_sha512 {
    my $password = shift;
    my $gen = __PACKAGE__->new( passphrase => $password );
    return ( $gen->salt_hex, $gen->hash_hex );
}

sub validate_salted_sha512 {
    my ( $password, $salt_hex, $hash_hex ) = @_;
    my $auth = __PACKAGE__->new(
        salt_hex => $salt_hex,
        hash_hex => $hash_hex
    );
    return $auth->match($password);
}

1;    # End of Authen::Passphrase::SaltedSHA512

__END__

=head1 NAME

Authen::Passphrase::SaltedSHA512 - Safe, Sane, and Simple passphrase salting,
hashing and authentication.

=head1 VERSION

Version 0.07

=head1 SYNOPSIS

This module is a subclass of
L<Authen::Passphrase::SaltedDigest|http://search.cpan.org/perldoc?Authen::Passphrase::SaltedDigest>.
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.