1 files changed, 117 insertions, 0 deletions
diff --git a/src/vnet/ipsec/ipsec_itf.h b/src/vnet/ipsec/ipsec_itf.h
new file mode 100644
index 00000000000..93e03f7b477
--- /dev/null
+++ b/src/vnet/ipsec/ipsec_itf.h
@@ -0,0 +1,117 @@
+/*
+ * ipsec_itf.c: IPSec dedicated interface type
+ *
+ * Copyright (c) 2020 Cisco and/or its affiliates.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at:
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef __IPSEC_ITF_H__
+#define __IPSEC_ITF_H__
+
+#include <vnet/tunnel/tunnel.h>
+#include <vnet/ipsec/ipsec_sa.h>
+
+/**
+ * @brief A dedicated IPSec interface type
+ *
+ * In order to support route based VPNs one needs 3 elements: an interface,
+ * for routing to resolve routes through, an SA from the peer to describe
+ * security, and encap, to describe how to reach the peer. There are two
+ * ways one could model this:
+ *
+ *  interface + encap + SA = (interface + encap) + SA =
+ *          ipip-interface + SA transport mode
+ *
+ * or
+ *
+ *  interface + encap + SA = interface + (encap + SA) =
+ *          IPSec-interface + SA tunnel mode
+ *
+ * It's a question of where you add the parenthesis, from the perspective
+ * of the external user the effect is identical.
+ *
+ * The IPsec interface serves as the encap-free interface to be used
+ * in conjunction with an encap-describing tunnel mode SA.
+ *
+ * VPP supports both models, which modelshould you pick?
+ * A route based VPN could impose 0, 1 or 2 encaps. the support matrix for
+ * these use cases is:
+ *
+ *        |  0  |  1  |  2  |
+ *  --------------------------
+ *  ipip  |  N  |  Y  |  Y  |
+ *  ipsec |  P  |  Y  |  P  |
+ *
+ * Where P = potentially.
+ * ipsec could potnetially support 0 encap (i.e. transport mode) since neither
+ * the interface nor the SA *requires* encap. However, for a route beased VPN
+ * to use transport mode is probably wrong since one shouldn't use thransport
+ * mode for transit traffic, since without encap it is not guaranteed to return.
+ * ipsec could potnetially support 2 encaps, but that would require the SA to
+ * describe both, something it does not do at this time.
+ *
+ * ipsec currently does not support:
+ *   - multipoint interfaces
+ * but this is only because it is not yet implemented, rather than it cannot
+ * be done.
+ *
+ * Internally the difference is that the midchain adjacency for the IPSec
+ * interface has no associated encap (whereas for an ipip tunnel it describes
+ * the peer). Consequently, features on the output arc see packets without
+ * any encap. Since the protecting SAs are in tunnel mode,
+ * they apply the encap. The midchain adj is stacked only once the proctecting
+ * SA is known, since only then is the peer known. Otherwise the VLIB graph
+ * nodes used are the same:
+ *    (routing) --> ipX-michain --> espX-encrypt --> adj-midchain-tx --> (routing)
+ * where X = 4 or 6.
+ *
+ * Some benefits to the ipsec interface:
+ *   - it is slightly more efficient since the encapsulating IP header has
+ *     its checksum updated only once.
+ *   - even when the interface is admin up traffic cannot be sent to a peer
+ *     unless the SA is available (since it's the SA that determines the
+ *     encap). With ipip interfaces a client must use the admin state to
+ *     prevent sending until the SA is available.
+ *
+ * The best recommendations i can make are:
+ *   - pick a model that supports your use case
+ *   - make sure any other features you wish to use are supported by the model
+ *   - choose the model that best fits your control plane's model.
+ *
+ *
+ * gun reloaded, fire away.
+ */
+typedef struct ipsec_itf_t_
+{
+  tunnel_mode_t ii_mode;
+  int ii_user_instance;
+  u32 ii_sw_if_index;
+} __clib_packed ipsec_itf_t;
+
+
+extern int ipsec_itf_create (u32 user_instance,
+			     tunnel_mode_t mode, u32 * sw_if_indexp);
+extern int ipsec_itf_delete (u32 sw_if_index);
+
+extern void ipsec_itf_adj_stack (adj_index_t ai, u32 sai);
+extern void ipsec_itf_adj_unstack (adj_index_t ai);
+
+/*
+ * fd.io coding-style-patch-verification: ON
+ *
+ * Local Variables:
+ * eval: (c-set-style "gnu")
+ * End:
+ */
+
+#endif