From: Vinjar Hillestad <vhillestad@gmail.com>
Date: Fri, 21 Jun 2019 14:09:28 +0000 (+0000)
Subject: Documenting base64_decode and base64_content
X-Git-Tag: suricata-5.0.0-rc1~154
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4c18fee3c69ac04629f095604473843eaea2c98e;p=thirdparty%2Fsuricata.git

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
index 0000000000..178fbe74d1
--- /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 c81440ef94..f11c9e9ae9 100644
--- 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