/ 
DBIx-Class-CryptColumn-0.009
River stage zero No dependents
/ DBIx::Class::CryptColumn

NAME

DBIx::Class::CryptColumn - Automatically hash password/passphrase columns

VERSION

version 0.009

SYNOPSIS

__PACKAGE__->load_components(qw(CryptColumn));

__PACKAGE__->add_columns(
    id => {
        data_type         => 'integer',
        is_auto_increment => 1,
    },
    password => {
        data_type          => 'text',
        inflate_passphrase => {
            encoder        => 'Argon2',
            verify_and_rehash_method  => 'verify_and_rehash_password',
        },
    },
);

__PACKAGE__->set_primary_key('id');

In application code:

# 'plain' will automatically be hashed using the specified
# inflate_passphrase arguments
$rs->create({ password => 'plain' });

my $row = $rs->find({ id => $id });

if ($row->verify_and_rehash_password($given_password)) {
  ...
}

# equivalent to

if ($row->password->verify_password($given_password)) {
  if ($row->password->needs_rehash) {
    $row->update({ password => $input });
  }
  ...
}

# Change password
$row->password('new password');

DESCRIPTION

This component can be used to automatically hash password columns using any scheme supported by Crypt::Passphrase whenever the value of these columns is changed, as well as conveniently check if any given password matches the hash.

Its main advantage over other similar DBIx::Class extensions is that it provides the cryptographic agility of Crypt::Passphrase; that means that it allows you to define a single scheme that will be used for new passwords, but several schemes to check passwords against. 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.

ARGUMENTS

In addition to the usual Crypt::Passphrase arguments, this module takes three extra arguments that each set a method on the row.

  • verify_method

    If this option is set it adds a method with that name to the row class to verify if a password matches the known hash. This method takes a password as its single argument.

  • rehash_method

    If this option is set it will add a method with the given name that checks if a password needs to be rehashed. It takes no arguments.

  • verify_and_rehash_method

    If this option is set it will add a method with the given name that verifies if a password matches the known hash. If it does and the hash needs a rehash it will rehash the password and store the result to the database. In either case it returns the result of the verification. This method takes a password as its only argument. This option is recommended over the others for most deployments.

  • recode_hash_method

    If this option is set it will add a method with the given name that checks if the hash recodes to a new value, and if so updates it in the database, otherwise this is a no-op.

METHODS

register_column

Chains with the register_column method in DBIx::Class::Row, and sets up passphrase columns according to the options documented above. This would not normally be directly called by end users.

set_column

Hash a passphrase column whenever it is set.

set_inflated_column

Sets an inflated password column that does not need to be hashed again.

new

Hash all passphrase columns on new() so that copy(), create(), and others DWIM.

SEE ALSO

DBIx::Class::PassphraseColumn

DBIx::Class::EncodedColumn

AUTHOR

Leon Timmermans <leont@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2023 by Leon Timmermans.

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