From patchwork Mon May 16 23:00: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: 67910 Delivered-To: patch@linaro.org Received: by 10.140.92.199 with SMTP id b65csp1653439qge; Mon, 16 May 2016 10:31:20 -0700 (PDT) X-Received: by 10.140.205.68 with SMTP id a65mr31943700qhb.6.1463419880219; Mon, 16 May 2016 10:31:20 -0700 (PDT) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id i123si16384363qhc.81.2016.05.16.10.31.19; Mon, 16 May 2016 10:31:20 -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 9F60E6173D; Mon, 16 May 2016 17:31:19 +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 97A726172B; Mon, 16 May 2016 17:31:13 +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 5C88661731; Mon, 16 May 2016 17:31:11 +0000 (UTC) Received: from na01-bn1-obe.outbound.protection.outlook.com (mail-bn1on0054.outbound.protection.outlook.com [157.56.110.54]) by lists.linaro.org (Postfix) with ESMTPS id 18E546162F for ; Mon, 16 May 2016 17:31:10 +0000 (UTC) Received: from BLUPR0301CA0021.namprd03.prod.outlook.com (10.162.113.159) by BY2PR03MB475.namprd03.prod.outlook.com (10.141.141.150) with Microsoft SMTP Server (TLS) id 15.1.492.11; Mon, 16 May 2016 17:31:09 +0000 Received: from BN1AFFO11FD026.protection.gbl (2a01:111:f400:7c10::138) by BLUPR0301CA0021.outlook.office365.com (2a01:111:e400:5259::31) with Microsoft SMTP Server (TLS) id 15.1.497.12 via Frontend Transport; Mon, 16 May 2016 17:31:08 +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 BN1AFFO11FD026.mail.protection.outlook.com (10.58.52.86) with Microsoft SMTP Server (TLS) id 15.1.492.8 via Frontend Transport; Mon, 16 May 2016 17:31:08 +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 u4GHV5RF017294 for ; Mon, 16 May 2016 10:31:07 -0700 From: Nikhil Agarwal To: Date: Tue, 17 May 2016 04:30:44 +0530 Message-ID: <1463439644-6229-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: 131078934688917331; (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)(189002)(199003)(9170700003)(229853001)(2351001)(36756003)(2870700001)(47776003)(2906002)(11100500001)(586003)(6806005)(104016004)(1220700001)(106466001)(450100001)(50986999)(86362001)(77096005)(189998001)(50466002)(107886002)(105596002)(8936002)(87936001)(19580395003)(19580405001)(23676002)(50226002)(5820100001)(110136002)(8676002)(5008740100001)(81166006)(92566002); DIR:OUT; SFP:1101; SCL:1; SRVR:BY2PR03MB475; H:tx30smr01.am.freescale.net; FPR:; SPF:SoftFail; MLV:sfv; MX:1; A:1; LANG:en; X-Microsoft-Exchange-Diagnostics: 1; BN1AFFO11FD026; 1:3akw2f1SFKcXljDNwskCmueeO9RO1t3myRK/mVTNHbiuRMKEJu1HwYIEjETk/Mjuw4qEZbvIvyXBBTpZni2l/gyKul06W1U8auMx59wbdfUA5IqergEtL5KU+IaWCYpaSKV6854KNspx5R/oDsUHBiTZKkjcKmZe7fRJ5XVvE0+Or5CtcuaNBnqWBMOSmp966kRKPsVCh8KXsZtIs5kEDW/E7JsGN3WEcP2PjspYwvnbHQfbXJWPr18NiCv3Dw0VXJzrvVQplA3mZqQRfMtsOS8OZRc+dLdOM/A7h9Z6RPu0qYxkXqRbQzr9hAEjitMkORrXZhwZJSpXZVJ08xbIoJbHYcFlsMKrPfjxvLF1tYUK1XK4xg5m9yeK/5U3NqF4eGNZGcgkwXv+oaGXyy+Fhm5gbj5iiGc+jGYa9TPuOICA/tBA7I5kae0qzmIJ6deuNcoeGrG9qrSbBkb/+qTOFjIG8BI3pfYDEC0u8PYlcvj6xbgnhD7AkP/kY/4VBmWxYuM1Th1mqrjfhaCkUq8Oc29rbZ+pEqv9fp8nO5jKhV8= X-MS-Office365-Filtering-Correlation-Id: fa5eef18-9e6f-4d8b-5c4b-08d37dafde0f X-Microsoft-Exchange-Diagnostics: 1; BY2PR03MB475; 2:xQCAMtYlB14JG9nOubNxX7gy9fpQl3D4F/+b2du7d709/IkeAMzR3enDtkTcugR/ZbHSNm0Lkx44aKutBM3IvHp5y8QdZWJCFGZBDcoPrlR5xeXf5IIi0l5BrL7bbhlmGePiHsHMK4hQr46lJASC5abBS9hh0P7BINvPkr6qhhGAeeSXWCCko/beKfY9YIZI; 3:a3axofB6fwe7dawm8Ytbpi1whNfMBzBHVAZ2ErTV645bj6UciPWnj6/yH48261dw/Mm7Q/5gWOXDT3VXv9DQPPNjOx12pMQol1ebnvKv2JhG808KFA5k36AIygyopurAU3dRAhKRm0Gd+l19qLdvhyCxhhXp/Gy8tC1kUYjH5hARyDz41s1ildtvEkBGHgGfC2pRKUWHnEe5uY6VOOYoe2NfZuIXEztWM66596EIj94=; 25:ND0fu8rnF9bQV9xIfll5/TkW3Fb9B9IwjYF9pjvv0GxQL+UaSPalUhtUIMesYv7Fbszf6KJcndnYBOv6RnGtNxbUDbpz1sUuwQ5PhhGfpfPotEhoCrIzU4IZxvR7wV3Ndtnq2zAlz5ieXIlH0sNzDnoS5N12bcumWMNHHjFU/yHPxIpb6HBmKRvTvvvPuX5+mlJVufRzhWdYlLr+L7tO4YAMURMop/JpVWaiiVUuS2yjDkCqTpKOcB+FAy41AOJ1SYNHAMLwO2Uy6V2M/fl5HuNYw46OIN5K1nsHG3h+hScK8qVXptof0Lt61nGKYRNPqctpCZszD/KWLa2VxYpfYsjYKf8x+VUBA2x1mCDsi+yeplSZ+4WecXYY8vXzo9I5AuANN4Fvy3DQccXU5suLglVuJ3SvnCodhHUdrral81E= X-Microsoft-Antispam: UriScan:;BCL:0;PCL:0;RULEID:;SRVR:BY2PR03MB475; X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:; X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(601004)(2401047)(13024025)(13015025)(13018025)(13017025)(13023025)(5005006)(8121501046)(10201501046)(3002001)(6055026); SRVR:BY2PR03MB475; BCL:0; PCL:0; RULEID:(400006); SRVR:BY2PR03MB475; X-Microsoft-Exchange-Diagnostics: 1; BY2PR03MB475; 4:NKgj5E74NcHaxX5S2Ere3IZYod2kzmPvtO8cTFSOhuovBOlATW5htkcgUjjZBJ5ZITqPQshX1rPt6sv2NUwVmtK3OK39bUDKWiTmybN0aLc+ztf/XMpHnRDqQOnW9scSPCTAq6NR3A7IIcQeQgwhP8Tqcpx3bM7baET+Lfpyyh6GpOvr12O5QIPiml2SkuKKKyepNsKyZEKu2wazIXEdxLq52ovQvizEy2bzUxftShWByFg6CyIbPnsMhTQ+AKERjjPkgR7vMr2pK+m7yNaGQQfXoMOGJMd8tp0HtBFjCLMTmxMrzenqbD+FUXvYSOT2YgLsoWtip9AVk1qjJYXlXsrDCQ3tfzMIsSvO1HnHU6n8vu8q6FEJy+Tde/mlgk01Gqqkxq3Q5LemJh6f3nkTTEKbTcw3p9KXqMV55x+dFyFIFrmT6UUK4rwIZsmWr5+Pod41CP10nsxaqgq3/rYs3/TE3nSEN8ozb6pyZ5RTLTc= X-Forefront-PRVS: 09443CAA7E X-Microsoft-Exchange-Diagnostics: =?utf-8?B?MTtCWTJQUjAzTUI0NzU7MjM6OUNxRU42a25UVXRaY0xQOFdEWUxCR0lWWHRs?= =?utf-8?B?a2xUdzBoYVJmSitsODUwWHh2U2VDdEdGR3VGcS9NQTc4TGU0VVJYNGtqKzRU?= =?utf-8?B?VjBiMU55SzBxUEN0TWorc29VbzUrbXZRNnpPRmlTTEVtazFZc2NBY2d1ZkpB?= =?utf-8?B?bFJGZnFLMmZPZG5ZRElVekxMOTJvci9GWDNVTHFQZXN1NmxwWEdsbVJZOGVJ?= =?utf-8?B?MXNvTll5Q29TR0kweXJSeWdKSkZRT29UVmNtMi9BK20rdDdsZ01IZ0lNZTJo?= =?utf-8?B?NFJ5VUNKS0tFbmY2aS9mMDRobGlObGhlZCtRMzZJSzF1T2RHdVdjTlFmQUxn?= =?utf-8?B?MjRqRzh4YjcwRWcxZkhLSUtPcXVwQklSSkpEVStwY1h3ZVBJSTlWaG9BOTBD?= =?utf-8?B?RVJWN0p6NHVTcnJsYzh2MTdNcGNwNHRSRHRKY1g5bnVnM05WaHo1bVMzdkVr?= =?utf-8?B?OXNhck4rUHJDUFp5OC9RM2FyZ0IzV3ZmbWM2b3BocW1wWGczaU5tR0JIRFVV?= =?utf-8?B?ajJudnNVZWVPOEtKdU5QT0ExdUMzZlUvdEVsa0VlZVdQNEZWUEtqdStYRkVQ?= =?utf-8?B?cmdTQnJ4am5sckxvRTBEVnBrRjV5dDU3czh4VXRwVDhULzZNN0J3UklrVUUw?= =?utf-8?B?MmRNcjcxbTFtaGYveDkwZ3BkYjg5SUQvYTJYUkhDZEVmNytUK3NLWU8xa1Ri?= =?utf-8?B?dm9TZ0JJK3JIbG4rS3JLVGdxMzF6QkVDL3hDUDZDL2ozN3g5SUV5M2M5WVJK?= =?utf-8?B?bFRRS2VtU3RRb3k5SUozRVNZUDhUS1dUZDYvT2dsenhXYVVGZ3FYRU1Oc05G?= =?utf-8?B?bGpSbUJUbWlqYkJQQ05FWjdxaVRNSzJBaVUwakVBaHpQUmU5UnpVZUQ2Q0F2?= =?utf-8?B?K280VEF5bXB3VldLb3l5NzR1WXBNQzVsUGZyVmdPd280TGM3ZGRLNzFBTVVF?= =?utf-8?B?eXRuM3ZNZm1nOXl0RW9KZGZPU0tuRmNYZkh3QnZ1K3B2N3RVM2ZQNU5Lc01D?= =?utf-8?B?N0t1WGJ2UmkzeXNzRjJPU2tCb3lCQUpnWHBuZ1dteUVYc0QwZmdObW1FUFZ3?= =?utf-8?B?MmhnMjdEMC9UQUdWTGRDeEEycmV4dXpKTjJMQjJGTUx4VjQwTWE5NFp6Umpj?= =?utf-8?B?Yk5KVkQ1eVNHNS9IcUxLelpQa1c1eEoyNHEyK0dZNWVtTUpmakczaWFSVHFw?= =?utf-8?B?TGE4enNjbFRDOExwOWhpYzJoRU9VUFNZVkpNb2t2aG5Cd0VUNysrK1ZzOFZ4?= =?utf-8?B?RVNOaGJQWjVVajRQQjhVR2JvN3dVZkVjalcveHY0TW1LZWE3VGxkOVZiZkg3?= =?utf-8?Q?zc2giy0Z4YwsHIwP7wMC9E/vAbB05Bs=3D?= X-Microsoft-Exchange-Diagnostics: 1; BY2PR03MB475; 5:dQisIY+b4AYo5vtpJ1R7TgolKhNVK4pBjRmrBfdaIYhwZvYP5WAuDnUlpTFCaSAbSr+o7cj+ebUZQAURA/B+Zm3MpKZfHvm6Wd6GRCEkAehrFCCmJvuaENsYdRHSUWmvik8sddfKaFWxA+1pmzf8fcaN6FZgduYV7XljsRheMno=; 24:doAWZQyNwxo+wGSxrxSQ1SPHpLvfmBKWuWOqzS5RL7pfgmv67bM1po+3vAeJHjUTS3pijpkWpVM+/9pgqMEjdKiFLsfKvLVMaWu279z1atU=; 7:MY2XxmPUF+luxX/hk3Gt3+NpG5O9N1dpQ2Ef1XZCFNEaRnHLZXc6W0It/2xSeauvn2d3+bPH7m0DVKtjci78rFG5UYrvbaG2nxfjRHs6N3HJFyFV3HNiuisnxMTmJD5nP1ktWeALooyz5FQi56f7e4a15GknfxtYlOY7YX9aMKJcMFUCdLSUdJOBX9sM/EUK SpamDiagnosticOutput: 1:23 SpamDiagnosticMetadata: NSPM X-MS-Exchange-CrossTenant-OriginalArrivalTime: 16 May 2016 17:31:08.5953 (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: BY2PR03MB475 X-Topics: crypto patch Subject: [lng-odp] [PATCH v4] 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 Reviewed-by: Balasubramanian Manoharan --- doc/users-guide/users-guide.adoc | 87 +++++++++++++++++++++++++++++++--------- 1 file changed, 69 insertions(+), 18 deletions(-) diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 0221634..b094802 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -909,24 +909,75 @@ 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 +the completion queue in its session parameters. + +ODP crypto APIs support chained operation sessions in which hashing and ciphering +both can be achieved using a single session and operation call. The order of +cipher and hashing can be controlled by the `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. Applications may indicate a preference +for synchronous or asynchronous processing in the session's `pref_mode` parameter. +However crypto operations may complete synchronously even if an asynchronous +preference is indicated, and applications must examine the `posted` output +parameter from `odp_crypto_operation()` to determine whether the operation has +completed or if an `ODP_EVENT_CRYPTO_COMPL` notification is expected. In the case +of an async operation, the `posted` output parameter 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. + +The application 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 the 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[]