NAME

Apache::AuthDigest::API - mod_perl API for Digest authentication

SYNOPSIS

PerlModule Apache::AuthDigest::API
PerlModule My::DigestAuthenticator

<Location /protected>
  PerlAuthenHandler My::DigestAuthenticator
  Require valid-user
  AuthType Digest
  AuthName "cookbook"
</Location>

DESCRIPTION

Apache::AuthDigest::API is a simple API for interacting with Digest authentication. For more information on Digest authentication, see RFC 2617: ftp://ftp.isi.edu/in-notes/rfc2617.txt

The API itself is very similar to the API mod_perl offers natively for Basic authentication:

mod_perl's Basic support       AuthDigest::API equivalent

  my $r = shift;                 $r = Apache::AuthDigest::API->new(shift)

  $r->get_basic_auth_pw()        $r->get_digest_auth_response()       

  $r->note_basic_auth_failure    $r->note_digest_auth_failure()

  [none]                         $r->compare_digest_response()

see Recipe 13.8 in the mod_perl Developer's Cookbook for a far more detailed explanantion than will be covered here.

new()

creates a new Apache::AuthDigest::API object. Apache::AuthDigest::API is a subclass of the Apache class so, with the exception of the addition of new methods, $r can be used the same as if it were a normal Apache object

my $r = Apache::AuthDigest::API->new(Apache->request);

get_digest_auth_response()

this parses out the authentication header sent by the client. it returns a status and a reference to a hash representing the client Digest request (if any).

my ($status, $response) = $r->get_digest_auth_response;
return $status unless $status == OK;

note_digest_auth_failure()

sets the proper authentication headers which prompt a client to send a proper Digest request in order to access the requested resource.

$r->note_digest_auth_failure;
return AUTH_REQUIRED;

compare_digest_response()

this method represents a shortcut for comparing a client Digest request with whatever credentials are stored on the server. the first argument is the hash reference returned by get_digest_auth_response(). the second argument is a MD5 digest of the user credentials. the credentials should be in the form

user:realm:password 

before they are hashed. the following Perl one-liner will generate a suitable digest:

$ perl -MDigest::MD5 -e'print Digest::MD5::md5_hex("user:realm:password"),"\n"'

EXAMPLE

for a complete example, see the My/DigestAuthenticator.pm file in the test suite for this package, as well as AuthDigest.pm. In general, the steps are the same as for Basic authentication, examples of which abound on CPAN, the Eagle book, and the Cookbook:

use Apache::AuthDigest::API;

sub handler {

  my $r = Apache::AuthDigest::API->new(shift);

  my ($status, $response) = $r->get_digest_auth_response;

  return $status unless $status == OK;

  my $digest = my_get_user_credentials_routine($r->user, $r->auth_name);

  return OK if $r->compare_digest_response($response, $digest);

  $r->note_digest_auth_failure;
  return AUTH_REQUIRED;
}

NOTES

this module essentially mimics the Digest implementation provided by mod_digest.c that ships with Apache. there is another implementation, classified as "experimental" that also ships with Apache, mod_auth_digest.c, which is more complete wrt RFC 2617. of particular interest is that the mod_digest implementation does not work with MSIE (so neither does this implemenation). at some point, Apache::AuthDigest::API::Full will implement a completely compliant API - this will have to do for now.

FEATURES/BUGS

none that I know of yet, but consider this alphaware.

SEE ALSO

perl(1), mod_perl(1), Apache(3), Apache::AuthDigest(3)

AUTHORS

Geoffrey Young <geoff@modperlcookbook.org>

Paul Lindner <paul@modperlcookbook.org>

Randy Kobes <randy@modperlcookbook.org>

COPYRIGHT

Copyright (c) 2002, Geoffrey Young, Paul Lindner, Randy Kobes.

All rights reserved.

This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

HISTORY

This code is derived from the Cookbook::DigestAPI module, available as part of "The mod_perl Developer's Cookbook".

For more information, visit http://www.modperlcookbook.org/