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 ();

PHP compatible functional interface, typical using defaults:

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

PHP compatible 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($[peppered_password, PASSWORD_ARGON2ID);  # store this in your database
        # ... and when verifying passwords, then you must pepper them first.

Static method use, using defaults:

        use PHP::Functions::Password;
        my $password = 'secret';
        my $crypted_string = PHP::Functions::Password->hash($password);

Static method use, using options:

        use PHP::Functions::Password;
        my $password = 'secret';
        my $crypted_string = PHP::Functions::Password->hash($password, algo => PASSWORD_ARGON2ID, time_cost => 8);
        # Note that the method hash() has a different argument signature compared to the function password_hash(). The algorithm has become one of the hash options.

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 difference 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!

Returns a string.

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.

STATIC METHODS

algos()

See password_algos().

get_info($crypted)

Similar to password_get_info($crypted), with the difference that this returns undef if the $crypted string format is unrecognized. Returns a hashref if there is a match, else undef.

hash($password, %options)

Similar to password_hash($password, $algo, %options) but with a different argument signature. The difference is that this method doesn't have an $algo argument, but instead allows the algorithm to be specified using the 'algo' option (in %options).

needs_rehash($crypted, $algo, %options)

See password_needs_rehash($crypted, $algo, %options).

verify($password, $crypted)

See verify($password, $crypted).

SEE ALSO

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

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)