| Message ID | 1462977909-13532-1-git-send-email-Nikhil.Agarwal@linaro.org |
|---|---|
| State | New |
| Headers | show |
A number of grammatical corrections and suggestions for improvement. On Wed, May 11, 2016 at 9:45 AM, Nikhil Agarwal <Nikhil.Agarwal@linaro.org> wrote: > From: Nikhil Agarwal <nikhil.agarwal@linaro.org> > > Signed-off-by: Nikhil Agarwal <nikhil.agarwal@linaro.org> > --- > 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] > + > +=== 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 > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp > >
On 11 May 2016 at 20:15, Nikhil Agarwal <Nikhil.Agarwal@linaro.org> wrote: > From: Nikhil Agarwal <nikhil.agarwal@linaro.org> > > Signed-off-by: Nikhil Agarwal <nikhil.agarwal@linaro.org> > --- > 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. Minor Correction: The synchronous of asynchronous type is decided by the implementation and not by the session type. The odp_crypto_op_mode_t in crypto session params is just a preferred mode but the crypto operation could be performed either in synchronous or asynchronous mode depending upon the implementation. And the application should check for the return of the value of "posted" in odp_crypto_operation() to know whether the operation was performed synchronously or asynchronously. Regards, Bala > 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) > +* 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 > +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 > +both can be achieved using single session and single operation call. > Order of > +cipher and Hashing can be controlled by `auth_cipher_text` session > parameter. > + > +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. > + > +=== 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 > +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 > +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. > +In in-place mode output packet is same as input packet. In case of > out-of-place > +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 > +session’s output pool. > + > +User can also specify a context associated with a given operation which > will be > +retained during async operation and can be retrieved via completion event. > + > +In case of async session `*posted` (output variable of > odp_crypto_operation API) > +will be set to true. Results of asynchronous session will be posted as > completion > +events to session’s completion queues which can be accessed directly or > via ODP > +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. > + > +=== Capability inquiries > + > +ODP provides an interface to inquire implementation’s crypto capabilities. > +This interface returns a bitmask for supported algorithms and hardware > backed > +algorithms. > > include::users-guide-tm.adoc[] > > -- > 2.7.0 > > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp > >
On 11 May 2016 at 19:15, Bill Fischofer <bill.fischofer@linaro.org> wrote: > A number of grammatical corrections and suggestions for improvement. > > On Wed, May 11, 2016 at 9:45 AM, Nikhil Agarwal <Nikhil.Agarwal@linaro.org > > wrote: > >> From: Nikhil Agarwal <nikhil.agarwal@linaro.org> >> >> Signed-off-by: Nikhil Agarwal <nikhil.agarwal@linaro.org> >> --- >> 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 >> lng-odp@lists.linaro.org >> https://lists.linaro.org/mailman/listinfo/lng-odp >> >> > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > 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"
On Thu, May 12, 2016 at 11:25 AM, Mike Holmes <mike.holmes@linaro.org> wrote: > > > On 11 May 2016 at 19:15, Bill Fischofer <bill.fischofer@linaro.org> wrote: > >> A number of grammatical corrections and suggestions for improvement. >> >> On Wed, May 11, 2016 at 9:45 AM, Nikhil Agarwal < >> Nikhil.Agarwal@linaro.org> wrote: >> >>> From: Nikhil Agarwal <nikhil.agarwal@linaro.org> >>> >>> Signed-off-by: Nikhil Agarwal <nikhil.agarwal@linaro.org> >>> --- >>> 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 >>> lng-odp@lists.linaro.org >>> https://lists.linaro.org/mailman/listinfo/lng-odp >>> >>> >> >> _______________________________________________ >> lng-odp mailing list >> lng-odp@lists.linaro.org >> 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" > > >
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 <bill.fischofer@linaro.org> wrote: > > On Thu, May 12, 2016 at 11:25 AM, Mike Holmes <mike.holmes@linaro.org> > wrote: > >> >> >> On 11 May 2016 at 19:15, Bill Fischofer <bill.fischofer@linaro.org> >> wrote: >> >>> A number of grammatical corrections and suggestions for improvement. >>> >>> On Wed, May 11, 2016 at 9:45 AM, Nikhil Agarwal < >>> Nikhil.Agarwal@linaro.org> wrote: >>> >>>> From: Nikhil Agarwal <nikhil.agarwal@linaro.org> >>>> >>>> Signed-off-by: Nikhil Agarwal <nikhil.agarwal@linaro.org> >>>> --- >>>> 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 >>>> lng-odp@lists.linaro.org >>>> https://lists.linaro.org/mailman/listinfo/lng-odp >>>> >>>> >>> >>> _______________________________________________ >>> lng-odp mailing list >>> lng-odp@lists.linaro.org >>> 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" >> >> >> >
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 <nikhil.agarwal@linaro.org> 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 <bill.fischofer@linaro.org> wrote: > >> >> On Thu, May 12, 2016 at 11:25 AM, Mike Holmes <mike.holmes@linaro.org> >> wrote: >> >>> >>> >>> On 11 May 2016 at 19:15, Bill Fischofer <bill.fischofer@linaro.org> >>> wrote: >>> >>>> A number of grammatical corrections and suggestions for improvement. >>>> >>>> On Wed, May 11, 2016 at 9:45 AM, Nikhil Agarwal < >>>> Nikhil.Agarwal@linaro.org> wrote: >>>> >>>>> From: Nikhil Agarwal <nikhil.agarwal@linaro.org> >>>>> >>>>> Signed-off-by: Nikhil Agarwal <nikhil.agarwal@linaro.org> >>>>> --- >>>>> 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 >>>>> lng-odp@lists.linaro.org >>>>> https://lists.linaro.org/mailman/listinfo/lng-odp >>>>> >>>>> >>>> >>>> _______________________________________________ >>>> lng-odp mailing list >>>> lng-odp@lists.linaro.org >>>> 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 > lng-odp@lists.linaro.org > https://lists.linaro.org/mailman/listinfo/lng-odp > >
Good idea Bill, I will add to ARCH call On 12 May 2016 at 14:02, Bala Manoharan <bala.manoharan@linaro.org> 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 <nikhil.agarwal@linaro.org> 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 <bill.fischofer@linaro.org> >> wrote: >> >>> >>> On Thu, May 12, 2016 at 11:25 AM, Mike Holmes <mike.holmes@linaro.org> >>> wrote: >>> >>>> >>>> >>>> On 11 May 2016 at 19:15, Bill Fischofer <bill.fischofer@linaro.org> >>>> wrote: >>>> >>>>> A number of grammatical corrections and suggestions for improvement. >>>>> >>>>> On Wed, May 11, 2016 at 9:45 AM, Nikhil Agarwal < >>>>> Nikhil.Agarwal@linaro.org> wrote: >>>>> >>>>>> From: Nikhil Agarwal <nikhil.agarwal@linaro.org> >>>>>> >>>>>> Signed-off-by: Nikhil Agarwal <nikhil.agarwal@linaro.org> >>>>>> --- >>>>>> 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 >>>>>> lng-odp@lists.linaro.org >>>>>> https://lists.linaro.org/mailman/listinfo/lng-odp >>>>>> >>>>>> >>>>> >>>>> _______________________________________________ >>>>> lng-odp mailing list >>>>> lng-odp@lists.linaro.org >>>>> 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 >> lng-odp@lists.linaro.org >> https://lists.linaro.org/mailman/listinfo/lng-odp >> >> > > _______________________________________________ > lng-odp mailing list > lng-odp@lists.linaro.org > 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"
I have those changes. Please check if i have missed anything. On 12 May 2016 at 23:32, Bala Manoharan <bala.manoharan@linaro.org> 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 <nikhil.agarwal@linaro.org> 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 <bill.fischofer@linaro.org> >> wrote: >> >>> >>> On Thu, May 12, 2016 at 11:25 AM, Mike Holmes <mike.holmes@linaro.org> >>> wrote: >>> >>>> >>>> >>>> On 11 May 2016 at 19:15, Bill Fischofer <bill.fischofer@linaro.org> >>>> wrote: >>>> >>>>> A number of grammatical corrections and suggestions for improvement. >>>>> >>>>> On Wed, May 11, 2016 at 9:45 AM, Nikhil Agarwal < >>>>> Nikhil.Agarwal@linaro.org> wrote: >>>>> >>>>>> From: Nikhil Agarwal <nikhil.agarwal@linaro.org> >>>>>> >>>>>> Signed-off-by: Nikhil Agarwal <nikhil.agarwal@linaro.org> >>>>>> --- >>>>>> 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 >>>>>> lng-odp@lists.linaro.org >>>>>> https://lists.linaro.org/mailman/listinfo/lng-odp >>>>>> >>>>>> >>>>> >>>>> _______________________________________________ >>>>> lng-odp mailing list >>>>> lng-odp@lists.linaro.org >>>>> 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 >> lng-odp@lists.linaro.org >> https://lists.linaro.org/mailman/listinfo/lng-odp >> >> >
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 <nikhil.agarwal@linaro.org> wrote: > I have those changes. Please check if i have missed anything. > > On 12 May 2016 at 23:32, Bala Manoharan <bala.manoharan@linaro.org> 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 <nikhil.agarwal@linaro.org> >> 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 <bill.fischofer@linaro.org> >>> wrote: >>> >>>> >>>> On Thu, May 12, 2016 at 11:25 AM, Mike Holmes <mike.holmes@linaro.org> >>>> wrote: >>>> >>>>> >>>>> >>>>> On 11 May 2016 at 19:15, Bill Fischofer <bill.fischofer@linaro.org> >>>>> wrote: >>>>> >>>>>> A number of grammatical corrections and suggestions for improvement. >>>>>> >>>>>> On Wed, May 11, 2016 at 9:45 AM, Nikhil Agarwal < >>>>>> Nikhil.Agarwal@linaro.org> wrote: >>>>>> >>>>>>> From: Nikhil Agarwal <nikhil.agarwal@linaro.org> >>>>>>> >>>>>>> Signed-off-by: Nikhil Agarwal <nikhil.agarwal@linaro.org> >>>>>>> --- >>>>>>> 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 >>>>>>> lng-odp@lists.linaro.org >>>>>>> https://lists.linaro.org/mailman/listinfo/lng-odp >>>>>>> >>>>>>> >>>>>> >>>>>> _______________________________________________ >>>>>> lng-odp mailing list >>>>>> lng-odp@lists.linaro.org >>>>>> 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 >>> lng-odp@lists.linaro.org >>> https://lists.linaro.org/mailman/listinfo/lng-odp >>> >>> >> >
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) +* 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 +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 +both can be achieved using single session and single operation call. Order of +cipher and Hashing can be controlled by `auth_cipher_text` session parameter. + +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. + +=== 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 +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 +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. +In in-place mode output packet is same as input packet. In case of out-of-place +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 +session’s output pool. + +User can also specify a context associated with a given operation which will be +retained during async operation and can be retrieved via completion event. + +In case of async session `*posted` (output variable of odp_crypto_operation API) +will be set to true. Results of asynchronous session will be posted as completion +events to session’s completion queues which can be accessed directly or via ODP +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. + +=== Capability inquiries + +ODP provides an interface to inquire implementation’s crypto capabilities. +This interface returns a bitmask for supported algorithms and hardware backed +algorithms. include::users-guide-tm.adoc[]