Add initial code

The inital code is from this patch:
https://gerrit.fd.io/r/#/c/vpp/+/16580/
It is contributed by Intel and Travelping.
Jerome Tollet, Ed Warnicke, Dave Barach, Damjan Marion from Cisco
and other guys have gave lots of useful comments on it.

The initial code is used for identifying layer-7 applications for HTTPS/TLS traffic

- Below is the brief design info.

- Provides a default APPID database for scan.

- Dynamically create new SW mapping has been supported now.

- Support TCP connection state tracking.

- Support TCP segments reassembly on the fly, which handles out-of-order tcp segments and overlapping segments.
  It means that we do not need to reassembly segments first, then dedect applicaion,
  and then fragment segments again, which helps to improve performance.

- Support Hyperscan Stream mode, which can scan rules straddling into different tcp segments.
  It means that if there is a rule "abcde", then "abc" can be in packet 1,
  and "de" can be in packet 2.

- Configure static dpi flows with 5-tuple and VRF-aware, and supports both ipv4 and ipv6 flows.
  These flows will first try to HW offload to NIC based on DPDK rte_flow mechanism
  and vpp/vnet/flow infrastructure.
  If failed, then will create static SW flow mappings.
  Each flow configuration will create two HW or SW flow mappings, i.e. for forward and reverse traffic.
  And both flow mappings will be mapped to the same dpi flow.
  SW entry aging out mechanism will be added later.
        "dpi flow [add | del]  "
        "[src-ip <ip-addr>] [dst-ip <ip-addr>] "
        "[src-port <port>] [dst-port <port>] "
        "[protocol <protocol>] [vrf-id <nn>]",
        "dpi set flow-offload hw <interface-name> rx <flow-id> [del]",
        "dpi set ip4 flow-bypass <interface> [del]",

- When HW flow offload matched, packets will be redirected to DPI plugin with dpi flow_id in packet descriptor.
   If not, packets will be bypassed to DPI plugin from ip-input, and then lookup SW flow mapping table.

- Then will detect layer 7 applications.
   This first patch only detect sub protocls within SSL/TLS.
   1). Identify SSL/TLS certificate message and subsequent segments.
   2). Scan SSL/TLS certificate message through hyperscan, and get application id if matched.
   3). If maximum packets for this flow are checked and not found matched application, the detection will end up.

Ticket:
Type: feature

Signed-off-by: Hongjun Ni <hongjun.ni@intel.com>
Signed-off-by: Andreas Schultz <andreas.schultz@travelping.com>
Signed-off-by: Mathias Gumz <mathias.gumz@travelping.com>
Change-Id: I839cc70ddc80ea594d22a04e2cabf92a7b9c74e7

1 files changed, 107 insertions, 0 deletions

diff --git a/src/dpi_plugin_doc.md b/src/dpi_plugin_doc.md
new file mode 100644
index 0000000..fc069c0
--- /dev/null
+++ b/src/dpi_plugin_doc.md
@@ -0,0 +1,107 @@
+# DPI plugin for VPP    {#dpi_plugin_doc}
+
+## Overview
+
+DPI plugin can identify and analyze the traffic running on networks in real time.
+It can be used on many use cases, such as Web Application Firewall,
+Policy based routing, Intrusion Detection System, Intrusion Prevention System, etc.
+
+The main use case for current approach would be identification of cooperating traffic 
+for an established TCP connection (i.e. traffic that is not intentionally disguised) 
+to support application-based QoS.
+
+
+## Design
+
+The DPI plugin leverage Hyperscan to perform regex matching.
+
+Hyperscan is a high-performance multiple regex matching library.
+Please refer to below for details:
+http://intel.github.io/dpi/dev-reference/
+
+Below is the brief design:
+
+1. Provides a default APPID database for detection.
+
+2. Support TCP connection state tracking.
+
+3. Support TCP segments reassembly on the fly, which handles out-of-order tcp segments and overlapping segments.
+   It means that we do not need to reassembly segments first, then dedect applicaion, 
+   and then fragment segments again, which helps to improve performance.
+
+4. Support Hyperscan Stream mode, which can detect one rule straddling into some tcp segments.
+   It means that if there is a rule "abcde", then "abc" can be in packet 1, 
+   and "de" can be in packet 2.
+
+5. Configure static dpi flows with 5-tuple and VRF-aware, and supports both ipv4 and ipv6 flows.
+   These flows will first try to HW offload to NIC based on DPDK rte_flow mechanism
+   and vpp/vnet/flow infrastructure.
+   If failed, then will create static SW flow mappings.
+   Each flow configuration will create two HW or SW flow mappings, i.e. for forward and reverse traffic.
+   And both flow mappings will be mapped to the same dpi flow.
+   Dynamically create new SW mapping and aging out mechanism will be added later.
+
+        "dpi flow [add | del]  "
+        "[src-ip <ip-addr>] [dst-ip <ip-addr>] "
+        "[src-port <port>] [dst-port <port>] "
+        "[protocol <protocol>] [vrf-id <nn>]",
+        
+        "dpi tcp reass flow_id <nn> <enable|disable> "
+        "[ <client | server | both> ]",
+
+        "dpi set flow-offload hw <interface-name> rx <flow-id> [del]",
+
+        "dpi set ip4 flow-bypass <interface> [del]",
+
+6. When HW flow offload matched, packets will be redirected to DPI plugin with dpi flow_id in packet descriptor.
+   If not, packets will be bypassed to DPI plugin from ip-input, and then lookup SW flow mapping table.
+
+7. Then will detect layer 7 applications.
+   This first patch only detect sub protocls within SSL/TLS.
+   1). Identify SSL/TLS certificate message and subsequent segments.
+   2). Scan SSL/TLS certificate message through hyperscan, and get application id if matched.
+   3). If maximum packets for this flow are checked and not found matched application, the detection will end up.
+
+
+## Hyperscan Installation
+
+Hyperscan can be installed from packages directly on below OS:
+  Ubuntu 16.04.03
+  Ubuntu 18.04 and later version
+  Fedora 27 and later version
+  openSUSE rolling-release Tumbleweed and later version
+
+If you cannot install Hyperscan from packages directly,
+you can build and install it from the source code.
+
+Below are steps to build and install Hyperscan on Ubuntu 16.04:
+1).Install binary prerequisites
+apt-get install cmake ragel
+apt-get install libboost-dev
+apt-get install python-dev libbz2-dev
+
+2).Download Hyperscan sources
+wget https://github.com/intel/hyperscan/archive/v5.0.0.tar.gz
+tar -xf v5.0.0.tar.gz
+
+3).Download boost headers
+wget https://dl.bintray.com/boostorg/release/1.68.0/source/boost_1_68_0.tar.gz
+tar -xf boost_1_68_0.tar.gz
+cp -r boost_1_68_0/boost hyperscan-5.0.0/include
+
+4).Build and install Hyperscan shared library.
+   Just follow the instruction from here. Compilation can take a long time.
+cd hyperscan-5.0.0
+mkdir build
+cd build
+cmake -DBUILD_SHARED_LIBS=true ..
+make
+make install
+
+## Multi-Thread Support
+Since generated bytecode database is read only, you can run multiple cores
+to utilize the byte database to scale.
+
+
+
+