I've posted my review comments for v3. I suspect v4 should do it. On Fri, May 13, 2016 at 12:19 AM, Nikhil Agarwal <[email protected]> wrote:
> 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
