FD.io VPP  v21.06-3-gbb25fbf28
Vector Packet Processing
ipsec_itf.h
Go to the documentation of this file.
1 /*
2  * ipsec_itf.c: IPSec dedicated interface type
3  *
4  * Copyright (c) 2020 Cisco and/or its affiliates.
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at:
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
18 #ifndef __IPSEC_ITF_H__
19 #define __IPSEC_ITF_H__
20 
21 #include <vnet/tunnel/tunnel.h>
22 #include <vnet/ipsec/ipsec_sa.h>
23 
24 /**
25  * @brief A dedicated IPSec interface type
26  *
27  * In order to support route based VPNs one needs 3 elements: an interface,
28  * for routing to resolve routes through, an SA from the peer to describe
29  * security, and encap, to describe how to reach the peer. There are two
30  * ways one could model this:
31  *
32  * interface + encap + SA = (interface + encap) + SA =
33  * ipip-interface + SA transport mode
34  *
35  * or
36  *
37  * interface + encap + SA = interface + (encap + SA) =
38  * IPSec-interface + SA tunnel mode
39  *
40  * It's a question of where you add the parenthesis, from the perspective
41  * of the external user the effect is identical.
42  *
43  * The IPsec interface serves as the encap-free interface to be used
44  * in conjunction with an encap-describing tunnel mode SA.
45  *
46  * VPP supports both models, which modelshould you pick?
47  * A route based VPN could impose 0, 1 or 2 encaps. the support matrix for
48  * these use cases is:
49  *
50  * | 0 | 1 | 2 |
51  * --------------------------
52  * ipip | N | Y | Y |
53  * ipsec | P | Y | P |
54  *
55  * Where P = potentially.
56  * ipsec could potnetially support 0 encap (i.e. transport mode) since neither
57  * the interface nor the SA *requires* encap. However, for a route beased VPN
58  * to use transport mode is probably wrong since one shouldn't use thransport
59  * mode for transit traffic, since without encap it is not guaranteed to return.
60  * ipsec could potnetially support 2 encaps, but that would require the SA to
61  * describe both, something it does not do at this time.
62  *
63  * ipsec currently does not support:
64  * - multipoint interfaces
65  * but this is only because it is not yet implemented, rather than it cannot
66  * be done.
67  *
68  * Internally the difference is that the midchain adjacency for the IPSec
69  * interface has no associated encap (whereas for an ipip tunnel it describes
70  * the peer). Consequently, features on the output arc see packets without
71  * any encap. Since the protecting SAs are in tunnel mode,
72  * they apply the encap. The midchain adj is stacked only once the proctecting
73  * SA is known, since only then is the peer known. Otherwise the VLIB graph
74  * nodes used are the same:
75  * (routing) --> ipX-michain --> espX-encrypt --> adj-midchain-tx --> (routing)
76  * where X = 4 or 6.
77  *
78  * Some benefits to the ipsec interface:
79  * - it is slightly more efficient since the encapsulating IP header has
80  * its checksum updated only once.
81  * - even when the interface is admin up traffic cannot be sent to a peer
82  * unless the SA is available (since it's the SA that determines the
83  * encap). With ipip interfaces a client must use the admin state to
84  * prevent sending until the SA is available.
85  *
86  * The best recommendations i can make are:
87  * - pick a model that supports your use case
88  * - make sure any other features you wish to use are supported by the model
89  * - choose the model that best fits your control plane's model.
90  *
91  *
92  * gun reloaded, fire away.
93  */
94 typedef struct ipsec_itf_t_
95 {
99 } __clib_packed ipsec_itf_t;
100 
101 
102 extern int ipsec_itf_create (u32 user_instance,
103  tunnel_mode_t mode, u32 * sw_if_indexp);
104 extern int ipsec_itf_delete (u32 sw_if_index);
105 
106 extern void ipsec_itf_adj_stack (adj_index_t ai, u32 sai);
107 extern void ipsec_itf_adj_unstack (adj_index_t ai);
108 
109 extern u8 *format_ipsec_itf (u8 * s, va_list * a);
110 
111 extern ipsec_itf_t *ipsec_itf_get (index_t ii);
112 
113 /*
114  * fd.io coding-style-patch-verification: ON
115  *
116  * Local Variables:
117  * eval: (c-set-style "gnu")
118  * End:
119  */
120 
121 #endif
ipsec_itf_t_::ii_mode
tunnel_mode_t ii_mode
Definition: ipsec_itf.h:96
ipsec_itf_t_::ii_sw_if_index
u32 ii_sw_if_index
Definition: ipsec_itf.h:98
ipsec_itf_get
ipsec_itf_t * ipsec_itf_get(index_t ii)
Definition: ipsec_itf.c:34
ipsec_itf_t_
A dedicated IPSec interface type.
Definition: ipsec_itf.h:94
tunnel.h
mode
vl_api_tunnel_mode_t mode
Definition: gre.api:48
ipsec_sa.h
ipsec_itf_t_::ii_user_instance
int ii_user_instance
Definition: ipsec_itf.h:97
ipsec_itf_adj_stack
void ipsec_itf_adj_stack(adj_index_t ai, u32 sai)
Definition: ipsec_itf.c:64
format_ipsec_itf
u8 * format_ipsec_itf(u8 *s, va_list *a)
Definition: ipsec_format.c:414
index_t
u32 index_t
A Data-Path Object is an object that represents actions that are applied to packets are they are swit...
Definition: dpo.h:43
ipsec_itf_delete
int ipsec_itf_delete(u32 sw_if_index)
Definition: ipsec_itf.c:320
u32
unsigned int u32
Definition: types.h:88
ipsec_itf_create
int ipsec_itf_create(u32 user_instance, tunnel_mode_t mode, u32 *sw_if_indexp)
Definition: ipsec_itf.c:272
adj_index_t
u32 adj_index_t
An index for adjacencies.
Definition: adj_types.h:30
tunnel_mode_t
enum tunnel_mode_t_ tunnel_mode_t
u8
unsigned char u8
Definition: types.h:56
a
a
Definition: bitmap.h:544
ipsec_itf_t
struct ipsec_itf_t_ ipsec_itf_t
A dedicated IPSec interface type.
sw_if_index
vl_api_interface_index_t sw_if_index
Definition: wireguard.api:34
ipsec_itf_adj_unstack
void ipsec_itf_adj_unstack(adj_index_t ai)
Definition: ipsec_itf.c:58