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