[API-NEXT,v6,1/2] api: ipsec: document TFC padding usage

Message ID 1515430837-17818-2-git-send-email-odpbot@yandex.ru
State New
Headers show
Series
  • IPsec TFC packets/padding support
Related show

Commit Message

Github ODP bot Jan. 8, 2018, 5 p.m.
From: Dmitry Eremin-Solenikov <dmitry.ereminsolenikov@linaro.org>


It is possible to include TFC padding into ESP packets. Document usage
of such padding according to RFC.

Signed-off-by: Dmitry Eremin-Solenikov <dmitry.ereminsolenikov@linaro.org>

---
/** Email created from pull request 329 (lumag:ipsec-tfc)
 ** https://github.com/Linaro/odp/pull/329
 ** Patch: https://github.com/Linaro/odp/pull/329.patch
 ** Base sha: 6303c7d0e98fafe0f14c8c4dd9989b3b7633ebf4
 ** Merge commit sha: 52e02806dd3cade37d6594389c800c0f3610a267
 **/
 include/odp/api/spec/ipsec.h | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

Patch

diff --git a/include/odp/api/spec/ipsec.h b/include/odp/api/spec/ipsec.h
index 4c3c498cd..3728e2e26 100644
--- a/include/odp/api/spec/ipsec.h
+++ b/include/odp/api/spec/ipsec.h
@@ -238,6 +238,10 @@  typedef struct odp_ipsec_capability_t {
 	 */
 	odp_support_t retain_header;
 
+	/** Implementation will automatically truncate TFC padding in received
+	 *  packets in ESP tunnel mode */
+	odp_bool_t tfc_padding_truncate;
+
 	/** Maximum number of different destination CoSes in classification
 	 *  pipelining. The same CoS may be used for many SAs. This is equal or
 	 *  less than 'max_cos' capability in classifier API.
@@ -1206,6 +1210,14 @@  typedef struct odp_ipsec_status_t {
  * restored. The amount and content of packet data before the IP header is
  * undefined.
  *
+ * Additional TFC padding might be present after packet contents. For ESP
+ * transport mode ODP does not truncate such padding, it up to an application
+ * to detect and drop it. For ESP tunnel mode, received side can use total
+ * (IPv4) or payload (IPv6) length from internal headers to drop such TFC
+ * padding. If tfc_padding_truncate capability is set, implementation will
+ * truncate received packets automatically. Otherwise ODP application has to
+ * truncate packets manually.
+ *
  * Each successfully transformed packet has a valid value for these metadata
  * regardless of the inner packet parse configuration
  * (odp_ipsec_inbound_config_t):
@@ -1271,6 +1283,11 @@  int odp_ipsec_in(const odp_packet_t pkt_in[], int num_in,
  * with IPSEC, etc headers constructed according to the standards. The amount
  * and content of packet data before the IP header is undefined.
  *
+ * Additional TFC padding might be present after packet payload (see RFC 4303
+ * section 2.7 for the list of requirements). It should be filled by
+ * application before submitting packet to ODP. Such padding will be included
+ * into encrypted packet. Receiver side will skip this padding.
+ *
  * Each successfully transformed packet has a valid value for these metadata:
  * - L3 offset: Offset to the first byte of the (outmost) IP header
  *