Update documentation to emphasize the importance of REQBODY_PROCESSOR_ERROR handling.

doc/modsecurity2-apache-reference.xml

@@ -24,7 +24,7 @@
     reach web applications. It provides protection from a range of attacks
     against web applications and allows for HTTP traffic monitoring and
     real-time analysis with little or no changes to existing
-    infrastructure.</para>
+    infrastructure._err</para>
 
     <section>
       <title>HTTP Traffic Logging</title>
@@ -2090,11 +2090,26 @@ SecRule XML "@validateDTD /opt/apache-frontend/conf/xml.dtd"</programlisting>
       <title><literal
       moreinfo="none">REQBODY_PROCESSOR_ERROR</literal></title>
 
-      <para>0 (no error) or 1 (error). If you want to stop processing on an
-      error you must have an explicit rule in phase 2 to do so.
-      Example:</para>
+      <para>Possible values are 0 (no error) or 1 (error). This variable will
+      be set by request body processors (typically the
+      <classname>multipart/request-data</classname> parser or the XML parser)
+      when they fail to properly parse a request payload.</para>
+
+      <para>Example:</para>
 
       <programlisting format="linespecific">SecRule<emphasis role="bold"> REQBODY_PROCESSOR_ERROR</emphasis> "@eq 1" deny,phase:2</programlisting>
+
+      <note>
+        <para>Your policies <emphasis>must</emphasis> have a rule to check
+        REQBODY_PROCESSOR_ERROR at the beginning of phase 2. Failure to do so
+        will leave the door open for impedance mismatch attacks. It is
+        possible, for example, that a payload that cannot be parsed by
+        ModSecurity can be successfully parsed by more tolerant parser
+        operating in the application. If your policy dictates blocking then
+        you should reject the request if error is detected. When operating in
+        detection-only mode your rule should alert with high severity when
+        request body processing fails.</para>
+      </note>
     </section>
 
     <section>
@@ -4175,4 +4190,4 @@ SecRule XML "<emphasis role="bold">@validateSchema /path/to/apache2/conf/xml.xsd
       </itemizedlist>
     </section>
   </section>
-</article>
+</article>