Configuration

 Top

To enforce your Security Policy, mod_parmguard is configured through:

 Apache Directives

Directive NameDescription
ParmguardConfFile
(Server and Location Level)
Value: /path/to/XML/Configuration/File

Gives the name of the XML Configuration File that applies from here.

If this directive appears at Server Level, the specified Configuration File is valid for all the requests. It can be considered as the "default" Configuration.

If this directive appears at Location Level, it overrides the global Configuration File.
ParmguardPeriodicReload
(Server Level)
Apache 2.x only
Value: number_of_seconds

If this parameters is not equal to 0, it allows mod_parmguard to periodically reload the XML Configuration Files that have been modified.
There is no need to restart the server anymore !
ParmguardTrace
(Server Level)
Value: debug

Sets the module in "debug" mode. Debug messages will be added to stdout at init time and then in the Apache error log.
ParmguardEngine
(Location Level)
Value: on|off

Activate or desactivate the module for the current Location block.

Configuration Sample

...
LoadModule parmguard_module modules/mod_parmguard.so
# unuseful for Apache 2.x:
AddModule mod_parmguard.c
...
#ParmguardTrace debug
ParmguardConfFile /usr/local/apache/conf/mainconf.xml
...
<Location /appl1>
    ParmguardEngine on
</Location>

<Location /appl2>
    ParmguardEngine on
    ParmguardConfFile /usr/local/apache/conf/appl2conf.xml
</Location>


 XML Configuration File

Let's learn by examples !

Imagine you wrote the following HTML Form:

<HTML>
<BODY>
<H1>Example form</H1>

<FORM ACTION="validate.php" METHOD=GET>
  Name: <INPUT TYPE=TEXT NAME="name" SIZE=10>
  Age: <INPUT TYPE=TEXT NAME="age" SIZE=2>
  Civility:
  <SELECT name="civ">
    <OPTION value="ms">Ms</OPTION>
    <OPTION value="mrs">Mrs</OPTION>
    <OPTION value="mr">Mr</OPTION>
  </SELECT>
  <INPUT TYPE=SUBMIT VALUE="Run the script!">
</FORM>

</BODY>
</HTML>

This Form sends its input to the validate.php script.

The script must work with consistent values. Checking can be made at different stages:

  • at client-side using JavaScript (not sufficient)
  • by the script itself (depends on the developper skill)
  • by mod_parmguard (strict enforcing !)

As a paranoïd (a normal !) Administrator, here is a possible Security Policy for this script:

  • the name parameter MUST BE a STRING with a maximum length of 10 characters taken from the standard US-English alphabet
  • the age parameter MUST BE an INTEGER between 10 and 99
  • the civ parameter MUST BE one of the following values: ms, mrs and mr
  • requests that DO NOT MATCH these criteria are logged and rejected with a 404 HTTP Error code

This Policy can be enforced by creating the following XML Configuration File:

<xml version="1.0"?>>
<!DOCTYPE parmguard SYSTEM "mod_parmguard.dtd"/>
<parmguard>

  <!-- define the HTTP Error Code when Requests are rejected: -->
  <global name="http_error_code" value="404"/>

  <!-- define the constraints for "validate.php": -->
  <url>
    <match>validate.php</match>

    <parm name="name">
      <type name="string"/>
      <attr name="maxlen" value="10"/>
      <attr name="charclass" value="^[a-zA-Z]+$"/>
    </parm>

    <parm name="age">
      <type name="integer"/>
      <attr name="minval" value="10"/>
      <attr name="maxval" value="99"/>
    </parm>

    <parm name="civ">
      <type name="enum"/>
      <attr name="multiple" value="0"/>
      <attr name="option" value="mrs"/>
      <attr name="option" value="ms"/>
      <attr name="option" value="mr"/>
    </parm>
  </url>
</parmguard>

As you can see if you read the associated DTD (mod_parmguard.dtd), the XML Configuration file is made up of 3 sections:

 Basic Types

Parameters Values are "typed". By default, mod_parmguard language defines a small set of Basic Types.

Each Type owns its attributes. By giving a Type, Attribute Values, you define Parameters Constraints !

List of Basic Types:

