Improve documentation for authenticate_digest()
[catagits/Catalyst-Authentication-Credential-HTTP.git] / lib / Catalyst / Authentication / Credential / HTTP.pm
index d668e53..1e2648d 100644 (file)
@@ -9,17 +9,25 @@ use URI::Escape    ();
 use Catalyst       ();
 use Digest::MD5    ();
 
-BEGIN {
-    __PACKAGE__->mk_accessors(qw/_config realm/);
-}
-
-our $VERSION = "1.007";
+__PACKAGE__->mk_accessors(qw/
+    _config 
+    authorization_required_message 
+    password_field 
+    username_field 
+    type 
+    realm 
+    algorithm 
+    use_uri_for
+/);
+
+our $VERSION = '1.012';
 
 sub new {
     my ($class, $config, $app, $realm) = @_;
     
     $config->{username_field} ||= 'username';
-    my $self = { _config => $config, _debug => $app->debug };
+    # _config is shity back-compat with our base class.
+    my $self = { %$config, _config => $config, _debug => $app->debug ? 1 : 0 };
     bless $self, $class;
     
     $self->realm($realm);
@@ -30,11 +38,12 @@ sub new {
 
 sub init {
     my ($self) = @_;
-    my $type = $self->_config->{'type'} ||= 'any';
+    my $type = $self->type || 'any';
     
     if (!grep /$type/, ('basic', 'digest', 'any')) {
         Catalyst::Exception->throw(__PACKAGE__ . " used with unsupported authentication type: " . $type);
     }
+    $self->type($type);
 }
 
 sub authenticate {
@@ -59,18 +68,22 @@ sub authenticate_basic {
     my $headers = $c->req->headers;
 
     if ( my ( $username, $password ) = $headers->authorization_basic ) {
-           my $user_obj = $realm->find_user( { $self->_config->{username_field} => $username }, $c);
+           my $user_obj = $realm->find_user( { $self->username_field => $username }, $c);
            if (ref($user_obj)) {
             my $opts = {};
-            $opts->{$self->_config->{password_field}} = $password 
-                if $self->_config->{password_field};            
+            $opts->{$self->password_field} = $password
+                if $self->password_field;
             if ($self->check_password($user_obj, $opts)) {
-                $c->set_authenticated($user_obj);
                 return $user_obj;
             }
-        }
-        else {
-            $c->log->debug("Unable to locate user matching user info provided") if $c->debug;
+            else {
+                $c->log->debug("Password mismatch!") if $c->debug;
+                return;
+            }
+         }
+         else {
+             $c->log->debug("Unable to locate user matching user info provided")
+                if $c->debug;
             return;
         }
     }
@@ -126,12 +139,12 @@ sub authenticate_digest {
 
         my $username = $res{username};
 
-        my $user;
+        my $user_obj;
 
-        unless ( $user = $auth_info->{user} ) {
-            $user = $realm->find_user( { $self->_config->{username_field} => $username }, $c);
+        unless ( $user_obj = $auth_info->{user} ) {
+            $user_obj = $realm->find_user( { $self->username_field => $username }, $c);
         }
-        unless ($user) {    # no user, no authentication
+        unless ($user_obj) {    # no user, no authentication
             $c->log->debug("Unable to locate user matching user info provided") if $c->debug;
             return;
         }
@@ -150,12 +163,12 @@ sub authenticate_digest {
         # the idea of the for loop:
         # if we do not want to store the plain password in our user store,
         # we can store md5_hex("$username:$realm:$password") instead
-        my $password_field = $self->_config->{password_field};
+        my $password_field = $self->password_field;
         for my $r ( 0 .. 1 ) {
             # calculate H(A1) as per spec
-            my $A1_digest = $r ? $user->$password_field() : do {
+            my $A1_digest = $r ? $user_obj->$password_field() : do {
                 $ctx = Digest::MD5->new;
-                $ctx->add( join( ':', $username, $realm->name, $user->$password_field() ) );
+                $ctx->add( join( ':', $username, $realm->name, $user_obj->$password_field() ) );
                 $ctx->hexdigest;
             };
             if ( $nonce->algorithm eq 'MD5-sess' ) {
@@ -170,11 +183,10 @@ sub authenticate_digest {
                     $A2_digest );
             my $rq_digest = Digest::MD5::md5_hex($digest_in);
             $nonce->nonce_count($nonce_count);
-            $c->cache->set( __PACKAGE__ . '::opaque:' . $nonce->opaque,
-                $nonce );
+            my $key = __PACKAGE__ . '::opaque:' . $nonce->opaque;
+            $self->store_digest_authorization_nonce( $c, $key, $nonce );
             if ($rq_digest eq $res{response}) {
-                $c->set_authenticated($user);
-                return 1;
+                return $user_obj;
             }
         }
     }
@@ -191,7 +203,7 @@ sub _check_cache {
 
 sub _is_http_auth_type {
     my ( $self, $type ) = @_;
-    my $cfgtype = lc( $self->_config->{'type'} || 'any' );
+    my $cfgtype = lc( $self->type );
     return 1 if $cfgtype eq 'any' || $cfgtype eq lc $type;
     return 0;
 }
@@ -201,10 +213,10 @@ sub authorization_required_response {
 
     $c->res->status(401);
     $c->res->content_type('text/plain');
-    if (exists $self->_config->{authorization_required_message}) {
+    if (exists $self->{authorization_required_message}) {
         # If you set the key to undef, don't stamp on the body.
-        $c->res->body($self->_config->{authorization_required_message}) 
-            if defined $c->res->body($self->_config->{authorization_required_message}); 
+        $c->res->body($self->authorization_required_message) 
+            if defined $self->authorization_required_message; 
     }
     else {
         $c->res->body('Authorization required.');
@@ -271,7 +283,7 @@ sub _build_auth_header_domain {
           unless ref($domain) && ref($domain) eq "ARRAY";
 
         my @uris =
-          $self->_config->{use_uri_for}
+          $self->use_uri_for
           ? ( map { $c->uri_for($_) } @$domain )
           : ( map { URI::Escape::uri_escape($_) } @$domain );
 
@@ -320,7 +332,7 @@ sub _digest_auth_nonce {
 
     my $nonce   = $package->new;
 
-    if ( my $algorithm = $opts->{algorithm} || $self->_config->{algorithm}) { 
+    if ( my $algorithm = $opts->{algorithm} || $self->algorithm) { 
         $nonce->algorithm( $algorithm );
     }
 
@@ -516,12 +528,17 @@ Performs HTTP basic authentication.
 
 =item authenticate_digest $c, $realm, \%auth_info
 
-Performs HTTP digest authentication. Note that the password_type B<must> by I<clear> for
-digest authentication to succeed, and you must have L<Catalyst::Plugin::Session> in
-your application as digest authentication needs to store persistent data.
+Performs HTTP digest authentication.
+
+The password_type B<must> be I<clear> for digest authentication to
+succeed.  If you do not want to store your user passwords as clear
+text, you may instead store the MD5 digest in hex of the string
+'$username:$realm:$password'.
 
-Note - if you do not want to store your user passwords as clear text, then it is possible
-to store instead the MD5 digest in hex of the string '$username:$realm:$password' 
+L<Catalyst::Plugin::Cache> is used for persistent storage of the nonce
+values (see L</Nonce>).  It must be loaded in your application, unless
+you override the C<store_digest_authorization_nonce> and
+C<get_digest_authorization_nonce> methods as shown below.
 
 Takes an additional parameter of I<algorithm>, the possible values of which are 'MD5' (the default)
 and 'MD5-sess'. For more information about 'MD5-sess', see section 3.2.2.2 in RFC 2617.
@@ -623,6 +640,8 @@ Patches contributed by:
 
 =item Peter Corlett
 
+=item Devin Austin (dhoss) C<dhoss@cpan.org>
+
 =back
 
 =head1 SEE ALSO