From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from NAM03-BY2-obe.outbound.protection.outlook.com (mail-by2nam03on0078.outbound.protection.outlook.com [104.47.42.78]) by dpdk.org (Postfix) with ESMTP id 8104523B for ; Mon, 18 Sep 2017 13:14:04 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=CAVIUMNETWORKS.onmicrosoft.com; s=selector1-cavium-com; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version; bh=6SmSBZFjBbNCZCZYbVvIjT/Ul1oKw2LipQcGpxwdfMU=; b=iQkokwQW4fkxEdbUk7ABMpfO+MBWt3+McF1aW0BoktBc7XV5G8U7vwcxETazacUXeSncaPJV2u35jdqqjVb34FLLt2/sTD67xRQ8v2i0dDUsi2ZfDySpgQ29vym+7akMRlk8LJS8Dwb2KAYEqVO2rFLiQVzL3Xdi40iig1BOTHM= Authentication-Results: spf=none (sender IP is ) smtp.mailfrom=Jerin.JacobKollanukkaran@cavium.com; Received: from jerin (111.93.218.67) by CO2PR07MB2519.namprd07.prod.outlook.com (10.166.201.6) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256) id 15.20.56.11; Mon, 18 Sep 2017 11:13:58 +0000 Date: Mon, 18 Sep 2017 16:43:39 +0530 From: Jerin Jacob To: Akhil Goyal Cc: dev@dpdk.org, declan.doherty@intel.com, pablo.de.lara.guarch@intel.com, hemant.agrawal@nxp.com, radu.nicolau@intel.com, borisp@mellanox.com, aviadye@mellanox.com, thomas@monjalon.net, sandeep.malik@nxp.com Message-ID: <20170918111338.GA16299@jerin> References: <20170914082651.26232-1-akhil.goyal@nxp.com> <20170914082651.26232-3-akhil.goyal@nxp.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20170914082651.26232-3-akhil.goyal@nxp.com> User-Agent: Mutt/1.9.0 (2017-09-02) X-Originating-IP: [111.93.218.67] X-ClientProxiedBy: MA1PR01CA0097.INDPRD01.PROD.OUTLOOK.COM (10.174.56.141) To CO2PR07MB2519.namprd07.prod.outlook.com (10.166.201.6) X-MS-PublicTrafficType: Email X-MS-Office365-Filtering-Correlation-Id: 48862419-36fc-474f-1bb3-08d4fe865d79 X-Microsoft-Antispam: UriScan:; BCL:0; PCL:0; RULEID:(300000500095)(300135000095)(300000501095)(300135300095)(22001)(300000502095)(300135100095)(2017030254152)(300000503095)(300135400095)(2017052603199)(201703131423075)(201703031133081)(201702281549075)(300000504095)(300135200095)(300000505095)(300135600095)(300000506095)(300135500095); SRVR:CO2PR07MB2519; X-Microsoft-Exchange-Diagnostics: 1; CO2PR07MB2519; 3:orL/PN1yt5LVkWmJKY7cQ8Y+HqKNnpCmqczCyv/T9uhyA3VC/OOvDsvxaRleKeku7d50XmpT1N/Dy81dGqo/4PDwN7qw5yLTYwPVZq/N2goYM6U6QJvjFHMFOv9tT4Dou80HfHCMj2di4FfT+lEIv0+3tWkpS7/c4aiGB+NtjsahPGD+e+88Kglkrl7EJBhNs5fvIS2oCoWeURgmgC484fs7IVPdhiIcFmniRw1dd2+F9ABDjMQqHuL/Y9LWlhXY; 25:LgMcR0HId4QUt831VubiLJ4sjfwDkHyCv7MOlviIvrLFWJ8jjR441sKSCDtGs6fijEPhziOAADf2PMU+upZsFYWQZDOQKJOMLqhOgkqnvrrHYdpeZH2q1v2+0Y4ReZST4caJZbrY9SIo5WPCGsGGXq4f/b9O7Yi3uBKtS9teeIeIRpUEYV/KRkmi8wStSYHfhTaYALqAVP5MZXrpxJXSLXCmke/6En/hEmLEtrZBEQOvfRsMTI85tLIv5y/NknoDThn7IfonT4c2mnweikWgzZMB9r6r9v3bEiJWlfOD59CE1SLHcroq7rCLRxekvST3CC+DbsLUvsjfYFMm+bqoUQ==; 31:hYy2ap9xMCS4/Ag99/CLnh2OA4TCF/cYcc7gbxZVLMlhMbyDuAVZocdcshyNQCI9XTj/MKFKG5ci+nXW+9hHzCb6dgI3DoAoc7e4JNJuwKG/1vjN8BIN1PoTWVpYW+6+l6Bj46Q2aIhXkheUOASzDsGkWRG8u8WPotQ+wz2WspaVbSkOs6j0GTcfHU0fvufG8GvMe7M/EmUUS3K+KoFsYeI9bGgxII5HnvPx1Ahucds= X-MS-TrafficTypeDiagnostic: CO2PR07MB2519: X-Microsoft-Exchange-Diagnostics: 1; CO2PR07MB2519; 20:RZN7udE5ZXyMSY46rRDBaIiw/jGDzyQXXMZYoSLswjT5mCJ6ILa5xTBxF/yxi9HFCIODmESNWPSjb/E0/uIRc9ZWaRQSiW6MkSo4ySmPXjWMx/36RkskyfWCzeItHIhsvvxr9evFnTuTasKuTokfHqXCeDWqMsvg00fGEgoGuJK66Edm0Tom8R3NKy6L5PQjhXpS84+mBMiJqf7+MIzyihxflLkkJRAWrH6/1kT0rZJXF7Aaoidy8buSBh5gZ9SbCuEqk1S6/4eBoSwjc4cxmJ7/KuOHj83uSvEx+TEREzh927jvcj8kmljI2X/v49wpF1Fav/yvHiEq1/zcz25Iv4AukxEv7DvcGN84rrqn0Mym3esvJBECfoD4itza4tVm5pKcdvw8mjQ4ruwef5mWQ3RNgrsvG5zUyCeHJ9DjV7HPmltBwBC4YTreVIAP9+EoRJx5mHPsjSHpyblPNn5s5d03FcZ3MuKfKm1EkWO/ZNwDjXyYa3ynsaNIEvEpdiP6cLlJOiBHEx8TLh/t8MbQebggiGwFite/VeiZknqeqwzY4dW6pEP+awiugrB8YJrfJLjTItXy7YQobhxNFrKFKUQHfd7tq32K8RKXtNFFu74= X-Exchange-Antispam-Report-Test: UriScan:(192374486261705)(185117386973197)(228905959029699); X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(100000700101)(100105000095)(100000701101)(100105300095)(100000702101)(100105100095)(6040450)(2401047)(8121501046)(5005006)(93006095)(100000703101)(100105400095)(3002001)(10201501046)(6041248)(20161123560025)(20161123564025)(20161123562025)(20161123558100)(20161123555025)(201703131423075)(201702281528075)(201703061421075)(201703061406153)(6072148)(201708071742011)(100000704101)(100105200095)(100000705101)(100105500095); SRVR:CO2PR07MB2519; BCL:0; PCL:0; RULEID:(100000800101)(100110000095)(100000801101)(100110300095)(100000802101)(100110100095)(100000803101)(100110400095)(100000804101)(100110200095)(100000805101)(100110500095); SRVR:CO2PR07MB2519; X-Microsoft-Exchange-Diagnostics: 1; CO2PR07MB2519; 4:02247lBxGuUuwuH3GT9yopvGMP+Fbz2eY41somDYhcLsoiYqQy897x/Nhq3yikyB1IwzbTjH22s8hZbSSnyESfijcLMGztaLwmXRnwC89YXFCOVv7FdTHtHyyVp9AXJfwVIKh/EoKmdIzEBq7LUSp4Z6OrVMHmI6+sxYq0/fH16TcSpGDdAhGni5cwvAEmARAmy2pfB9SEq6yictu1nu8OqfmxlHctRJkiWTTWn8GovH9GDCrVo4WoMfx+bivyG6GmuDGfgQX/d8PBSQnyYDA/loWgq4b/wKWx2RFMJvozmFYiycj2UhY52/TuF36VszlWo+LqjWC2DLWYdeGYy3GuKgaqqFEVD2msjxAdMxSZc= X-Forefront-PRVS: 04347F8039 X-Forefront-Antispam-Report: SFV:NSPM; SFS:(10009020)(6009001)(376002)(346002)(13464003)(189002)(199003)(6116002)(6666003)(15650500001)(106356001)(8676002)(68736007)(105586002)(8936002)(2906002)(81166006)(81156014)(6916009)(66066001)(42882006)(2950100002)(478600001)(316002)(16586007)(55016002)(16526017)(5660300001)(9686003)(83506001)(7416002)(189998001)(58126008)(8656003)(50466002)(72206003)(25786009)(76176999)(33716001)(54356999)(6246003)(101416001)(33656002)(97736004)(305945005)(53936002)(50986999)(7736002)(4326008)(6496005)(229853002)(110136004)(5890100001)(3846002)(23726003)(1076002)(5009440100003)(47776003)(18370500001); DIR:OUT; SFP:1101; SCL:1; SRVR:CO2PR07MB2519; H:jerin; FPR:; SPF:None; PTR:InfoNoRecords; MX:1; A:1; LANG:en; Received-SPF: None (protection.outlook.com: cavium.com does not designate permitted sender hosts) X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1; CO2PR07MB2519; 23:owPjtUYSAKzJwlQ8j4tQZKmCSk/pg4He86+VFLVJn?= =?us-ascii?Q?L6xSqFj1scO2nl8Hdv04AT97Rx7jwpYgzDEo5gvopU7lagHCxXQjk6+GXSKF?= =?us-ascii?Q?8mqRMZzpRnWSkjtA5keOQvcU7yI0xQeGkt1gMlKKkurYzO8wPe1f6E9S7XkZ?= =?us-ascii?Q?5KioPts1wvbxV2n+C/udtBY2aYbjBh4hmm0X41xSsM5JuVnYILRYQKl2CoDt?= =?us-ascii?Q?Quww8xTCJb18cWt96QB4AR5CdiSIiMPsSoyNFsQsQPrzvGFsscGBFNsNfVmy?= =?us-ascii?Q?5fA9CofoHlSBfmsd+I2lXUhcgdBFO7rPYA3qxdzmF3+gtvY6BRSJtcfZ5Xy/?= =?us-ascii?Q?fxvM/2LUegQkJk/kG29Xibc942s6NLLydDfTOUS4FRl3INTZ5JkNabIn7aaE?= =?us-ascii?Q?EyID/bWvmWew2DIGMozfx8td6JiMzj5RVYhuoZkDYNaWDVgneFyAbN48nOLh?= =?us-ascii?Q?/Nhgyh6ExCCvn6RQZjWHB0cP4fVWrdfCeiQG9mLXvP8iKpmAlZbFWiQ9FXSu?= =?us-ascii?Q?UeRol9gKtup0iNmtck8tW6I7vj1XIsPONtHH+XWf7oGsVcFQnLao3lt6mPve?= =?us-ascii?Q?5k0LS5EnJgkbUIC27ijoELkb+j1SdFM3BawYAJcv4eXTw/GhwmNCYg3OVILB?= =?us-ascii?Q?PLyK0aMmbzhbqBCzmHpV9X6IeTiLK4UF21d0lU2TkvhJ533i/DoT+JbpDTNF?= =?us-ascii?Q?2T26kf13fnXIOgS5TQ3dHZkAuWcYKZAnr+Id1Rkn5ZvJIymFKOST/1DP5oUH?= =?us-ascii?Q?lnJWkE2hw5wpSgRa9KMLHPBzivauWUgWF1ebZOAHBWeKYwCYTCXByeagxcjz?= =?us-ascii?Q?k+HEp+eFTKDg5BdvI4WRtObANMgkuOKHwbzOOp/yNzV5ET9uRKgurTnGesDS?= =?us-ascii?Q?wLyAvgEPqupFfr4HxNYbmZbUZ/y5OeStt+khmApARkmS8K784/AozSfwwI1p?= =?us-ascii?Q?D25PRlGgTZb7Brp72XDnBuYQvJIFbF9TD1Y85BLnVPmEwEsf5rUZuLXsjmo8?= =?us-ascii?Q?ZkD5sR2MbicGBbIY/D6SMU6oTdve+zmgQcLFQ0D8Z2Etyosw5bTOzIdvDmw0?= =?us-ascii?Q?3dbQtaO9ASBiQ1RaQ11rRuIVoK7QZ4Gou/HkSbmGIQNS6Tvg1yGqyfUSPywY?= =?us-ascii?Q?nmMY4ylUn75X/Tho9tJ7Po6JrzunGnseThy3BaUsSuz4/7LQi80Pu+e74MoM?= =?us-ascii?Q?o7OQrxIErIA7+O3JcrjVnFjpeXkfd35Bi+h0rFTagulxl++kcNBe1VeLFpYq?= =?us-ascii?Q?BxzcvN8x5fm0nViwogHnoCYtb5qfkpQ8+5zw9pOHaVa3fev4qYcA7KLDiWri?= =?us-ascii?Q?85t/QehqjzfW85MWLJUv8Vf+ydtsoCJuN71Bcs+EX1Z30mfhQQHsCOuHEcBt?= =?us-ascii?Q?ieg+A=3D=3D?= X-Microsoft-Exchange-Diagnostics: 1; CO2PR07MB2519; 6:lILkd8kcBnG04VkwngI2ip3QGngvXdpiEyClKLN7PpTZ+kkzdwjFRA+iup3xrzTR5+OAUBy70WVk7EBHwFkn6D9I918c+lAwHN3IidvOhfpmdFyWd/iXbvNB8r9G5G5A5FouevNMGC3hQIdktt7vyoy07eBxJzYLfBfXtKxXCAtFpdPc13oYVdf2ddDbUVh4RSMvb3TdyAiUffVrefGp5SFwHJOtVqcBtBi4iN2vD7oCvDHBlb8EVV8GiD70Ui1HOhzB3r6BuYVUf4WRYEXxvNTqNZof/ZvnRyByNAz1xtW4bdUyfgPLfzaRL3CRcP2tSn2+W3FerQ81twno2JnY7Q==; 5:H6DV5KQwCXwJi2bhi4OxUZuAhhrYcgnAkOmWEfsHZej0Dr81sJlQgtA99HPQ129AYfm78AaUo9obTOjUagTGueee5j+K99qbX+NSJV/oT2LOVzerVUPt0DmQHhMbvIGSYoH8PIVjCB1XBoa9fXFKnQ==; 24:XhV7BBGE1z5qnsfHcORn5IpHTqKpI+o0MoM6Ue06oYZ0gJXdh68GD6k1a/V3BpY98/o7VBFit8cGdX2Q9Iz7eTmb3b8y8uvVmZg36cIgLRs=; 7:d6/85/XDLF7y7LGc44WRTBFLY7ciovsotOnSXnN/T+/jn13KZfThz5EeoMxb5cPPf13ztSXNxehVQ66vLhWCcqxJMaSXXwCE7mAevsJ3fA2sWq10Vr9j6riGH4qDMZYVkN268iKAdUDAbhiJnepMXcyOdYARz+Jyqjcp94C2GXJ3THYjyfcWA7k060u/GymRYZupgB/rrM6fUSNr09iWsJbZSlxR+UKorhVJQ8L9f2c= SpamDiagnosticOutput: 1:99 SpamDiagnosticMetadata: NSPM X-OriginatorOrg: caviumnetworks.com X-MS-Exchange-CrossTenant-OriginalArrivalTime: 18 Sep 2017 11:13:58.4935 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 711e4ccf-2e9b-4bcf-a551-4094005b6194 X-MS-Exchange-Transport-CrossTenantHeadersStamped: CO2PR07MB2519 Subject: Re: [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: , X-List-Received-Date: Mon, 18 Sep 2017 11:14:05 -0000 -----Original Message----- > Date: Thu, 14 Sep 2017 13:56:42 +0530 > From: Akhil Goyal > To: dev@dpdk.org > CC: declan.doherty@intel.com, pablo.de.lara.guarch@intel.com, > hemant.agrawal@nxp.com, radu.nicolau@intel.com, borisp@mellanox.com, > aviadye@mellanox.com, thomas@monjalon.net, sandeep.malik@nxp.com, > jerin.jacob@caviumnetworks.com > Subject: [PATCH 02/11] doc: add details of rte security > X-Mailer: git-send-email 2.9.3 > +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 s/descriptos/descriptors > +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 ^^^^^^^^^^^ Do you mean application here instead of driver? > + 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 s/encryptoed/encrypted > +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 | | > + | +------|------+ | s/SABD/SADB > + | +------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 Only packet Encryption here. Right? > + | NIC | Authentication happens inline > + | | > + +--------|--------+ ^^^ I guess the "|" can be removed. > + > + > +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 s/descriptos/descriptors > +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). s/fragemented/fragmented > + 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 s/unencryptoed/clear > +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 | | > + | +------|------+ | s/SABD/SADB > + | +------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 Only packet Encryption here. Right? > + | | Authentication happens inline. > + +--------|--------+ I guess the "|" can be removed. > + > + > +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 head room and tail room > +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 > + | +------|------+ | s/SABD/SADB > + | +------|------+ | > + | | \--------------------\ > + | | 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``. If DEV_TX_OFFLOAD_SEC_NEED_MDATA is set. > + > +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 | > + +-------+ +--------+ +-----+ > -- > 2.9.3 >