diff options
Diffstat (limited to 'doc/users-guide/users-guide-crypto.adoc')
| -rw-r--r-- | doc/users-guide/users-guide-crypto.adoc | 81 |
1 files changed, 48 insertions, 33 deletions
diff --git a/doc/users-guide/users-guide-crypto.adoc b/doc/users-guide/users-guide-crypto.adoc index c18e369bb..0f33d6548 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: @@ -26,40 +28,53 @@ 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 +lengths, 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. - - -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. +synchronously or asynchronously. `odp_crypto_op()` is the synchronous API +while `odp_crypto_op_enq()` is the asynchronous API. 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. 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 op_mode field of `odp_crypto_session_t` indicates whether asynchronous +or synchronous operations are used with the session. If `op_mode` is set +to `ODP_CRYPTO_SYNC` then the synchronous API must be used and if `op_mode` +is set to `ODP_CRYPTO_ASYNC` then the asynchronous API must be used. It is +an error to use a form of the API that does not match the mode of the crypto +session. + +The output of a 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 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 @@ -79,7 +94,7 @@ any software generated pseudo-random data. May not be available on all platforms. These form a hierarchy with BASIC being the lowest kind of random and TRUE -behing the highest. The main API for accessing random data is: +being the highest. The main API for accessing random data is: [source,c] ----- |