JezK
Edit File: DBIx::Class::PassphraseColumn.3pm
.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "DBIx::Class::PassphraseColumn 3pm" .TH DBIx::Class::PassphraseColumn 3pm "2019-10-26" "perl v5.28.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" DBIx::Class::PassphraseColumn \- Automatically hash password/passphrase columns .SH "VERSION" .IX Header "VERSION" version 0.05 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& _\|_PACKAGE_\|_\->load_components(qw(PassphraseColumn)); \& \& _\|_PACKAGE_\|_\->add_columns( \& id => { \& data_type => \*(Aqinteger\*(Aq, \& is_auto_increment => 1, \& }, \& passphrase => { \& data_type => \*(Aqtext\*(Aq, \& passphrase => \*(Aqrfc2307\*(Aq, \& passphrase_class => \*(AqSaltedDigest\*(Aq, \& passphrase_args => { \& algorithm => \*(AqSHA\-1\*(Aq, \& salt_random => 20, \& }, \& passphrase_check_method => \*(Aqcheck_passphrase\*(Aq, \& }, \& ); \& \& _\|_PACKAGE_\|_\->set_primary_key(\*(Aqid\*(Aq); .Ve .PP In application code: .PP .Vb 4 \& # \*(Aqplain\*(Aq 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 => \*(Aqplain\*(Aq }); \& \& my $row = $rs\->find({ id => $id }); \& my $passphrase = $row\->passphrase; # an Authen::Passphrase instance \& \& if ($row\->check_passphrase($input)) { ... \& \& $row\->passphrase(\*(Aqnew passphrase\*(Aq); \& $row\->passphrase( Authen::Passphrase::RejectAll\->new ); .Ve .SH "DESCRIPTION" .IX Header "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. .SH "METHODS" .IX Header "METHODS" .SS "register_column" .IX Subsection "register_column" Chains with the \f(CW\*(C`register_column\*(C'\fR method in \f(CW\*(C`DBIx::Class::Row\*(C'\fR, and sets up passphrase columns according to the options documented above. This would not normally be directly called by end users. .SS "set_column" .IX Subsection "set_column" Hash a passphrase column whenever it is set. .SS "new" .IX Subsection "new" Hash all passphrase columns on \f(CW\*(C`new()\*(C'\fR so that \f(CW\*(C`copy()\*(C'\fR, \f(CW\*(C`create()\*(C'\fR, and others \fB\s-1DWIM\s0\fR. .SH "COMPARISON TO SIMILAR MODULES" .IX Header "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. .IP "\(bu" 4 \&\f(CW\*(C`DigestColumns\*(C'\fR performs the hashing operation on \f(CW\*(C`insert\*(C'\fR and \&\f(CW\*(C`update\*(C'\fR. \f(CW\*(C`PassphraseColumn\*(C'\fR and \f(CW\*(C`EncodedColumn\*(C'\fR perform the operation when the value is set, or on \f(CW\*(C`new\*(C'\fR. .IP "\(bu" 4 \&\f(CW\*(C`DigestColumns\*(C'\fR supports only algorithms of the Digest family. .IP "\(bu" 4 \&\f(CW\*(C`EncodedColumn\*(C'\fR 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. .IP "\(bu" 4 \&\f(CW\*(C`PassphraseColumn\*(C'\fR delegates password hashing and encoding to \&\f(CW\*(C`Authen::Passphrase\*(C'\fR, which already has support for a huge number of hashing schemes. Writing a new \f(CW\*(C`Authen::Passphrase\*(C'\fR subclass to support other schemes is easy. .IP "\(bu" 4 \&\f(CW\*(C`EncodedColumn\*(C'\fR and \f(CW\*(C`DigestColumns\*(C'\fR require all values in a hashed column to use the same hashing scheme. \f(CW\*(C`PassphraseColumn\*(C'\fR stores both the hashed passphrase value \fIand\fR the scheme used to hash it. Therefore it's possible to have different rows using different hashing schemes. .Sp 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. .IP "\(bu" 4 \&\f(CW\*(C`PassphraseColumn\*(C'\fR and \f(CW\*(C`EncodedColumn\*(C'\fR support having more than one hashed column per table and each column can use a different hashing scheme. \f(CW\*(C`DigestColumns\*(C'\fR is limited to one hashed column per table. .IP "\(bu" 4 \&\f(CW\*(C`DigestColumns\*(C'\fR supports changing certain options at runtime, as well as the option to not automatically hash values on set. Neither \f(CW\*(C`PassphraseColumn\*(C'\fR nor \&\f(CW\*(C`EncodedColumn\*(C'\fR support this. .SH "OPTIONS" .IX Header "OPTIONS" This module provides the following options for \f(CW\*(C`add_column\*(C'\fR: .ie n .IP """passphrase => $encoding""" 4 .el .IP "\f(CWpassphrase => $encoding\fR" 4 .IX Item "passphrase => $encoding" This specifies the encoding that passphrases will be stored in. Possible values are \&\f(CW\*(C`rfc2307\*(C'\fR and \f(CW\*(C`crypt\*(C'\fR. The value of \f(CW$encoding\fR is passed on unmodified to the \&\f(CW\*(C`inflate_passphrase\*(C'\fR option provided by DBIx::Class::InflateColumn::Authen::Passphrase. Please refer to its documentation for details. .ie n .IP """passphrase_class => $name""" 4 .el .IP "\f(CWpassphrase_class => $name\fR" 4 .IX Item "passphrase_class => $name" When receiving a plain string value for a passphrase, that value will be hashed using the \f(CW\*(C`Authen::Passphrase\*(C'\fR subclass specified by \f(CW$name\fR. A value of \&\f(CW\*(C`SaltedDigest\*(C'\fR, for example, will cause passphrases to be hashed using \&\f(CW\*(C`Authen::Passphrase::SaltedDigest\*(C'\fR. .ie n .IP """passphrase_args => \e%args""" 4 .el .IP "\f(CWpassphrase_args => \e%args\fR" 4 .IX Item "passphrase_args => %args" When attempting to hash a given passphrase, the \f(CW%args\fR specified in this options will be passed to the constructor of the \f(CW\*(C`Authen::Passphrase\*(C'\fR class specified using \f(CW\*(C`passphrase_class\*(C'\fR, in addition to the actual password to hash. .ie n .IP """passphrase_check_method => $method_name""" 4 .el .IP "\f(CWpassphrase_check_method => $method_name\fR" 4 .IX Item "passphrase_check_method => $method_name" If this option is specified, a method with the name \f(CW$method_name\fR 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. .SH "SEE ALSO" .IX Header "SEE ALSO" DBIx::Class::InflateColumn::Authen::Passphrase .PP DBIx::Class::EncodedColumn .PP DBIx::Class::DigestColumns .SH "SUPPORT" .IX Header "SUPPORT" Bugs may be submitted through the \s-1RT\s0 bug tracker <https://rt.cpan.org/Public/Dist/Display.html?Name=DBIx-Class-PassphraseColumn> (or bug\-DBIx\-Class\-PassphraseColumn@rt.cpan.org <mailto:bug-DBIx-Class-PassphraseColumn@rt.cpan.org>). .SH "AUTHOR" .IX Header "AUTHOR" Florian Ragwitz <rafl@debian.org> .SH "CONTRIBUTOR" .IX Header "CONTRIBUTOR" Karen Etheridge <ether@cpan.org> .SH "COPYRIGHT AND LICENCE" .IX Header "COPYRIGHT AND LICENCE" This software is copyright (c) 2010 by Florian Ragwitz. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.