Merge pull request #2765 in SNORT/snort3 from ~JRITTLE/snort3:doc_iec104_service_insp...

Squashed commit of the following:

commit f6e25e62a7ab803c360f168349da23a6f6609db0
Author: jrittle <jrittle@cisco.com>
Date:   Mon Feb 22 14:36:01 2021 -0500

    iec104: adding documentation for iec104 service inspector

diff --git a/doc/user/CMakeLists.txt b/doc/user/CMakeLists.txt
index 426827e13fe6f5caff8d421ae6fb3709d5382f90..4fa414db7fd40e83b28c1d0bbbd966388a4037fe 100644 (file)
--- a/doc/user/CMakeLists.txt
+++ b/doc/user/CMakeLists.txt
@@ -21,6 +21,7 @@ set (
     high_availability.txt
     http_inspect.txt
     http2_inspect.txt
+    iec104.txt
     overview.txt
     params.txt
     perf_monitor.txt

diff --git a/doc/user/features.txt b/doc/user/features.txt
index cd2d735a4a36baabe3fa8b8da4172793e4a2bd2a..b1879aedd9f07826ef4c808e9cf90c1fa660a4d2 100644 (file)
--- a/doc/user/features.txt
+++ b/doc/user/features.txt
@@ -73,6 +73,10 @@ include::http_inspect.txt[]
 
 include::http2_inspect.txt[]
 
+=== IEC104 Inspector
+
+include::iec104.txt[]
+
 === Performance Monitor
 
 include::perf_monitor.txt[]

diff --git a/doc/user/iec104.txt b/doc/user/iec104.txt
new file mode 100644 (file)
index 0000000..3e89224
--- /dev/null
+++ b/doc/user/iec104.txt
@@ -0,0 +1,118 @@
+iec104 inspector is a service inspector for the IEC 60870-5-104 protocol.
+
+==== Overview
+
+IEC 60870-5-104 (iec104) is a protocol distributed by the International 
+Electrotechnical Commission (IEC) that provides a standardized method of
+sending telecontrol messages between central stations and outstations, 
+typically running on TCP port 2404.
+
+It is used in combination with the companion specifications in the 
+IEC 60870-5 family, most notably IEC 60870-5-101, to provide reliable
+transport via TCP/IP. 
+
+An iec104 Application Protocol Data Unit (APDU) consists of one of three 
+Application Protocol Control Information (APCI) structures, each beginning
+with the start byte 0x68. In the case of an Information Transfer APCI, an
+Application Service Data Unit (ASDU) follows the APCI.
+
+The iec104 inspector decodes the iec104 protocol and provides rule options
+to access certain protocol fields and data content. This allows the user to 
+write rules for iec104 packets without decoding the protocol. 
+
+
+==== Configuration
+
+iec104 messages can be normalized to either combine a message spread across
+multiple frames, or to split apart multiple messages within one frame. No
+manual configuration is necessary to leverage this functionality.
+
+
+==== Quick Guide
+
+A typical iec104 configuration looks like this:
+
+   binder =
+   {  
+       { 
+           when = 
+           { 
+               proto = 'tcp', 
+               ports = '2404' 
+           }, 
+           use = 
+           { 
+               type = 'iec104' 
+           }, 
+       },
+   }
+   
+   iec104 = { }
+
+In this example, the tcp inspector is defined based on port. All
+configurations are default.
+
+Debug logging can be enabled with the following additional configuration:
+
+   trace =
+   {
+       modules = 
+       { 
+           iec104 = 
+           { 
+               all = 1 
+           } 
+       }
+   }
+
+
+==== Rule Options
+
+New rule options are supported by enabling the iec104 inspector:
+
+* iec104_apci_type
+* iec104_asdu_func
+
+===== iec104_apci_type
+
+Determining the APCI type of an iec104 message involves checking the state
+of one to two bits in the message's first control field octet. This can
+be completed with a `byte_test` in a plaintext rule, however it adds unnecessary
+complexity to the rule. Since most rules inspecting iec104 traffic will target 
+APCI Type I messages, this option was created to alleviate the need to manually 
+check the type and subsequently reduce the complexity of the rule. 
+
+This option takes one argument with three acceptable configurations.
+
+Examples:
+
+    iec104_apci_type:unnumbered_control_function;
+    iec104_apci_type:S;
+    iec104_apci_type:i;
+
+This option is used to verify that the message being processed is of the
+specified type. The argument passed to this rule option can be specified
+in one of three ways: the full type name, the lowercase type abbreviation,
+or the uppercase type abbreviation. 
+
+===== iec104_asdu_func
+
+Determining the ASDU function of an iec104 message can be completed with a
+plaintext rule that checks a single byte in the message, however it also 
+requires verifying that the message's APCI is of Type I. Since a rule writer
+may not necessarily know that this additional check must be made, this 
+option was created to simplify the process of verifying the function type
+and subsequently reduce the complexity of the rule.
+
+This option takes one argument with two acceptable configurations.
+
+Examples:
+
+    iec104_asdu_func:M_SP_NA_1;
+    iec104_asdu_func:m_ps_na_1;
+
+This option is used to verify that the message being processed is using
+the specified ASDU function. The argument passed to this rule option can 
+be specified in one of two ways: the uppercase function name, or the 
+lowercase function name.
+