I have those changes. Please check if i have missed anything. On 12 May 2016 at 23:32, Bala Manoharan <[email protected]> wrote:
> 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
