From patchwork Wed May 11 14:45:09 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Nikhil Agarwal X-Patchwork-Id: 67551 Delivered-To: patch@linaro.org Received: by 10.140.92.199 with SMTP id b65csp263916qge; Wed, 11 May 2016 07:45:25 -0700 (PDT) X-Received: by 10.140.196.74 with SMTP id r71mr3965351qha.41.1462977925087; Wed, 11 May 2016 07:45:25 -0700 (PDT) Return-Path: Received: from lists.linaro.org (lists.linaro.org. [54.225.227.206]) by mx.google.com with ESMTP id z9si5359692qhz.77.2016.05.11.07.45.24; Wed, 11 May 2016 07:45:25 -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 5FA876164A; Wed, 11 May 2016 14:45:24 +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.9 required=5.0 tests=BAD_ENC_HEADER,BAYES_00, 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 A4FFE61606; Wed, 11 May 2016 14:45:18 +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 2D3D46163B; Wed, 11 May 2016 14:45:16 +0000 (UTC) Received: from na01-bl2-obe.outbound.protection.outlook.com (mail-bl2on0088.outbound.protection.outlook.com [65.55.169.88]) by lists.linaro.org (Postfix) with ESMTPS id 0902C6107B for ; Wed, 11 May 2016 14:45:15 +0000 (UTC) Received: from BY2PR03CA005.namprd03.prod.outlook.com (10.255.93.22) by DM2PR0301MB0605.namprd03.prod.outlook.com (10.160.95.21) with Microsoft SMTP Server (TLS) id 15.1.492.11; Wed, 11 May 2016 14:45:13 +0000 Received: from BN1BFFO11FD028.protection.gbl (10.255.93.4) by BY2PR03CA005.outlook.office365.com (10.255.93.22) with Microsoft SMTP Server (TLS) id 15.1.492.11 via Frontend Transport; Wed, 11 May 2016 14:45:12 +0000 Received-SPF: None (protection.outlook.com: rhuath.am.freescale.net does not designate permitted sender hosts) Received: from az84smr01.freescale.net (192.88.158.2) by BN1BFFO11FD028.mail.protection.outlook.com (10.58.144.91) with Microsoft SMTP Server (TLS) id 15.1.492.8 via Frontend Transport; Wed, 11 May 2016 14:45:10 +0000 Received: from rhuath.am.freescale.net (rhuath.am.freescale.net [10.81.117.101]) by az84smr01.freescale.net (8.14.3/8.14.0) with ESMTP id u4BEj9vj030041; Wed, 11 May 2016 07:45:09 -0700 Received: by rhuath.am.freescale.net (Postfix, from userid 65013428) id 72A9521057; Wed, 11 May 2016 09:45:09 -0500 (CDT) From: Nikhil Agarwal To: Date: Wed, 11 May 2016 09:45:09 -0500 Message-ID: <1462977909-13532-1-git-send-email-Nikhil.Agarwal@linaro.org> X-Mailer: git-send-email 1.6.2.5 X-EOPAttributedMessage: 0 X-Matching-Connectors: 131074515117252317; (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)(428002)(189002)(199003)(9170700003)(47776003)(1220700001)(2906002)(4326007)(36756003)(103686003)(105586002)(106466001)(229853001)(6806005)(2351001)(101416001)(42186005)(90966002)(5008740100001)(586003)(87936001)(960300001)(92566002)(48376002)(110136002)(189998001)(50466002)(50226002)(52956003)(50986999)(46386002)(45336002)(8936002)(5003940100001)(81166006)(19580395003)(19580405001)(16796002)(42882005)(4720700001); DIR:OUT; SFP:1101; SCL:1; SRVR:DM2PR0301MB0605; H:az84smr01.freescale.net; FPR:; SPF:None; MLV:sfv; MX:1; A:0; LANG:en; X-Microsoft-Exchange-Diagnostics: 1; BN1BFFO11FD028; 1:F4nqf4ArZo7zEuuwb9GqkAwxf2cE8Ru6iCYpFvHu1WWzFW9biL0zEGxULVhMlDJ7L8DVG6LqChzfUS5HDL65y1tgLoJdc6Eis6xR6sLRBWu+LcC0PEj55tmvbjXyVPTjzL14KsdtFSQ5tZFacGTzP/I2ZAiEYLjrPbT+moZpCMqmREOvx21zLnGvibERNX/Qo5BKPCDHm+ttLoE8fvtp2Fzd/2I5S1330cy1ADZ8YIsLxf92wXW7wDMxeo6F453OFd2s86JFg0Ruaco88khja1AKwfRMHyl2de3SHJXcDgEIk+O7PPSPCHMwPYqqoDIsMJdzBJMx252m6dKXhi2fXhfGa0b10zMK0rWOdz+/c84Kf5As8C/gKScvQADHzKCyu2ltaXxfqkZyjloAIE0U+MxnsrFrYVhacKRvdLvMWF9qnS7a2zeVttKuzTNIyaCkWW39oOi0CsPn4K0Pi4YLJJ0DQWapz/Et3d+NBBV7lDnADmBjpel4hypgtul/joEq/WDevWG5Bbo5ET7tcgau1xJjCG/5xk1sio+dKSBm30+U1OjIUUj1l2wjapTQyM8L MIME-Version: 1.0 X-MS-Office365-Filtering-Correlation-Id: 1da2f634-ef6a-4533-3d7d-08d379aadb20 X-Microsoft-Exchange-Diagnostics: 1; DM2PR0301MB0605; 2:sfHK7x+R/5cZtrU6D/aYW4MnLyI1RureZtnjBFzYpyW2I+E1WBNqHzXhgov33OqLOMzLtEaJwQuTEDhBX8q2Gj6ZhTAB0iVGTQu5VarcW+0H6tBsJ1ejjv908NaxR+2u0CS4WcwGJiUUChOwvZprd8qro/Iis5OZhj8yaxRoEYKSDBq1tToF+izXA3lIwXB2; 3:ukrOp/H32wL9HGxQXcvjy9SGRm4OvWXLawYUZw2H+cpliYPnxoG8zlPlTen7EwAj+QwTBKH5c6BsF8kFsrVJ8IlQnGRPVOPgu5Y9fjPeu67fLsWpG8XksdyzEu6cfY+tsimdIeWtsZZD3tLZq1XJJ9uV2YNeE5b/JDPMpA4J3ZxLKuWkUuVsXRYxtM+gjXn09q/P953G+Ufojd/gtbGnQyUpzXrXCA2k6LX0mymIZ3o=; 25:AHWBq5VgzXMp5ydAp7akz1rIHbz8/jcWAROcbvZf2BRAcCHnqTdI2bdmsJNNykqE/r1ZwNS+rVUpRmHKvsZkCLdzuBJ7BSYXJEwpyoSIPM+OVG7JRhvl0+Oz2MH9SkesvOFzkxUziVAs96erQDHZaI3A3hGABwriDb2gYXuC4wcnDb6V0/zhfD4eFbCUIb+2aWT61JNz+DMtb0km9ZXeHv2f2cUrItSbRP1ExZXWiWUpx2PQMm0KzNBMaFECWEKflXfWJJL+IaajkHrvXKDU5JoifaBQluzgcJWpwE3jYKivWZpMoKngqpYFHFYEOWgMlHU4nga4jL0YleQ2mbzvVehZcQ4wXrggKaj6Voec38KvGlFGJ1qLG8mXMUMUB5WOoRnP8U5FUMdM033wTzWAs0xnSRlc6awWyummXrU/e37QD5uzhssrI5dgdlreslr6 X-Microsoft-Antispam: UriScan:;BCL:0;PCL:0;RULEID:;SRVR:DM2PR0301MB0605; X-Microsoft-Antispam-PRVS: X-Exchange-Antispam-Report-Test: UriScan:; X-Exchange-Antispam-Report-CFA-Test: BCL:0; PCL:0; RULEID:(601004)(2401047)(5005006)(8121501046)(13017025)(13023025)(13024025)(13015025)(13018025)(10201501046)(3002001)(6055026); SRVR:DM2PR0301MB0605; BCL:0; PCL:0; RULEID:(400006); SRVR:DM2PR0301MB0605; X-Microsoft-Exchange-Diagnostics: 1; DM2PR0301MB0605; 4:iAckY+3yTeO5aHePmhDUwYQLy4qFgFm39gO+GkxWf/yCnBYfn8x2b8iMfCJCDstzNsKkcmarQOAdAUe9FGtKAxFsy5tHPS04b6bl53F/k0/1n4oUJDWYO3aoui8+Vhylmi1cJmjuG+3FBr13btyc2eUjqkID3E/kExC7kQnsY6dXVEYlZi8iVt3vrzAvCJyCFl22HXkc1qF6Cw8yD+b8YJtKSEIvfu9bn47GPULQwrzFemYpz9E0xXJblPaDvUjM4m2eST8gB/1FrmjUo/ug/ivuAF0z2yzWkPdAhVb6YoFdFy55aSmnHavOzVDGEl/SmyxKFJpP0JbE2U1foNtPAEJuB0zsJZQf/bWtAdV1Xw+FyrB7EqDTwQtL1/KzvCFbopZepbSRsgHZ7GDS6/UqL2i96qF+wKpdw5vN0dpWcWGqe8y6gXEWF4xn7vOOzUB5DaNJAwqycZugvOcr3AtNlCivZYIaXjpDrnq7kp5mGAA= X-Forefront-PRVS: 0939529DE2 X-Microsoft-Exchange-Diagnostics: =?us-ascii?Q?1; DM2PR0301MB0605; 23:E1OU/mYaqjIO809kFGI16AqZLA9XoTeXCdOK6jD?= =?us-ascii?Q?JU+tfmrMOIgeOavIW9BH+VPb84OtlYHgK0lrFWGi+bpOpCn71cC37fX8xQEN?= =?us-ascii?Q?rEO5FDyHGv6aucKAyI8PmWvmKu1Ff5pYZqZr92EnHpxv1dhE9K8B+x36zUzU?= =?us-ascii?Q?0K1pjWTDxL58jZSXR9wE/JIbB92MIyy2qEnXZw47kb4ywB+nWnx3Rao1hd3P?= =?us-ascii?Q?y6VFn3tYpAtGamE0o34SnRJLk62TFnnyim2HfdUp/rPjOztaA5YwByFE81T4?= =?us-ascii?Q?reqGMZgFPhWXvLKUmk8SNTIBf9idzh71Z5nHx7U6HGxik/lTb0/fl2QJfQPq?= =?us-ascii?Q?nyoXl6cD1VAA6AFQVvllDjkMwkPkwca9FDRbEHZsUxK53F+q4ZI/Yu1h81sM?= =?us-ascii?Q?9DJ05AGuiGsUlEvD9cAI/0uwRtwdzb/ssbCs0uORSMMCfg1ez1r1h+952srr?= =?us-ascii?Q?90IkPk9p4jXsM188TwWOMqZ7wJGk++357jki1XTLv87HcVXHMxHu6gJaY1XC?= =?us-ascii?Q?crwLllGAK1bJoDJsqOXkzyaKHhzu6fge2tkbq91uUMFWEY+cZ7q5bjjeM15f?= =?us-ascii?Q?OwcGD/FW09tz0n6gEGibzeldwTD8RvfZBHiBawxQIieKd1kzpM52J5R8RUf5?= =?us-ascii?Q?JWT0K8KE9b2YZJc7rQmRWeqB0chiQ6d8y3VGcHuFUZYaLwmqjnJG1hnbcjD2?= =?us-ascii?Q?sQf8IDZXJb1UNH7JnAaLMym8s15H+XAc3mtgBvdx2Z0pwY5mIsqxvPH38zt7?= =?us-ascii?Q?LT9Yc530U3Yqw9ezfqO3ECSWYr8B5qmFTMGVNEB1fHX4A3Zhzj4f/9hzHJfL?= =?us-ascii?Q?GAA4JNuHqKKiT4ctUZM7IA3oMhTLe1mGhufrWbhcqMZWmxS0NhMpQ5SCmjzA?= =?us-ascii?Q?yombA+NU8Bohg+osh7G74rhF2WJvaTgi6F3Rl2XriQB/6vOhyGXxCqiW128X?= =?us-ascii?Q?NWjvn3EGSkgM4FXu4P8O09oWJLjPXh9MlGlEf86KOhEWvy1MS+uVYo4MMN6C?= =?us-ascii?Q?hk/Ka6cfN+SmQeGBZCnI54gymjqvAxXq3fU59newvXUQLHbHE/UjO61+DGlH?= =?us-ascii?Q?mVez/fS5Foak8TAH6hTRI2weMn0kOhXpGGUlkFsUL3fft9ic98w=3D=3D?= X-Microsoft-Exchange-Diagnostics: 1; DM2PR0301MB0605; 5:iVQKkNgkJDEHNvZZQjZwX73N13UzHHI0wovi93gDV9kQ0zX6Y/dHWp4dQIB7cMtpIs3N8qJTayh+HJeb1FyuPchkZFC7DdsuT6A4B92v21+DKTI/A1EAZltfC0hvLRCtKKQT3lZS/NOFwnHqVFo5nIzIUc2kjaIsVXu3L/HOJA4=; 24:5c+k9TyU54P8HQ3Hk3Fn0de+kfVZL2cdwdThET4FDFmB4BDapgfCmP02FmL9SdwgvEMiw8mmjZJrQKvwFAF1i7DUVeMj6Aq9fZ7Uquqsty4=; 7:mgAyulsjK8bgNGg/eXaWUiUHqtxG2eWILqKMazYrOaelHiJzIszXkOLn1c4xdq6Bc8LsyWNv7cVcYcTtRkkwQC+ul/uBU3T/clnjmm5WTQb1JlPIwR+AjVvlP/TxZyhVeUF5Fd9J4nuPMU2VLXLCUN3HCbQZyMj90+sPdSu088iZ/cfCu2tWL23GVI4rvQ4P SpamDiagnosticOutput: 1:23 SpamDiagnosticMetadata: NSPM X-MS-Exchange-CrossTenant-OriginalArrivalTime: 11 May 2016 14:45:10.8204 (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: DM2PR0301MB0605 X-Topics: crypto patch Subject: [lng-odp] [PATCH] 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" From: Nikhil Agarwal Signed-off-by: Nikhil Agarwal --- doc/users-guide/users-guide.adoc | 81 +++++++++++++++++++++++++++++++--------- 1 file changed, 63 insertions(+), 18 deletions(-) -- 2.7.0 diff --git a/doc/users-guide/users-guide.adoc b/doc/users-guide/users-guide.adoc index 0221634..b80ed8c 100644 --- a/doc/users-guide/users-guide.adoc +++ b/doc/users-guide/users-guide.adoc @@ -909,24 +909,69 @@ 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 single operation call. 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 output packet if required. + +=== Crypto operations + +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 API returns when the operation is completed or after the +request has been submitted. + +The operation arguments specify for each packet the areas which 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 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 +session’s output pool. + +User can also specify a context associated with a given operation which will be +retained during async operation and can be retrieved via completion event. + +In case of async session `*posted` (output variable of odp_crypto_operation API) +will be set to true. Results of asynchronous session will be posted as completion +events to session’s completion queues 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 to generate random data bytes. It has argument to specify +whether to use system entropy source for random number generation or not. + +=== Capability inquiries + +ODP provides an interface to inquire implementation’s crypto capabilities. +This interface returns a bitmask for supported algorithms and hardware backed +algorithms. include::users-guide-tm.adoc[]