lib/Catalyst/Plugin/Authentication/Credential/Password.pm

   1 #!/usr/bin/perl
   2
   3 package Catalyst::Plugin::Authentication::Credential::Password;
   4
   5 use strict;
   6 use warnings;
   7
   8 use Scalar::Util        ();
   9 use Catalyst::Exception ();
  10 use Digest              ();
  11
  12 sub login {
  13     my ( $c, $user, $password, @rest ) = @_;
  14
  15     for ( $c->request ) {
  16         unless ( $user ||= $_->param("login")
  17             || $_->param("user")
  18             || $_->param("username") )
  19         {
  20             $c->log->debug(
  21                 "Can't login a user without a user object or user ID param")
  22                   if $c->debug;
  23             return;
  24         }
  25
  26         unless ( $password ||= $_->param("password")
  27             || $_->param("passwd")
  28             || $_->param("pass") )
  29         {
  30             $c->log->debug("Can't login a user without a password")
  31               if $c->debug;
  32             return;
  33         }
  34     }
  35
  36     unless ( Scalar::Util::blessed($user)
  37         and $user->isa("Catalyst::Plugin::Authentication::User") )
  38     {
  39         if ( my $user_obj = $c->get_user( $user, $password, @rest ) ) {
  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     }
  48
  49     if ( $c->_check_password( $user, $password ) ) {
  50         $c->set_authenticated($user);
  51         $c->log->debug("Successfully authenticated user '$user'.")
  52           if $c->debug;
  53         return 1;
  54     }
  55     else {
  56         $c->log->debug(
  57             "Failed to authenticate user '$user'. Reason: 'Incorrect password'")
  58           if $c->debug;
  59         return;
  60     }
  61 }
  62
  63 sub _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
 116 Catalyst::Plugin::Authentication::Credential::Password - Authenticate a user
 117 with a password.
 118
 119 =head1 SYNOPSIS
 120
 121     use Catalyst qw/
 122       Authentication
 123       Authentication::Store::Foo
 124       Authentication::Credential::Password
 125       /;
 126
 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
 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
 144 This authentication credential checker takes a username (or userid) and a
 145 password, and tries various methods of comparing a password based on what
 146 the chosen store's user objects support:
 147
 148 =over 4
 149
 150 =item clear text password
 151
 152 If the user has clear a clear text password it will be compared directly.
 153
 154 =item crypted password
 155
 156 If UNIX crypt hashed passwords are supported, they will be compared using
 157 perl's builtin C<crypt> function.
 158
 159 =item hashed password
 160
 161 If the user object supports hashed passwords, they will be used in conjunction
 162 with L<Digest>.
 163
 164 =back
 165
 166 =head1 METHODS
 167
 168 =over 4
 169
 170 =item login $username, $password
 171
 172 Try to log a user in.
 173
 174 C<$username> can be a string (e.g. retrieved from a form) or an object.
 175 If the object is a L<Catalyst::Plugin::Authentication::User> it will be used
 176 as is. Otherwise C<< $c->get_user >> is used to retrieve it.
 177
 178 C<$password> is a string.
 179
 180 If C<$username> or C<$password> are not provided, the query parameters
 181 C<login>, C<user>, C<username> and C<password>, C<passwd>, C<pass> will
 182 be tried instead.
 183
 184 =back
 185
 186 =head1 RELATED USAGE
 187
 188 After the user is logged in, the user object for the current logged in user
 189 can be retrieved from the context using the C<< $c->user >> method.
 190
 191 The current user can be logged out again by calling the C<< $c->logout >>
 192 method.
 193
 194 =head1 SUPPORTING THIS PLUGIN
 195
 196 For a User class to support credential verification using this plugin, it
 197 needs to indicate what sort of password a given user supports
 198 by implementing the C<supported_features> method in one or many of the
 199 following ways:
 200
 201 =head2 Clear Text Passwords
 202
 203 Predicate:
 204
 205         $user->supported_features(qw/password clear/);
 206
 207 Expected methods:
 208
 209 =over 4
 210
 211 =item password
 212
 213 Returns the user's clear text password as a string to be compared with C<eq>.
 214
 215 =back
 216
 217 =head2 Crypted Passwords
 218
 219 Predicate:
 220
 221         $user->supported_features(qw/password crypted/);
 222
 223 Expected methods:
 224
 225 =over 4
 226
 227 =item crypted_password
 228
 229 Return'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
 235 Predicate:
 236
 237         $user->supported_features(qw/password hashed/);
 238
 239 Expected methods:
 240
 241 =over 4
 242
 243 =item hashed_password
 244
 245 Return's the hash of the user's password as B<binary>.
 246
 247 =item hash_algorithm
 248
 249 Returns a string suitable for feeding into L<Digest/new>.
 250
 251 =item password_pre_salt
 252
 253 =item password_post_salt
 254
 255 Returns a string to be hashed before/after the user's password. Typically only
 256 a pre-salt is used.
 257
 258 =back
 259
 260 =head2 Crypt::SaltedHash Passwords
 261
 262 Predicate:
 263
 264         $user->supported_features(qw/password salted_hash/);
 265
 266 Expected methods:
 267
 268 =over 4
 269
 270 =item hashed_password
 271
 272 Returns the hash of the user's password as returned from L<Crypt-SaltedHash>->generate.
 273
 274 =back
 275
 276 Optional methods:
 277
 278 =over 4
 279
 280 =item password_salt_len
 281
 282 Returns the length of salt used to generate the salted hash.
 283
 284 =back
 285
 286 =cut
 287
 288