More docs

[catagits/Catalyst-Plugin-Authentication.git] / lib / Catalyst / Plugin / Authentication / Credential / Password.pm

#!/usr/bin/perl\r
\r
package Catalyst::Plugin::Authentication::Credential::Password;\r
\r
use strict;\r
use warnings;\r
\r
use Scalar::Util        ();\r
use Catalyst::Exception ();\r
use Digest              ();\r
\r
sub login {\r
    my ( $c, $user, $password ) = @_;\r
\r
    for ( $c->request ) {\r
             $user ||= $_->param("login")\r
          || $_->param("user")\r
          || $_->param("username")\r
          || return;\r
\r
             $password ||= $_->param("password")\r
          || $_->param("passwd")\r
          || $_->param("pass")\r
          || return;\r
    }\r
\r
    $user = $c->get_user($user) || return\r
      unless Scalar::Util::blessed($user)\r
      and $user->isa("Catalyst:::Plugin::Authentication::User");\r
\r
    if ( $c->_check_password( $user, $password ) ) {\r
        $c->set_authenticated($user);\r
        return 1;\r
    }\r
    else {\r
        return;\r
    }\r
}\r
\r
sub _check_password {\r
    my ( $c, $user, $password ) = @_;\r
\r
    if ( $user->supports(qw/password clear/) ) {\r
        return $user->password eq $password;\r
    }\r
    elsif ( $user->supports(qw/password crypted/) ) {\r
        my $crypted = $user->crypted_password;\r
        return $crypted eq crypt( $password, $crypted );\r
    }\r
    elsif ( $user->supports(qw/password hashed/) ) {\r
\r
        my $d = Digest->new( $user->hash_algorithm );\r
        $d->add( $user->password_pre_salt || '' );\r
        $d->add($password);\r
        $d->add( $user->password_post_salt || '' );\r
\r
        my $stored   = $user->hashed_password;\r
        my $computed = $d->digest;\r
\r
        return ( ( $computed eq $stored )\r
              || ( unpack( "H*", $computed ) eq $stored ) );\r
    }\r
    elsif ( $user->supports(qw/password salted_hash/) ) {\r
        require Crypt::SaltedHash;\r
\r
        my $salt_len =\r
          $user->can("password_salt_len") ? $user->password_salt_len : 0;\r
\r
        return Crypt::SaltedHash->validate( $user->hashed_password, $password,\r
            $salt_len );\r
    }\r
    elsif ( $user->supports(qw/password self_check/) ) {\r
\r
        # while somewhat silly, this is to prevent code duplication\r
        return $user->check_password($password);\r
\r
    }\r
    else {\r
        Catalyst::Exception->throw(\r
                "The user object $user does not support any "\r
              . "known password authentication mechanism." );\r
    }\r
}\r
\r
__PACKAGE__;\r
\r
__END__\r
\r
=pod\r
\r
=head1 NAME\r
\r
Catalyst::Plugin::Authentication::Credential::Password - Authenticate a user\r
with a password.\r
\r
=head1 SYNOPSIS\r
\r
    use Catalyst qw/\r
      Authentication\r
      Authentication::Store::Foo\r
      Authentication::Credential::Password\r
      /;\r
\r
    sub login : Local {\r
        my ( $self, $c ) = @_;\r
\r
        $c->login( $c->req->param('username'), $c->req->param('password') );\r
    }\r
\r
=head1 DESCRIPTION\r
\r
This authentication credential checker takes a username (or userid) and a 
password, and tries various methods of comparing a password based on what 
the chosen store's user objects support:\r
\r
=over 4\r
\r
=item clear text password\r
\r
If the user has clear a clear text password it will be compared directly.\r
\r
=item crypted password\r
\r
If UNIX crypt hashed passwords are supported, they will be compared using\r
perl's builtin C<crypt> function.\r
\r
=item hashed password\r
\r
If the user object supports hashed passwords, they will be used in conjunction\r
with L<Digest>.\r
\r
=back\r
\r
=head1 METHODS\r
\r
=over 4\r
\r
=item login $username, $password\r
\r
Try to log a user in.\r
\r
C<$username> can be a string (e.g. retrieved from a form) or an object. 
If the object is a L<Catalyst::Plugin::Authentication::User> it will be used 
as is. Otherwise C<< $c->get_user >> is used to retrieve it.\r
\r
C<$password> is a string.\r
\r
If C<$username> or C<$password> are not provided the query parameters 
C<login>, C<user>, C<username> and C<password>, C<passwd>, C<pass> will 
be tried instead.

=back

=head1 RELATED USAGE

After the user is logged in, the user object for the current logged in user 
can be retrieved from the context using the C<< $c->user >> method.

The current user can be logged out again by calling the C<< $c->logout >> 
method.

=head1 SUPPORTING THIS PLUGIN\r

For a User class to support credential verification using this plugin, it
needs to indicate what sort of password a given user supports 
by implementing the C<supported_features> method in one or many of the 
following ways:

=head2 Clear Text Passwords\r
\r
Predicate:\r
\r
	$user->supported_features(qw/password clear/);\r
\r
Expected methods:\r
\r
=over 4\r
\r
=item password\r
\r
Returns the user's clear text password as a string to be compared with C<eq>.\r
\r
=back\r
\r
=head2 Crypted Passwords\r
\r
Predicate:\r
\r
	$user->supported_features(qw/password crypted/);\r
\r
Expected methods:\r
\r
=over 4\r
\r
=item crypted_password\r
\r
Return's the user's crypted password as a string, with the salt as the first two chars.\r
\r
=back\r
\r
=head2 Hashed Passwords\r
\r
Predicate:\r
\r
	$user->supported_features(qw/password hashed/);\r
\r
Expected methods:\r
\r
=over 4\r
\r
=item hashed_password\r
\r
Return's the hash of the user's password as B<binary>.\r
\r
=item hash_algorithm\r
\r
Returns a string suitable for feeding into L<Digest/new>.\r
\r
=item password_pre_salt\r
\r
=item password_post_salt\r
\r
Returns a string to be hashed before/after the user's password. Typically only\r
a pre-salt is used.\r
\r
=back\r
\r
=head2 Crypt::SaltedHash Passwords\r
\r
Predicate:\r
\r
	$user->supported_features(qw/password salted_hash/);\r
\r
Expected methods:\r
\r
=over 4\r
\r
=item hashed_password\r
\r
Returns the hash of the user's password as returned from L<Crypt-SaltedHash>->generate.\r
\r
=back\r
\r
Optional methods:\r
\r
=over 4\r
\r
=item password_salt_len\r
\r
Returns the length of salt used to generate the salted hash.\r
\r
=back\r
\r
=cut\r
\r
\r