|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | ARGUMENTS | RETURN VALUE | SEE ALSO | COLOPHON |
|
|
|
ibv_flow_action_esp(3) ibv_flow_action_esp(3)
ibv_flow_action_esp - Flow action esp for verbs
#include <infiniband/verbs.h>
struct ibv_flow_action *
ibv_create_flow_action_esp(struct ibv_context *ctx,
struct ibv_flow_action_esp *esp);
int
ibv_modify_flow_action_esp(struct ibv_flow_action *action,
struct ibv_flow_action_esp *esp);
int ibv_destroy_flow_action(struct ibv_flow_action *action);
An IPSEC ESP flow steering action allows a flow steering rule to
decrypt or encrypt a packet after matching. Each action contains
the necessary information for this operation in the params
argument.
After the crypto operation the packet will continue to be
processed by flow steering rules until it reaches a final action
of discard or delivery.
After the action is created, then it should be associated with a
struct ibv_flow_attr using struct ibv_flow_spec_action_handle flow
specification. Each action can be associated with multiple flows,
and ibv_modify_flow_action_esp will alter all associated flows
simultaneously.
ctx RDMA device context to create the action on.
esp ESP parameters and key material for the action.
action Existing action to modify ESP parameters.
action Argument
struct ibv_flow_action_esp {
struct ibv_flow_action_esp_attr *esp_attr;
/* See Key Material */
uint16_t keymat_proto;
uint16_t keymat_len;
void *keymat_ptr;
/* See Replay Protection */
uint16_t replay_proto;
uint16_t replay_len;
void *replay_ptr;
struct ibv_flow_action_esp_encap *esp_encap;
uint32_t comp_mask;
uint32_t esn;
};
comp_mask
Bitmask specifying what fields in the structure are valid.
esn The starting value of the ESP extended sequence number.
Valid only if IBV_FLOW_ACTION_ESP_MASK_ESN is set in
comp_mask.
The 32 bits of esn will be used to compute the full 64 bit
ESN required for the AAD construction.
When in IB_UVERBS_FLOW_ACTION_ESP_FLAGS_INLINE_CRYPTO mode,
the implementation will automatically track rollover of the
lower 32 bits of the ESN. However, an update of the window
is required once every 2^31 sequences.
When in IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLOAD mode
this value is automatically incremended and it is also used
for anti-replay checks.
esp_attr
See ESP Attributes. May be NULL on modify.
keymat_proto, keymat_len, keymat_ptr
Describe the key material and encryption standard to use.
May be NULL on modify.
replay_proto, replay_len, replay_ptr
Describe the replay protection scheme used to manage
sequence numbers and prevent replay attacks. This field is
only valid in full offload mode. May be NULL on modify.
esp_encap
Describe the encapsulation of ESP packets such as the IP
tunnel and/or UDP encapsulation. This field is only valid
in full offload mode. May be NULL on modify.
ESP attributes
struct ibv_flow_action_esp_attr {
uint32_t spi;
uint32_t seq;
uint32_t tfc_pad;
uint32_t flags;
uint64_t hard_limit_pkts;
};
flags A bitwise OR of the various IB_UVERBS_FLOW_ACTION_ESP_FLAGS
described below.
IB_UVERBS_FLOW_ACTION_ESP_FLAGS_DECRYPT,
IB_UVERBS_FLOW_ACTION_ESP_FLAGS_ENCRYPT
The action will decrypt or encrypt a packet using
the provided keying material.
The implementation may require that encrypt is only
used with an egress flow steering rule, and that
decrypt is only used with an ingress flow steering
rule.
Full Offload Mode
When esp_attr flag IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLOAD is
set the ESP header and trailer are added and removed automatically
during the cipher operation. In this case the esn and spi are
used to populate and check the ESP header, and any information
from the keymat (eg a IV) is placed in the headers and otherwise
handled automatically.
For decrypt the hardware will perform anti-replay.
Decryption failure will cause the packet to be dropped.
This action must be combined with the flow steering that
identifies the packets protected by the SA defined in this action.
The following members of the esp_attr are used only in full
offload mode:
spi The value for the ESP Security Parameters Index. It is
only used for IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLAOD.
seq The initial 32 lower bytes of the sequence number. This is
the value of the ESP sequence number. It is only used for
IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLAOD.
tfc_pad
The length of Traffic Flow Confidentiality Padding as
specified by RFC4303. If it is set to zero no additional
padding is added. It is only used for
IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLAOD.
hard_limit_pkts
The hard lifetime of the SA measured in number of packets.
As specified by RFC4301. After this limit is reached the
action will drop future packets to prevent breaking the
crypto. It is only used for
IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLAOD.
Inline Crypto Mode
When esp_attr flag IB_UVERBS_FLOW_ACTION_ESP_FLAGS_INLINE_CRYPTO
is set the user must providate packets with additional headers.
For encrypt the packet must contain a fully populated IPSEC packet
except the data payload is left un-encrypted and there is no IPsec
trailer. If the IV must be unpredictable, then a flag should
indicate the transofrmation such as
IB_UVERBS_FLOW_ACTION_IV_ALGO_SEQ.
IB_UVERBS_FLOW_ACTION_IV_ALGO_SEQ means that the IV is incremented
sequentually. If the IV algorithm is supported by HW, then it
could provide support for LSO offload with ESP inline crypto.
Finally, the IV used to encrypt the packet replaces the IV field
provided, the payload is encrypted and authenticated, a trailer
with padding is added and the ICV is added as well.
For decrypt the packet is authenticated and decrypted in-place,
resulting in a decrypted IPSEC packet with no trailer. The result
of decryption and authentication can be retrieved from an extended
CQ via the ibv_wc_read_XXX(3) function.
This mode must be combined with the flow steering including
IBV_FLOW_SPEC_IPV4 and IBV_FLOW_SPEC_ESP to match the outer packet
headers to ensure that the action is only applied to IPSEC packets
with the correct identifiers.
For inline crypto, we have some special requirements to maintain a
stateless ESN while maintaining the same parameters as software.
The system supports offloading a portion of the IPSEC flow,
enabling a single flow to be split between multiple NICs.
Determining the ESN for Ingress Packets
We require a “modify” command once every 2^31 packets. This
modify command allows the implementation in HW to be stateless, as
follows:
ESN 1 ESN 2 ESN 3
|-------------*-------------|-------------*-------------|-------------*
^ ^ ^ ^ ^ ^
^ - marks where command invoked to update the SA ESN state
machine.
| - marks the start of the ESN scope (0-2^32-1). At this point
move SA ESN “new_window” bit to zero and increment ESN.
* - marks the middle of the ESN scope (2^31). At this point move
SA ESN “new_window” bit to one.
For decryption the implementation uses the following state machine
to determine ESN:
if (!overlap) {
use esn // regardless of packet.seq
} else { // new_window
if (packet.seq >= 2^31)
use esn
else // packet.seq < 2^31
use esn+1
}
This mechanism is controlled by the esp_attr flag:
IB_UVERBS_FLOW_ACTION_ESP_FLAGS_ESN_NEW_WINDOW
This flag is only used to provide stateless ESN support for
inline crypto. It is used only for
IB_UVERBS_FLOW_ACTION_ESP_FLAGS_INLINE_CRYPTO and
IBV_FLOW_ACTION_ESP_MASK_ESN.
Setting this flag indicates that the bottom of the replay
window is between 2^31 - 2^32.
Key Material for AES GCM (IBV_ACTION_ESP_KEYMAT_AES_GCM)
The AES GCM crypto algorithm as defined by RFC4106. This struct
is to be provided in keymat_ptr when keymat_proto is set to
IBV_ACTION_ESP_KEYMAT_AES_GCM.
struct ibv_flow_action_esp_aes_keymat_aes_gcm {
uint64_t iv;
uint32_t iv_algo; /* Use enum ib_uverbs_flow_action_esp_aes_gcm_keymat_iv_algo */
uint32_t salt;
uint32_t icv_len;
uint32_t key_len;
uint32_t aes_key[256 / 32];
};
iv The starting value for the initialization vector used only
with IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLOAD
encryption as defined in RFC4106. This field is ignored
for IB_UVERBS_FLOW_ACTION_ESP_FLAGS_INLINE_CRYPTO.
For a given key, the IV MUST NOT be reused.
iv_algo
The algorithm used to transform/generate new IVs with
IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLOAD encryption.
The only supported value is
IB_UVERBS_FLOW_ACTION_IV_ALGO_SEQ to generate sequantial
IVs.
salt The salt as defined by RFC4106.
icv_len
The length of the Integrity Check Value in bytes as defined
by RFC4106.
aes_key, key_len
The cipher key data. It must be either 16, 24 or 32 bytes
as defined by RFC4106.
Bitmap Replay Protection (IBV_FLOW_ACTION_ESP_REPLAY_BMP)
A shifting bitmap is used to identify which packets have already
been transmitted. Each bit in the bitmap represents a packet, it
is set if a packet with this ESP sequence number has been received
and it passed authentication. If a packet with the same sequence
is received, then the bit is already set, causing replay
protection to drop the packet. The bitmap represents a window of
size sequence numbers. If a newer sequence number is received,
then the bitmap will shift to represent this as in RFC6479. The
replay window cannot shift more than 2^31 sequence numbers
forward.
This struct is to be provided in replay_ptr when reply_proto is
set to IBV_FLOW_ACTION_ESP_REPLAY_BMP. In this mode reply_ptr and
reply_len should point to a struct ibv_flow_action_esp_replay_bmp
containing: size : The size of the bitmap.
ESP Encapsulation
An esp_encap specification is required when eps_attr flags
IB_UVERBS_FLOW_ACTION_ESP_FLAGS_TUNNEL is set. It is used to
provide the fields for the encapsulation header that is
added/removed to/from packets. Tunnel and Transport mode are
defined as in RFC4301. UDP encapsulation of ESP can be specified
by providing the appropriate UDP header.
This setting is only used in
IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLOAD mode.
struct ibv_flow_action_esp_encap {
void *val; /* pointer to struct ibv_flow_xxxx_filter */
struct ibv_flow_action_esp_encap *next_ptr;
uint16_t len; /* Len of mask and pointer (separately) */
uint16_t type; /* Use flow_spec enum */
};
Each link in the list specifies a network header in the same
manner as the flow steering API. The header should be selected
from a supported header in `enum ibv_flow_spec_type'.
Upon success ibv_create_flow_action_esp will return a new struct
ibv_flow_action object, on error NULL will be returned and errno
will be set.
Upon success ibv_modify_action_esp will return 0. On error the
value of errno will be returned. If ibv_modify_flow_action fails,
it is guaranteed that the last action still holds. If it
succeeds, there is a point in the future where the old action is
applied on all packets until this point and the new one is applied
on all packets from this point and on.
ibv_create_flow(3), ibv_destroy_action(3), RFC 4106
This page is part of the rdma-core (RDMA Core Userspace Libraries
and Daemons) project. Information about the project can be found
at ⟨https://github.com/linux-rdma/rdma-core⟩. If you have a bug
report for this manual page, send it to
linux-rdma@vger.kernel.org. This page was obtained from the
project's upstream Git repository
⟨https://github.com/linux-rdma/rdma-core.git⟩ on 2025-08-11. (At
that time, the date of the most recent commit that was found in
the repository was 2025-08-04.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
ibv_flow_action_esp(3)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|