lib/Catalyst/Authentication/Credential/Password.pm

   1 package Catalyst::Authentication::Credential::Password;
   2
   3 use strict;
   4 use warnings;
   5
   6 use base qw/Class::Accessor::Fast/;
   7
   8 use Scalar::Util        ();
   9 use Catalyst::Exception ();
  10 use Digest              ();
  11
  12 BEGIN {
  13     __PACKAGE__->mk_accessors(qw/_config realm/);
  14 }
  15
  16 sub new {
  17     my ($class, $config, $app, $realm) = @_;
  18
  19     my $self = { _config => $config };
  20     bless $self, $class;
  21
  22     $self->realm($realm);
  23
  24     $self->_config->{'password_field'} ||= 'password';
  25     $self->_config->{'password_type'}  ||= 'clear';
  26     $self->_config->{'password_hash_type'} ||= 'SHA-1';
  27
  28     my $passwordtype = $self->_config->{'password_type'};
  29     if (!grep /$passwordtype/, ('none', 'clear', 'hashed', 'salted_hash', 'crypted', 'self_check')) {
  30         Catalyst::Exception->throw(__PACKAGE__ . " used with unsupported password type: " . $self->_config->{'password_type'});
  31     }
  32     return $self;
  33 }
  34
  35 sub authenticate {
  36     my ( $self, $c, $realm, $authinfo ) = @_;
  37
  38     ## because passwords may be in a hashed format, we have to make sure that we remove the
  39     ## password_field before we pass it to the user routine, as some auth modules use
  40     ## all data passed to them to find a matching user...
  41     my $userfindauthinfo = {%{$authinfo}};
  42     delete($userfindauthinfo->{$self->_config->{'password_field'}});
  43
  44     my $user_obj = $realm->find_user($userfindauthinfo, $c);
  45     if (ref($user_obj)) {
  46         if ($self->check_password($user_obj, $authinfo)) {
  47             return $user_obj;
  48         }
  49     } else {
  50         $c->log->debug("Unable to locate user matching user info provided") if $c->debug;
  51         return;
  52     }
  53 }
  54
  55 sub check_password {
  56     my ( $self, $user, $authinfo ) = @_;
  57
  58     if ($self->_config->{'password_type'} eq 'self_check') {
  59         return $user->check_password($authinfo->{$self->_config->{'password_field'}});
  60     } else {
  61         my $password = $authinfo->{$self->_config->{'password_field'}};
  62         my $storedpassword = $user->get($self->_config->{'password_field'});
  63
  64         if ($self->_config->{'password_type'} eq 'none') {
  65             return 1;
  66         } elsif ($self->_config->{'password_type'} eq 'clear') {
  67             # FIXME - Should we warn in the $storedpassword undef case,
  68             #         as the user probably fluffed the config?
  69             return unless defined $storedpassword;
  70             return $password eq $storedpassword;
  71         } elsif ($self->_config->{'password_type'} eq 'crypted') {
  72             return $storedpassword eq crypt( $password, $storedpassword );
  73         } elsif ($self->_config->{'password_type'} eq 'salted_hash') {
  74             require Crypt::SaltedHash;
  75             my $salt_len = $self->_config->{'password_salt_len'} ? $self->_config->{'password_salt_len'} : 0;
  76             return Crypt::SaltedHash->validate( $storedpassword, $password,
  77                 $salt_len );
  78         } elsif ($self->_config->{'password_type'} eq 'hashed') {
  79
  80              my $d = Digest->new( $self->_config->{'password_hash_type'} );
  81              $d->add( $self->_config->{'password_pre_salt'} || '' );
  82              $d->add($password);
  83              $d->add( $self->_config->{'password_post_salt'} || '' );
  84
  85              my $computed    = $d->clone()->digest;
  86              my $b64computed = $d->clone()->b64digest;
  87              return ( ( $computed eq $storedpassword )
  88                    || ( unpack( "H*", $computed ) eq $storedpassword )
  89                    || ( $b64computed eq $storedpassword)
  90                    || ( $b64computed.'=' eq $storedpassword) );
  91         }
  92     }
  93 }
  94
  95 __PACKAGE__;
  96
  97 __END__
  98
  99 =pod
 100
 101 =head1 NAME
 102
 103 Catalyst::Authentication::Credential::Password - Authenticate a user
 104 with a password.
 105
 106 =head1 SYNOPSIS
 107
 108     use Catalyst qw/
 109       Authentication
 110       /;
 111
 112     package MyApp::Controller::Auth;
 113
 114     sub login : Local {
 115         my ( $self, $c ) = @_;
 116
 117         $c->authenticate( { username => $c->req->param('username'),
 118                             password => $c->req->param('password') });
 119     }
 120
 121 =head1 DESCRIPTION
 122
 123 This authentication credential checker takes authentication information
 124 (most often a username) and a password, and attempts to validate the password
 125 provided against the user retrieved from the store.
 126
 127 =head1 CONFIGURATION
 128
 129     # example
 130     __PACKAGE__->config('Plugin::Authentication' =>
 131                 {
 132                     default_realm => 'members',
 133                     realms => {
 134                         members => {
 135
 136                             credential => {
 137                                 class => 'Password',
 138                                 password_field => 'password',
 139                                 password_type => 'hashed',
 140                                 password_hash_type => 'SHA-1'
 141                             },
 142                             ...
 143
 144
 145 The password module is capable of working with several different password
 146 encryption/hashing algorithms. The one the module uses is determined by the
 147 credential configuration.
 148
 149 Those who have used L<Catalyst::Plugin::Authentication> prior to the 0.10 release
 150 should note that the password field and type information is no longer part
 151 of the store configuration and is now part of the Password credential configuration.
 152
 153 =over 4
 154
 155 =item class
 156
 157 The classname used for Credential. This is part of
 158 L<Catalyst::Plugin::Authentication> and is the method by which
 159 Catalyst::Authentication::Credential::Password is loaded as the
 160 credential validator. For this module to be used, this must be set to
 161 'Password'.
 162
 163 =item password_field
 164
 165 The field in the user object that contains the password. This will vary
 166 depending on the storage class used, but is most likely something like
 167 'password'. In fact, this is so common that if this is left out of the config,
 168 it defaults to 'password'. This field is obtained from the user object using
 169 the get() method. Essentially: $user->get('passwordfieldname');
 170 B<NOTE> If the password_field is something other than 'password', you must
 171 be sure to use that same field name when calling $c->authenticate().
 172
 173 =item password_type
 174
 175 This sets the password type.  Often passwords are stored in crypted or hashed
 176 formats.  In order for the password module to verify the plaintext password
 177 passed in, it must be told what format the password will be in when it is retreived
 178 from the user object. The supported options are:
 179
 180 =over 8
 181
 182 =item none
 183
 184 No password check is done. An attempt is made to retrieve the user based on
 185 the information provided in the $c->authenticate() call. If a user is found,
 186 authentication is considered to be successful.
 187
 188 =item clear
 189
 190 The password in user is in clear text and will be compared directly.
 191
 192 =item self_check
 193
 194 This option indicates that the password should be passed to the check_password()
 195 routine on the user object returned from the store.
 196
 197 =item crypted
 198
 199 The password in user is in UNIX crypt hashed format.
 200
 201 =item salted_hash
 202
 203 The password in user is in salted hash format, and will be validated
 204 using L<Crypt::SaltedHash>.  If this password type is selected, you should
 205 also provide the B<password_salt_len> config element to define the salt length.
 206
 207 =item hashed
 208
 209 If the user object supports hashed passwords, they will be used in conjunction
 210 with L<Digest>. The following config elements affect the hashed configuration:
 211
 212 =over 8
 213
 214 =item password_hash_type
 215
 216 The hash type used, passed directly to L<Digest/new>.
 217
 218 =item password_pre_salt
 219
 220 Any pre-salt data to be passed to L<Digest/add> before processing the password.
 221
 222 =item password_post_salt
 223
 224 Any post-salt data to be passed to L<Digest/add> after processing the password.
 225
 226 =back
 227
 228 =back
 229
 230 =back
 231
 232 =head1 USAGE
 233
 234 The Password credential module is very simple to use. Once configured as
 235 indicated above, authenticating using this module is simply a matter of
 236 calling $c->authenticate() with an authinfo hashref that includes the
 237 B<password> element. The password element should contain the password supplied
 238 by the user to be authenticated, in clear text. The other information supplied
 239 in the auth hash is ignored by the Password module, and simply passed to the
 240 auth store to be used to retrieve the user. An example call follows:
 241
 242     if ($c->authenticate({ username => $username,
 243                            password => $password} )) {
 244         # authentication successful
 245     } else {
 246         # authentication failed
 247     }
 248
 249 =head1 METHODS
 250
 251 There are no publicly exported routines in the Password module (or indeed in
 252 most credential modules.)  However, below is a description of the routines
 253 required by L<Catalyst::Plugin::Authentication> for all credential modules.
 254
 255 =head2 new( $config, $app, $realm )
 256
 257 Instantiate a new Password object using the configuration hash provided in
 258 $config. A reference to the application is provided as the second argument.
 259 Note to credential module authors: new() is called during the application's
 260 plugin setup phase, which is before the application specific controllers are
 261 loaded. The practical upshot of this is that things like $c->model(...) will
 262 not function as expected.
 263
 264 =head2 authenticate( $authinfo, $c )
 265
 266 Try to log a user in, receives a hashref containing authentication information
 267 as the first argument, and the current context as the second.
 268
 269 =head2 check_password( )
 270
 271 =cut