.\" Automatically generated by Pandoc 3.1.11.1
.\"
.TH "ibv_flow_action_esp" "3" "" "" ""
.SH NAME
ibv_flow_action_esp \- Flow action esp for verbs
.SH SYNOPSIS
.IP
.EX
#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);
.EE
.SH DESCRIPTION
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
\f[I]params\f[R] argument.
.PP
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.
.PP
After the action is created, then it should be associated with a
\f[I]struct ibv_flow_attr\f[R] using \f[I]struct
ibv_flow_spec_action_handle\f[R] flow specification.
Each action can be associated with multiple flows, and
\f[I]ibv_modify_flow_action_esp\f[R] will alter all associated flows
simultaneously.
.SH ARGUMENTS
.TP
\f[I]ctx\f[R]
RDMA device context to create the action on.
.TP
\f[I]esp\f[R]
ESP parameters and key material for the action.
.TP
\f[I]action\f[R]
Existing action to modify ESP parameters.
.SS \f[I]action\f[R] Argument
.IP
.EX
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;
};
.EE
.TP
\f[I]comp_mask\f[R]
Bitmask specifying what fields in the structure are valid.
.TP
\f[I]esn\f[R]
The starting value of the ESP extended sequence number.
Valid only if \f[I]IBV_FLOW_ACTION_ESP_MASK_ESN\f[R] is set in
\f[I]comp_mask\f[R].
.RS
.PP
The 32 bits of \f[I]esn\f[R] will be used to compute the full 64 bit ESN
required for the AAD construction.
.PP
When in \f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_INLINE_CRYPTO\f[R] 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\[ha]31
sequences.
.PP
When in \f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLOAD\f[R] mode this
value is automatically incremended and it is also used for anti\-replay
checks.
.RE
.TP
\f[I]esp_attr\f[R]
See \f[I]ESP Attributes\f[R].
May be NULL on modify.
.TP
\f[I]keymat_proto\f[R], \f[I]keymat_len\f[R], \f[I]keymat_ptr\f[R]
Describe the key material and encryption standard to use.
May be NULL on modify.
.TP
\f[I]replay_proto\f[R], \f[I]replay_len\f[R], \f[I]replay_ptr\f[R]
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.
.TP
\f[I]esp_encap\f[R]
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.
.SS ESP attributes
.IP
.EX
struct ibv_flow_action_esp_attr {
    uint32_t   spi;
    uint32_t   seq;
    uint32_t   tfc_pad;
    uint32_t   flags;
    uint64_t   hard_limit_pkts;
};
.EE
.TP
\f[I]flags\f[R]
A bitwise OR of the various \f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS\f[R]
described below.
.RS
.TP
\f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_DECRYPT\f[R], \f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_ENCRYPT\f[R]
The action will decrypt or encrypt a packet using the provided keying
material.
.RS
.PP
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.
.RE
.RE
.SS Full Offload Mode
When \f[I]esp_attr\f[R] flag
\f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLOAD\f[R] is set the ESP
header and trailer are added and removed automatically during the cipher
operation.
In this case the \f[I]esn\f[R] and \f[I]spi\f[R] are used to populate
and check the ESP header, and any information from the \f[I]keymat\f[R]
(eg a IV) is placed in the headers and otherwise handled automatically.
.PP
For decrypt the hardware will perform anti\-replay.
.PP
Decryption failure will cause the packet to be dropped.
.PP
This action must be combined with the flow steering that identifies the
packets protected by the SA defined in this action.
.PP
The following members of the esp_attr are used only in full offload
mode:
.TP
\f[I]spi\f[R]
The value for the ESP Security Parameters Index.
It is only used for
\f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLAOD\f[R].
.TP
\f[I]seq\f[R]
The initial 32 lower bytes of the sequence number.
This is the value of the ESP sequence number.
It is only used for
\f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLAOD\f[R].
.TP
\f[I]tfc_pad\f[R]
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
\f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLAOD\f[R].
.TP
\f[I]hard_limit_pkts\f[R]
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
\f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLAOD\f[R].
.SS Inline Crypto Mode
When \f[I]esp_attr\f[R] flag
\f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_INLINE_CRYPTO\f[R] is set the user
must providate packets with additional headers.
.PP
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 \f[I]IB_UVERBS_FLOW_ACTION_IV_ALGO_SEQ\f[R].
.PP
\f[I]IB_UVERBS_FLOW_ACTION_IV_ALGO_SEQ\f[R] 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.
.PP
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.
.PP
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 \f[I]ibv_wc_read_XXX(3)\f[R] function.
.PP
This mode must be combined with the flow steering including
\f[I]IBV_FLOW_SPEC_IPV4\f[R] and \f[I]IBV_FLOW_SPEC_ESP\f[R] to match
the outer packet headers to ensure that the action is only applied to
IPSEC packets with the correct identifiers.
.PP
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.
.SS Determining the ESN for Ingress Packets
We require a \[lq]modify\[rq] command once every 2\[ha]31 packets.
This modify command allows the implementation in HW to be stateless, as
follows:
.IP
.EX
           ESN 1                       ESN 2                      ESN 3
