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
