NAME

PHP::Functions::Password - Perl ports of PHP password functions

DESCRIPTION

This module provides ported PHP password functions. This module supports the bcrypt, argon2i, and argon2id algorithms, as is the case with the equivalent PHP functions at the date of writing this. All functions may also be called as class methods and support inheritance too. See http://php.net/manual/en/ref.password.php for detailed usage instructions.

SYNOPSIS

use PHP::Functions::Password ();

Functional interface, typical use:

use PHP::Functions::Password qw(password_hash);
my $password = 'secret';
my $crypted_string = password_hash($password);  # uses PASSWORD_BCRYPT algorithm

Functional interface use, using options:

use PHP::Functions::Password qw(:all);
my $password = 'secret';

# Specify options (see PHP docs for which):
my $crypted_string = password_hash($password, PASSWORD_DEFAULT, cost => 11);

# Use a different algorithm:
my $crypted_string = password_hash($password, PASSWORD_ARGON2ID);

# Better practice using a 'pepper':
use Digest::SHA qw(hmac_sha256);
my $pepper = 'Abracadabra and Hocus pocus';  # retrieve this from a secrets config file for example (and don't loose it!)
my $peppered_password = hmac_sha256($password, $pepper);
my $crypted_string = password_hash($password, PASSWORD_ARGON2ID);  # store this in your database
# ... and when verifying passwords, then you pepper then first too.

Class method use, using options:

use PHP::Functions::Password;
my $password = 'secret';
my $crypted_string = PHP::Functions::Password->hash($password, cost => 9);
# Note that the 2nd argument of password_hash() has been dropped here and may be specified
# as an option as should've been the case in the original password_hash() function IMHO.

EXPORTS

The following names can be imported into the calling namespace by request:

password_algos
password_get_info
password_hash
password_needs_rehash
password_verify
PASSWORD_ARGON2I
PASSWORD_ARGON2ID
PASSWORD_BCRYPT
PASSWORD_DEFAULT
:all    - what it says
:consts - the PASSWORD_* constants
:funcs  - the password_* functions

PHP COMPATIBLE AND EXPORTABLE FUNCTIONS

password_algos()

The same as http://php.net/manual/en/function.password-algos.php

Returns an array of supported password algorithm signatures.

password_get_info($crypted)

The same as http://php.net/manual/en/function.password-get-info.php with the exception that it returns the following additional keys in the result:

algoSig	e.g. '2y'
salt (encoded)
hash (encoded)
version (only for argon2 algorithms)

Returns a hash in array context, else a hashref.

password_hash($password, $algo, %options)

Similar to http://php.net/manual/en/function.password-hash.php with the difference that the $algo argument is optional and defaults to PASSWORD_DEFAULT for your programming pleasure.

Important notes about the 'salt' option which you shouldn't use in the first place:

- The PASSWORD_BCRYPT 'salt' option is deprecated since PHP 7.0, but if you do pass it, then it must be 16 bytes long!
- For algorithms other than PASSWORD_BCRYPT, PHP doesn't support the 'salt' option, but if you do pass it, then it must be in raw bytes!

password_needs_rehash($crypted, $algo, %options)

The same as http://php.net/manual/en/function.password-needs-rehash.php.

password_verify($password, $crypted)

The same as http://php.net/manual/en/function.password-verify.php.

SHORTENED ALIAS METHODS

algos()

Alias of password_algos().

get_info($crypted)

Alias of password_get_info($crypted).

hash($password, %options)

Proxy method for password_hash($password, $algo, %options). The difference is that this method does have an $algo argument, but instead allows the algorithm to be specified with the 'algo' option (in %options).

needs_rehash($crypted, $algo, %options)

Alias of password_needs_rehash($crypted, $algo, %options).

verify($password, $crypted)

Alias of verify($password, $crypted).

SEE ALSO

L<Crypt::Bcrypt> used for all the bcrypt support.
L<Crypt::OpenSSL::Random> used for random salt generation.
L<Crypt::Argon2> recommended for argon2 algorithm support.

COPYRIGHT

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Craig Manley (craigmanley.com)