From patchwork Thu May 12 15:46:23 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Nikhil Agarwal X-Patchwork-Id: 67632 Delivered-To: patch@linaro.org Received: by 10.140.92.199 with SMTP id b65csp671659qge; Thu, 12 May 2016 03:16:59 -0700 (PDT) X-Received: by 10.140.97.7 with SMTP id l7mr8631466qge.71.1463048219095; Thu, 12 May 2016 03:16:59 -0700 (PDT) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id 10si8068616qho.34.2016.05.12.03.16.58; Thu, 12 May 2016 03:16:59 -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 B7BE861648; Thu, 12 May 2016 10:16:58 +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 4719861588; Thu, 12 May 2016 10:16:54 +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 8A139615E3; Thu, 12 May 2016 10:16:49 +0000 (UTC) Received: from na01-bl2-obe.outbound.protection.outlook.com (mail-bl2on0084.outbound.protection.outlook.com [65.55.169.84]) by lists.linaro.org (Postfix) with ESMTPS id B4C0A6156A for ; Thu, 12 May 2016 10:16:48 +0000 (UTC) Received: from BY2PR03CA043.namprd03.prod.outlook.com (10.141.249.16) by BL2PR03MB467.namprd03.prod.outlook.com (10.141.92.23) with Microsoft SMTP Server (TLS) id 15.1.485.9; Thu, 12 May 2016 10:16:48 +0000 Received: from BN1AFFO11FD033.protection.gbl (2a01:111:f400:7c10::117) by BY2PR03CA043.outlook.office365.com (2a01:111:e400:2c5d::16) with Microsoft SMTP Server (TLS) id 15.1.497.12 via Frontend Transport; Thu, 12 May 2016 10:16:47 +0000 Received-SPF: SoftFail (protection.outlook.com: domain of transitioning linaro.org discourages use of 192.88.158.2 as permitted sender) Received: from az84smr01.freescale.net (192.88.158.2) by BN1AFFO11FD033.mail.protection.outlook.com (10.58.52.246) with Microsoft SMTP Server (TLS) id 15.1.492.8 via Frontend Transport; Thu, 12 May 2016 10:16:47 +0000 Received: from netperf2.ap.freescale.net ([10.232.133.164]) by az84smr01.freescale.net (8.14.3/8.14.0) with ESMTP id u4CAGj8D022234 for ; Thu, 12 May 2016 03:16:45 -0700 From: Nikhil Agarwal To: Date: Thu, 12 May 2016 21:16:23 +0530 Message-ID: <1463067983-5693-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: 131075218074124108; (91ab9b29-cfa4-454e-5278-08d120cd25b8); () X-Forefront-Antispam-Report: CIP:192.88.158.2; IPV:NLI; CTRY:US; EFV:NLI; SFV:NSPM; SFS:(10009020)(6009001)(2980300002)(199003)(189002)(9170700003)(87936001)(50986999)(6806005)(104016004)(19580395003)(11100500001)(1220700001)(50466002)(5008740100001)(19580405001)(86362001)(36756003)(105596002)(106466001)(23676002)(229853001)(77096005)(2906002)(586003)(189998001)(107886002)(2351001)(5820100001)(110136002)(50226002)(2870700001)(8936002)(47776003)(92566002)(81166006)(450100001); DIR:OUT; SFP:1101; SCL:1; SRVR:BL2PR03MB467; H:az84smr01.freescale.net; FPR:; SPF:SoftFail; MLV:sfv; A:1; MX:1; LANG:en; X-Microsoft-Exchange-Diagnostics: 1; BN1AFFO11FD033; 1:dyD1VUYZt2GPc730+/lJ9zMOtMFiE63dEXHlRSwcKg15nM0v+O+lyr9ZhEVcsiCth4PdUNPglIhYTlyE9xmne1xC6FztAxay78SgMtmHCuopsV8u4iSh9g9rJZgiW66GqVI19Xkp9wlAZle3QsT75U2JJ4kbh7qYolWaShvd3zoHM+BMgFsTnxcUyzSuW+s7xBPEXnzgc0aREcTvtUcnASFk+YBvguCcp5NrQ74PRJ0APSQB2bhvaD/3Of3H/lIwG+EEzdg5D7IKP8nZLPY99bTO5f0dGQtsaE4Ijhs5AjL+vdY+5znPGAWyHjVHQG2D9MwCyv7T4d/nzEYjJ2I7r88qna0r0wFh79hL6lgaUCJP9gG+iUQ8Q0gBvzQ7LU7g7mr8XH3gptk4nLV5wJRfmYDzmIHU49Hldt5NAxx1AyKo9r32C5dlXTZ8Jl07cvIDOUJOhP2DUbUUHIRLCePKmg7qz0qZiTuCM8Ex4Mfe+IEGo1KZzYdj4UiePq/Qo5GvIM1cJtD2DjgOfPg0TjtN/NjWsks9It6Ck0ZMlTKsL7E= X-MS-Office365-Filtering-Correlation-Id: 18883f5a-c43f-4f93-ddea-08d37a4e869e X-Microsoft-Exchange-Diagnostics: 1; BL2PR03MB467; 2:4SXKRZEc/3Wb9gakje/yF/dXmNkTVqc/Mg2Ycl4HdRlvWEKSkKJs/EWm57JenUrzeNgnHNLj+rWqilBbB3MS4Zt36wJMf7C05lbQwYf6y+yNIJU7OPPbFkQ88NSvKCCEbzKttaypP1DmiuGhH8bQ+itvEpSyTwEh0BML13YMt3700p4eGRvSk5yuPuwUlkbV; 3:EC5fxf+nXu01dG6x+sxF/AcEfsFRU2pMmLwX8irR0AUt9WAEF3AWUpW8KFTC3ntn3PZxWOQMC2fswM1DkGEDzuWh7JFoKJYPv/LazKyKwKshvBeWF7HNawUZ+aFOsnbN0v7mkOWe8mjDwlo584kNP6OtmXXCZuxaS4CE37+w1GZg29za1Js5diFZ9XiBjSvLVnLRVaEGGzBcYq3sfCg5UajwIGiDXmdEkfqLpS6sTb4=; 25:nvhj6wTUHAuP6YY58gXqmK2tXDVZEZSq3jqjLF+WBJlXDxn64NS6vo1UyQrf/OC2FzA4E0ff+ybX/JxX+PCXbGsMFnLNq3uYzao3867sj85SYMJaykCsSYOgjz6DbNT/NFbUteY0WM8AQXqzRRD7AO4c18HehzGZqRxAkzUnPhewoyiGKOPmAKtKgqsOfralL1Xmka1u28+sCpNcewbQHv9R3WgQkwiMsHRaNuszA0OcdH6CADUkA4ZzaUTFLkyNNJzSvhEn/jeQuZ0nGpP9U5JOb4KvH98Y82WvTCq/4BcJIyL1qUy/Ksbc4sAUO5Ef38O+HE1OqZl2V9kwy/EOj9V/L2yoe3sUbJ3zjwp2dh+V7gfjHAy1/SOf5JMt73R9DozFsLhrbRea/0zEE3WZZr4pbho8WRuIl32skCnczd0= X-Microsoft-Antispam: UriScan:;BCL:0;PCL:0;RULEID:;SRVR:BL2PR03MB467; X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:; X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(601004)(2401047)(13023025)(13018025)(13015025)(13024025)(5005006)(13017025)(8121501046)(3002001)(10201501046)(6055026); SRVR:BL2PR03MB467; BCL:0; PCL:0; RULEID:(400006); SRVR:BL2PR03MB467; X-Microsoft-Exchange-Diagnostics: 1; BL2PR03MB467; 4:DNB2SxdmKRJYV/XiqeLYsk2kaP0brIqXmWUc9eCJvbmvuqQ7XHS2VPcBQ3ks9SLFM6unvttGjvBnOKTBovPgi3UAnrZgRdhXuPiUnBjePp3XWHSWgmBBd7q1ZvP+4X6vPpb9gRaZRTVmOuvmD2Xmp0/tfpJBUb/e0YET52l39/40B2vTaogWEPbgg+/kzyu7Jn78gRn4xlwap+eeKvnTPbWrhkW1DpzwsWtFK/fWtutnH7ezF/k6H9Y/KQDeAkF4wIlbMR9NCw6Su2vm4f9BMUdGdnXvAzeXp96tURmAYhN8lINdZf1hvtrZq2NvCLF4NvRDYn7sDL/i86zEITaqzt6d/c6R8xYsXBxY+KZuUcTO4nvWlJx510nws5HaQoRxOHkyxBryean1RDHCoG0PKm3jRcgWIDRffJ3yaEgOgwxRo8NIJsdvFX+g8UgoPZe0/5KD7SRl3BEvCSPbMnbcNoj7ooNrC+fUrGH1qZ+5cIg= X-Forefront-PRVS: 0940A19703 X-Microsoft-Exchange-Diagnostics: =?utf-8?B?MTtCTDJQUjAzTUI0Njc7MjM6VThlQlR2ZkJ6SVNwMXg4aFZ4Ti8yV3FpWjcr?= =?utf-8?B?Q0w4Y1Q2TGtoZVNzWDRLaVkwUjVKb0pMMUQzRWR5WlFpUmVJL2tEaVBFc2sy?= =?utf-8?B?ZUtZZWRueXY4dzJRKzQya1IvVzJtSkw2MndKaXdwQTdPelV3anVGdmduTVNm?= =?utf-8?B?V1BkQ1NmMERPK0Vib2lqZnBuY1p4eXY0U0RtZDltNnZEUGJIdXNycHpwcGVv?= =?utf-8?B?WG5CUVVERXl3RzFpM0VtMlgrL1V3UmJDN24wdSt5WlFDOEJGMkJRSnRUc25m?= =?utf-8?B?TkVZd2hrQVJsMGFkZVNuOFdIaEJGamRuMU51bkZ3VlBFRHRnY2N0OGdneWpq?= =?utf-8?B?SzU1TEF2bzhnNTZldjJpQ2xxMUdXSEpQV3RPdEhrRmJ1Wk1SWXJLajBrdjZu?= =?utf-8?B?aiszS0QrU0FHSlBCc1hJUkorVGMzeHNDeFJ4T2pzRUNMSmxrT0o0QkR5dzlK?= =?utf-8?B?eGRZNlhqK21RWC8xYjNKRHZhNldXbk5XbUMxcFdodVIrNytCZzR2cWZ2SWV6?= =?utf-8?B?SnRmcUFvNU9PbUZzQ2E3d3cvMU5ia2RuQ1poTHllUjljZmU1MTIyZTF3b0Fh?= =?utf-8?B?Z2N2NDlGbDJHZ2YreUQwZzBBVXFZUGR6Q0dQZWFQenN1VGZleDVuWGN2TnlP?= =?utf-8?B?QTV1L0xOOFc2NVhvNXVZWGR2MHF0M3dyeVlrOHhIVENydzlFMUdUL0YzM2JT?= =?utf-8?B?SFVvT2pZeDdxU2NCZVcrZW1OYlUwdFRISDZEd0l2emVCaGE3UkQzVmk0dk9Z?= =?utf-8?B?U3ptb0lPd1BXQ1h3Sy9USkNZT2JLWCt3R2tLdjRmNG5pTzdMS0pwQmwrUFZT?= =?utf-8?B?bUhkY2V3MDlqK1plSW5IZXVRTVltT3Z3MWdXTURaOVgrYUVodmpzRWlNdjVu?= =?utf-8?B?WUZYM3Z5ZnU4aG9xMWlURHRLdUthdnlGQ1hGZ05SdWtjRFVyMHFCMmRjRW8r?= =?utf-8?B?V2VXanRDNHdIODZPOTFIRW9zS0FqcUoxWDFxbExnZFhXVVpzWkhTRExtelc0?= =?utf-8?B?UXl2aHNJa24xV2h2OTFvRG5zWmVlNXZhdmV4RGVtYW1kRTF1akF2bU1VSFpW?= =?utf-8?B?YmQ2dXVTZnNHc3RqeFNBaE83Q3NhcDZ6SWFHMjlqckZTWXdtV3V0a1R4a3hF?= =?utf-8?B?WXk5RzN2TzYrZHdhbW9pejh3d3ZtNHdXVWRxQ0dzZi9qRlExdEFYeVNiUURs?= =?utf-8?B?QStjaHNDWVByVHhEVjBMSnNSYUhEcFJkWjBtY29QU3B3OG9BQjFnc2d6aUlm?= =?utf-8?B?Y24vSkFIREFiTzZ1N3BQQitVZjBxQTJRRTB0TU0zNElwajZydm1GNkxBWVN0?= =?utf-8?B?bytjZkpVdmRIZz09?= X-Microsoft-Exchange-Diagnostics: 1; BL2PR03MB467; 5:kFTXbFQDOCN93Oy9jAm9dsDhFi9e40A7vVppU3elpF1fZuW0bgm/tXDLXUPqYFH8wT+yNArt6WI14Ij4rEENm9hqsARtiLFr4pkWw4C2rBVECn1pcEio8MM40IKCLR3k5Hul4BC6bD7rM8Vhjqii1iFxA7WmSW5Fvy5ntVD2tKE=; 24:c0ilIU74D95oYsAGsA6ECSnEdUKt9OaUtr5L+m+7xGK3ATQ5pGf6z3hklDE3KOv+dfkTdt0eYMdkcJjLsonVdYAmH8wbRvsZHr5uveu/XgA=; 7:oWJm9Fa76s+uJ4pGgiWdE5GKA44+2rSciD4DD5bTfezrIpdFTlx/gzKxR4xkN6SKowddiSDzuZHvNK4URhDcG5zZPz9eE9jYmKymt7CR9aagrCTMNauCQBhT4Ryr4w8aiEw/Ik00BoImpWLctWQXISkYbp9ifypZSBa61ep3yKy+trBdv6R3O2fVL/7Bsij3 SpamDiagnosticOutput: 1:23 SpamDiagnosticMetadata: NSPM X-MS-Exchange-CrossTenant-OriginalArrivalTime: 12 May 2016 10:16:47.1940 (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.158.2]; Helo=[az84smr01.freescale.net] X-MS-Exchange-CrossTenant-FromEntityHeader: HybridOnPrem X-MS-Exchange-Transport-CrossTenantHeadersStamped: BL2PR03MB467 X-Topics: crypto patch Subject: [lng-odp] [PATCH v2] 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 | 83 +++++++++++++++++++++++++++++++--------- 1 file changed, 65 insertions(+), 18 deletions(-) diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 0221634..e8d690e 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -909,24 +909,71 @@ 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 +(synchronous or asynchronous) the API returns when the operation is completed +or after the request has been submitted. + +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. + +In the case of an async session, the `*posted` (output variable of +odp_crypto_operation API) will be set to true. 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[]