view release on metacpan or  search on metacpan

Headers.pm  view on Meta::CPAN

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 B<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.

=head2 Other Options

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

=over 3

=item B<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.

=back

=over 3

=item B<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.

B<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>. :)

=back

=over 3

=item B<<prefix>>B<</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.

=back

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