Hi Nikhil, I had some comments on V1 regarding session type. If you agree can you please incorporate on next version.
Regards, Bala On 12 May 2016 at 22:22, Nikhil Agarwal <[email protected]> wrote: > Yes I do agree with mentioning only the API names here. I did that in v2 > of this patch. > > On 12 May 2016 at 22:14, Bill Fischofer <[email protected]> wrote: > >> >> On Thu, May 12, 2016 at 11:25 AM, Mike Holmes <[email protected]> >> wrote: >> >>> >>> >>> On 11 May 2016 at 19:15, Bill Fischofer <[email protected]> >>> wrote: >>> >>>> A number of grammatical corrections and suggestions for improvement. >>>> >>>> On Wed, May 11, 2016 at 9:45 AM, 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. 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) >>>>> >>>> >>>> Add space before (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 >>>>> >>>> >>>> No need to capitalize asynchronous here >>>> >>>> >>>>> +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 >>>>> >>>> >>>> hashing (no caps) >>>> >>>> >>>>> +both can be achieved using single session and single operation call. >>>>> Order of >>>>> >>>> >>>> using a single session and operation call. The order of >>>> >>>> >>>>> +cipher and Hashing can be controlled by `auth_cipher_text` session >>>>> parameter. >>>>> >>>> >>>> hashing >>>> >>>> >>>>> + >>>>> +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. >>>>> >>>> >>>> of an output packet >>>> >>>> >>>>> + >>>>> +=== 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 >>>>> >>>> >>>> using the `odp_crypto_operation()` API. Depending on the session type >>>> (synchronous >>>> or asynchronous) the API... >>>> >>>> >>>>> +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 >>>>> >>>> >>>> [grammar]: 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. >>>>> >>>> >>>> new buffer mode (no caps) >>>> >>>> >>>>> +In in-place mode output packet is same as input packet. In case of >>>>> out-of-place >>>>> >>>> >>>> ...output packet is the same as... >>>> >>>> >>>>> +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 >>>>> >>>> >>>> application, while in new buffer mode the implementation allocates... >>>> >>>> >>>>> +session’s output pool. >>>>> >>>> >>>> the session's output pool. >>>> >>>> >>>>> + >>>>> +User can also specify a context associated with a given operation >>>>> which will be >>>>> >>>> >>>> The user (or The caller) ...a given context that will be >>>> >>>> >>>>> +retained during async operation and can be retrieved via completion >>>>> event. >>>>> >>>> >>>> ...via the completion event. >>>> >>>> >>>>> + >>>>> +In case of async session `*posted` (output variable of >>>>> odp_crypto_operation API) >>>>> >>>> >>>> In the case of an async session, the `*posted` ... >>>> >>>> >>>>> +will be set to true. Results of asynchronous session will be posted >>>>> as completion >>>>> >>>> >>>> Results of an asynchronous session... >>>> >>>> >>>>> +events to session’s completion queues which can be accessed directly >>>>> or via ODP >>>>> >>>> >>>> ...to the session's completion queues, which can be accessed directly >>>> or via the ODP scheduler. >>>> >>>> >>>>> +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. >>>>> >>>> >>>> [Might not be a bad idea to show this API here] >>>> >>> >>> I think we should mention APIs sparingly, the reason for doxygen is that >>> this sort of information rots and it can be easily looked up in the api >>> guide when you come to write an application. >>> If possible I think we need to be writing about how things fit together, >>> what the rational is, what to be aware of etc and not slip too far to >>> having information that is already in the api guide. >>> >> >> True, but I'm not referring to duplicating info but rather mentioning >> APIs by name. Given that we're LTS, their names aren't going to be >> changing. The Guide should give people a good idea where in the Reference >> they need to look for more detail if needed. >> >> >>> >>> Having said that I did propose one simple mechanism that allows sections >>> of the API guide to be automatically pulled into this doc by adding >>> asciidoc markers in a similar way to eh doxygen ones we have already. >>> >> >> We need to revisit this for Tiger Moth but should also discuss whether >> this is OK for RC3 since again this doesn't change any API but just adds >> some documentation markers to files. I suggest we take this up during >> Monday's ARCH call. >> >> >>> >>> >>> >>>> >>>> >>>>> + >>>>> +=== Capability inquiries >>>>> + >>>>> +ODP provides an interface to inquire implementation’s crypto >>>>> capabilities. >>>>> +This interface returns a bitmask for supported algorithms and >>>>> hardware backed >>>>> +algorithms. >>>>> >>>> >>>> [Again, show this API] >>>> >>>> >>>>> >>>>> 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 >>>> >>>> >>> >>> >>> -- >>> Mike Holmes >>> Technical Manager - Linaro Networking Group >>> Linaro.org <http://www.linaro.org/> *│ *Open source software for ARM >>> SoCs >>> "Work should be fun and collaborative, the rest follows" >>> >>> >>> >> > > _______________________________________________ > 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
