[dpdk-dev] [PATCH 0/2] Document rte_flow security action

[dpdk-dev] [PATCH 0/2] Document rte_flow security action

[Boris Pismenny]

This series updates the documentation regarding the use of rte_flow
security actions for configuring crypto offload. This documentation
attempts to provide guidelines for the use of security sessions with
inline and protocol offloads.

The documentation relfects my understanding of the current status of
inline crypto offload. I've added some documentation for full protocol
offload as well, even though I am not familiar with any existing
implementation.

Full protocol offload is the first encap/decap action in rte_flow.
For example, in IPsec it implies ESP encap/decap. As an encap/decap
offload, it offloads header construction to hardware.
This raises the following question:
Should the rte_flow pattern hold the pattern of headers to add/remove
by hardware?

My answer is yes, because it allows us to describe more complex
encapsulation offloads and their order - [GRE | ESP | TCP] vs.
[ESP | GRE | TCP]. By providing the full pattern we resolve the
ambiguity and define the order of encapsulation. While actions describe
the encapsulation operation related to each header.

The patches are based on the integration branch of dpdk-draft-ipsec.

Boris Pismenny (2):
  doc: add details of rte_flow security actions
  ethdev: update documentation for security action

 doc/guides/prog_guide/rte_flow.rst | 83 +++++++++++++++++++++++++++++++++++++-
 lib/librte_ether/rte_flow.h        | 24 +++++++----
 2 files changed, 97 insertions(+), 10 deletions(-)

-- 
1.8.3.1

[dpdk-dev] [PATCH 1/2] doc: add details of rte_flow security actions

[Boris Pismenny]

Signed-off-by: Boris Pismenny <borisp@mellanox.com>
---
 doc/guides/prog_guide/rte_flow.rst | 83 +++++++++++++++++++++++++++++++++++++-
 1 file changed, 81 insertions(+), 2 deletions(-)

