NAME

Authen::Passphrase::Scrypt - passphrases using Tarsnap's scrypt algorithm

SYNOPSIS

use Authen::Passphrase::Scrypt;

# Hash a password
my $sc = Authen::Passphrase::Scrypt->new(
    passphrase => 'correcthorsebatterystaple'
);
my $hash = $sc->as_rfc2307;
say "The given password hashes to $hash";

# Verify a password
$sc = Authen::Passphrase::Scrypt->from_rfc2307($hash);
say 'The password was "correcthorsebatterystaple"'
    if $sc->match('correcthorsebatterystaple');
say 'The password was "xkcd"' if $sc->match('xkcd');

# Advanced hashing
my $sc = Authen::Passphrase::Scrypt->new(
    passphrase => 'xkcd',
    logN       => 14, # General work factor
    r          => 16, # Memory work factor
    p          => 1,  # CPU (parallellism) work factor
    salt       => 'SodiumChloride && sODIUMcHLORIDE', # Must be 32 bytes
);
say 'The given password now hashes to ', $sc->as_rfc2307;

DESCRIPTION

This is experimental code, DO NOT USE in security-critical software.

Scrypt is a key derivation function that was originally developed for use in the Tarsnap online backup system and is designed to be far more secure against hardware brute-force attacks than alternative functions such as PBKDF2 or bcrypt.

Authen::Passphrase::Scrypt is a module for hashing and verifying passphrases using scrypt. It offers the same interface as Authen::Passphrase. It is not however possible to use this module from within Authen::Passphrase. The methods are:

Authen::Passphrase::Scrypt->new(%args)

Creates a new Authen::Passphrase::Scrypt from a given passphrase and parameters. Use this to hash a passphrase. This function takes either a key value list or a hashref. The arguments are:

passphrase

The passphrase. Mandatory.

logN

The general work factor (affects both CPU and memory cost). Defaults to 14

r

The blocksize (affects memory cost). Defaults to 16.

p

The parallelization factor (affects CPU cost). Defaults to 1.

salt

A 32-byte string used as a salt. By default it is randomly generated using Data::Entropy.

All of the parameters change the result of the hash. They are all stored in the hash, so there is no need to store them separately (or provide them to the hash verification methods).

It is normally sufficient to only use the logN parameter to control the speed of scrypt. r and p are intended to be used only for fine-tuning: if scrypt uses too much memory but not enough CPU, decrease logN and increase p; if scrypt uses too much CPU but not enough memory, decrease logN and increase r.

Note that 2^logN must fit in 64 bits and r * p < 2^30.

$sc->as_rfc2307

Returns the hash of the passphrase, in RFC2307 format. This is "{SCRYPT}" followed by the base64-encoded 96-byte result described here: https://security.stackexchange.com/questions/88678/why-does-node-js-scrypt-function-use-hmac-this-way/91050

Authen::Passphrase::Scrypt->from_rfc2307($rfc2307)

Creates a new Authen::Passphrase::Scrypt from a hash in RFC2307 format. Use this to verify if a passphrase matches a hash.

$sc->match($passphrase)

Returns true if the given passphrase matches the hash, false otherwise.

Authen::Passphrase::Scrypt->from_crypt

$sc->as_crypt

These functions both croak. They are provided for compatibility with the Authen::Passphrase interface.

SEE ALSO

Authen::Passphrase, https://www.tarsnap.com/scrypt.html, https://www.npmjs.com/package/scrypt

AUTHOR

Marius Gavrilescu, <marius@ieval.ro>

COPYRIGHT AND LICENSE

Copyright (C) 2017-2018 by Marius Gavrilescu

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.24.1 or, at your option, any later version of Perl 5 you may have available.