JannePeltonen replied on github web page:
doc/users-guide/users-guide-ipsec.adoc
line 64
@@ -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
+operations.
+* Whether classification pipelining is supported (to be discussed below).
+
+In addition, capabilities also inform the application of the maximum number
+of destination queues and classification CoS targets supported. These
+will be discussed further later.
+
+==== IPsec Operation Modes
+IPsec operates in one of three modes: Synchronous, Asynchronous, and Inline.
+
+==== Lookaside Processing
+Synchronous and Asynchronous are types of _lookaside_ processing. In lookaside
+mode, the application receives (or creates) an IPsec packet and then uses ODP
+to perform one of two functions:
+
+* To decrypt an IPsec packet into a "normal" packet
+* To take a "normal" packet and encrypt it into an IPsec packet.
+
+This process may be performed _synchronously_ with the APIs `odp_ipsec_in()`
+(to decrypt) and `odp_ipsec_out()` (to encrypt). Upon return from these calls
+the requested packet transformation is complete, or an error return code
+indicates that it could not be performed (_e.g.,_ packet decryption failed).
+
+Synchronous processing may be preferred if the application has a large number
+of worker threads so that blocking any individual worker while IPsec processing
+is performed represents a reasonable design. The alternative is to use
+_asynchronous_ forms of these APIs:
Comment:
Maybe it should be made more clear somewhere that the synchronous processing
calls are allowed only in the synchronous operating mode and asynchronous calls
in asynchronous and inline operation mode (and inline calls only in the inline
mode).
> JannePeltonen wrote
> This dummy packet stuff is not yet (if ever?) part of the API spec. I think
> this patch should be in sync with what is the current state of api-next,
> which still uses the status event for indicating SA disable completion.
>> JannePeltonen wrote
>> "This call" could be replaced with odp_ipsec_sa_disable() to make the text
>> more clear.
>>> JannePeltonen wrote
>>> I think this may give the impression that calling odp_ipsec_sa_disable() is
>>> optional, when in fact it is mandatory before odp_ipsec_sa_destroy().
>>>> JannePeltonen wrote
>>>> According to the API spec soft limit alerts do not need to be edge
>>>> triggered. The spec says: "It's implementation defined how many times soft
>>>> lifetime expiration is reported: only once, first N or all packets
>>>> following the limit crossing."
>>>>> JannePeltonen wrote
>>>>> Is it clear enough here that the mtu error bit is set only when MTU
>>>>> checking was requested and not in case fragmentation offload was
>>>>> requested?
>>>>>> JannePeltonen wrote
>>>>>> Same comment as for odp_ipsec_{in,out}(), the description of the return
>>>>>> code is not correct.
>>>>>>> JannePeltonen wrote
>>>>>>> The return code does not tell whether the application of the SA was
>>>>>>> successful but how many input packets were consumed by the operation.
>>>>>>> The per-packet operation status is retrieved via the odp_ipsec_result()
>>>>>>> api for the outputted packets, which will be available only when the
>>>>>>> function succeeds.
>>>>>>>> JannePeltonen wrote
>>>>>>>> The operating mode is a global setting, not per-SA setting as the text
>>>>>>>> implies. And the relevant type is odp_ipsec_op_mode_t, not
>>>>>>>> odp_ipsec_mode_t which is for selecting between tunnel and transport
>>>>>>>> mode.
>>>>>>>>> JannePeltonen wrote
>>>>>>>>> "How this is done" sounds a bit awkward as it is not clear what
>>>>>>>>> "this" refers to (the way the IPsec services are used). Maybe the
>>>>>>>>> sentence should be reworded.
>>>>>>>>>> JannePeltonen wrote
>>>>>>>>>> Would "minimum size" be better than "size" here?
>>>>>>>>>>> JannePeltonen wrote
>>>>>>>>>>> The queue is not only for status events but for ipsec packet events
>>>>>>>>>>> too. Maybe just remove the word "status"?
>>>>>>>>>>>> JannePeltonen wrote
>>>>>>>>>>>> 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_r148319066
updated_at 2017-11-01 16:58:20
