doc/userguide: document dns.query.name, dns.answer.name

With some other minor cleanups in the DNS keyword section.

doc/userguide/rules/dns-keywords.rst

@@ -1,10 +1,27 @@
 DNS Keywords
 ============
 
-There are some more content modifiers (If you are unfamiliar with
+Suricata supports sticky buffers as well as keywords for efficiently
-content modifiers, please visit the page :doc:`payload-keywords` These
+matching on specific fields in DNS messages.
-ones make sure the signature checks a specific part of the
+
-network-traffic.
+Note that sticky buffers are expected to be followed by one or more
+:doc:`payload-keywords`.
+
+dns.answer.name
+---------------
+
+``dns.answer.name`` is a sticky buffer that is used to look at the
+name field in DNS answer resource records.
+
+``dns.answer.name`` will look at both requests and responses, so
+``flow`` is recommended to confine to a specific direction.
+
+The buffer being matched on contains the complete re-assembled
+resource name, for example "www.suricata.io".
+
+``dns.answer.name`` supports :doc:`multi-buffer-matching`.
+
+``dns.answer.name`` was introduced in Suricata 8.0.0.
 
 dns.opcode
 ----------
@@ -32,20 +49,26 @@ Match on DNS requests where the **opcode** is NOT 0::
 dns.query
 ---------
 
-With **dns.query** the DNS request queries are inspected. The dns.query
+``dns.query`` is a sticky buffer that is used to inspect DNS query
-keyword works a bit different from the normal content modifiers. When
+names in DNS request messages. Example::
-used in a rule all contents following it are affected by it.  Example:
 
-  alert dns any any -> any any (msg:"Test dns.query option";
+  alert dns any any -> any any (msg:"Test dns.query option"; dns.query; content:"google"; nocase; sid:1;)
-  dns.query; content:"google"; nocase; sid:1;)
+
+Being a sticky buffer, payload keywords such as content are to be used after ``dns.query``:
 
 .. image:: dns-keywords/dns_query.png
 
-The **dns.query** keyword affects all following contents, until pkt_data
+The ``dns.query`` keyword affects all following contents, until
-is used or it reaches the end of the rule.
+pkt_data is used or it reaches the end of the rule.
 
 .. note:: **dns.query** is equivalent to the older **dns_query**.
 
+.. note:: **dns.query** will only match on DNS request messages, to
+          also match on DNS response message, see
+          `dns.query.name`_.
+
+``dns.query.name`` supports :doc:`multi-buffer-matching`.
+
 Normalized Buffer
 ~~~~~~~~~~~~~~~~~
 
@@ -68,7 +91,19 @@ DNS query on the wire (snippet)::
 
     mail.google.com
 
-Multiple Buffer Matching
+dns.query.name
-~~~~~~~~~~~~~~~~~~~~~~~~
+---------------
+
+``dns.query.name`` is a sticky buffer that is used to look at the name
+field in DNS query (question) resource records. It is nearly identical
+to ``dns.query`` but supports both DNS requests and responses.
+
+``dns.query.name`` will look at both requests and responses, so
+``flow`` is recommended to confine to a specific direction.
+
+The buffer being matched on contains the complete re-assembled
+resource name, for example "www.suricata.io".
+
+``dns.query.name`` supports :doc:`multi-buffer-matching`.
 
-``dns.query`` supports multiple buffer matching, see :doc:`multi-buffer-matching`.
+``dns.query.name`` was introduced in Suricata 8.0.0.