view release on metacpan or  search on metacpan

lib/Apache/AppSamurai/Util.pm  view on Meta::CPAN

=head2 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 C<$IDLEN>
global in the Util.pm file.  Future versions may be more flexible and allow
alternate digest algorithms.

=head2 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.

=head2 CheckHostName()

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

=head2 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.

=head2 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.

=head1 SEE ALSO

L<Apache::AppSamurai>, L<Digest::SHA>

=head1 AUTHOR

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

=head1 BUGS

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

=head1 SUPPORT

See L<Apache::AppSamurai> for support information.

=head1 ACKNOWLEDGEMENTS

This module includes date calculation code from
L<CGI::Util>.

=head1 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.

=cut