diff --git a/doc/guides/prog_guide/rte_flow.rst b/doc/guides/prog_guide/rte_flow.rst
index 662a912..62da436 100644
--- a/doc/guides/prog_guide/rte_flow.rst
+++ b/doc/guides/prog_guide/rte_flow.rst
@@ -187,7 +187,7 @@ Pattern item
 Pattern items fall in two categories:
 
 - Matching protocol headers and packet data (ANY, RAW, ETH, VLAN, IPV4,
-  IPV6, ICMP, UDP, TCP, SCTP, VXLAN, MPLS, GRE and so on), usually
+  IPV6, ICMP, UDP, TCP, SCTP, VXLAN, MPLS, GRE, ESP and so on), usually
   associated with a specification structure.
 
 - Matching meta-data or affecting pattern processing (END, VOID, INVERT, PF,
@@ -955,6 +955,14 @@ Usage example, fuzzy match a TCPv4 packets:
    | 4     | END      |
    +-------+----------+
 
+Item: ``ESP``
+^^^^^^^^^^^^^
+
+Matches an ESP header.
+
+- ``hdr``: ESP header definition (``rte_esp.h``).
+- Default ``mask`` matches SPI only.
+
 Actions
 ~~~~~~~
 
@@ -972,7 +980,7 @@ They fall in three categories:
   additional processing by subsequent flow rules.
 
 - Other non-terminating meta actions that do not affect the fate of packets
-  (END, VOID, MARK, FLAG, COUNT).
+  (END, VOID, MARK, FLAG, COUNT, SECURITY).
 
 When several actions are combined in a flow rule, they should all have
 different types (e.g. dropping a packet twice is not possible).
@@ -1354,6 +1362,77 @@ rule or if packets are not addressed to a VF in the first place.
    | ``vf``       | VF ID to redirect packets to   |
    +--------------+--------------------------------+
 
+Action: ``SECURITY``
+^^^^^^^^^^^^^^^^^^^^
+
+Perform the security action on flows matched by the pattern items
+according to the configuration of the security session.
+
+This action modifies the payload of matched flows. For INLINE_CRYPTO, the
+security protocol headers and IV are fully provided by the application as
+specified in the flow pattern. The payload of matching packets is
+encrypted on egress, and decrypted and authenticated on ingress.
+For INLINE_PROTOCOL, the security protocol is fully offloaded to HW,
+providing full encapsulation and decapsulation of packets in security
+protocols. The flow pattern specifies both the outer security header fields
+and the inner packet fields. The security session specified in the action
+must match the pattern parameters.
+
+The security session specified in the action must be created on the same
+port as the flow action that is being specified.
+
+The ingress/egress flow attribute should match that specified in the
+security session if the security session supports the definition of the
+direction.
+
+Multiple flows can be configured to use the same security session.
+
+- Non-terminating by default.
+
+.. _table_rte_flow_action_security
+
+.. table:: SECURITY
+
+   +----------------------+--------------------------------------+
+   | Field                | Value                                |
+   +======================+======================================+
+   | ``security_session`` | security session to apply            |
+   +----------------------+--------------------------------------+
+
+Usage example, configure IPsec inline using INLINE_CRYPTO security session:
+
+The encryption algorithm, keys and salt are part of the opaque
+``rte_security_session``. The SA is identified according to the IP and ESP
+fields in the pattern items.
+
+.. _table_rte_flow_item_esp_inline_example:
+
+.. table:: IPsec inline crypto flow pattern items.
+
+   +-------+----------+
+   | Index | Item     |
+   +=======+==========+
+   | 0     | Ethernet |
+   +-------+----------+
+   | 1     | IPv4     |
+   +-------+----------+
+   | 2     | ESP      |
+   +-------+----------+
+   | 3     | END      |
+   +-------+----------+
+
+.. _table_rte_flow_action_esp_inline_example:
+
+.. table:: IPsec inline flow actions.
+
+   +-------+----------+
+   | Index | Action   |
+   +=======+==========+
+   | 0     | SECURITY |
+   +-------+----------+
+   | 1     | END      |
+   +-------+----------+
+
 Negative types
 ~~~~~~~~~~~~~~
 
-- 
1.8.3.1

[dpdk-dev] [PATCH 2/2] ethdev: update documentation for security action

[Boris Pismenny]

Signed-off-by: Boris Pismenny <borisp@mellanox.com>
---
 lib/librte_ether/rte_flow.h | 24 ++++++++++++++++--------
 1 file changed, 16 insertions(+), 8 deletions(-)

diff --git a/lib/librte_ether/rte_flow.h b/lib/librte_ether/rte_flow.h
index dce92ca..48d4fca 100644
--- a/lib/librte_ether/rte_flow.h
+++ b/lib/librte_ether/rte_flow.h
@@ -1043,19 +1043,27 @@ struct rte_flow_action_vf {
 /**
  * RTE_FLOW_ACTION_TYPE_SECURITY
  *
- * Perform security action on define flow as specified by security session.
- * The security session specified in the action must be created on the same port
- * as the flow action that is being specified.
+ * Perform the security action on flows matched by the pattern items
+ * according to the configuration of the security session.
+ *
+ * This action modifies the payload of matched flows. For INLINE_CRYPTO, the
+ * security protocol headers and IV are fully provided by the application as
+ * specified in the flow pattern. The payload of matching packets is
+ * encrypted on egress, and decrypted and authenticated on ingress.
+ * For INLINE_PROTOCOL, the security protocol is fully offloaded to HW,
+ * providing full encapsulation and decapsulation of packets in security
+ * protocols. The flow pattern specifies both the outer security header fields
+ * and the inner packet fields. The security session specified in the action
+ * must match the pattern parameters.
+ *
+ * The security session specified in the action must be created on the same
+ * port as the flow action that is being specified.
  *
  * The ingress/egress flow attribute should match that specified in the
  * security session if the security session supports the definition of the
  * direction.
  *
- * Multiple flows can be configured to use the same security session. For
- * example if the security session specifies an egress IPsec SA, then multiple
- * flows can be specified to that SA. In the case of an ingress IPsec SA then
- * it is only valid to have a single flow to map to that security session.
- *
+ * Multiple flows can be configured to use the same security session.
  *
  * Non-terminating by default.
  */
-- 
1.8.3.1

Re: [dpdk-dev] [PATCH 1/2] doc: add details of rte_flow security actions

[Mcnamara, John]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Boris Pismenny
> Sent: Sunday, September 17, 2017 1:07 PM
> To: dev@dpdk.org
> Cc: akhil.goyal@nxp.com; Doherty, Declan <declan.doherty@intel.com>; De
> Lara Guarch, Pablo <pablo.de.lara.guarch@intel.com>;
> hemant.agrawal@nxp.com; Nicolau, Radu <radu.nicolau@intel.com>;
> borisp@mellanox.com; aviadye@mellanox.com; thomas@monjalon.net;
> sandeep.malik@nxp.com; jerin.jacob@caviumnetworks.com;
> nelio.laranjeiro@6wind.com; liranl@mellanox.com
> Subject: [dpdk-dev] [PATCH 1/2] doc: add details of rte_flow security
> actions
> 
> Signed-off-by: Boris Pismenny <borisp@mellanox.com>


Thanks for the docs. Minor comments below.



> +
> +Multiple flows can be configured to use the same security session.
> +
> +- Non-terminating by default.

This is a single bullet point list and it seems disconnected from the previous
line. Maybe convert it to a sentence instead.



> +
> +.. _table_rte_flow_action_security

This is missing a colon at the end and causes a doc build warning.


> +Usage example, configure IPsec inline using INLINE_CRYPTO security
> session:

This doesn't seem to connect to the following paragraph. Maybe something
like:

    The following is an example of configuring IPsec inline using the
    INLINE_CRYPTO security session:

Reviewed-by: John McNamara <john.mcnamara@intel.com>

Re: [dpdk-dev] [PATCH 2/2] ethdev: update documentation for security action

[Mcnamara, John]

> -----Original Message-----
> From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Boris Pismenny
> Sent: Sunday, September 17, 2017 1:07 PM
> To: dev@dpdk.org
> Cc: akhil.goyal@nxp.com; Doherty, Declan <declan.doherty@intel.com>; De
> Lara Guarch, Pablo <pablo.de.lara.guarch@intel.com>;
> hemant.agrawal@nxp.com; Nicolau, Radu <radu.nicolau@intel.com>;
> borisp@mellanox.com; aviadye@mellanox.com; thomas@monjalon.net;
> sandeep.malik@nxp.com; jerin.jacob@caviumnetworks.com;
> nelio.laranjeiro@6wind.com; liranl@mellanox.com
> Subject: [dpdk-dev] [PATCH 2/2] ethdev: update documentation for security
> action
> 
> Signed-off-by: Boris Pismenny <borisp@mellanox.com>

Acked-by: John McNamara <john.mcnamara@intel.com>