aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorJoão Valverde <j@v6e.pt>2022-10-25 04:20:18 +0100
committerJoão Valverde <j@v6e.pt>2022-10-31 21:02:39 +0000
commit0853ddd1cb9c94e83bba5ac2608c8de0dc94dae4 (patch)
tree9f571c07583e4a4527647471a5ca43411bd39fc5 /doc
parent31a0147daa278cfed749c0cbfc6db87bb5cfc3c9 (diff)
dfilter: Add support for raw (bytes) addressing mode
This adds new syntax to read a field from the tree as bytes, instead of the actual type. This is a useful extension for example to match matformed strings that contain unicode replacement characters. In this case it is not possible to match the raw value of the malformed string field. This extension fills this need and is generic enough that it should be useful in many other situations. The syntax used is to prefix the field name with "@". The following artificial example tests if the HTTP user agent contains a particular invalid UTF-8 sequence: @http.user_agent == "Mozill\xAA" Where simply using "http.user_agent" won't work because the invalid byte sequence will have been replaced with U+FFFD. Considering the following programs: $ dftest '_ws.ftypes.string == "ABC"' Filter: _ws.ftypes.string == "ABC" Syntax tree: 0 TEST_ANY_EQ: 1 FIELD(_ws.ftypes.string <FT_STRING>) 1 FVALUE("ABC" <FT_STRING>) Instructions: 00000 READ_TREE _ws.ftypes.string <FT_STRING> -> reg#0 00001 IF_FALSE_GOTO 3 00002 ANY_EQ reg#0 == "ABC" <FT_STRING> 00003 RETURN $ dftest '@_ws.ftypes.string == "ABC"' Filter: @_ws.ftypes.string == "ABC" Syntax tree: 0 TEST_ANY_EQ: 1 FIELD(_ws.ftypes.string <RAW>) 1 FVALUE(41:42:43 <FT_BYTES>) Instructions: 00000 READ_TREE @_ws.ftypes.string <FT_BYTES> -> reg#0 00001 IF_FALSE_GOTO 3 00002 ANY_EQ reg#0 == 41:42:43 <FT_BYTES> 00003 RETURN In the second case the field has a "raw" type, that equates directly to FT_BYTES, and the field value is read from the protocol raw data.
Diffstat (limited to 'doc')
-rw-r--r--doc/wireshark-filter.adoc20
1 files changed, 20 insertions, 0 deletions
diff --git a/doc/wireshark-filter.adoc b/doc/wireshark-filter.adoc
index 67fdf36c9c..378b95ad84 100644
--- a/doc/wireshark-filter.adoc
+++ b/doc/wireshark-filter.adoc
@@ -388,6 +388,26 @@ For more complicated ranges the same syntax used with slices is valid:
means layers number 2, 3 or 4 inclusive. The hash symbol is required to
distinguish a layer range from a slice.
+== The at operator
+
+By prefixing the field name with an at sign (@) the comparison is done against
+the raw packet data for the field.
+
+A character string must be decoded from a source encoding during dissection.
+If there are decoding errors the resulting string will usually contain
+replacement characters:
+
+[subs="replacements"]
+----
+browser.comment == "string is &#xFFFD;&#xFFFD;&#xFFFD;&#xFFFD;"
+----
+
+The at operator allows testing the raw undecoded data:
+
+ @browser.comment == 73:74:72:69:6e:67:20:69:73:20:aa:aa:aa:aa
+
+The syntactical rules for a bytes field type apply to the second example.
+
=== The membership operator
A field may be checked for matches against a set of values simply with the