-- a vanilla web site backend

current version: 0.02

Sourceforge

Control panel
CVS
News
Bug Tracking
Mailing lists
Message forums
Downloads

Sponsors

Documentation:

LibWeb::Digest

NAME

LibWeb::Digest - Digest generation for libweb applications

SUPPORTED PLATFORMS

BSD, Linux, Solaris and Windows.

REQUIRE

Digest::HMAC
Digest::SHA1
Digest::MD5

ISA

LibWeb::Class

SYNOPSIS

   use LibWeb::Digest;
   my $d = new LibWeb::Digest();

   my $mac = $d->generate_MAC(
                              -data => $data,
                              -key => $key,
                              -algorithm => 'Digest::SHA1',
                              -format => 'b64'
                             );

   my $digest
       = $d->generate_digest(
                             -data => $data,
                             -key => $key,
                             -algorithm => 'Digest::MD5',
                             -format => 'b64'
                            );

ABSTRACT

This class provides methods to

Generate message authenticity check (MAC) code which is mostly used in authentication cookies sent to browsers, and
generate digest code (binary, hex or B64) by using the algorithm provided by either Digest::MD5 or Digest::SHA1,

The current version of LibWeb::Digest is available at

    http://libweb.sourceforge.net

Several LibWeb applications (LEAPs) have be written, released and are available at

    http://leaps.sourceforge.net

DESCRIPTION

GENERATING A MAC FOR USER/SESSION AUTHENTICATION

The following discussion on MAC is extracted from a WWW security FAQ written by Lincoln Stein,

   http://www.w3.org/Security/Faq/wwwsf7.html#Q66

``If possible, cookies should contain information that allows the system to verify that the person using them is authorized to do so. A popular scheme is to include the following information in cookies:

   1.the session ID or authorization information 
   2.the time and date the cookie was issued 
   3.an expiration time 
   4.the IP address of the browser the cookie was issued to 
   5.a message authenticity check (MAC) code

By incorporating an expiration date and time into the cookie, system designers can limit the potential damage that a hijacked cookie can do. If the cookie is intercepted, it can only be used for a finite time before it becomes invalid. The idea of including the browser's IP address into the cookie is that the cookie will only be accepted if the stored IP address matches the IP address of the browser submitting it. This makes it difficult for an interloper to hijack the cookie, because it is hard (although not impossible) to spoof an IP address.

The MAC code is there to ensure that none of the fields of the cookie have been tampered with. There are many ways to compute a MAC, most of which rely on one-way hash algorithms such as MD5 or SHA to create a unique fingerprint for the data within the cookie. Here's a simple but relatively secure technique that uses MD5:

     MAC = MD5("secret key " +
                MD5("session ID" + "issue date" +
                    "expiration time" + "IP address" +
                    "secret key")
               )

This algorithm first performs a string concatenation of all the data fields in the cookie, then adds to it a secret string known only to the Web server. The whole is then passed to the MD5 function to create a unique hash. This value is again concatenated with the secret key, and the whole thing is rehashed. (The second round of MD5 hashing is necessary in order to avoid an attack in which additional data is appended to the end of the cookie and a new hash recalculated by the attacker.)

This hash value is now incorporated into the cookie data. Later, when the cookie is returned to the server, the software should verify that the cookie hasn't expired and is being returned by the proper IP address. Then it should regenerate the MAC from the data fields, and compare that to the MAC in the cookie. If they match, there's little chance that the cookie has been tampered with.'' -- Lincoln Stein.

In fact, this is the technique used by LibWeb to handle user/session authentication via cookies. LibWeb::Admin and LibWeb::Session use LibWeb::Digest::generate_MAC() to generate MACs. LibWeb::Digest::generate_MAC() uses Digest::HMAC and uses either Digest::MD5 or Digest::SHA1 as the digest algorithm.

METHODS

generate_MAC()

Params:

   -data=>, -key=>, -algorithm=>, -format=>

Pre:

-data is the data from which the MAC is to be generated,
-key is the private key such that the MAC generated is unique to that key (sorry, I do not have a rigorous definition for that right now),
-algorithm must be either 'Digest::MD5' or 'Digest::SHA1',
-format is the format of the generated MAC, which must be 'binary', 'hex' or 'b64'.

Post:

Generate a MAC and return it.

generate_digest()