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()

Params:

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

Pre:

• -data is the data from which the digest is to be generated,

• -key is the private key such that the digest 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 digest, which must be 'binary', 'hex' or 'b64'.

Post:

• Generate a digest and return it.

AUTHORS

Colin Kong (colin.kong@toronto.edu)

CREDITS

Lincoln Stein (lstein@cshl.org)

BUGS

SEE ALSO

Digest::HMAC, Digest::SHA1, Digest::MD5, Crypt::CBC, Crypt::Blowfish, Crypt::DES, Crypt::IDEA, LibWeb::Admin, LibWeb::Crypt, LibWeb::Session.

cpanm LibWeb::CGI

perl -MCPAN -e shell
install LibWeb::CGI