NAME

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

VERSION

version 0.05

SYNOPSIS

    __PACKAGE__->load_components(qw(PassphraseColumn));

    __PACKAGE__->add_columns(
        id => {
            data_type         => 'integer',
            is_auto_increment => 1,
        },
        passphrase => {
            data_type        => 'text',
            passphrase       => 'rfc2307',
            passphrase_class => 'SaltedDigest',
            passphrase_args  => {
                algorithm   => 'SHA-1',
                salt_random => 20,
            },
            passphrase_check_method => 'check_passphrase',
        },
    );

    __PACKAGE__->set_primary_key('id');

In application code:

    # 'plain' will automatically be hashed using the specified passphrase_class
    # and passphrase_args. The result of the hashing will stored in the
    # specified encoding
    $rs->create({ passphrase => 'plain' });

    my $row = $rs->find({ id => $id });
    my $passphrase = $row->passphrase; # an Authen::Passphrase instance

    if ($row->check_passphrase($input)) { ...

    $row->passphrase('new passphrase');
    $row->passphrase( Authen::Passphrase::RejectAll->new );

DESCRIPTION

This component can be used to automatically hash password columns using any scheme supported by Authen::Passphrase whenever the value of these columns is changed.

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.

new

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

COMPARISON TO SIMILAR MODULES

This module is similar to both DBIx::Class::EncodedColumn and DBIx::Class::DigestColumns. Here's a brief comparison that might help you decide which one to choose.

  • DigestColumns performs the hashing operation on insert and update. PassphraseColumn and EncodedColumn perform the operation when the value is set, or on new.

  • DigestColumns supports only algorithms of the Digest family.

  • EncodedColumn employs a set of thin wrappers around different cipher modules to provide support for any cipher you wish to use and wrappers are very simple to write.

  • PassphraseColumn delegates password hashing and encoding to Authen::Passphrase, which already has support for a huge number of hashing schemes. Writing a new Authen::Passphrase subclass to support other schemes is easy.

  • EncodedColumn and DigestColumns require all values in a hashed column to use the same hashing scheme. PassphraseColumn stores both the hashed passphrase value and the scheme used to hash it. Therefore it's possible to have different rows using different hashing schemes.

    This is especially useful when, for example, being tasked with importing records (e.g. users) from a legacy application, that used a certain hashing scheme and has no plain-text passwords available, into another application that uses another hashing scheme.

  • PassphraseColumn and EncodedColumn support having more than one hashed column per table and each column can use a different hashing scheme. DigestColumns is limited to one hashed column per table.

  • DigestColumns supports changing certain options at runtime, as well as the option to not automatically hash values on set. Neither PassphraseColumn nor EncodedColumn support this.

OPTIONS

This module provides the following options for add_column:

passphrase => $encoding

This specifies the encoding that passphrases will be stored in. Possible values are rfc2307 and crypt. The value of $encoding is passed on unmodified to the inflate_passphrase option provided by DBIx::Class::InflateColumn::Authen::Passphrase. Please refer to its documentation for details.

passphrase_class => $name

When receiving a plain string value for a passphrase, that value will be hashed using the Authen::Passphrase subclass specified by $name. A value of SaltedDigest, for example, will cause passphrases to be hashed using Authen::Passphrase::SaltedDigest.

passphrase_args => \%args

When attempting to hash a given passphrase, the %args specified in this options will be passed to the constructor of the Authen::Passphrase class specified using passphrase_class, in addition to the actual password to hash.

passphrase_check_method => $method_name

If this option is specified, a method with the name $method_name will be created in the result class. This method takes one argument, a plain text passphrase, and returns a true value if the provided passphrase matches the encoded passphrase stored in the row it's being called on.

SEE ALSO

DBIx::Class::InflateColumn::Authen::Passphrase

DBIx::Class::EncodedColumn

DBIx::Class::DigestColumns

SUPPORT

Bugs may be submitted through the RT bug tracker (or bug-DBIx-Class-PassphraseColumn@rt.cpan.org).

AUTHOR

Florian Ragwitz <rafl@debian.org>

CONTRIBUTOR

Karen Etheridge <ether@cpan.org>

COPYRIGHT AND LICENCE

This software is copyright (c) 2010 by Florian Ragwitz.

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