update Authentication for 0.06
[catagits/Catalyst-Plugin-Authentication.git] / lib / Catalyst / Plugin / Authentication / Credential / Password.pm
CommitLineData
a90296d4 1#!/usr/bin/perl
2
3package Catalyst::Plugin::Authentication::Credential::Password;
4
5use strict;
6use warnings;
7
8use Scalar::Util ();
9use Catalyst::Exception ();
10use Digest ();
11
12sub login {
2f7d8b59 13 my ( $c, $user, $password, @rest ) = @_;
a90296d4 14
15 for ( $c->request ) {
a93f1197 16 unless ( $user ||= $_->param("login")
17 || $_->param("user")
18 || $_->param("username") )
19 {
20 $c->log->debug(
85d1d92d 21 "Can't login a user without a user object or user ID param")
22 if $c->debug;
a93f1197 23 return;
24 }
25
26 unless ( $password ||= $_->param("password")
27 || $_->param("passwd")
28 || $_->param("pass") )
29 {
85d1d92d 30 $c->log->debug("Can't login a user without a password")
31 if $c->debug;
a93f1197 32 return;
33 }
a90296d4 34 }
35
a93f1197 36 unless ( Scalar::Util::blessed($user)
85d1d92d 37 and $user->isa("Catalyst::Plugin::Authentication::User") )
a93f1197 38 {
2f7d8b59 39 if ( my $user_obj = $c->get_user( $user, $password, @rest ) ) {
a93f1197 40 $user = $user_obj;
41 }
42 else {
43 $c->log->debug("User '$user' doesn't exist in the default store")
44 if $c->debug;
45 return;
46 }
47 }
a90296d4 48
49 if ( $c->_check_password( $user, $password ) ) {
50 $c->set_authenticated($user);
a93f1197 51 $c->log->debug("Successfully authenticated user '$user'.")
52 if $c->debug;
a90296d4 53 return 1;
54 }
55 else {
a93f1197 56 $c->log->debug(
85d1d92d 57 "Failed to authenticate user '$user'. Reason: 'Incorrect password'")
a93f1197 58 if $c->debug;
a90296d4 59 return;
60 }
61}
62
63sub _check_password {
64 my ( $c, $user, $password ) = @_;
65
66 if ( $user->supports(qw/password clear/) ) {
67 return $user->password eq $password;
68 }
69 elsif ( $user->supports(qw/password crypted/) ) {
70 my $crypted = $user->crypted_password;
71 return $crypted eq crypt( $password, $crypted );
72 }
73 elsif ( $user->supports(qw/password hashed/) ) {
74
75 my $d = Digest->new( $user->hash_algorithm );
76 $d->add( $user->password_pre_salt || '' );
77 $d->add($password);
78 $d->add( $user->password_post_salt || '' );
79
80 my $stored = $user->hashed_password;
81 my $computed = $d->digest;
82
83 return ( ( $computed eq $stored )
84 || ( unpack( "H*", $computed ) eq $stored ) );
85 }
86 elsif ( $user->supports(qw/password salted_hash/) ) {
87 require Crypt::SaltedHash;
88
89 my $salt_len =
90 $user->can("password_salt_len") ? $user->password_salt_len : 0;
91
92 return Crypt::SaltedHash->validate( $user->hashed_password, $password,
93 $salt_len );
94 }
95 elsif ( $user->supports(qw/password self_check/) ) {
96
97 # while somewhat silly, this is to prevent code duplication
98 return $user->check_password($password);
99
100 }
101 else {
102 Catalyst::Exception->throw(
103 "The user object $user does not support any "
104 . "known password authentication mechanism." );
105 }
106}
107
108__PACKAGE__;
109
110__END__
111
112=pod
113
114=head1 NAME
115
116Catalyst::Plugin::Authentication::Credential::Password - Authenticate a user
117with a password.
118
119=head1 SYNOPSIS
120
121 use Catalyst qw/
122 Authentication
123 Authentication::Store::Foo
124 Authentication::Credential::Password
125 /;
126
8d3ca09c 127 package MyApp::Controller::Auth;
128
129 # *** NOTE ***
130 # if you place an action named 'login' in your application's root (as
131 # opposed to inside a controller) the following snippet will recurse,
132 # giving you lots of grief.
133 # never name actions in the root controller after plugin methods - use
134 # controllers and : Global instead.
135
a90296d4 136 sub login : Local {
137 my ( $self, $c ) = @_;
138
139 $c->login( $c->req->param('username'), $c->req->param('password') );
140 }
141
142=head1 DESCRIPTION
143
9b09fd1c 144This authentication credential checker takes a username (or userid) and a
145password, and tries various methods of comparing a password based on what
a90296d4 146the chosen store's user objects support:
147
148=over 4
149
150=item clear text password
151
152If the user has clear a clear text password it will be compared directly.
153
154=item crypted password
155
156If UNIX crypt hashed passwords are supported, they will be compared using
157perl's builtin C<crypt> function.
158
159=item hashed password
160
161If the user object supports hashed passwords, they will be used in conjunction
162with L<Digest>.
163
164=back
165
166=head1 METHODS
167
168=over 4
169
170=item login $username, $password
171
172Try to log a user in.
173
a2fcf979 174C<$username> can be a string (e.g. retrieved from a form) or an object.
9b09fd1c 175If the object is a L<Catalyst::Plugin::Authentication::User> it will be used
a90296d4 176as is. Otherwise C<< $c->get_user >> is used to retrieve it.
177
178C<$password> is a string.
179
d1481e8f 180If C<$username> or C<$password> are not provided, the query parameters
9b09fd1c 181C<login>, C<user>, C<username> and C<password>, C<passwd>, C<pass> will
182be tried instead.
183
184=back
185
186=head1 RELATED USAGE
187
188After the user is logged in, the user object for the current logged in user
189can be retrieved from the context using the C<< $c->user >> method.
190
191The current user can be logged out again by calling the C<< $c->logout >>
192method.
193
a90296d4 194=head1 SUPPORTING THIS PLUGIN
9b09fd1c 195
196For a User class to support credential verification using this plugin, it
197needs to indicate what sort of password a given user supports
198by implementing the C<supported_features> method in one or many of the
199following ways:
200
a90296d4 201=head2 Clear Text Passwords
202
203Predicate:
204
205 $user->supported_features(qw/password clear/);
206
207Expected methods:
208
209=over 4
210
211=item password
212
213Returns the user's clear text password as a string to be compared with C<eq>.
214
215=back
216
217=head2 Crypted Passwords
218
219Predicate:
220
221 $user->supported_features(qw/password crypted/);
222
223Expected methods:
224
225=over 4
226
227=item crypted_password
228
229Return's the user's crypted password as a string, with the salt as the first two chars.
230
231=back
232
233=head2 Hashed Passwords
234
235Predicate:
236
237 $user->supported_features(qw/password hashed/);
238
239Expected methods:
240
241=over 4
242
243=item hashed_password
244
245Return's the hash of the user's password as B<binary>.
246
247=item hash_algorithm
248
249Returns a string suitable for feeding into L<Digest/new>.
250
251=item password_pre_salt
252
253=item password_post_salt
254
255Returns a string to be hashed before/after the user's password. Typically only
256a pre-salt is used.
257
258=back
259
260=head2 Crypt::SaltedHash Passwords
261
262Predicate:
263
264 $user->supported_features(qw/password salted_hash/);
265
266Expected methods:
267
268=over 4
269
270=item hashed_password
271
272Returns the hash of the user's password as returned from L<Crypt-SaltedHash>->generate.
273
274=back
275
276Optional methods:
277
278=over 4
279
280=item password_salt_len
281
282Returns the length of salt used to generate the salted hash.
283
284=back
285
286=cut
287
288