.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 "Catalyst::Authentication::Credential::Password 3pm"
.TH Catalyst::Authentication::Credential::Password 3pm "2023-01-22" "perl v5.36.0" "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"
Catalyst::Authentication::Credential::Password \- Authenticate a user
with a password.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    use Catalyst qw/
\&      Authentication
\&      /;
\&
\&    package MyApp::Controller::Auth;
\&
\&    sub login : Local {
\&        my ( $self, $c ) = @_;
\&
\&        $c\->authenticate( { username => $c\->req\->param(\*(Aqusername\*(Aq),
\&                            password => $c\->req\->param(\*(Aqpassword\*(Aq) });
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This authentication credential checker takes authentication information
(most often a username) and a password, and attempts to validate the password
provided against the user retrieved from the store.
.SH "CONFIGURATION"
.IX Header "CONFIGURATION"
.Vb 6
\&    # example
\&    _\|_PACKAGE_\|_\->config(\*(AqPlugin::Authentication\*(Aq =>
\&                {
\&                    default_realm => \*(Aqmembers\*(Aq,
\&                    realms => {
\&                        members => {
\&
\&                            credential => {
\&                                class => \*(AqPassword\*(Aq,
\&                                password_field => \*(Aqpassword\*(Aq,
\&                                password_type => \*(Aqhashed\*(Aq,
\&                                password_hash_type => \*(AqSHA\-1\*(Aq
\&                            },
\&                            ...
.Ve
.PP
The password module is capable of working with several different password
encryption/hashing algorithms. The one the module uses is determined by the
credential configuration.
.PP
Those who have used Catalyst::Plugin::Authentication prior to the 0.10 release
should note that the password field and type information is no longer part
of the store configuration and is now part of the Password credential configuration.
.IP "class" 4
.IX Item "class"
The classname used for Credential. This is part of
Catalyst::Plugin::Authentication and is the method by which
Catalyst::Authentication::Credential::Password is loaded as the
credential validator. For this module to be used, this must be set to
\&'Password'.
.IP "password_field" 4
.IX Item "password_field"
The field in the user object that contains the password. This will vary
depending on the storage class used, but is most likely something like
\&'password'. In fact, this is so common that if this is left out of the config,
it defaults to 'password'. This field is obtained from the user object using
the \fBget()\fR method. Essentially: \f(CW$user\fR\->get('passwordfieldname');
\&\fB\s-1NOTE\s0\fR If the password_field is something other than 'password', you must
be sure to use that same field name when calling \f(CW$c\fR\->\fBauthenticate()\fR.
.IP "password_type" 4
.IX Item "password_type"
This sets the password type.  Often passwords are stored in crypted or hashed
formats.  In order for the password module to verify the plaintext password
passed in, it must be told what format the password will be in when it is retrieved
from the user object. The supported options are:
.RS 4
.IP "none" 8
.IX Item "none"
No password check is done. An attempt is made to retrieve the user based on
the information provided in the \f(CW$c\fR\->\fBauthenticate()\fR call. If a user is found,
authentication is considered to be successful.
.IP "clear" 8
.IX Item "clear"
The password in user is in clear text and will be compared directly.
.IP "self_check" 8
.IX Item "self_check"
This option indicates that the password should be passed to the \fBcheck_password()\fR
routine on the user object returned from the store.
.IP "crypted" 8
.IX Item "crypted"
The password in user is in \s-1UNIX\s0 crypt hashed format.
.IP "salted_hash" 8
.IX Item "salted_hash"
The password in user is in salted hash format, and will be validated
using Crypt::SaltedHash.  If this password type is selected, you should
also provide the \fBpassword_salt_len\fR config element to define the salt length.
.IP "hashed" 8
.IX Item "hashed"
If the user object supports hashed passwords, they will be used in conjunction
with Digest. The following config elements affect the hashed configuration:
.RS 8
.IP "password_hash_type" 8
.IX Item "password_hash_type"
The hash type used, passed directly to \*(L"new\*(R" in Digest.
.IP "password_pre_salt" 8
.IX Item "password_pre_salt"
Any pre-salt data to be passed to \*(L"add\*(R" in Digest before processing the password.
.IP "password_post_salt" 8
.IX Item "password_post_salt"
Any post-salt data to be passed to \*(L"add\*(R" in Digest after processing the password.
.RE
.RS 8
.RE
.RE
.RS 4
.RE
.SH "USAGE"
.IX Header "USAGE"
The Password credential module is very simple to use. Once configured as
indicated above, authenticating using this module is simply a matter of
calling \f(CW$c\fR\->\fBauthenticate()\fR with an authinfo hashref that includes the
\&\fBpassword\fR element. The password element should contain the password supplied
by the user to be authenticated, in clear text. The other information supplied
in the auth hash is ignored by the Password module, and simply passed to the
auth store to be used to retrieve the user. An example call follows:
.PP
.Vb 6
\&    if ($c\->authenticate({ username => $username,
\&                           password => $password} )) {
\&        # authentication successful
\&    } else {
\&        # authentication failed
\&    }
.Ve
.SH "METHODS"
.IX Header "METHODS"
There are no publicly exported routines in the Password module (or indeed in
most credential modules.)  However, below is a description of the routines
required by Catalyst::Plugin::Authentication for all credential modules.
.ie n .SS "new( $config, $app, $realm )"
.el .SS "new( \f(CW$config\fP, \f(CW$app\fP, \f(CW$realm\fP )"
.IX Subsection "new( $config, $app, $realm )"
Instantiate a new Password object using the configuration hash provided in
\&\f(CW$config\fR. A reference to the application is provided as the second argument.
Note to credential module authors: \fBnew()\fR is called during the application's
plugin setup phase, which is before the application specific controllers are
loaded. The practical upshot of this is that things like \f(CW$c\fR\->model(...) will
not function as expected.
.ie n .SS "authenticate( $authinfo, $c )"
.el .SS "authenticate( \f(CW$authinfo\fP, \f(CW$c\fP )"
.IX Subsection "authenticate( $authinfo, $c )"
Try to log a user in, receives a hashref containing authentication information
as the first argument, and the current context as the second.
.SS "check_password( )"
.IX Subsection "check_password( )"