Cleanup the API examples and add more docs.

apache2/api/README

@@ -1,39 +1,76 @@
+Custom ModSecurity Modules
+--------------------------
 
-This directory contains two examples how you can extend
+This directory contains three examples how you can extend
 ModSecurity without having to touch it directly, simply
 by creating custom Apache modules.
 
 NOTE: ModSecurity must be compiled with API support
       to use this feature (do not use -DNO_MODSEC_API).
 
-1)
+
+Building the Example Custom Modules
+-----------------------------------
+
+1) Example custom transformation function module
 
 Module mod_tfn_reverse.c creates a custom transformation
 function "reverse" that reverses the content it receives
 on input.
 
-To compile simply do:
+  # Compile as a normal user
+  apxs -ca mod_tfn_reverse.c
 
-  apxs -cia mod_tfn_reverse.c
+  # Install as superuser
+  sudo apxs -i mod_tfn_reverse.la
 
-2)
+
+2) Example custom operator module
 
 Module mod_op_strstr.c creates a custom operator "strstr"
 that implements fast matching using the Boyer-Moore-Horspool
 algorithm.
 
 Compiling this module is more involved because it requires
-access to ModSecurity structures. For example:
+access to ModSecurity structures.
 
-  apxs -I<MODSECURITY_SOURCE_CODE> -I/usr/include/libxml2 -cia mod_op_strstr.c
+  # Compile as a normal user
+  apxs -I<MODSECURITY_SOURCE_CODE> -I/usr/include/libxml2 \
+       -ca mod_op_strstr.c
 
-3)
+  # Install as superuser
+  sudo apxs -i mod_op_strstr.la
+
+
+3) Example custom target variable module
 
 Module mod_var_remote_addr_port.c creates a custom variable "REMOTE_ADDR_PORT"
 that combines the REMOTE_ADDR and REMOTE_PORT into a.b.c.d:port format.
 
 Compiling this module is more involved because it requires
-access to ModSecurity structures. For example:
+access to ModSecurity structures.
 
-  apxs -I<MODSECURITY_SOURCE_CODE> -cia mod_var_remote_addr_port.c
+  # Compile as a normal user
+  apxs -I<MODSECURITY_SOURCE_CODE> -I/usr/include/libxml2 \
+       -ca mod_var_remote_addr_port.c
+
+  # Install as superuser
+  sudo apxs -i mod_var_remote_addr_port.la
+
+
+Using the Modules
+-----------------
+
+Once the modules are built and installed, you load them like any other Apache module, but they must be loaded *after* the mod_security2.so module.
+
+  # Load ModSecurity
+  LoadModule security2_module modules/mod_security2.so
+
+  # Load ModSecurity custom modules
+  LoadModule tfn_reverse_module modules/mod_tfn_reverse.so
+  LoadModule op_strstr_module modules/mod_op_strstr.so
+  LoadModule var_remote_addr_port_module modules/mod_var_remote_addr_port.so
+
+  # All three custom var/op/tfn used
+  SecRule REMOTE_ADDR_PORT "@strstr 1.2.3.4:5678" "t:reverse"
 

apache2/api/mod_op_strstr.c

@@ -12,9 +12,6 @@
 #define ALPHABET_SIZE       256
 #define MAX_PATTERN_SIZE    64
 
-APR_DECLARE_OPTIONAL_FN(void, modsec_register_operator,
-    (const char *name, void *fn_init, void *fn_exec));
-
 static void initBoyerMooreHorspool(const char *pattern, int patlength,
     int *bm_badcharacter_array);
 
@@ -53,8 +50,6 @@ static int op_strstr_init(msre_rule *rule, char **error_msg) {
  * Operator execution entry point.
  */
 static int op_strstr_exec(modsec_rec *msr, msre_rule *rule, msre_var *var, char **error_msg) {
-    char *valuecopy = NULL;
-
     /* Here we need to inspect the contents of the supplied variable. */
 
     /* In a general case it is possible for the value

apache2/api/mod_tfn_reverse.c

@@ -7,8 +7,10 @@
 #include "ap_config.h"
 #include "apr_optional.h"
 
+/* Must be declared if modsecurity.h is not included */
 APR_DECLARE_OPTIONAL_FN(void, modsec_register_tfn, (const char *name, void *fn));
 
+
 /**
  * This function will be invoked by
  * ModSecurity to transform input.

apache2/api/mod_var_remote_addr_port.c

@@ -39,40 +39,6 @@ static int var_simple_generate(msre_var *var, apr_table_t *vartab, apr_pool_t *m
     return var_simple_generate_ex(var, vartab, mptmp, value, strlen(value));
 }
 
-/**
- * Validate that a target parameter is valid. We only need to take
- * care of the case when the parameter is a regular expression.
- */
-static char *var_generic_list_validate(msre_ruleset *ruleset, msre_var *var) {
-    /* It's OK if there's no parameter. */
-    if (var->param == NULL) return NULL;
-
-    /* Is it a regular expression? */
-    if ((strlen(var->param) > 2)&&(var->param[0] == '/')
-        &&(var->param[strlen(var->param) - 1] == '/'))
-    { /* Regex. */
-        msc_regex_t *regex = NULL;
-        const char *errptr = NULL;
-        const char *pattern = NULL;
-        int erroffset;
-
-        pattern = apr_pstrmemdup(ruleset->mp, var->param + 1, strlen(var->param + 1) - 1);
-        if (pattern == NULL) return FATAL_ERROR;
-
-        regex = msc_pregcomp(ruleset->mp, pattern, PCRE_DOTALL | PCRE_CASELESS | PCRE_DOLLAR_ENDONLY, &errptr, &erroffset);
-        if (regex == NULL) {
-            return apr_psprintf(ruleset->mp, "Error compiling pattern (pos %i): %s",
-                erroffset, errptr);
-        }
-
-        /* Store the compiled regex for later. */
-        var->param_data = regex;
-    }
-
-    /* Simple string */
-    return NULL;
-}
-
 
 /* -- Module specific code -- */
 
@@ -83,7 +49,6 @@ static int var_remote_addr_port_generate(modsec_rec *msr, msre_var *var, msre_ru
     apr_table_t *vartab, apr_pool_t *mptmp)
 {
     const char *value = apr_psprintf(mptmp, "%s:%d", msr->remote_addr, msr->remote_port);
-    msre_var *rvar = NULL;
 
     return var_simple_generate(var, vartab, mptmp, value);
 }