From patchwork Thu Sep 14 08:26:42 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Akhil Goyal X-Patchwork-Id: 28712 Return-Path: X-Original-To: patchwork@dpdk.org Delivered-To: patchwork@dpdk.org Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 40167199B3; Thu, 14 Sep 2017 10:29:21 +0200 (CEST) Received: from NAM01-BN3-obe.outbound.protection.outlook.com (mail-bn3nam01on0072.outbound.protection.outlook.com [104.47.33.72]) by dpdk.org (Postfix) with ESMTP id 9607C7D4E for ; Thu, 14 Sep 2017 10:29:19 +0200 (CEST) Received: from CY4PR03CA0021.namprd03.prod.outlook.com (10.168.162.31) by CY1PR03MB2363.namprd03.prod.outlook.com (10.166.207.150) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.35.12; Thu, 14 Sep 2017 08:29:17 +0000 Received: from BY2FFO11FD037.protection.gbl (2a01:111:f400:7c0c::136) by CY4PR03CA0021.outlook.office365.com (2603:10b6:903:33::31) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.56.8 via Frontend Transport; Thu, 14 Sep 2017 08:29:17 +0000 Authentication-Results: spf=fail (sender IP is 192.88.168.50) smtp.mailfrom=nxp.com; NXP1.onmicrosoft.com; dkim=none (message not signed) header.d=none;NXP1.onmicrosoft.com; dmarc=fail action=none header.from=nxp.com; Received-SPF: Fail (protection.outlook.com: domain of nxp.com does not designate 192.88.168.50 as permitted sender) receiver=protection.outlook.com; client-ip=192.88.168.50; helo=tx30smr01.am.freescale.net; Received: from tx30smr01.am.freescale.net (192.88.168.50) by BY2FFO11FD037.mail.protection.outlook.com (10.1.14.222) with Microsoft SMTP Server (version=TLS1_0, cipher=TLS_RSA_WITH_AES_256_CBC_SHA) id 15.20.13.11 via Frontend Transport; Thu, 14 Sep 2017 08:29:17 +0000 Received: from netperf2.ap.freescale.net ([10.232.133.164]) by tx30smr01.am.freescale.net (8.14.3/8.14.0) with ESMTP id v8E8T36G025953; Thu, 14 Sep 2017 01:29:13 -0700 From: Akhil Goyal To: CC: , , , , , , , , Date: Thu, 14 Sep 2017 13:56:42 +0530 Message-ID: <20170914082651.26232-3-akhil.goyal@nxp.com> X-Mailer: git-send-email 2.9.3 In-Reply-To: <20170914082651.26232-1-akhil.goyal@nxp.com> References: <20170914082651.26232-1-akhil.goyal@nxp.com> X-EOPAttributedMessage: 0 X-Matching-Connectors: 131498513575814016; (91ab9b29-cfa4-454e-5278-08d120cd25b8); () X-Forefront-Antispam-Report: CIP:192.88.168.50; IPV:NLI; CTRY:US; EFV:NLI; SFV:NSPM; SFS:(10009020)(6009001)(336005)(39860400002)(39380400002)(376002)(346002)(2980300002)(1109001)(1110001)(339900001)(199003)(189002)(316002)(105606002)(6666003)(6916009)(8656003)(110136004)(77096006)(4326008)(2351001)(106466001)(2950100002)(33646002)(16586007)(50466002)(104016004)(5890100001)(48376002)(85426001)(356003)(498600001)(189998001)(50226002)(81156014)(81166006)(47776003)(7416002)(76176999)(97736004)(36756003)(2906002)(1076002)(68736007)(8676002)(305945005)(15650500001)(54906002)(575784001)(8936002)(53936002)(86362001)(50986999)(5660300001)(5003940100001); DIR:OUT; SFP:1101; SCL:1; SRVR:CY1PR03MB2363; H:tx30smr01.am.freescale.net; FPR:; SPF:Fail; PTR:InfoDomainNonexistent; A:1; MX:1; LANG:en; X-Microsoft-Exchange-Diagnostics: 1; BY2FFO11FD037; 1:u7XtrgB46wYMytE9BP+5IY4Pu/5cYRtXBxwvIfaShKYuJ2gvs1eBid2awFoS14tEhoeKFSCvEb9lBR1PMJpezthE+FcYEzUonlLt/3FwHCwYbaZoauDag94YW9Wnvmm2 MIME-Version: 1.0 X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: f3afbff6-aeca-40be-9878-08d4fb4ab091 X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(300000500095)(300135000095)(300000501095)(300135300095)(22001)(300000502095)(300135100095)(300000503095)(300135400095)(2017052603199)(201703131430075)(201703131517081)(300000504095)(300135200095)(300000505095)(300135600095)(300000506095)(300135500095); SRVR:CY1PR03MB2363; X-Microsoft-Exchange-Diagnostics: 1; CY1PR03MB2363; 3:jm/ezJPd0Gr2/J7BJFVIojDb2ayC6z0GeYc3FiqhIh5tuG+rSe1qdkNsralSC4CR2lv2WYQCn2MC/hs283rJy/se/f3NJBV+f3T6BVt1uYWin3EdMJMlO/mtDolxgXxYOp6tMXMjZzGkqene5jvxKqBAnfGrLxPH6QNPIB9XMXqqrpM6FuvxZhG+DnQcJQzHhJueWo4t6cHHHWuRGGWOS3shrjRajW8iM2VWPG/ybrE1+sMGNvJQcMo7PqvaM6JPfLzT4uK2YoSIKOR1dK46exgLLAFUo9wSzy91+4g1cvQehMS1ygsl4+1blr2sV4i1AaOPGQpugBKgi2eHYPr9/QMEYxzsw5q76qgD27V4AoM=; 25:OztrGAW80n6Nzl3aJgjIaBgHEA2cBnU7cSpg6Q8GzPqO85v//rj5NRuR6bjAEeBsjtKv85hPdNsCMlsz4flD+NxCz/C6RMoOaolHuQbtrKa+YV6A3haOTxW4cCDIDmDk+he9wod2eG9CUAu8bMlv6Xj759qLXdFUUUufNcCTomPcooVqUwIwxKBzh75siyFNmXZj8TZdcAP7gJwvGnjf16Jf27rw4jAADhXeBOPHNgyThJJo/i2Jj9Ttl/5i+jgJ7m18xagpB3jlSNNz5PNZgm0Of/sBY+ApCq3ES28ayCY7qra9ClRxshD5iX4p5T/NBMb7fIOimqzs8Su4HRoEvg== X-MS-TrafficTypeDiagnostic: CY1PR03MB2363: X-Microsoft-Exchange-Diagnostics: 1; CY1PR03MB2363; 31:pEAF1E9JGbR8BfplQAGfJ/X156W8vMs0fAwD02XeveKlh9BZjOlAnGYPK3GIkpZaDRLcv++KlQoF8/MNkqIRwDccocuYEvDvlzumT6RiBqYJaULlpHfvK9Tyl9ijzic7L+4AwRw/CfDHhcZ+XXLvn+Ad0gA4pE9Aexa/sbm8lpIW+gsKk2m+sKn9xUXKjlgUb9/RYmgowuBKIF+L1hwZEUOXo0yRQSd1kWZ5Y5PaC9U=; 4:5A6nCaZ9lZha6CFlbHTQCySOFlihMQRMtMUvJMA2/31P9AczNM84YzzSPOM5NV66yyxk3BNTuyvlq7JPYpdxj2ot+vnC26DkMu3X8VN33PLVK+y0LXSSAUg4rXWnowxn00+VFxCkm1wsdtoCe+6L66+gTOntRSgv43HCWUfe9qSOcJo35QCkHAHPk9kzJkbUWV8Mn2U5bqfPQzOceWBY11/qCtN3Id+trxgB54xvb1QzjPRfTn6oe6lly/+KLvVmhiYUnzofkfOGxyWz2NNhCkbah4c66oOdrj4eemevn/yLeWSwij2+4kVrvtt3Lk3M32aK5kq8AzGDw/Y04f706w== X-Exchange-Antispam-Report-Test: UriScan:(192374486261705)(185117386973197); X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(100000700101)(100105000095)(100000701101)(100105300095)(100000702101)(100105100095)(6095135)(2401047)(5005006)(8121501046)(3002001)(10201501046)(93006095)(93001095)(100000703101)(100105400095)(6055026)(6096035)(20161123565025)(20161123561025)(20161123556025)(201703131430075)(201703131448075)(201703131433075)(201703161259150)(201703151042153)(20161123559100)(20161123563025)(201708071742011)(100000704101)(100105200095)(100000705101)(100105500095); SRVR:CY1PR03MB2363; BCL:0; PCL:0; RULEID:(100000800101)(100110000095)(100000801101)(100110300095)(100000802101)(100110100095)(100000803101)(100110400095)(400006)(100000804101)(100110200095)(100000805101)(100110500095); SRVR:CY1PR03MB2363; X-Forefront-PRVS: 0430FA5CB7 X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1; CY1PR03MB2363; 23:OGqLOGkczEUhhTVVKplHSA2WfR9YpEZsyifb7QreP?= GHxMBs9sBR4497Vi87TaUTgg2SZu6WcyEtoReykiRvfLfiAWMR+saAs6ZBgKv0SBGUujyThw6rAtu+bPukcrY9Yy8PLLSdIcgmT4hX+OD5CAmtHbpuk78huKbDLGOckTuZNAw9Yfk2y73kIcOvbBaY2Hk9i5HxLwzKqH2Ld3qQQxmaDjJFKL4nnyHMRFjambOcKL70r9hX0KrNePegpmLBzluzpCFjh1+oS4f/jwFKrKf7fufAkNjR/wb1lzm0v7U6G4MSzxBZEEEW0ABjyBjoYZT8AJoL0Lmwi4yj+XmrQpueA0UW259ADBbE3bWTYSRq1DZUw+ZEuRarl/9fGplySpme9iCagoJ+TPoVyWNHaJbyoa0cL5m3r1BdhEOtWdp9wj3k2rRDibWUnSE5Uiq09VXloknk9QLkKPgTppLDQYtNHgkpIA+0RLP2/U7b55aGB+th28X/y2cRLj+9gyBTeQXq5NYwwxAeTsRRVzByT0/lzjkdeMczhBehNGPdhcAavDGTqEkCSbEBTcpbvTPWzLCoAvkwROI91z+bXYUa8lAf/CkTEexqJ3BZHYcKQb3nNFjj/Oe1Gs1duSAoEblKmcN1n7tPh/52ro5Y/RZF5dDL5BZQTm8boJYpW31gXZ/D/nm9gHT95VINAXGQrjmJ1/z/X5FhnwAUCTMeJ6cUG/WFeiv783cq0iyEe5lQcohwrkO4fE1OAU+VQsvEv0ffQ0KMEbrJE1Q5L0jB2IQ2+8SV0/1/Ve9bkJs/rGsX1vmEyNcBe3h8mZTNPPkL9gvCUnIAV+lXv0agiHmpw+yKSYNlD4xDKrfpR5x2lEJFt+1gfdVh53BadT6Yez4QoKb5AIKy9rmq3V0idv6cvuHzCLyekR66+CkzVFpAAfwNNlhPfJEwjOawNRoAHvhJiFgAYoTOD8L7q+6oWqQV7U1F3j0yczEIH281lXLSQrnR6AIBlKr+bwDM8J1DVJAGQtU4W6W1xcx+65bdhh/EsXnCi218+8I63jER5sxX45v6WbogrMm0soCL0n4g/C7WLxTbKUI7B/xAK2AIF6LnYNPnFEA3g2x3oovHfFbPn7PvR0FIUiRNDYQdhowfXGfEsy+eD9Ssymkft+WIRLXUfGRh/hZBeWmaNMMe6NWGSaMzojNh2CY9pmKhObPV4FGvPNFV+AmBy7JPqLZXSKs5uK/TgOdNouUUM44iH7t9imfXDCPyaeOhEVYQ/ePjDZwPU6M/+Z6/bA0K9oUDjca1XWrSXnA== X-Microsoft-Exchange-Diagnostics: 1; CY1PR03MB2363; 6:DPIL1h7qnTlBfJ4nDgohAHc580ooaotedNwhKEzVs2WggkwcbMuWEhqIg/XYN8eMyR09UaBARyQUnsdzv6fvVXBp+zm9QJYihkeQwcPPhxT7CaE28bdstGFKENwManRM5lmwlZFpNKUaEOPXmgt5sYWejNY7L6CrlvZ8SC7FFmobDLwC/uxFfUEjnDxwS3LZdlCVMNoP/t2aB7RBQ3RfLT5pirctlVdi3byHVW4t+PtjM2W0GuLI2AQfHGNB9MXrT8fzqEMyd3hDY3nJq9Tz5mDLFA8lhDx4ZdcHncGqYpn/oUhnaHRa+6LSH6E5ovy/VNfNoNwz3kuIcZiNCj2BLA==; 5:whUwk/CsJg3AxAcVCqAtK0a4JoxGI+6UhXE73pKA5S8G+kWSvcxRn0cfuWA6d+XPBQ926imBtw/AfB/iYOqh0VSGdnheA3UCDNfIxDi8b/a117RJlQQvUGaB57Ou7IGzDSX3S0SZVSJc87J8k1umHQ==; 24:QkYVDKsRKOYF+PacN77a09t311vD7bhvy5slTCRYqToaODFutrNd8kcdfRwREKhS/+Y+YkdhUi0YwCl7FB/pnoglHRmdW4ah0dQBTzAbwOM=; 7:Uy/2C4IPyp+PD/VqCHAM0PYPds0BCNdchE9zLoJdx9VIWhAB9CZDUVjJs9I+S2bytl3Pq+jqTspBCXwEwyG4OBjscxaGMLtJkkPMsOv7zd8N06a7x082jb7r+Ohdr3nTq2mhikzSDYTaGRRW0qx8dX5EklbxNqRVf9NGpjw9a/SK09revimkHS+lnz0v4WHazVJ3ZRfkSWEM8zKON9Ne9pYMN8pvP9ESVGBpCLmX6cE= SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-MS-Exchange-CrossTenant-OriginalArrivalTime: 14 Sep 2017 08:29:17.2693 (UTC) X-MS-Exchange-CrossTenant-Id: 5afe0b00-7697-4969-b663-5eab37d5f47e X-MS-Exchange-CrossTenant-OriginalAttributedTenantConnectingIp: TenantId=5afe0b00-7697-4969-b663-5eab37d5f47e; Ip=[192.88.168.50]; Helo=[tx30smr01.am.freescale.net] X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: CY1PR03MB2363 Subject: [dpdk-dev] [PATCH 02/11] doc: add details of rte security X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Signed-off-by: Hemant Agrawal Signed-off-by: Akhil Goyal Reviewed-by: John McNamara --- doc/api/doxy-api-index.md | 3 +- doc/api/doxy-api.conf | 1 + doc/guides/prog_guide/index.rst | 1 + doc/guides/prog_guide/rte_security.rst | 552 +++++++++++++++++++++++++++++++++ 4 files changed, 556 insertions(+), 1 deletion(-) create mode 100644 doc/guides/prog_guide/rte_security.rst diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md index 19e0d4f..a3d39fc 100644 --- a/doc/api/doxy-api-index.md +++ b/doc/api/doxy-api-index.md @@ -55,7 +55,8 @@ The public API headers are grouped by topics: [KNI] (@ref rte_kni.h), [ixgbe] (@ref rte_pmd_ixgbe.h), [i40e] (@ref rte_pmd_i40e.h), - [crypto_scheduler] (@ref rte_cryptodev_scheduler.h) + [crypto_scheduler] (@ref rte_cryptodev_scheduler.h), + [security] (@ref rte_security.h) - **memory**: [memseg] (@ref rte_memory.h), diff --git a/doc/api/doxy-api.conf b/doc/api/doxy-api.conf index 823554f..ff6a9fc 100644 --- a/doc/api/doxy-api.conf +++ b/doc/api/doxy-api.conf @@ -66,6 +66,7 @@ INPUT = doc/api/doxy-api-index.md \ lib/librte_reorder \ lib/librte_ring \ lib/librte_sched \ + lib/librte_security \ lib/librte_table \ lib/librte_timer \ lib/librte_vhost diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index 40f04a1..480fa19 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -46,6 +46,7 @@ Programmer's Guide rte_flow traffic_management cryptodev_lib + rte_security link_bonding_poll_mode_drv_lib timer_lib hash_lib diff --git a/doc/guides/prog_guide/rte_security.rst b/doc/guides/prog_guide/rte_security.rst new file mode 100644 index 0000000..2de56d1 --- /dev/null +++ b/doc/guides/prog_guide/rte_security.rst @@ -0,0 +1,552 @@ +.. BSD LICENSE + Copyright 2017 NXP. + + 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 NXP 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. + + +Security Library +================ + +The security library provides a framework for management and provisioning +of security protocol operations offloaded to hardware based devices. The +library defines generic APIs to create and free security sessions which can +support complete protocol offload as well as inline crypto operation with +NIC or crypto devices. The framework currently only supports IPSEC protocol +and it's operations, other protocols will be added in future. + +Design Principles +----------------- + +The security library provides an additional offload capability to existing +crypto device and/or ethernet device. + +.. code-block:: console + + +---------------+ + | rte_security | + +---------------+ + \ / + +-----------+ +--------------+ + | NIC PMD | | CRYPTO PMD | + +-----------+ +--------------+ + +Following offload types can be supported: + +Inline Crypto +~~~~~~~~~~~~~ + +RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO: +The crypto processing for security protocol (e.g. IPSEC) is processed +inline during receive and transmission on NIC port. The flow based +security action should be configured on the port. + +Ingress Data path - The packet is decrypted in RX path and relevant +crypto status is set in rx descriptors. After the successful inline +crypto processing the packet is presented to host as a regular rx packet +but all security protocol related headers are still attached to the +packet. e.g. In case of IPSEC, the IPSEC tunnel headers (if any), +ESP/AH headers will remain in the packet but the received packet +contains the decrypted data where the encrypted data was when the packet +arrived. The driver rx path check the descriptos and and based on the +crypto status sets additional flags in the rte_mbuf.ol_flags field. + +.. note:: + + The underlying device may not support crypto processing all ingress packet + matching to a particular flow (e.g. fragmented packets), such packets will + be passed as encrypted packets. It is the responsibility of driver to + process such encrypted packets using other crypto driver instance. + +Egress Data path - The software prepares the egress packet by adding +relevant security protocol headers in the packets. Only the data will not be +encryptoed by the software. The driver will accordingly configure the +tx descriptors. The HW device will encrypt the data before sending the +the packet out. + +.. note:: + + The underlying device may support post encryption TSO. + +.. code-block:: console + + Egress Data Path + | + +--------|--------+ + | egress IPsec | + | | | + | +------V------+ | + | | SABD lookup | | + | +------|------+ | + | +------V------+ | + | | Tunnel | | <------ Add tunnel header to packet + | +------|------+ | + | +------V------+ | + | | ESP | | <------ Add ESP header without trailer to packet + | | | | <------ Mark packet to be offloaded, add trailer + | +------|------+ | meta-data to mbuf + +--------V--------+ + | + +--------V--------+ + | L2 Stack | + +--------|--------+ + | + +--------V--------+ + | | + | NIC PMD | <------ Set hw context for inline crypto offload + | | + +--------|--------+ + | + +--------|--------+ + | HW ACCELERATED | <------ Packet Encryption/Decryption and + | NIC | Authentication happens inline + | | + +--------|--------+ + + +Inline protocol offload +~~~~~~~~~~~~~~~~~~~~~~~ + +RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL: +The crypto and protocol processing for security protocol (e.g. IPSEC) +is processed inline during receive and transmission. The flow based +security action should be configured on the port. + +Ingress Data path - The packet is decrypted in RX path and relevant +crypto status is set in rx descriptors. After the successful inline +crypto processing the packet is presented to host as a regular rx packet +but all security protocol related headers optionally removed from the +packet. e.g. In case of IPSEC, the IPSEC tunnel headers (if any), +ESP/AH headers will be removed from the packet and the received packet +will contains the decrypted packet only. The driver rx path check the +descriptos and and based on the crypto status sets additional flags in +the rte_mbuf.ol_flags field. + +.. note:: + + The underlying device in this case is stateful.It is expected that + the device shall support crypto processing for all kind of packets matching + to a given flow, this includes fragemented packets (post reassembly). + e.g. In case of IPSEC the device may internally manage anti-replay etc. + It will provide configuration option for anti-replay behavior i.e. to drop + the packets or pass them to driver with err flags set in descriptor. + +Egress Data path - The software will send the unencryptoed packet +without any security protocol headers added to the packet.The driver +will configure the security index and requirement in the tx descriptors. +The HW device will do security processing on the packet that includes +adding the relevant protocol headers and encrypt the data before sending +the the packet out.The software should make sure that the buffer +has required header and tailer space for any protocol header addition. The +software may also do early fragmentation if the resulatant packet is expected +to cross MTU. + + +.. note:: + + The underlying device will manage state information required for egress + processing. e.g. In case of IPSEC, the seq number will be added to be the + packet, It shall provide indication when sequence number is about to + overflow. The underlying device may support post encryption TSO. + +.. code-block:: console + + Egress Data Path + | + +--------|--------+ + | egress IPsec | + | | | + | +------V------+ | + | | SABD lookup | | + | +------|------+ | + | +------V------+ | + | | Desc | | <------ Mark packet to be offloaded + | +------|------+ | + +--------V--------+ + | + +--------V--------+ + | L2 Stack | + +--------|--------+ + | + +--------V--------+ + | | + | NIC PMD | <------ Set hw context for inline crypto offload + | | + +--------|--------+ + | + +--------|--------+ + | HW ACCELERATED | <------ Add tunnel, ESP header etc header to + | NIC | packet.Packet Encryption/Decryption and + | | Authentication happens inline. + +--------|--------+ + + +Lookaside protocol offload +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL: +This extend the librte_cryptodev to support the programming of IPsec +Security Association (SA) as part of crypto session creation including +the definition. In addition to standard crypto processing, as defined by +the cryptodev, the security protocol processing is also offloaded to the +crypto device. + +Decryption: The packet is sent to the crypto device for security +protocol processing. The device will decrypt the packet and it will also +optionally remove the additional security headers from the packet. +e.g. In case of IPSEC, the IPSEC tunnel headers (if any), ESP/AH headers +will be removed from the packet and the decrypted packet may contains +the decrypted packet only. + +.. note:: + + In case of IPSEC the device may internally manage anti-replay etc. + It will provide configuration option for anti-replay behavior i.e. to drop + the packets or pass them to driver with err flags set in descriptor. + +Encryption: The software will submit the packet to cryptodev as usual +to encryption, the HW device in this case will also add relevant +security protocol header along with encrypting the packet. The software +should make sure that the buffer has required header and tailer space +for any protocol header addition. + +.. note:: + + In case of IPSEC, the seq number will be added to be the packet, + It shall provide indication when sequence number is about to + overflow. + +.. code-block:: console + + Egress Data Path + | + +--------|--------+ + | egress IPsec | + | | | + | +------V------+ | + | | SABD lookup | | <------ SA maps to cryptodev session + | +------|------+ | + | +------|------+ | + | | \--------------------\ + | | Crypto | | | <- Crypto processing through + | | /----------------\ | inline crypto PMD + | +------|------+ | | | + +--------V--------+ | | + | | | + +--------V--------+ | | create <-- SA is added to hw + | L2 Stack | | | inline using existing create + +--------|--------+ | | session sym session APIs + | | | | + +--------V--------+ +---|---|----V---+ + | | | \---/ | | <--- Add tunnel, ESP header etc + | NIC PMD | | INLINE | | header to packet.Packet + | | | CRYPTO PMD | | Encryption/Decryption and + +--------|--------+ +----------------+ Authentication happens + | inline. + +--------|--------+ + | NIC | + +--------|--------+ + V + +Device Features and Capabilities +--------------------------------- + +Device Capabilities For Security Operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The device(crypto or ethernet) capabilities which support security operations, +are defined by the security action type, security protocol, protocol +capabilities and corresponding crypto capabilities for security. For the full +scope of the Security capability see the definition of the structure in the +*DPDK API Reference*. + +.. code-block:: c + + struct rte_security_capability; + +Each driver(crypto or ethernet) defines its own private array of capabilities +for the operations it supports. Below is an example of the capabilities for a +PMD which supports the IPSec protocol. + +.. code-block:: c + + static const struct rte_security_capability pmd_security_capabilities[] = { + { /* IPsec Lookaside Protocol offload ESP Transport Egress */ + .action = RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL, + .protocol = RTE_SECURITY_PROTOCOL_IPSEC, + .ipsec = { + .proto = RTE_SECURITY_IPSEC_SA_PROTO_ESP, + .mode = RTE_SECURITY_IPSEC_SA_MODE_TUNNEL, + .direction = RTE_SECURITY_IPSEC_SA_DIR_EGRESS, + .options = { 0 } + }, + .crypto_capabilities = pmd_capabilities + }, + { /* IPsec Lookaside Protocol offload ESP Tunnel Ingress */ + .action = RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL, + .protocol = RTE_SECURITY_PROTOCOL_IPSEC, + .ipsec = { + .proto = RTE_SECURITY_IPSEC_SA_PROTO_ESP, + .mode = RTE_SECURITY_IPSEC_SA_MODE_TUNNEL, + .direction = RTE_SECURITY_IPSEC_SA_DIR_INGRESS, + .options = { 0 } + }, + .crypto_capabilities = pmd_capabilities + }, + { + .action = RTE_SECURITY_ACTION_TYPE_NONE + } + }; + static const struct rte_cryptodev_capabilities pmd_capabilities[] = { + { /* SHA1 HMAC */ + .op = RTE_CRYPTO_OP_TYPE_SYMMETRIC, + .sym = { + .xform_type = RTE_CRYPTO_SYM_XFORM_AUTH, + .auth = { + .algo = RTE_CRYPTO_AUTH_SHA1_HMAC, + .block_size = 64, + .key_size = { + .min = 64, + .max = 64, + .increment = 0 + }, + .digest_size = { + .min = 12, + .max = 12, + .increment = 0 + }, + .aad_size = { 0 }, + .iv_size = { 0 } + } + } + }, + { /* AES CBC */ + .op = RTE_CRYPTO_OP_TYPE_SYMMETRIC, + .sym = { + .xform_type = RTE_CRYPTO_SYM_XFORM_CIPHER, + .cipher = { + .algo = RTE_CRYPTO_CIPHER_AES_CBC, + .block_size = 16, + .key_size = { + .min = 16, + .max = 32, + .increment = 8 + }, + .iv_size = { + .min = 16, + .max = 16, + .increment = 0 + } + } + } + } + } + + +Capabilities Discovery +~~~~~~~~~~~~~~~~~~~~~~ + +Discovering the features and capabilities of a driver(crypto/ethernet) +is achieved through the ``rte_security_capabilities_get`` function. + +.. code-block:: c + + const struct rte_security_capability *rte_security_capabilities_get(uint16_t id); + +This allows the user to query a specific driver and get all the device +security capabilities. It returns an array of ``rte_security_capability`` structure +which contains all the capabilities for the device. + +Security Session Create/Free +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Security Sessions are created to store the immutable fields of a particular Security +association for a particular protocol which is defined by a security session +configuration structure which is used in the operation processing of a packet flow. +Sessions are used to manage protocol specific information as well as crypto parameters. +Security sessions cache this immutable data in a optimal way for the underlying PMD +and this allows further acceleration of the offload of Crypto workloads. + +The Secutiry framework provides APIs to create and free sessions for crypto/ethernet +devices, where sessions are mempool objects. It is the application's responsibility +to create and manage the session mempools. Mempool object size should be able to +accommodate the driver's private data of the session. + +Once the session mempools have been created, ``rte_security_session_create()`` +is used to allocate and initialize a session for the required crypto/ethernet device. +Sessions already created can be updated with the ``rte_security_session_update``. + +When a session is no longer used, user must call ``rte_security_session_destroy()`` +to free driver private session data and return the memory back to the mempool. + +For look aside protocol offload to hardware crypto device, the ``rte_crypto_op`` +created by the application is attached to the security session by the API +``rte_security_attach_session``. + +For Inline Crypto and Inline protocol offload, device specific defined metadata is +updated in the mbuf using ``rte_security_set_pkt_metadata``. + +Session configuration +~~~~~~~~~~~~~~~~~~~~~ + +Security Session configuration structure is defined as ``rte_security_session_conf`` + +.. code-block:: c + + struct rte_security_session_conf { + enum rte_security_session_action_type action_type; + /**< Type of action to be performed on the session */ + enum rte_security_session_protocol protocol; + /**< Security protocol to be configured */ + union { + struct rte_security_ipsec_xform ipsec; + struct rte_security_macsec_xform macsec; + }; + /**< Configuration parameters for security session */ + struct rte_crypto_sym_xform *crypto_xform; + /**< Security Session Crypto Transformations */ + }; + +The configuration structure reuses the ``rte_crypto_sym_xform`` for crypto related +configuration. ``rte_security_session_action_type`` specify whether the session is +configured for Lookaside Protocol offload or Inline Crypto or Inline Protocol +Offload. + +.. code-block:: c + + enum rte_security_session_action_type { + RTE_SECURITY_ACTION_TYPE_NONE, + /**< No security actions */ + RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO, + /**< Crypto processing for security protocol is processed inline + * during transmission */ + RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL, + /**< All security protocol processing is performed inline during + * transmission */ + RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL + /**< All security protocol processing including crypto is performed + * on a lookaside accelerator */ + }; + +The ``rte_security_session_protocol`` is defined as + +.. code-block:: c + + enum rte_security_session_protocol { + RTE_SECURITY_PROTOCOL_IPSEC, + /**< IPsec Protocol */ + RTE_SECURITY_PROTOCOL_MACSEC, + /**< MACSec Protocol */ + }; + +Currently the library defines configuration parameters for IPSec only. For other +protocols like MACSec, structures and enums are defined as place holders which +will be updated in the future. + +IPsec related configuration parameters are defined in ``rte_security_ipsec_xform`` + +.. code-block:: c + + struct rte_security_ipsec_xform { + uint32_t spi; + /**< SA security parameter index */ + uint32_t salt; + /**< SA salt */ + struct rte_security_ipsec_sa_options options; + /**< various SA options */ + enum rte_security_ipsec_sa_direction direction; + /**< IPSec SA Direction - Egress/Ingress */ + enum rte_security_ipsec_sa_protocol proto; + /**< IPsec SA Protocol - AH/ESP */ + enum rte_security_ipsec_sa_mode mode; + /**< IPsec SA Mode - transport/tunnel */ + struct rte_security_ipsec_tunnel_param tunnel; + /**< Tunnel parameters, NULL for transport mode */ + }; + + +Security API +~~~~~~~~~~~~ + +The rte_security Library API is described in the *DPDK API Reference* document. + +Flow based Security Session +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In case of NIC based offloads, the security session specified in the +'rte_flow_action_security' must be created on the same port as the +flow action that is being specified. + +The ingress/egress flow attribute should match that specified in the security +session if the security session supports the definition of the direction. + +Multiple flows can be configured to use the same security session. For +example if the security session specifies an egress IPsec SA, then multiple +flows can be specified to that SA. In the case of an ingress IPsec SA then +it is only valid to have a single flow to map to that security session. + +.. code-block:: console + + Configuration Path + | + +--------|--------+ + | Add/Remove | + | IPsec SA | <------ Build security flow action of + | | | ipsec transform + |--------|--------| + | + +--------V--------+ + | Flow API | + +--------|--------+ + | + +--------V--------+ + | | + | NIC PMD | <------ Add/Remove SA to/from hw context + | | + +--------|--------+ + | + +--------|--------+ + | HW ACCELERATED | + | NIC | + | | + +--------|--------+ + +o Add/Delete SA flow: + To add a new inline SA construct a rte_flow_item for Ethernet + IP + ESP + using the SA selectors and the rte_crypto_ipsec_xform as the rte_flow_action. + Note that any rte_flow_items may be empty, which means it is not checked. + +.. code-block:: console + + In its most basic form, IPsec flow specification is as follows: + +-------+ +----------+ +--------+ +-----+ + | Eth | -> | IP4/6 | -> | ESP | -> | END | + +-------+ +----------+ +--------+ +-----+ + + However, the API can represent, IPsec crypto offload with any encapsulation: + +-------+ +--------+ +-----+ + | Eth | -> ... -> | ESP | -> | END | + +-------+ +--------+ +-----+