view release on metacpan or  search on metacpan

lib/Crypt/Passphrase.pm  view on Meta::CPAN

This will be used as-is.

=back

This argument is mandatory.

=item * validators

This is a list of additional validators for passwords. These values can each either be the same an encoder value, except that the last entry may also be a coderef that takes the password and the hash as its arguments and returns a boolean value.

This argument is optional and defaults to an empty list. The encoder is always considered as a validator and thus doesn't need to be specified.

=item * normalization

This sets the unicode normalization form used for the password. Valid values are C<'C'> (composed; the the default), C<'D'> (decomposed), C<'KC'> (legacy composed) and C<'KD'> (legacy decomposed). You should probably not change this unless it's neces...

=back

=head2 hash_password

 $passphrase->hash_password($password)

This will hash a C<$password> with the encoder cipher, and return it (in crypt format). This will generally use a salt, and as such will return a different value each time even when called with the same password.

=head2 verify_password

 $passphrase->verify_password($password, $hash)

This will check a C<$password> satisfies a certain C<$hash> and returns success or not. It will always return false if C<$hash> isn't defined.

=head2 needs_rehash

 $passphrase->needs_rehash($hash)

This will check if a hash needs to be rehashed, either because it's in the wrong cipher or because the parameters are insufficient.

Calling this only ever makes sense after a password has been verified.

=head2 recode_hash

 $passphrase->recode_hash($hash)

This recodes a hash if needed. This is mainly relevant when upgrading to a new pepper, but can also be relevant when a cipher has multiple known encodings (e.g. scrypt). It will return the hash unmodified otherwise.

=head2 curry_with_hash

 $passphrase->curry_with_hash($hash)

This creates a C<Crypt::Passphrase::PassphraseHash> object for the hash, effectively currying C<Crypt::Passphrase> with that hash. This can be useful for plugging C<Crypt::Passphrase> into some frameworks (e.g. ORMs) that require a singular object to...

=head1 TIPS AND TRICKS

=head2 Custom configurations

While encoders generally allow for a default configuration, I would strongly encourage anyone to research what settings work for your application. It is generally a trade-off between usability/resources and security.

If your application is deployed by different people than it's developed by it may be helpful to have the configuration for C<Crypt::Passphrase> part of your application configuration file and not be hardcoded so that your users can choose the right s...

=head2 Unicode

C<Crypt::Passphrase> considers passwords to be text, and as such you should ensure any password input is decoded if it contains any non-ascii characters. C<Crypt::Passphrase> will take care of both normalizing and encoding such input.

=head2 DOS attacks

Hashing passwords is by its nature a heavy operations. It can be abused by malignant actors who want to try to DOS your application. It may be wise to do some form of DOS protection such as a proof-of-work scheme or a captcha.

=head2 Levels of security

In some situations, it may be appropriate to have different password settings for different users (e.g. set them more strict for administrators than for ordinary users).

=head1 SEE ALSO

=head2 Encoders

The following encoders are currently available on CPAN:

=over 4

=item * L<Crypt::Passphrase::Argon2|Crypt::Passphrase::Argon2>

This is a state-of-the-art memory-hard password hashing algorithm, recommended for higher-end parameters. Winner of the Password Hash Competition of 2015.

=item * L<Crypt::Passphrase::Bcrypt|Crypt::Passphrase::Bcrypt>

And older but still safe password hashing algorithm, recommended for lower-end parameters or if you need to be compatible with BSD system passwords.

=item * L<Crypt::Passphrase::Yescrypt|Crypt::Passphrase::Yescrypt>

Another state-of-the-art memory-hard password hashing algorithm. Finalist of the Password Hash Competition of 2015 and used in some recent Linux distributions for user passwords.

=item * L<Crypt::Passphrase::Argon2::AES|Crypt::Passphrase::Argon2::AES>

A peppering implementation that AES encrypts an argon2 hash. Recommended when wanting to pepper with argon2 as it allows offline repeppering and offers strong cryptographic guarantees.

=item * L<Crypt::Passphrase::Argon2::HSM|Crypt::Passphrase::Argon2::HSM>

A peppering implementation like above, except it uses a PKCS11 Hardware Security Module instead of encrypting locally for additional information security. Supported algorithms will depend on your HSM.

=item * L<Crypt::Passphrase::Bcrypt::AES|Crypt::Passphrase::Bcrypt::AES>

A peppering implementation that AES encrypts a bcrypt hash. Recommended when wanting to pepper with bcrypt as it allows offline repeppering and offers strong cryptographic guarantees.

=item * L<Crypt::Passphrase::PBKDF2|Crypt::Passphrase::PBKDF2>

A FIPS-standardized hashing algorithm. Only recommended when FIPS-compliance is required. This is the only portable pure-perl backend.

=item * L<Crypt::Passphrase::Linux|Crypt::Passphrase::Linux>

An implementation of SHA-512, SHA256 and MD5 based C<crypt()>. Recommended if you need to be compatible with standard Linux system passwords.

=item * L<Crypt::Passphrase::Scrypt|Crypt::Passphrase::Scrypt>

A first-generation memory-hard algorithm, if you want a memory-hard algorithm something more recent like argon2 or yescrypt is recommended instead.

=item * L<Crypt::Passphrase::System|Crypt::Passphrase::System>

Your system's C<crypt> implementation. Support for various algorithms varies between platforms and platform versions, and while on some platforms it's a decent backend one should not rely on this for a portable result. This is mainly useful if you ca...

=item * L<Crypt::Passphrase::Pepper::Simple|Crypt::Passphrase::Pepper::Simple>

A meta-encoder that adds peppering to your passwords by pre-hashing the inputs. Recommended only when wanting to pepper with hashes other than argon2 or bcrypt as it can be combined with any encoder. It is provided in this distribution.