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