Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

Apache::Access::Headers
mod_perl HTTP header authorization module

Apache::Access::Headers - mod_perl HTTP header authorization module


NAME

Apache::Access::Headers - mod_perl HTTP header authorization module


SYNOPSIS


 # in httpd.conf

 PerlSetVar HeadersAccessConf conf/headers_access.conf

        

 DocumentRoot /usr/local/apache/htdocs

 <Directory "/usr/local/apache/htdocs">

    PerlModule Apache::Access::Headers

    PerlAccessHandler Apache::Access::Headers

 </Directory>


DESCRIPTION

This module is intended to be used as a mod_perl PerlAccessHandler. It's function is to authorize requests for server resources based on the existence of and content of HTTP headers.

Authorizing HTTP headers may be be set by a web browser, a software agent, or an authenitcating proxy server. This module was originally written to work with the latter.

Note: The default reponse from the handler is currently FORBIDDEN. This behavior is not yet configurable.


CONFIGURING APACHE

Module configuration is simple ( read: limited ). Currently, the module only works with a single configuration file, and works best when configured for a server's document root. See the LIMITATIONS section for an explanation of the modules current short-comings.

Add the following line to httpd.conf outside all Directory, Location and VirtualHost blocks:


 PerlSetVar HeadersAccessConf /path/to/conf/headers_access.conf

 

And add the following lines to the DocumentRoot Directory block:

  PerlModule Apache::Access::Headers

  PerlAccessHandler Apache::Access::Headers


CONFIGURATION FILE

General Options

Although the modules is currently limited to a single xml-based configuration file, this configuration file is quite flexible.

The shell of the conf file is:


 <headers_authz>

  <headers>

  [...]

  </headers>

 </headers_authz>

The important part of the conf file is the <header> blocks within the <headers> block. Each <header> block must contain two items: an <id> tag and a <path> tag.

The <id> tag specifies the name of the HTTP header that that must be set to allow access to the urls matched by the <path> tags. <path> tags are treated as regular expressions ( i.e., m|^$k$| where $k is the value of the <path> tag ).

Using the Sample Configuration File below, a request for /secrets/index.html must contain an X-Can-View-Secret-Stuff header with a non-zero value in order to be successfully authorized.

Likewise, a request for /secrets.html requires that either an X-Can-View-Secret-Stuff header or an X-Can-View-Super-Secret-Stuff header is present and set to a non-zero value.

As mentioned above, <path> tags are treated as regular expressions. You'll notice, then, that the <path> tag for <id>X-Secret-User-ID</id> in the sample conf contains parantheses. Parentheses tells the module to require that the value assigned to the needed header ( i.e. X-Secret-User-ID ) equal $1.

For example, using the sample conf, a request for /users/jeffo/ must have an X-Secret-User-ID header set to 'jeffo'. If X-Secret-User-ID header is present but set to 'tori', the request will be denied.

Other Options

There are three special configuration options. They are outlined here:

ALL
If the <id> of a <header> block is 'ALL', then _all_ requests for resources matched by the attached <path> tags. This is useful for allowing access to <path>/</path> and <path>index.html</path>, etc.

REFERER
If the <id> of a <header> block is 'REFERER', then the referer header is checked against an array of referer values specified by <referer> tags in the <header> block.

For example, using the sample conf file, requests for /images/background.gif coming from a page on http://www.rulez.com/, or http://www.picnicman.com/ will be accepted.

<referer> tags are treated as regexes ( like <path> tags ). The regex used is 'm|^$ar|' where $ar is the contents of the <referer> tags.




One little trick is to use 'https?://' at the start of the regex

to allow connections from either secure or insecure pages.

Note: If the referer is not matched, FORBIDDEN will not be automatically returned. In this case, the module continues to loop over <path> values, looking for a secondary match.

i.e. if a request for /images/button.gif does not come from a valid referer, but contains a X-Can-View-Secret-Stuff header, the image will be served.

This behavior is open to debate. Admittedly, it's a hack meant to overcome some problems with the original spec. If you don't like it, then don't use REFERER as an <id>. :)

<prefix></prefix>
You'll notice a commented-out <prefix> tag in the sample conf file. The prefix tag was added because some - *cough* - authenticating proxies prepend a string to header values defined in the authtencation database.

If the <prefix> tag is set, then all header checks will look for $PREFIX . $HEADER.

For example, if <prefix> is set to 'Rulez-', requests for /secret/index.html would require not a X-Can-View-Secret-Stuff header, but a Rulez-X-Can-View-Secret-Stuff header.

Sample Configuration File


 <header_access>

  <headers>

   <!-- <prefix>Rulez-</prefix> -->

   <header>

    <id>ALL</id>

    <path>/</path>

    <path>/index.html</path>

   </header>

   <header>

    <id>REFERER</id>

    <referer>https?://www.rulez.com/</referer>

    <referer>https?://ww.picnicman.com/</referer>

    <path>/images/.*</path>

    <path>/cgi/*.cgi</path>

   </header>

   <header>

    <id>X-Can-View-Secret-Stuff</id>

    <path>/secret/.*</path>

    <path>/secrets.html</path>

    <path>/images/.*</path>

   </header>

   <header>

    <id>X-Can-View-Super-Secret-Stuff</id>

    <path>/super-secret/.*</path>

    <path>/secrets.html</path>

   </header>

   <header>

    <id>X-Secret-User-ID</id>

    <path>/users/(.*?)/.*(</path>

   </header>

  </headers>

</header_access>

Configuration File DTD


 <?xml version="1.0" ?>

 <!DOCTYPE header_access [

  <!ELEMENT header_access ( headers+ ) >

  <!ELEMENT headers ( header+ ) >

  <!ELEMENT header ( id, path+, referer+ ) >

  <!ELEMENT id ( #PCDATA ) >

  <!ELEMENT path ( #PCDATA ) >

  <!ELEMENT referer ( #PCDATA ) >

 ]>


TESTING & DEBUGGING

If you set Apache's LogLevel to 'debug', the module will spit out a bunch of information regarding it's handling of the request.


 ErrorLog ./logs/error_log

 LogLevel debug

This is particularly useful if you're creating complicated <path> tag regexes, or if you really have no idea why a request is getting though. :)


LIMITATIONS & THE FUTURE

This module was originally written to cover the entire document root of a web server. And right now, that's all it does. This was a security-driven decision. The down-side is that the module is not VirtualHost or Directory friendly.

I wanted to release this first version before adding support for use in VirtualHosts and Directory blocks with separate conf files.

If interest - and time - allow, these will be the key features of the next release. ( Not to mention configuration of the default return policy and inversion of deny, allow rules, etc. )


RESOURCES

For an example of a commercial authentication proxy, see SecureComputing's PremierAccess product. http://securecomputing.com/. I don't necessarily recommend it; I just know it because I wrote this to work with it. :)


AUTHOR

Jeffrey O'Connell, Jr. <jeffo@rulez.com>


COPYRIGHT

Copyright (c) 2003 Jeffrey O'Connell, Jr., Rulez New Media

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

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy