JannePeltonen replied on github web page: doc/users-guide/users-guide-ipsec.adoc line 37 @@ -0,0 +1,443 @@ +== IPsec services + +In addition to general cryptographic services, ODP offers offload support for +the IPsec protocol. IPsec is a general term referencing a suite of protocols +and packet formats and as such a full discussion of IPsec is beyond the scope +of this document. See https://tools.ietf.org/html/rfc4301[RFC 4301] and +related RFCs for more detail. This section assumes the reader is already +familiar with IPsec and focuses on explaining the ODP APIs that support it. + +ODP provides APIs for the following IPsec services: + +* General IPsec configuration +* Security Association (SA) configuration and lifecycle management +* Synchronous and Asynchronous IPsec lookaside processing +* Inline processing for full IPsec RX and/or TX offload +* Pipelining for RX traffic +* Fragmentation support for TX traffic +* IPsec event management + +=== IPsec Capabilities and Configuration +As with other features, ODP provides APIs that permit applications to query +platform-specific IPsec capabilities. The `odp_ipsec_capability()` API queries +the general IPsec features available while the `odp_ipsec_cipher_capability()` +and `odp_ipsec_auth_capability()` APIs provide detail on the range of +cipher and authentication algorithms supported by IPsec on this platform. + +General IPsec capabilities that are reported include: + +* The IPsec operation modes supported by this implementation. Different +operation modes may be _not supported_, _supported_, or _preferred_. A +preferred form means that this mode takes advantage of hardware +acceleration features to achieve best performance. +* Whether IPsec AH processing is supported. All ODP platforms must provide +support for IPsec ESP processing, however since AH is relatively rare, it +may not be supported, or supported only via software emulation (_e.g.,_ be +non-preferred). +* Whether IPsec headers should be retained on decrypt for inbound inline
Comment: This should be: "...can be retained..." instead of "...should be retained..." as this is a capability and application chooses whether it wants to retain the headers if the ODP is capable. > Bill Fischofer(Bill-Fischofer-Linaro) wrote: > I'd like to see us all make it a priority to close on #197 next week. I'll > post a doc update once we're all agreed on the precise semantics and > operation flow. So I'm fine with holding off merging this PR until then. >> Dmitry Eremin-Solenikov(lumag) wrote: >> Any update here? @NikhilA-Linaro, @bala-manoharan can you please comment >> wrt your implementations? >>> Dmitry Eremin-Solenikov(lumag) wrote: >>> Well, we do not have #197 merged, so it is too early to depend on that. >>> Also, frankly speaking, this `sa_disabled` warning inside >>> `odp_ipsec_result_t` is a backup plan. It is expected that most of the >>> implementations will report this as a proper `ODP_IPSEC_STATUS` event, >>> carrying this warning bit inside. >>>> Bill Fischofer(Bill-Fischofer-Linaro) wrote: >>>> OK, changed in v6. >>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>> s/default // >>>>>> Bill Fischofer(Bill-Fischofer-Linaro) wrote: >>>>>> OK, corrected in v5. >>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>> In lookaside mode soft limit expiration is reported as `warn` part of >>>>>>> `ipsec_op_status` packet metadata. >>>>>>>> Bill Fischofer(Bill-Fischofer-Linaro) wrote: >>>>>>>> OK, in v4 I've added a new terminal state `SA_Expired` to the FSM and >>>>>>>> have updated the doc to say "expired" rather than "disabled". From the >>>>>>>> expired state the only valid operation is `odp_ipsec_sa_destroy()`. >>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>> Yep. It is just not a 'disabled' state, because we have separate >>>>>>>>> definition for 'disabled SA'. >>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>> IIRC, one can call it only once in NXP case. @NikhilA-Linaro, could >>>>>>>>>> you please comment? >>>>>>>>>>> Bill Fischofer(Bill-Fischofer-Linaro) wrote: >>>>>>>>>>> So how is this indicated in lookaside mode? The whole point of ODP >>>>>>>>>>> providing the limit support is so the application doesn't have to >>>>>>>>>>> track byte/packet counts itself, so it's expected that soft limit >>>>>>>>>>> overruns will happen as part of lookaside processing as well. >>>>>>>>>>>> Bill Fischofer(Bill-Fischofer-Linaro) wrote: >>>>>>>>>>>> If you let yourself run out of gas, the car can stop at >>>>>>>>>>>> inconvenient times, which is why one pays attention to that low >>>>>>>>>>>> fuel warning light. A hard limit is a hard limit. That's what >>>>>>>>>>>> makes it hard. Any other definition seems confusingly fuzzy and >>>>>>>>>>>> unnecessary. >>>>>>>>>>>>> Bill Fischofer(Bill-Fischofer-Linaro) wrote: >>>>>>>>>>>>> I thought the restriction is that you can call this repeatedly as >>>>>>>>>>>>> long as an SA hasn't yet been created. I can change this (and the >>>>>>>>>>>>> state diagram) if that's not the case. >>>>>>>>>>>>>> Bill Fischofer(Bill-Fischofer-Linaro) wrote: >>>>>>>>>>>>>> It's part of the `enum`. In this case L2 would effectively be >>>>>>>>>>>>>> None. >>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>> Only in OUT INLINE mode, if I remember the outcome of >>>>>>>>>>>>>>> discussions correctly. >>>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>>> Ahem. It does not enter disabled state per se: >>>>>>>>>>>>>>>> - It is an undefined behaviour (iow, an application error) to >>>>>>>>>>>>>>>> submit packets to disabled SA >>>>>>>>>>>>>>>> - It is a perfectly valid to submit packets to SA after hard >>>>>>>>>>>>>>>> limit overrun (e.g. because other packets might be already >>>>>>>>>>>>>>>> queued at this moment). >>>>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>>>> It is worth mentioning that depending on the implementation >>>>>>>>>>>>>>>>> and application needs, inline processing might be enabled >>>>>>>>>>>>>>>>> either in both directions or in just one direction. >>>>>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>>>>> TBD: mention that it MUST be called at most once per IPsec >>>>>>>>>>>>>>>>>> application. >>>>>>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>>>>>> L2 does not make sense here, does it? >>>>>>>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>>>>>>> ... parsed after IPsec processing ... >>>>>>>>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>>>>>>>> TBD: describe that some IPsec packets still might be >>>>>>>>>>>>>>>>>>>>> reported via plain PktIO interface (e.g. because of SA >>>>>>>>>>>>>>>>>>>>> lookup failure). They can be resubmitted to IPsec in >>>>>>>>>>>>>>>>>>>>> lookaside mode. >>>>>>>>>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>>>>>>>>> If SA was not determined (because SA lookup failed for >>>>>>>>>>>>>>>>>>>>>> inbound packet), event will be sent to the default queue. >>>>>>>>>>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>>>>>>>>>> ... resulting packet is sent back serving as IPsec >>>>>>>>>>>>>>>>>>>>>>> completion event ... >>>>>>>>>>>>>>>>>>>>>>>> Dmitry Eremin-Solenikov(lumag) wrote: >>>>>>>>>>>>>>>>>>>>>>>> ... in inbound inline operations. https://github.com/Linaro/odp/pull/185#discussion_r148288564 updated_at 2017-11-01 15:15:29
