From patchwork Fri May 13 10:47:44 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Nikhil Agarwal X-Patchwork-Id: 67719 Delivered-To: patch@linaro.org Received: by 10.140.92.199 with SMTP id b65csp85876qge; Thu, 12 May 2016 22:18:14 -0700 (PDT) X-Received: by 10.55.117.202 with SMTP id q193mr14311474qkc.191.1463116694702; Thu, 12 May 2016 22:18:14 -0700 (PDT) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id x189si11073264qhb.21.2016.05.12.22.18.14; Thu, 12 May 2016 22:18:14 -0700 (PDT) Received-SPF: pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) client-ip=54.225.227.206; Authentication-Results: mx.google.com; spf=pass (google.com: domain of lng-odp-bounces@lists.linaro.org designates 54.225.227.206 as permitted sender) smtp.mailfrom=lng-odp-bounces@lists.linaro.org; dmarc=pass (p=NONE dis=NONE) header.from=linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 1D8026164E; Fri, 13 May 2016 05:18:14 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on ip-10-142-244-252 X-Spam-Level: * X-Spam-Status: No, score=1.1 required=5.0 tests=BAYES_00, DATE_IN_FUTURE_03_06, RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,SPF_HELO_PASS,URIBL_BLOCKED autolearn=disabled version=3.4.0 Received: from [127.0.0.1] (localhost [127.0.0.1]) by lists.linaro.org (Postfix) with ESMTP id 6EEE9615E3; Fri, 13 May 2016 05:18:08 +0000 (UTC) X-Original-To: lng-odp@lists.linaro.org Delivered-To: lng-odp@lists.linaro.org Received: by lists.linaro.org (Postfix, from userid 109) id 99301615E0; Fri, 13 May 2016 05:18:06 +0000 (UTC) Received: from na01-bn1-obe.outbound.protection.outlook.com (mail-bn1bon0066.outbound.protection.outlook.com [157.56.111.66]) by lists.linaro.org (Postfix) with ESMTPS id 6F830615E0 for ; Fri, 13 May 2016 05:18:05 +0000 (UTC) Received: from CH1PR03CA012.namprd03.prod.outlook.com (10.255.156.157) by DM2PR03MB477.namprd03.prod.outlook.com (10.141.85.19) with Microsoft SMTP Server (TLS) id 15.1.485.9; Fri, 13 May 2016 05:18:04 +0000 Received: from BN1BFFO11FD031.protection.gbl (10.255.156.132) by CH1PR03CA012.outlook.office365.com (10.255.156.157) with Microsoft SMTP Server (TLS) id 15.1.466.19 via Frontend Transport; Fri, 13 May 2016 05:18:03 +0000 Received-SPF: SoftFail (protection.outlook.com: domain of transitioning linaro.org discourages use of 192.88.168.50 as permitted sender) Received: from tx30smr01.am.freescale.net (192.88.168.50) by BN1BFFO11FD031.mail.protection.outlook.com (10.58.144.94) with Microsoft SMTP Server (TLS) id 15.1.492.8 via Frontend Transport; Fri, 13 May 2016 05:18:02 +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 u4D5I0xp022345 for ; Thu, 12 May 2016 22:18:01 -0700 From: Nikhil Agarwal To: Date: Fri, 13 May 2016 16:17:44 +0530 Message-ID: <1463136464-31766-1-git-send-email-Nikhil.Agarwal@linaro.org> X-Mailer: git-send-email 2.8.2 MIME-Version: 1.0 X-EOPAttributedMessage: 0 X-Matching-Connectors: 131075902831866666; (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)(2980300002)(199003)(189002)(9170700003)(105596002)(106466001)(189998001)(47776003)(92566002)(2870700001)(81166006)(107886002)(2906002)(50226002)(2351001)(19580405001)(1220700001)(8936002)(450100001)(5008740100001)(19580395003)(586003)(104016004)(6806005)(77096005)(5820100001)(229853001)(50466002)(50986999)(110136002)(23676002)(8676002)(87936001)(86362001)(36756003); DIR:OUT; SFP:1101; SCL:1; SRVR:DM2PR03MB477; H:tx30smr01.am.freescale.net; FPR:; SPF:SoftFail; MLV:sfv; A:1; MX:1; LANG:en; X-Microsoft-Exchange-Diagnostics: 1; BN1BFFO11FD031; 1:zpzXk5SED52nLGA2E1n2HqSSsdQRTrlx/L2cH+eCBj156Vx5U2k3hKbjmgNQQY5OYSodgjQH1bQaO0H6hWtWPIS5GyVvdRKkCYyf+uEdcVATtxZxGef4fqYTo9g8nyoRylrZhTKtwcYLKqGrgj6w7ODII2H8J5I2oKEmUrbRVo4o9jFoii0AT0IGGnEFgbp4LwzTDe9KO+0oKL9bJ8BBJLCS3UZEX31vG/eLfe3ld6blNCtBa2+W0qLD6S66gSfsHZzkik8BdNBW7x4p9mGW7x1rRHPOpsQ1AjDbZZjH1dECKanTlfJpB0jWQIa9D9Ny9Dlrg0qjL5I5n5h/MK6cGtZsHRKCXTtp+lLoduCIL2o+HlX/KwwXhAUdNHnPavhUyuwx7jt6OYc4pYyBTGImIF4VQ78EIoqVspR83CdCDEIPD4opyKoJqRKyVZIoFwZb87epCEgHIf6+N5m0fPZBds0Ce0q24UI32vtc9vzQm/x896yV5W4b3HV+/YLUNj/OL8eF4rJaDgWttUXBmNQ/nZ49fXKAo/gWZ5Ghg/P8Bc0= X-MS-Office365-Filtering-Correlation-Id: 00e330a9-d9bd-46a7-332a-08d37aedf55f X-Microsoft-Exchange-Diagnostics: 1; DM2PR03MB477; 2:FWA7guhzu9rFpjqP3GoJ+vmJHYwPadL6Xx/w4Bs5EQVxXnYokhr4e2bpuJtrKDhiZdN3eGPg/1j+8KqsgP5LV6ZFdXUaYxWDGaSgAvZOEjY4Zb6O/a4c55xPotfHVPctx1Ejyw8YXpeLnEZK97AcuXoMHB49w2etRpqRKR6Pof/QgCf7YtoY/GiIG1z7tJmD; 3:rZePjTCtJ9X/7ZwvsUGURBixs7VObcOMTyhqc7juTe9+Nn5ixZd3xhfpnCl+ZvOcb/cIcosicwJU8JMArmAyJtRzbeDrBXv0WlCVf5MmUnYVU5DxANR2PSn2yjzpNQI1O+sfpyLcx/1NC1e9vSFkycygXbxvShnDyLDOtSEtMVVxHw+PbiZWxC0W2ps/I+XaoKfgVoN4iAMHwewBEUepieFXifXK99EpTBZCTZcPj8M=; 25:kNdLx1DEYTXxf1ZlgRQL46K7WVvwMX00I4M5bmqH+SYlgllbvb5upR5V29tkyndtL3iEV47zqWX3v44W5rwFqqpWrWpWyajaMTzJBKc/Fbs+mwzH70J4xw6LULX4bePR1jxYdjQUBkwRKi5h07fhHo/LXjTRVfkix5ZjuL0HpmjpCkflKKzAPDu8zyvquzIXXexPFhwbc+sMs3QvkdylbX52AiPEgp9aqcJu2h4g6AGrxanKjnpndVfYZQPbeJ7jbVw5ZcGuB4b3EpNyt+TKZVleW9mo03zJO5BDAiA5u9APTD00pJ92gkXB8NC1tXHYQurwkXE1vqXMLwJxtbG6wxAdRDx6pizD7zS1KnyYSFiUpPzZNVEqbmRkWGB/4LfIa1rOcjZCKBdNooN4/CvcUG8LF+NUmUdECQge9xbmcqU= X-Microsoft-Antispam: UriScan:;BCL:0;PCL:0;RULEID:;SRVR:DM2PR03MB477; X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:; X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(601004)(2401047)(8121501046)(5005006)(13023025)(13024025)(13015025)(13017025)(13018025)(3002001)(10201501046)(6055026); SRVR:DM2PR03MB477; BCL:0; PCL:0; RULEID:(400006); SRVR:DM2PR03MB477; X-Microsoft-Exchange-Diagnostics: 1; DM2PR03MB477; 4:iH07iXqiIeu4m7fsUJ+LCjus1XN/Hh7A0vyH1gI7+AIo1gPWpMh3YaA69Bjg0OvHHaMAmhRVIYKzgvWfiqvho8vGT6xROWuvEJGQ8k7yI5W8AaMLIds8mQwOmkGgcXNERGwu/SPZNpAel3yD8XAKph7RE6rY+AkbyIGLX7MeEm6+rxRYMmiFzFPe8IrgfqI13rZwtsdMZQUmsZbNKvfgbd6+fXhuBBncd+kxvPbVMTylPMILCFNtBZg9n2amIOnpPukGpIZBSMn9En4Hn2WUHwmg3IibFvvOt5FRPkGi2OAX7+k6OC03QcMmpyqltjZbIjGr/uCSbRvjpqSa/EvZ8KqA7M1PeAMZ/bI0C+9tfpofXLKc57mHopZt0A/0HQa/La049W4iHuooMoymPLC9ubKyDTDxAUtJNLmWELDAHWeS7gP7iabDohfrRmRPIaL18TAFfxqh5s+txNwn5Xq/Q/mcvciCdbC7AxLMu4iQApY= X-Forefront-PRVS: 0941B96580 X-Microsoft-Exchange-Diagnostics: =?utf-8?B?MTtETTJQUjAzTUI0Nzc7MjM6Y1VxRjhrcm9PN3l2M25WRTBCQUVxdlBNTzZV?= =?utf-8?B?dDl0SHE4Y1VJRElQV241WEpXcEZrZ0xBVXlwaFVWa2JUSENjM0NTc2kyZXRE?= =?utf-8?B?RzlrTnNabWQybEVkY1owOE5ORnIrM0lGSnZka0JLeUxHRlprV3VlZnZWQkcv?= =?utf-8?B?anNaK3JrSzNRYzk2bzNKWlNER0dyRGhFd0FHdFkrR0VHNWlFMHRrbjZ3eldF?= =?utf-8?B?MWhFQUhJRUFPTXo5ZnNteEZUeXE3VGhaamdZaW02NUtpYlE0OVlRVEhJWDlr?= =?utf-8?B?YXhhZjNIN1JvdEVGdk9DUFlQZmR2MVl6RmVZdkJuVDBTcHYxY0J2SHhzN25l?= =?utf-8?B?eFdQM3QxblpPRGIxRXZkSlBLYWxzK1N0akhuZDg5N1JZRzlpQVBmNFpkNDd1?= =?utf-8?B?NCt0Z0ZHaEgwVlBuWHdqNUVYNS9TZXFhRkdIMUM4Y0Z1bEEvbWNWNjBCWWtK?= =?utf-8?B?am1JRmV4Qi9ieXhqaUc3RjJTR3JLSDN5dWVnWVZtMjFiTHYyNEVNMDZiN2dw?= =?utf-8?B?ejlySXh6V3I1K3JpL1hkUDJmbGdMaWNvcVVpN0sxcFZiYVFxK09XeGc4MFZ3?= =?utf-8?B?WU10ZzJNa1A5ZGNQWUZ2VGwvVEkwYmFsdXNCaHdaNzhDMG0yMlpraWl5NDRJ?= =?utf-8?B?V1dWWld3VSszY0VReWJNbjl3aEF1aGpSV2ZReXNvMUNuaG96dTVhUUxob2Fh?= =?utf-8?B?WVRRMDJBVE5STk1laDhwaCsvL0U2ejJLaUxBeTdxUjNNVG9MTU9yRUo3aGFU?= =?utf-8?B?NjBmdmhRdW1wMXlJY3FOWno5S2FnbWZaa3c5ZjlJMi8zbnhPRUI1WmlWbzhl?= =?utf-8?B?NGRhbUpRaXE5YWx6Wnh0eVFzeDQyWlRSTlExWjdaQk1YUWgxL3d4ZkZPVkRL?= =?utf-8?B?SENWMVZzdTFVVUZqR3J6QXFKMFF5T1RWcWpyM3ZBWWoyMWJnQVUyTHVIN1Nh?= =?utf-8?B?UGk1WVFQYm1IWWVmVWVzVHF3dlJvOVBnajNWY29pSVNsUmJFNkpIK2Z3Rkgz?= =?utf-8?B?ZUppZTdRNjBTMXc2NHltKzgrQjZ4cXlzdVlkc05VOGdONXFibzhnSnFnTW1z?= =?utf-8?B?aUVGKy9EcWtxQStqd1BNczk5eC9oeXNXODBIQmdiUldNVlRPUW40S2hRQW96?= =?utf-8?B?WDR5eFdoTWRwc28yMlhEUjlvT2NSM0xHelRVaVlFZFM3RXNJV2ZUQVFZWXVV?= =?utf-8?B?cUlMenM0dFNaYW1pdFVZRlNYTkdyNXBwa3FNaXRwY1kwODF5eEJQdEZjVmpn?= =?utf-8?B?SUdzYnRKYnUwbDdWeVBpTndpRzN2SGFjNGhyYnA2MXMyeDVrVkxXZ3lCMVJO?= =?utf-8?B?ZE5ack1JZmErZz09?= X-Microsoft-Exchange-Diagnostics: 1; DM2PR03MB477; 5:Fbdvh44ytB5yqYuk1kpPHxUkHchNBtZ426wIRXmeZBf1WK6uufkASf4vB5WZPVNz4MLlLiYxgi5Oxsai0zpX1DpaNvtMZf+n4jR8mgcQNBEU+BuNOeqncoQaItKRqChuJvdvgWbZQTB1FB3IiLCSbLJUylyQDUl2NJEcG2XSLxQ=; 24:BZ9d+C4mGEf/pADWhJh+RjyxTgGMnuT1xVqG+W1WW4RxxoUC7o7QKpc6EAf6VABu+UVAVr1+dAian3yhtZHb1gN6xEyJLlfo6X5D5ahtIqE=; 7:rBjEk/ds7sRlFupiXmWh+UiKe9yjcMnKCZIHHudquhN233ig9oG/0ixXr3dB5Wfu8T8MW1KdG83NQG++kXDtrD35dpR8n0CblNpFKPulI/1kQFWXu+8dUjH8vpGPSgGyxZe31Rl3o0wUYQ684TQ5OWpbS9HL5x3iHMKMvoKDLu2IIhP0/GwEPdFIJ1RLFVjJ SpamDiagnosticOutput: 1:23 SpamDiagnosticMetadata: NSPM X-MS-Exchange-CrossTenant-OriginalArrivalTime: 13 May 2016 05:18:02.9682 (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: DM2PR03MB477 X-Topics: crypto patch Subject: [lng-odp] [PATCH v3] doc: user-guide: Improve crypto section. X-BeenThere: lng-odp@lists.linaro.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: "The OpenDataPlane \(ODP\) List" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: lng-odp-bounces@lists.linaro.org Sender: "lng-odp" Signed-off-by: Nikhil Agarwal --- doc/users-guide/users-guide.adoc | 84 +++++++++++++++++++++++++++++++--------- 1 file changed, 66 insertions(+), 18 deletions(-) diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 0221634..b3b919d 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -909,24 +909,72 @@ include::users-guide-pktio.adoc[] == Cryptographic services -ODP provides support for cryptographic operations required by various security -protocols (e.g. IPSec). To apply a cryptographic operation to a packet a session -must be created first. Packets processed by a session share the same cryptographic -parameters like algorithms, keys, initialization vectors. A session is created with -*odp_crypto_session_create()* call. After session creation a cryptographic operation -can be applied to a packet using *odp_crypto_operation()* call. -Depending on the session type - synchronous or asynchronous the operation returns -when the operation completed or after the request has been submitted. In the -asynchronous case an operation completion event will be enqueued on the session -completion queue. The completion event conveys the status of the operation and -the result. The application has the responsibility to free the completion event. -The operation arguments specify for each packet the areas which are to be encrypted -or decrypted and authenticated. Also, in asynchronous case a context can be -associated with a given operation and when the operation completion event is -retrieved the associated context can be retrieved. An operation can be executed -in-place, when the output packet is the same as the input packet or the output -packet can be a new packet provided by the application or allocated by the -implementation from the session output pool. +ODP provides APIs to perform cryptographic operations required by various +communication protocols (e.g. IPSec). ODP cryptographic APIs are session based. + +ODP provides APIs for following cryptographic services: + +* Ciphering +* Authentication/data integrity via Keyed-Hashing (HMAC) +* Random number generation +* Crypto capability inquiries + +=== Crypto Sessions + +To apply a cryptographic operation to a packet a session must be created. All +packets processed by a session share the parameters that define the session. + +ODP supports synchronous and asynchronous crypto sessions. For asynchronous +sessions, the output of crypto operation is posted in a queue defined as +completion queue in session parameters. + +ODP crypto APIs support chained operation sessions in which hashing and ciphering +both can be achieved using single session and operation call. The order of cipher +and hashing can be controlled by `auth_cipher_text` session parameter. + +Other Session parameters include algorithms, keys, initialization vector +(optional), encode or decode, output queue for async mode and output packet pool +for allocation of an output packet if required. + +=== Crypto operations + +After session creation, a cryptographic operation can be applied to a packet +using the `odp_crypto_operation()` API. Depending on the implementation +(please note that implementation may perform the crypto operation in synchronous +or asynchronous mode irrespective of preffered mode specified by application in +`pref_mode` session param) the API returns when the operation is completed or +after the request has been submitted. In the case of an async operation, the +`*posted` (output variable of odp_crypto_operation API) will be set to true. + +The operation arguments specify for each packet the areas that are to be +encrypted or decrypted and authenticated. Also, there is an option of overriding +the initialization vector specified in session parameters. + +An operation can be executed in in-place, out-of-place or new buffer mode. +In in-place mode output packet is same as the input packet. +In case of out-of-place mode output packet is different from input packet as +specified by the application, while in new buffer mode implementation allocates +a new output buffer from the session’s output pool. + +User can also specify a context associated with a given operation that will be +retained during async operation and can be retrieved via the completion event. + +Results of an asynchronous session will be posted as completion events to the +session’s completion queue, which can be accessed directly or via ODP scheduler. +The completion event contains the status of the operation and the result. The +application has the responsibility to free the completion event. + +=== Random number Generation + +ODP provides an API `odp_random_data()` to generate random data bytes. It has +an argument to specify whether to use system entropy source for random number +generation or not. + +=== Capability inquiries + +ODP provides an API interface `odp_crypto_capability()` to inquire implementation’s +crypto capabilities. This interface returns a bitmask for supported algorithms +and hardware backed algorithms. include::users-guide-tm.adoc[]