|\-\-\-\-\-\-\-\-\-\-\-\-\-*\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-*\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-*
\[ha]             \[ha]             \[ha]             \[ha]             \[ha]             \[ha]
.EE
.PP
\[ha] \- marks where command invoked to update the SA ESN state machine.
.PD 0
.P
.PD
| \- marks the start of the ESN scope (0\-2\[ha]32\-1).
At this point move SA ESN \[lq]new_window\[rq] bit to zero and increment
ESN.
.PD 0
.P
.PD
* \- marks the middle of the ESN scope (2\[ha]31).
At this point move SA ESN \[lq]new_window\[rq] bit to one.
.PP
For decryption the implementation uses the following state machine to
determine ESN:
.IP
.EX
if (!overlap) {
    use esn // regardless of packet.seq
} else { // new_window
    if (packet.seq >= 2\[ha]31)
        use esn
    else // packet.seq < 2\[ha]31
        use esn+1
}
.EE
.PP
This mechanism is controlled by the \f[I]esp_attr\f[R] flag:
.TP
\f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_ESN_NEW_WINDOW\f[R]
This flag is only used to provide stateless ESN support for inline
crypto.
It is used only for
\f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_INLINE_CRYPTO\f[R] and
\f[I]IBV_FLOW_ACTION_ESP_MASK_ESN\f[R].
.RS
.PP
Setting this flag indicates that the bottom of the replay window is
between 2\[ha]31 \- 2\[ha]32.
.RE
.SS Key Material for AES GCM (\f[I]IBV_ACTION_ESP_KEYMAT_AES_GCM\f[R])
The AES GCM crypto algorithm as defined by RFC4106.
This struct is to be provided in \f[I]keymat_ptr\f[R] when
\f[I]keymat_proto\f[R] is set to
\f[I]IBV_ACTION_ESP_KEYMAT_AES_GCM\f[R].
.IP
.EX
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];
};
.EE
.TP
\f[I]iv\f[R]
The starting value for the initialization vector used only with
\f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLOAD\f[R] encryption as
defined in RFC4106.
This field is ignored for
\f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_INLINE_CRYPTO\f[R].
.RS
.PP
For a given key, the IV MUST NOT be reused.
.RE
.TP
\f[I]iv_algo\f[R]
The algorithm used to transform/generate new IVs with
\f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLOAD\f[R] encryption.
.RS
.PP
The only supported value is \f[I]IB_UVERBS_FLOW_ACTION_IV_ALGO_SEQ\f[R]
to generate sequantial IVs.
.RE
.TP
\f[I]salt\f[R]
The salt as defined by RFC4106.
.TP
\f[I]icv_len\f[R]
The length of the Integrity Check Value in bytes as defined by RFC4106.
.TP
\f[I]aes_key\f[R], \f[I]key_len\f[R]
The cipher key data.
It must be either 16, 24 or 32 bytes as defined by RFC4106.
.SS Bitmap Replay Protection (\f[I]IBV_FLOW_ACTION_ESP_REPLAY_BMP\f[R])
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 \f[I]size\f[R] 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\[ha]31 sequence numbers
forward.
.PP
This struct is to be provided in \f[I]replay_ptr\f[R] when
\f[I]reply_proto\f[R] is set to
\f[I]IBV_FLOW_ACTION_ESP_REPLAY_BMP\f[R].
In this mode reply_ptr and reply_len should point to a struct
ibv_flow_action_esp_replay_bmp containing: \f[I]size\f[R] : The size of
the bitmap.
.SS ESP Encapsulation
An \f[I]esp_encap\f[R] specification is required when \f[I]eps_attr\f[R]
flags \f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_TUNNEL\f[R] 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.
.PP
This setting is only used in
\f[I]IB_UVERBS_FLOW_ACTION_ESP_FLAGS_FULL_OFFLOAD\f[R] mode.
.IP
.EX
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 */
};
.EE
.PP
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'.
.SH RETURN VALUE
Upon success \f[I]ibv_create_flow_action_esp\f[R] will return a new
\f[I]struct ibv_flow_action\f[R] object, on error NULL will be returned
and errno will be set.
.PP
Upon success \f[I]ibv_modify_action_esp\f[R] 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.
.SH SEE ALSO
\f[I]ibv_create_flow(3)\f[R], \f[I]ibv_destroy_action(3)\f[R], \f[I]RFC
4106\f[R]
