1ibv_flow_action_esp(3)                                  ibv_flow_action_esp(3)
2
3
4

NAME

6       ibv_flow_action_esp - Flow action esp for verbs
7

SYNOPSIS

9              #include <infiniband/verbs.h>
10
11              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
18              int ibv_destroy_flow_action(struct ibv_flow_action *action);
19

DESCRIPTION

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
25       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
29       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

ARGUMENTS

35       ctx    RDMA device context to create the action on.
36
37       esp    ESP parameters and key material for the action.
38
39       action Existing action to modify ESP parameters.
40
41   action Argument
42              struct ibv_flow_action_esp {
43                  struct ibv_flow_action_esp_attr *esp_attr;
44
45                  /* See Key Material */
46                  uint16_t        keymat_proto;
47                  uint16_t        keymat_len;
48                  void           *keymat_ptr;
49
50                  /* See Replay Protection */
51                  uint16_t        replay_proto;
52                  uint16_t        replay_len;
53                  void           *replay_ptr;
54
55                  struct ibv_flow_action_esp_encap *esp_encap;
56
57                  uint32_t        comp_mask;
58                  uint32_t        esn;
59              };
60
61       comp_mask
62              Bitmask specifying what fields in the structure are valid.
63
64       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
67              The  32  bits of esn will be used to compute the full 64 bit ESN
68              required for the AAD construction.
69
70              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
75              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
79       esp_attr
80              See ESP Attributes.  May be NULL on modify.
81
82       keymat_proto, keymat_len, keymat_ptr
83              Describe  the  key material and encryption standard to use.  May
84              be NULL on modify.
85
86       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
91       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
96   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
105       flags  A bitwise OR of the various IB_UVERBS_FLOW_ACTION_ESP_FLAGS  de‐
106              scribed below.
107
108              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
113                     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
117   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
124       For decrypt the hardware will perform anti-replay.
125
126       Decryption failure will cause the packet to be dropped.
127
128       This action must be combined with the flow steering that identifies the
129       packets protected by the SA defined in this action.
130
131       The following members of the esp_attr are used  only  in  full  offload
132       mode:
133
134       spi    The  value  for  the  ESP Security Parameters Index.  It is only
135              used for IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLAOD.
136
137       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
141       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
147       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
153   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
157       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
162       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
166       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
170       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
175       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
180       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
185   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
189                         ESN 1                       ESN 2                      ESN 3
190              |-------------*-------------|-------------*-------------|-------------*
191              ^             ^             ^             ^             ^             ^
192
193       ^ - 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
199       For decryption the implementation uses the following state  machine  to
200       determine ESN:
201
202              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
211       This mechanism is controlled by the esp_attr flag:
212
213       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
218              Setting this flag indicates that the bottom of the replay window
219              is between 2^31 - 2^32.
220
221   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
226              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
230                  uint32_t   salt;
231                  uint32_t   icv_len;
232
233                  uint32_t   key_len;
234                  uint32_t   aes_key[256 / 32];
235              };
236
237       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
242              For a given key, the IV MUST NOT be reused.
243
244       iv_algo
245              The   algorithm   used   to   transform/generate  new  IVs  with
246              IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLOAD encryption.
247
248              The only supported value is IB_UVERBS_FLOW_ACTION_IV_ALGO_SEQ to
249              generate sequantial IVs.
250
251       salt   The salt as defined by RFC4106.
252
253       icv_len
254              The  length  of the Integrity Check Value in bytes as defined by
255              RFC4106.
256
257       aes_key, key_len
258              The cipher key data.  It must be either 16, 24 or  32  bytes  as
259              defined by RFC4106.
260
261   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
272       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
277   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
285       This  setting is only used in IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFF‐
286       LOAD mode.
287
288              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
295       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

RETURN VALUE

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
304       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

SEE ALSO

312       ibv_create_flow(3), ibv_destroy_action(3), RFC 4106
313
314
315
316                                                        ibv_flow_action_esp(3)
Impressum