Raku Land

Crypt::Passphrase

cpan:LEONT

Actions Status

NAME

Crypt::Passphrase - managing passwords in a cryptographically agile manner

SYNOPSIS

 my $authenticator = Crypt::Passphrase.new(
	:encoder<Argon2>,
	:validators<BCrypt Scrypt>
 );

 my $hash = get-hash($user);
 if (!$authenticator.verify-password($password, $hash)) {
     die "Invalid password";
 }
 elsif ($authenticator.needs-rehash($hash)) {
     update-hash($user, $authenticator.hash-password($password));
 }

DESCRIPTION

This module manages the passwords in a cryptographically agile manner. Following Postel's principle, it allows you to define a single scheme that will be used for new passwords, but several schemes to check passwords with. It will be able to tell you if you should rehash your password, not only because the scheme is outdated, but also because the desired parameters have changed.

new(%args)

This creates a new Crypt::Passphrase object. It takes two named arguments:

hash-password($password)

This will hash a 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.

verify-password($password, $hash)

This will check a password satisfies a certain hash.

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.

TIPS AND TRICKS

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.

Unicode

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. Crypt::Passphrase will take care of both normalizing and encoding such input.

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 schemei or a captcha.

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).

SEE ALSO

AUTHOR

Leon Timmermans fawaka@gmail.com

COPYRIGHT AND LICENSE

Copyright 2021 Leon Timmermans

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.