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. 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. > > >> + >> +=== 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
