Documenting base64_decode and base64_content

base64 doc changes based on #4027 pull feedback

diff --git a/doc/userguide/rules/base64-keywords.rst b/doc/userguide/rules/base64-keywords.rst
new file mode 100644 (file)
index 0000000..178fbe7
--- /dev/null
+++ b/doc/userguide/rules/base64-keywords.rst
@@ -0,0 +1,51 @@
+Base64 keywords
+===============
+
+Suricata supports decoding base64 encoded data from buffers and matching on the decoded data.
+
+This is achieved by using two keywords, ``base64_decode`` and ``base64_data``. Both keywords must be used in order to generate an alert.
+
+base64_decode
+-------------
+
+Decodes base64_data from a buffer and makes it available for the base64_data function.
+
+Syntax::
+
+    base64_decode:bytes <value>, offset <value>, relative;
+
+The ``bytes`` option specifies how many bytes Suricata should decode and make available for base64_data.
+The decoding will stop at the end of the buffer.
+
+The ``offset`` option specifies how many bytes Suricata should skip before decoding.
+Bytes are skipped relative to the start of the payload buffer if the ``relative`` is not set.
+
+The ``relative`` option makes the decoding start relative to the previous content match. Default behavior is to start at the beginning of the buffer.
+This option makes ``offset`` skip bytes relative to the previous match.
+
+.. note:: Regarding ``relative`` and ``base64_decode``:
+
+    The content match that you want to decode relative to must be the first match in the stream.
+
+base64_data
+-----------
+
+base64_data is a ``sticky buffer``.
+
+Enables content matching on the data previously decoded by base64_decode.
+
+Example
+-------
+
+Here is an example of a rule matching on the base64 encoded string "test" that is found inside the http_uri buffer.
+
+It starts decoding relative to the known string "somestring" with the known offset of 1. This must be the first occurrence of "somestring" in the buffer.
+
+Example::
+
+    Buffer content:
+    http_uri = "GET /en/somestring&dGVzdAo=&not_base64"
+
+    Rule:
+    alert http any any -> any any (msg:"Example"; content:"somestring"; base64_decode:bytes 8, offset 1, relative; \
+        http_uri; base64_content; content:"test"; sid:10001; rev:1;)

diff --git a/doc/userguide/rules/index.rst b/doc/userguide/rules/index.rst
index c81440ef94cda9e6de763b2244bcdfb957ee63c4..f11c9e9ae93dee6d391ecdeb773f2312d50cb457 100644 (file)
--- a/doc/userguide/rules/index.rst
+++ b/doc/userguide/rules/index.rst
@@ -23,6 +23,7 @@ Suricata Rules
    ftp-keywords
    kerberos-keywords
    snmp-keywords
+   base64-keywords
    app-layer
    xbits
    thresholding