1ibv_flow_action_esp(3) ibv_flow_action_esp(3)
2
6 ibv_flow_action_esp - Flow action esp for verbs
7
9 #include <infiniband/verbs.h>
10 struct ibv_flow_action *
12 ibv_create_flow_action_esp(struct ibv_context *ctx,
13 struct ibv_flow_action_esp *esp);
14 int
15 ibv_modify_flow_action_esp(struct ibv_flow_action *action,
16 struct ibv_flow_action_esp *esp);
17 int ibv_destroy_flow_action(struct ibv_flow_action *action);
19
21 An IPSEC ESP flow steering action allows a flow steering rule to de‐
22 crypt or encrypt a packet after matching. Each action contains the
23 necessary information for this operation in the params argument.
24 After the crypto operation the packet will continue to be processed by
26 flow steering rules until it reaches a final action of discard or de‐
27 livery.
28 After the action is created, then it should be associated with a struct
30 ibv_flow_attr using struct ibv_flow_spec_action_handle flow specifica‐
31 tion. Each action can be associated with multiple flows, and ibv_modi‐
32 fy_flow_action_esp will alter all associated flows simultaneously.
33
35 ctx RDMA device context to create the action on.
36 esp ESP parameters and key material for the action.
38 action Existing action to modify ESP parameters.
40 action Argument
42 struct ibv_flow_action_esp {
43 struct ibv_flow_action_esp_attr *esp_attr;
44 /* See Key Material */
46 uint16_t keymat_proto;
47 uint16_t keymat_len;
48 void *keymat_ptr;
49 /* See Replay Protection */
51 uint16_t replay_proto;
52 uint16_t replay_len;
53 void *replay_ptr;
54 struct ibv_flow_action_esp_encap *esp_encap;
56 uint32_t comp_mask;
58 uint32_t esn;
59 };
60 comp_mask
62 Bitmask specifying what fields in the structure are valid.
63 esn The starting value of the ESP extended sequence number. Valid
65 only if IBV_FLOW_ACTION_ESP_MASK_ESN is set in comp_mask.
66 The 32 bits of esn will be used to compute the full 64 bit ESN
68 required for the AAD construction.
69 When in IB_UVERBS_FLOW_ACTION_ESP_FLAGS_INLINE_CRYPTO mode, the
71 implementation will automatically track rollover of the lower 32
72 bits of the ESN. However, an update of the window is required
73 once every 2^31 sequences.
74 When in IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLOAD mode this
76 value is automatically incremended and it is also used for anti-
77 replay checks.
78 esp_attr
80 See ESP Attributes. May be NULL on modify.
81 keymat_proto, keymat_len, keymat_ptr
83 Describe the key material and encryption standard to use. May
84 be NULL on modify.
85 replay_proto, replay_len, replay_ptr
87 Describe the replay protection scheme used to manage sequence
88 numbers and prevent replay attacks. This field is only valid in
89 full offload mode. May be NULL on modify.
90 esp_encap
92 Describe the encapsulation of ESP packets such as the IP tunnel
93 and/or UDP encapsulation. This field is only valid in full off‐
94 load mode. May be NULL on modify.
95 ESP attributes
97 struct ibv_flow_action_esp_attr {
98 uint32_t spi;
99 uint32_t seq;
100 uint32_t tfc_pad;
101 uint32_t flags;
102 uint64_t hard_limit_pkts;
103 };
104 flags A bitwise OR of the various IB_UVERBS_FLOW_ACTION_ESP_FLAGS de‐
106 scribed below.
107 IB_UVERBS_FLOW_ACTION_ESP_FLAGS_DECRYPT, IB_UVERBS_FLOW_AC‐
109 TION_ESP_FLAGS_ENCRYPT
110 The action will decrypt or encrypt a packet using the
111 provided keying material.
112 The implementation may require that encrypt is only used
114 with an egress flow steering rule, and that decrypt is
115 only used with an ingress flow steering rule.
116 Full Offload Mode
118 When esp_attr flag IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLOAD is set
119 the ESP header and trailer are added and removed automatically during
120 the cipher operation. In this case the esn and spi are used to popu‐
121 late and check the ESP header, and any information from the keymat (eg
122 a IV) is placed in the headers and otherwise handled automatically.
123 For decrypt the hardware will perform anti-replay.
125 Decryption failure will cause the packet to be dropped.
127 This action must be combined with the flow steering that identifies the
129 packets protected by the SA defined in this action.
130 The following members of the esp_attr are used only in full offload
132 mode:
133 spi The value for the ESP Security Parameters Index. It is only
135 used for IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLAOD.
136 seq The initial 32 lower bytes of the sequence number. This is the
138 value of the ESP sequence number. It is only used for
139 IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLAOD.
140 tfc_pad
142 The length of Traffic Flow Confidentiality Padding as specified
143 by RFC4303. If it is set to zero no additional padding is
144 added. It is only used for IB_UVERBS_FLOW_AC‐
145 TION_ESP_FLAGS_FULL_OFFLAOD.
146 hard_limit_pkts
148 The hard lifetime of the SA measured in number of packets. As
149 specified by RFC4301. After this limit is reached the action
150 will drop future packets to prevent breaking the crypto. It is
151 only used for IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLAOD.
152 Inline Crypto Mode
154 When esp_attr flag IB_UVERBS_FLOW_ACTION_ESP_FLAGS_INLINE_CRYPTO is set
155 the user must providate packets with additional headers.
156 For encrypt the packet must contain a fully populated IPSEC packet ex‐
158 cept the data payload is left un-encrypted and there is no IPsec trail‐
159 er. If the IV must be unpredictable, then a flag should indicate the
160 transofrmation such as IB_UVERBS_FLOW_ACTION_IV_ALGO_SEQ.
161 IB_UVERBS_FLOW_ACTION_IV_ALGO_SEQ means that the IV is incremented se‐
163 quentually. If the IV algorithm is supported by HW, then it could pro‐
164 vide support for LSO offload with ESP inline crypto.
165 Finally, the IV used to encrypt the packet replaces the IV field pro‐
167 vided, the payload is encrypted and authenticated, a trailer with pad‐
168 ding is added and the ICV is added as well.
169 For decrypt the packet is authenticated and decrypted in-place, result‐
171 ing in a decrypted IPSEC packet with no trailer. The result of decryp‐
172 tion and authentication can be retrieved from an extended CQ via the
173 ibv_wc_read_XXX(3) function.
174 This mode must be combined with the flow steering including
176 IBV_FLOW_SPEC_IPV4 and IBV_FLOW_SPEC_ESP to match the outer packet
177 headers to ensure that the action is only applied to IPSEC packets with
178 the correct identifiers.
179 For inline crypto, we have some special requirements to maintain a
181 stateless ESN while maintaining the same parameters as software. The
182 system supports offloading a portion of the IPSEC flow, enabling a sin‐
183 gle flow to be split between multiple NICs.
184 Determining the ESN for Ingress Packets
186 We require a “modify” command once every 2^31 packets. This modify
187 command allows the implementation in HW to be stateless, as follows:
188 ESN 1 ESN 2 ESN 3
190 |-------------*-------------|-------------*-------------|-------------*
191 ^ ^ ^ ^ ^ ^
192 ^ - marks where command invoked to update the SA ESN state machine.
194 | - marks the start of the ESN scope (0-2^32-1). At this point move SA
195 ESN “new_window” bit to zero and increment ESN.
196 * - marks the middle of the ESN scope (2^31). At this point move SA
197 ESN “new_window” bit to one.
198 For decryption the implementation uses the following state machine to
200 determine ESN:
201 if (!overlap) {
203 use esn // regardless of packet.seq
204 } else { // new_window
205 if (packet.seq >= 2^31)
206 use esn
207 else // packet.seq < 2^31
208 use esn+1
209 }
210 This mechanism is controlled by the esp_attr flag:
212 IB_UVERBS_FLOW_ACTION_ESP_FLAGS_ESN_NEW_WINDOW
214 This flag is only used to provide stateless ESN support for in‐
215 line crypto. It is used only for IB_UVERBS_FLOW_AC‐
216 TION_ESP_FLAGS_INLINE_CRYPTO and IBV_FLOW_ACTION_ESP_MASK_ESN.
217 Setting this flag indicates that the bottom of the replay window
219 is between 2^31 - 2^32.
220 Key Material for AES GCM (IBV_ACTION_ESP_KEYMAT_AES_GCM)
222 The AES GCM crypto algorithm as defined by RFC4106. This struct is to
223 be provided in keymat_ptr when keymat_proto is set to IBV_AC‐
224 TION_ESP_KEYMAT_AES_GCM.
225 struct ibv_flow_action_esp_aes_keymat_aes_gcm {
227 uint64_t iv;
228 uint32_t iv_algo; /* Use enum ib_uverbs_flow_action_esp_aes_gcm_keymat_iv_algo */
229 uint32_t salt;
231 uint32_t icv_len;
232 uint32_t key_len;
234 uint32_t aes_key[256 / 32];
235 };
236 iv The starting value for the initialization vector used only with
238 IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLOAD encryption as de‐
239 fined in RFC4106. This field is ignored for IB_UVERBS_FLOW_AC‐
240 TION_ESP_FLAGS_INLINE_CRYPTO.
241 For a given key, the IV MUST NOT be reused.
243 iv_algo
245 The algorithm used to transform/generate new IVs with
246 IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLOAD encryption.
247 The only supported value is IB_UVERBS_FLOW_ACTION_IV_ALGO_SEQ to
249 generate sequantial IVs.
250 salt The salt as defined by RFC4106.
252 icv_len
254 The length of the Integrity Check Value in bytes as defined by
255 RFC4106.
256 aes_key, key_len
258 The cipher key data. It must be either 16, 24 or 32 bytes as
259 defined by RFC4106.
260 Bitmap Replay Protection (IBV_FLOW_ACTION_ESP_REPLAY_BMP)
262 A shifting bitmap is used to identify which packets have already been
263 transmitted. Each bit in the bitmap represents a packet, it is set if
264 a packet with this ESP sequence number has been received and it passed
265 authentication. If a packet with the same sequence is received, then
266 the bit is already set, causing replay protection to drop the packet.
267 The bitmap represents a window of size sequence numbers. If a newer
268 sequence number is received, then the bitmap will shift to represent
269 this as in RFC6479. The replay window cannot shift more than 2^31 se‐
270 quence numbers forward.
271 This struct is to be provided in replay_ptr when reply_proto is set to
273 IBV_FLOW_ACTION_ESP_REPLAY_BMP. In this mode reply_ptr and reply_len
274 should point to a struct ibv_flow_action_esp_replay_bmp containing:
275 size : The size of the bitmap.
276 ESP Encapsulation
278 An esp_encap specification is required when eps_attr flags
279 IB_UVERBS_FLOW_ACTION_ESP_FLAGS_TUNNEL is set. It is used to provide
280 the fields for the encapsulation header that is added/removed to/from
281 packets. Tunnel and Transport mode are defined as in RFC4301. UDP en‐
282 capsulation of ESP can be specified by providing the appropriate UDP
283 header.
284 This setting is only used in IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFF‐
286 LOAD mode.
287 struct ibv_flow_action_esp_encap {
289 void *val; /* pointer to struct ibv_flow_xxxx_filter */
290 struct ibv_flow_action_esp_encap *next_ptr;
291 uint16_t len; /* Len of mask and pointer (separately) */
292 uint16_t type; /* Use flow_spec enum */
293 };
294 Each link in the list specifies a network header in the same manner as
296 the flow steering API. The header should be selected from a supported
297 header in `enum ibv_flow_spec_type'.
298
300 Upon success ibv_create_flow_action_esp will return a new struct
301 ibv_flow_action object, on error NULL will be returned and errno will
302 be set.
303 Upon success ibv_modify_action_esp will return 0. On error the value
305 of errno will be returned. If ibv_modify_flow_action fails, it is
306 guaranteed that the last action still holds. If it succeeds, there is
307 a point in the future where the old action is applied on all packets
308 until this point and the new one is applied on all packets from this
309 point and on.
310
312 ibv_create_flow(3), ibv_destroy_action(3), RFC 4106
313 ibv_flow_action_esp(3)