NAME

Apache::AppSamurai::Util - Apache::AppSamurai utility methods

SYNOPSIS

 use Apache::AppSamurai::Util qw(expires CreateSessionAuthKey
                                CheckSidFormat HashPass HashAny
                                ComputeSessionId CheckUrlFormat
                                CheckHostName CheckHostIP XHalf);
 
 
 # Convert UNIX timestamp to a cookie expiration date
 $expirets = time() + 3600;
 $expire = expires($expire);

 # Get a random session authentication key.
 $newkey = CreateSessionAuthKey();

 # Compute a session authentication key from input.
 $junk = 'stuffySTUFFthing';
 $newkey = CreateSessionAuthKey($junk);

 # Untaint and check for valid session ID or session auth key format.
 if ($id = CheckSidFormat($id)) { print "ROCK ON!\n"; }

 # Check for a valid "passphrase" (must be all printables and normal
 # whitespace), then return a hash of input.
 $passphrase = "The quick brown cow jumped into the A&W root beer.";
 ($passkey = HashPass($passphrase)) or die "Bad passphrase";

 # Just hash the input, even if empty, and return hash.
 $hashstruff = HashAny('stuff');

 # Compute the real session ID by computing a HMAC of the user's session
 # authentication key and the server's key.
 $authkey = '628b49d96dcde97a430dd4f597705899e09a968f793491e4b704cae33a40dc02';
 $servkey = 'c44474038d459e40e4714afefa7bf8dae9f9834b22f5e8ec1dd434ecb62b512e';
 ($sessid = ComputeSessionId($authkey, $servkey)) or die "Bad input!";

 # Untaint and check for a valid session ID, session authentication key,
 # or server key value.  (All should be hex strings of a proper length.)
 ($authkey = CheckSidFormat($authkey)) or die "Bad authentication key!";

 # Untaint and check (loosely) for a properly formatted URL.
 $url = 'http://jerryonly.mil/TheApp?test=1';
 ($url = CheckUrlFormat($url)) or die "You call that an URL?";

 # Untaint and check for a decent looking hostname/DNS name
 $hn = 'jerryonly.mil';
 ($hn = CheckHostName($hn)) or die "Bad name, man.";

 # Untaint and check for a valid IP. IPv4 only supported at this time :(
 $ip = '10.11.12.13';
 ($ip = CheckHostIP($ip)) or die "That is no kind of dotted quad....";

 # Untaint and then X out the second half of the input.  This is used
 # for various debugging output to (hopefully) protect sensitive info from
 # ending up in logs.
 $msg = "Who stole my notebook?  Was it you Larry?";
 $msg = XHalf($msg);
 print $msg, "\n";
 # Prints out: Who stole my notebookXXXXXXXXXXXXXXXXXXXX

DESCRIPTION

This is a set of utility methods for Apache::AppSamurai and related sub-modules to use. All methods should be called with a full module path, (Apache::AppSamurai::Util::CheckHostIp(), etc), or be imported into the current namespace.

Almost all the methods return a clean, untainted value on success, or undef on failure.

METHODS

expires()

Convert a UNIX timestamp to a valid cookie expire stamp. (Copied from CGI::Util).

CreateSessionAuthKey()

Takes one or more arguments and concatenates them. If no arguments are given, a random string is created instead. Returns the SHA256 digest hex string of the input or random string.

HashPass()

Takes a scalar with printable text (normal chars and whitespace), and returns the SHA256 digest hex string of the input.

HashAny()

Concatenates one or more arguments and returns the SHA256 digest hex string of the input. This method allows an input of ''. Do not use for security checks without first checking your input.

ComputeSessionId()

Takes a session authentication key, (generally the cookie value from the client), as the first argument. The second is the server key, (configured with the ServerKey or ServerPass option in the Apache config.) After checking for valid input, a HMAC is calculated using the SHA256 digest algorithm. The HMAC is returned as a hex string.

This method of looking up the real (local) session ID allows for keeping the session authentication key a secret to the web server while it is not being actively used. This is important because the session authentication key is used (in part) to encrypt the user's session data. Without the session authentication key, a hacker can not steal information from a stale session file, remnant data on a hard drive, or from a hacked database.

CheckSidFormat()

Check input scalar for proper ID format. (Characters and length.) Returns the untainted input, or undef on failure.

Apache::AppSamurai currently uses SHA256 for all digest and ID functions. All are represented as hex strings with a length of 32 characters. (256 bits divided by 4 characters per nibble.) This magic number is set in the $IDLEN global in the Util.pm file. Future versions may be more flexible and allow alternate digest algorithms.

CheckUrlFormat()

Check the scalar for proper URL formatting. Returns the untainted URL or undef on failure.

This is just a basic check, and allows through ftp:, gopher:, etc in addition to http: and https:. It is just a sanity check. Apply more extensive filtering using mod_rewrite or other means, as needed.

CheckHostName()

Check scalar for basic hostname/domain name syntax. Returns an untainted version of the input, or undef on failure.

CheckHostIP()

Check input scalar for proper text IP format. Returns the untainted input on success, or undef on failure.

IPv4 dotted quads are only supported at this time. IPv6 support will be added, but considering the ungodly tangled mess that can represent an IPv6 address, the motivation to tackle it is not currently present.

XHalf()

Check that input scalar is text, then convert the second half of the string to a string of 'X's and return the new string.

This is used for debug logging of potentially sensitive information, where some context text is required, but where a full disclosure would be dangerous. Only use this method when the latter half of the text contains all or most of the sensitive data. It is a convenience function to avoid needing to write custom data sanitization into each logging event.

For instance, for a session ID of "628b49d96dcde97a430dd4f597705899e09a968f793491e4b704cae33a40dc02" the output would be: "628b49d96dcde97a430dd4f597705899XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", which would be fairly safe since only half the data would be revealed in the log. This is still 128 bits of digest, and in most cases would be enough not to seriously endanger the data.

On the other hand, if you allow long passwords and you log a basic authentication "Authorization:" header of: "cm9nZXJ0aGVtYW46VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2cu" the output would be: "cm9nZXJ0aGVtYW46VGhlIHF1aWNrIGJyb3duIGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX". This is not very safe. Here is what decoding produces: "rogertheman:The quick brown e×]u×]u×]u×]u×]u×]u×]u×]u×]u×" So, the user's name is "rogertheman". More importantly, we can guess what the rest of the password is, and we know the length of the password.

Apache::AppSamurai does log the Authorization: header using XHalf when Debug is enabled. Be very careful when running production servers! Only use Debug when absolutely needed, monitor the logs for sensitive information leak, and remove debug log data when possible.

That said, leave Debug set to 0 and do not use XHalf in any modules you code if you find it too risky.

SEE ALSO

Apache::AppSamurai, Digest::SHA

AUTHOR

Paul M. Hirsch, <paul at voltagenoir.org>

BUGS

See Apache::AppSamurai for information on bug submission and tracking.

SUPPORT

See Apache::AppSamurai for support information.

ACKNOWLEDGEMENTS

This module includes date calculation code from CGI::Util.

COPYRIGHT & LICENSE

Copyright 2007 Paul M. Hirsch, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Apache::AppSamurai

perl -MCPAN -e shell
install Apache::AppSamurai