This is an automated email from the git hooks/post-receive script. It was generated because a ref change was pushed to the repository containing the project "".
The branch, api-next has been updated via 4eae04e80a634c17ac276bb06bce468cbe28cde0 (commit) via 3b8515fbd81fe4017632e7e48754a5b99f684d2e (commit) via 42184679185ce0c979e065349360167e3fce6ca0 (commit) via 120e914768f731f18083afd950fba6a6793cca45 (commit) via de32602f12e563b2d5ff10b786c6fd506e74776f (commit) via 8a939edfa992620cf7a5cb495ce44dbc15c709c6 (commit) via 40a2663668ce995e4b6b410ca0d3bf3578d02a67 (commit) via 03203ea8b1c3d142b41f5c332527f20ed29c3040 (commit) via 60105f079350405920462a4b0d59c7e78d9a8492 (commit) via 6e02ad50626de86804cbd62ae467104ae7850220 (commit) via da905ec07e1e50b4d34975a81ea289ec96eba503 (commit) via 29139f725a7d6f2bd9e57a60abf1e55f4ac64c97 (commit) via 7508c5ac906bb7cb1d339b4c5e924f3a18e504ca (commit) via 87fbe7fbf2debf8bc44bfffc3d3a2d1827208452 (commit) via a7463a692a4e2dc311c2d383595adafd01433fa4 (commit) from 91c0b58fc87ba0431241818758cea94438cd5498 (commit)
Those revisions listed above that are new to this repository have not appeared on any other notification email; so we list those revisions in full, below.
- Log ----------------------------------------------------------------- commit 4eae04e80a634c17ac276bb06bce468cbe28cde0 Author: Bill Fischofer bill.fischofer@linaro.org Date: Sun Aug 27 11:34:24 2017 -0500
doc: userguide: document new packet-oriented crypto operations
Crypto now offers two complementary sets of cryptographic APIs: the original parameter-driven API and a new packet-oriented API designed to be more flexible and consistent with the protocol-aware APIs introduced as part of IPsec support. Update the ODP User Guide to include these new APIs.
Signed-off-by: Bill Fischofer bill.fischofer@linaro.org Reviewed-by: Dmitry Eremin-Solenikov dmitry.ereminsolenikov@linaro.org Signed-off-by: Maxim Uvarov maxim.uvarov@linaro.org
diff --git a/doc/users-guide/users-guide-crypto.adoc b/doc/users-guide/users-guide-crypto.adoc index c18e369b..029f47b1 100644 --- a/doc/users-guide/users-guide-crypto.adoc +++ b/doc/users-guide/users-guide-crypto.adoc @@ -1,8 +1,10 @@ == Cryptographic services
-ODP provides APIs to perform cryptographic operations required by various -communication protocols (_e.g.,_ IPsec). ODP cryptographic APIs are session -based. +ODP provides APIs to perform cryptographic operations required by +applications. ODP cryptographic APIs are session based and provide +cryptographic algorithm offload services. ODP also offers cryptographic +protocol offload services for protocols such as IPsec using a different set +of APIs. This section covers the main crypto APIs.
ODP provides APIs for following cryptographic services:
@@ -11,6 +13,11 @@ ODP provides APIs for following cryptographic services: * Random number generation * Crypto capability inquiries
+Ciphering and authentication services are accessible via two complementary +sets of related APIs. The original ODP crypto APIs, and a newer +_packet-oriented_ set of crypto APIs that are designed to be consistent with +the protocol-aware cryptographic services offered by the IPsec API set. + === Crypto Sessions
To apply a cryptographic operation to a packet a session must be created. All @@ -29,18 +36,40 @@ 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.
+The parameters that describe the characteristics of a crypto session are +encoded in the `odp_crypto_session_param_t` struct that is passed to the +`odp_crypto_session_create()` API. A successful call returns an +`odp_crypto_session_t` object that in turn is passed as an input parameter to +crypto operation calls. + +When an application is finished with a crypto session the +`odp_crypto_session_destroy()` API is used to release the resources associated +with an `odp_crypto_session_t`. + === 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. - +in one of two ways. + +==== Parameter-based Crypto Operations +This is the original ODP support for cryptographic operations. The +`odp_crypto_operation()` API takes an input `odp_crypto_op_param_t` struct +that describes the cryptographic operation to be performed. This struct +contains the session to use as well as the input packet the operation is to be +performed on. The caller may either specify an output packet to receive the +operation results or may request that the ODP implementation allocate a new +packet to receive these results from the output pool associated with the +`odp_crypto_session_t`. If the input packet is also used as the output packet, +then an "in place" operation is requested. + +When 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 @@ -61,6 +90,73 @@ 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.
+Upon receipt of an `ODP_EVENT_CRYPTO_COMPL` event, the +`odp_crypto_compl_result()` API is used to retrieve the +`odp_crypto_op_result_t` associated with the event. This result struct in turn +contains: + +* An indication of the success or failure of the crypto operation +* The user context associated with the event +* The output `odp_packet_t`. +* The `odp_crypto_op_status_t` for the requested cipher operation +* The `odp_crypto_op_status_t` for the requested authentication operation + +==== Packet-based Crypto Operations +To simplify the original cryptographic operation request API, as well as to +be more flexible and consistent with the protocol-aware APIs introduced for +IPsec support, a newer packet-oriented set of cryptographic operation +APIs is also provided. Applications may use either API set, but going forward +it is expected that these newer APIs will be the focus of continued +development. + +Instead of a single `odp_crypto_operation()` API, the packet-based form +provides two APIs: `odp_crypto_op()` is the synchronous form while +`odp_crypto_op_enq()` is the asynchronous form. To check which of these are +supported by the ODP implementation, examine the `sync_mode` and `async_mode` +fields in the `odp_crypto_capability_t` struct returned by the +`odp_crypto_capability()` API. + +Both forms take an input array of packets, an optional output array of packets +to receive the results, and an array of `odp_crypto_packet_op_param_t` structs +that describe the operation to be performed on each input packet. As with the +original APIs, the output array may be the same packets to request in-place +operation, or may be specified as `ODP_PACKET_INVALID` to request that ODP +allocate output packets from the pool associated with the +`odp_crypto_session_t` being used. + +The key differences between the `odp_crypto_op_param_t` used by the original +APIs and the `odp_crypto_packet_op_param_t` used by the new APIs are: + +* The original API takes a single `odp_crypto_op_param_t` since it operates on +a single packet whereas the new forms take an array of +`odp_crypto_packet_op_param_t` structs, one for each input packet. + +* The `odp_crypto_packet_op_param_t` does not contain any packet information +since the input and output packets are supplied as API parameters rather than +being encoded in this struct. + +* The `odp_crypto_packet_op_param_t` does not contain a user context field. + +In addition, the `odp_crypto_session_t` field `op_mode` is used instead of +the `pref_mode` field when the packet-oriented APIs are used. If the +`op_mode` is set to `ODP_CRYPTO_SYNC` then the synchronous form of the API +must be used and if `op_mode` is set to `ODP_CRYPTO_ASYNC` then the +asynchronous form of the API must be used. It is an error to attempt to use +a form of the API not properly matched to the mode of the crypto session. + +The output of a packet-based crypto operation is an `odp_packet_t` (one for +each input packet) that is returned either synchronously or +asynchronously. Asynchronous return is in the form of `ODP_EVENT_PACKET` +events that have event subtype `ODP_EVENT_PACKET_CRYPTO`. The packet +associated with such events is obtained via the +`odp_crypto_packet_from_event()` API. The `odp_crypto_result()` API, in turn, +retrieves the `odp_crypto_packet_result_t` from this `odp_packet_t` that +contains: + +* An indication of whether the crypto packet operation was successful or not +* The `odp_crypto_op_status_t` for the requested cipher operation +* The `odp_crypto_op_status_t` for the requested authentication operation + === Random number Generation
ODP provides two APIs to generate various kinds of random data bytes. Random
commit 3b8515fbd81fe4017632e7e48754a5b99f684d2e Merge: 91c0b58f 42184679 Author: Maxim Uvarov maxim.uvarov@linaro.org Date: Mon Sep 4 23:01:05 2017 +0300
Merge branch 'master' into api-next
Signed-off-by: Maxim Uvarov maxim.uvarov@linaro.org
-----------------------------------------------------------------------
Summary of changes: .travis.yml | 65 ++++++++++----- Makefile.am | 9 +- configure.ac | 64 +++++++------- doc/users-guide/users-guide-crypto.adoc | 120 ++++++++++++++++++++++++--- example/m4/configure.m4 | 11 +-- helper/include/odp/helper/ip.h | 8 +- helper/m4/configure.m4 | 9 +- test/Makefile.inc | 2 +- test/common_plat/m4/miscellaneous.m4 | 9 +- test/common_plat/m4/performance.m4 | 9 +- test/common_plat/m4/validation.m4 | 59 ++----------- test/common_plat/validation/api/Makefile.inc | 2 +- test/linux-generic/Makefile.inc | 2 +- test/linux-generic/m4/performance.m4 | 9 +- 14 files changed, 221 insertions(+), 157 deletions(-)
hooks/post-receive
-
git＠git-us.linaro.org