X-Git-Url: http://git.droids-corp.org/?a=blobdiff_plain;f=doc%2Fguides%2Fsample_app_ug%2Fipsec_secgw.rst;h=5ec9b1ed7062899963d1bda0be3e170f7b056fb2;hb=957394f726589f7e51362e58936e513de3cccb19;hp=d6cfdbf7aaea348914439ae8a6ff7ef73a01f329;hpb=7cacb05655397c0c50bcba89eb836d417bc78b69;p=dpdk.git diff --git a/doc/guides/sample_app_ug/ipsec_secgw.rst b/doc/guides/sample_app_ug/ipsec_secgw.rst index d6cfdbf7aa..5ec9b1ed70 100644 --- a/doc/guides/sample_app_ug/ipsec_secgw.rst +++ b/doc/guides/sample_app_ug/ipsec_secgw.rst @@ -1,32 +1,5 @@ -.. BSD LICENSE - Copyright(c) 2016-2017 Intel Corporation. All rights reserved. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions - are met: - - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - * Neither the name of Intel Corporation nor the names of its - contributors may be used to endorse or promote products derived - from this software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS - "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR - A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT - OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, - SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, - DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY - THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT - (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE - OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2016-2017 Intel Corporation. IPsec Security Gateway Sample Application ========================================= @@ -52,8 +25,8 @@ The application classifies the ports as *Protected* and *Unprotected*. Thus, traffic received on an Unprotected or Protected port is consider Inbound or Outbound respectively. -The application also supports complete IPSec protocol offload to hardware -(Look aside crypto accelarator or using ethernet device). It also support +The application also supports complete IPsec protocol offload to hardware +(Look aside crypto accelerator or using ethernet device). It also support inline ipsec processing by the supported ethernet device during transmission. These modes can be selected during the SA creation configuration. @@ -61,6 +34,12 @@ In case of complete protocol offload, the processing of headers(ESP and outer IP header) is done by the hardware and the application does not need to add/remove them during outbound/inbound processing. +For inline offloaded outbound traffic, the application will not do the LPM +lookup for routing, as the port on which the packet has to be forwarded will be +part of the SA. Security parameters will be configured on that port only, and +sending the packet on other ports could result in unencrypted packets being +sent out. + The Path for IPsec Inbound traffic is: * Read packets from the port. @@ -88,16 +67,15 @@ Constraints * No IPv6 options headers. * No AH mode. -* Supported algorithms: AES-CBC, AES-CTR, AES-GCM, HMAC-SHA1 and NULL. +* Supported algorithms: AES-CBC, AES-CTR, AES-GCM, 3DES-CBC, HMAC-SHA1 and NULL. * Each SA must be handle by a unique lcore (*1 RX queue per port*). -* No chained mbufs. Compiling the Application ------------------------- To compile the sample application see :doc:`compiling`. -The application is located in the ``rpsec-secgw`` sub-directory. +The application is located in the ``ipsec-secgw`` sub-directory. #. [Optional] Build the application for debugging: This option adds some extra flags, disables compiler optimizations and @@ -114,8 +92,14 @@ The application has a number of command line options:: ./build/ipsec-secgw [EAL options] -- -p PORTMASK -P -u PORTMASK -j FRAMESIZE + -l -w REPLAY_WINOW_SIZE -e -a + -c SAD_CACHE_SIZE --config (port,queue,lcore)[,(port,queue,lcore] --single-sa SAIDX + --rxoffload MASK + --txoffload MASK + --mtu MTU + --reassemble NUM -f CONFIG_FILE_PATH Where: @@ -129,9 +113,30 @@ Where: * ``-u PORTMASK``: hexadecimal bitmask of unprotected ports -* ``-j FRAMESIZE``: *optional*. Enables jumbo frames with the maximum size - specified as FRAMESIZE. If an invalid value is provided as FRAMESIZE - then the default value 9000 is used. +* ``-j FRAMESIZE``: *optional*. data buffer size (in bytes), + in other words maximum data size for one segment. + Packets with length bigger then FRAMESIZE still can be received, + but will be segmented. + Default value: RTE_MBUF_DEFAULT_BUF_SIZE (2176) + Minimum value: RTE_MBUF_DEFAULT_BUF_SIZE (2176) + Maximum value: UINT16_MAX (65535). + +* ``-l``: enables code-path that uses librte_ipsec. + +* ``-w REPLAY_WINOW_SIZE``: specifies the IPsec sequence number replay window + size for each Security Association (available only with librte_ipsec + code path). + +* ``-e``: enables Security Association extended sequence number processing + (available only with librte_ipsec code path). + +* ``-a``: enables Security Association sequence number atomic behavior + (available only with librte_ipsec code path). + +* ``-c``: specifies the SAD cache size. Stores the most recent SA in a per + lcore cache. Cache represents flat array containing SA's indexed by SPI. + Zero value disables cache. + Default value: 128. * ``--config (port,queue,lcore)[,(port,queue,lcore)]``: determines which queues from which ports are mapped to which cores. @@ -140,6 +145,32 @@ Where: on both Inbound and Outbound. This option is meant for debugging/performance purposes. +* ``--rxoffload MASK``: RX HW offload capabilities to enable/use on this port + (bitmask of DEV_RX_OFFLOAD_* values). It is an optional parameter and + allows user to disable some of the RX HW offload capabilities. + By default all HW RX offloads are enabled. + +* ``--txoffload MASK``: TX HW offload capabilities to enable/use on this port + (bitmask of DEV_TX_OFFLOAD_* values). It is an optional parameter and + allows user to disable some of the TX HW offload capabilities. + By default all HW TX offloads are enabled. + +* ``--mtu MTU``: MTU value (in bytes) on all attached ethernet ports. + Outgoing packets with length bigger then MTU will be fragmented. + Incoming packets with length bigger then MTU will be discarded. + Default value: 1500. + +* ``--frag-ttl FRAG_TTL_NS``: fragment lifetime (in nanoseconds). + If packet is not reassembled within this time, received fragments + will be discarded. Fragment lifetime should be decreased when + there is a high fragmented traffic loss in high bandwidth networks. + Should be lower for low number of reassembly buckets. + Valid values: from 1 ns to 10 s. Default value: 10000000 (10 s). + +* ``--reassemble NUM``: max number of entries in reassemble fragment table. + Zero value disables reassembly functionality. + Default value: 0. + * ``-f CONFIG_FILE_PATH``: the full path of text-based file containing all configuration items for running the application (See Configuration file syntax section below). ``-f CONFIG_FILE_PATH`` **must** be specified. @@ -226,7 +257,7 @@ Configurations -------------- The following sections provide the syntax of configurations to initialize -your SP, SA and Routing tables. +your SP, SA, Routing and Neighbour tables. Configurations shall be specified in the configuration file to be passed to the application. The file is then parsed by the application. The successful parsing will result in the appropriate rules being applied to the tables @@ -234,7 +265,7 @@ accordingly. Configuration File Syntax -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~ As mention in the overview, the Security Policies are ACL rules. The application parsers the rules specified in the configuration file and @@ -247,8 +278,8 @@ General rule syntax The parse treats one line in the configuration file as one configuration item (unless the line concatenation symbol exists). Every configuration -item shall follow the syntax of either SP, SA, or Routing rules specified -below. +item shall follow the syntax of either SP, SA, Routing or Neighbour +rules specified below. The configuration parser supports the following special symbols: @@ -383,7 +414,7 @@ The SA rule syntax is shown as follows: .. code-block:: console sa