|
Configuration | Top |
To enforce your Security Policy, mod_parmguard is configured through:
Apache Directives
 |
Directive Name | Description |
 |
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:
-
the "global" section that define the "global" parameters.
They are defined with the following syntax:
<global name="parm_name" value="parm_value"/>
-
the "usertype" section where the Administrator can define new data types to optimize the
parameters constraints
-
the Constraints section where the Administrator defines the Scripts Parameters Constraints.
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 Type | Attribute | Description |
 |
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 Name | Description |
 |
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
|
 |
|
 |