Basic TypeAttributeDescription
integer minval Gives the minimum signed value for the Parameter
maxval Gives the maximum signed value for the Parameter
decimal minval Gives the minimum signed value for the Parameter
maxval Gives the maximum signed value for the Parameter
string minlen Gives the minimum length for the Parameter
maxlen Gives the maximum length for the Parameter
charclass Regular expression that must match the Parameter value
enum multiple Indicates whether or not this parameter can have multiple values
(1=yes, 0=no)
option Gives an authorized value for the Parameterr


 User Types

Usually Web Applications are made up of Scripts that handle many times the same "kind" of Parameters. For example, an e-commerce Site will undoubtedly use Parameters that carry pricing information.

So if you need to constraint a Parameter named "price", that represents a real price, you can define the following Constraint:

<parm name="price">
  <type name="integer"/>
  <attr name="minval" value="0"/>
  <attr name="maxval" value="999999"/>
</parm>

But you will need to repeat this block of directive for each "price" Parameter. It could be much more efficient to define your own type and then to reference them in the Constraint. The previous sample then becomes:

<usertype name="price">
  <type name="integer"/>
  <attr name="minval" value="0"/>
  <attr name="maxval" value="999999"/>
</usertype>
...
<!-- usertype names and parm names do not collide ! -->
<parm name="price">
  <type name="price"/>
</parm>
...
<parm name="anotherprice">
  <type name="price"/>
</parm>

 Constraints Definition

Constraints are defined inside a <url> block using the following syntax:

<url>
  <match>Regular Expression</match>
  ...Script Parameters Constraints
</url>

Each URL that matches the Regular Expression specified in the <match> tag must be compliant with the following Constraints.
Script Parameters Constraints are defined by a list of <parm> block:

<parm name="parm_name">
  <type name="basic_type "/>
  <attr name="attribute_name " value="attr_value "/>
  ...
</parm>

or:

<parm name="parm_name">
  <type name="user_type "/>
</parm>

 XML Configuration File Syntax

List and Semantics of "global" parameters:

Parameter NameDescription
http_error_code Value: integer (default: 500)

Gives the HTTP Error Code returned to the Client for rejected Requests.
catch_all_pass Value: boolean (default: 0)

Indicates if Requests that do not match any filter must be accepted (value=1) or rejected (value=1). This parameter is supported but obsolete. Use undefined_url_action instead
catch_all_log Value: boolean (default: 1)

Indicates if Requests that do not match any filter must be logged (value=1) or not (value=1). This parameter is supported but obsolete. Use undefined_url_action instead
undefined_url_action Value: (accept|reject)[,log][,setenv] (default: reject,log)

Specifies the engine behaviour for Requests that do not match any filter:
one of "accept" or "reject" keywords must be given, "log" and "setenv" are optional:
  • accept: the Request is accepted so it is forwarded to the CGI Script
  • reject: the Request is rejected, the "http_error_code" value is returned to the client
  • log: the Request is logged
  • setenv: if the Request is "accepted", the PARMGUARD_URL_NOT_CHECKED environment variable is set and can be tested by the CGI Script
undefined_parm_action Value: (accept|reject)[,log][,setenv] (default: reject,log)

Specifies the engine behaviour for Script Parameters that are not constrained (not described in the XML Configuration File):
one of "accept" or "reject" keywords must be given, "log" and "setenv" are optional:
  • accept: the Request is accepted so it is forwarded to the CGI Script
  • reject: the Request is rejected, the "http_error_code" value is returned to the client
  • log: an error message complaining about this parameter is logged
  • setenv: if the Request is "accepted", two environment variables are set and can be tested by the CGI Script:
    PARMGUARD_PARM_NOT_CHECKED value is a comma separated list of the "undefined" Parameters
    PARMGUARD_PARM_NOT_CHECKED_parmname  is set with the illegal value
illegal_parm_action Value: (accept|reject)[,log][,setenv] (default: reject,log)

Specifies the engine behaviour for Script Parameters that failed their Constraints:
one of "accept" or "reject" keywords must be given, "log" and "setenv" are optional:
  • accept: the Request is accepted so it is forwarded to the CGI Script
  • reject: the Request is rejected, the "http_error_code" value is returned to the client
  • log: an error message complaining about this parameter is logged
  • setenv: if the Request is "accepted", two environment variables are set and can be tested by the CGI Script:
    PARMGUARD_PARM_ILLEGAL value is a comma separated list of the "illegal" Parameters
    PARMGUARD_PARM_ILLEGAL_parmname  is set to with the illegal value

www.trickytools.com