From 4b0f20eed87e8b1542f991e06f4868b05f36dd64 Mon Sep 17 00:00:00 2001 From: Junfeng Wang Date: Fri, 6 Sep 2019 07:10:24 -0400 Subject: add source code Change-Id: I70aa9a0e05bbb5f38b2d6fb74c9d21db356dc889 Signed-off-by: Junfeng Wang --- src/dpi_plugin_doc.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 src/dpi_plugin_doc.md (limited to 'src/dpi_plugin_doc.md') 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 ] [dst-ip ] " + "[src-port ] [dst-port ] " + "[protocol ] [vrf-id ]", + + "dpi tcp reass flow_id " + "[ ]", + + "dpi set flow-offload hw rx [del]", + + "dpi set ip4 flow-bypass [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. + + + + -- cgit 1.2.3-korg