On 11 May 2016 at 20:15, Nikhil Agarwal <[email protected]> wrote:
> From: Nikhil Agarwal <[email protected]> > > Signed-off-by: Nikhil Agarwal <[email protected]> > --- > doc/users-guide/users-guide.adoc | 81 > +++++++++++++++++++++++++++++++--------- > 1 file changed, 63 insertions(+), 18 deletions(-) > > 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. Minor Correction: The synchronous of asynchronous type is decided by the implementation and not by the session type. The odp_crypto_op_mode_t in crypto session params is just a preferred mode but the crypto operation could be performed either in synchronous or asynchronous mode depending upon the implementation. And the application should check for the return of the value of "posted" in odp_crypto_operation() to know whether the operation was performed synchronously or asynchronously. Regards, Bala > 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[] > > -- > 2.7.0 > > > _______________________________________________ > lng-odp mailing list > [email protected] > https://lists.linaro.org/mailman/listinfo/lng-odp > >
_______________________________________________ lng-odp mailing list [email protected] https://lists.linaro.org/mailman/listinfo/lng-odp
