From patchwork Wed Mar 21 18:09:53 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Yishai Hadas X-Patchwork-Id: 10299981 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 726CD6055B for ; Wed, 21 Mar 2018 18:10:31 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 5BA16298C3 for ; Wed, 21 Mar 2018 18:10:31 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 5A086298D7; Wed, 21 Mar 2018 18:10:31 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00, RCVD_IN_DNSWL_HI, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 2862E298E5 for ; Wed, 21 Mar 2018 18:10:30 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752415AbeCUSK2 (ORCPT ); Wed, 21 Mar 2018 14:10:28 -0400 Received: from mail-il-dmz.mellanox.com ([193.47.165.129]:57448 "EHLO mellanox.co.il" rhost-flags-OK-OK-OK-FAIL) by vger.kernel.org with ESMTP id S1752454AbeCUSK0 (ORCPT ); Wed, 21 Mar 2018 14:10:26 -0400 Received: from Internal Mail-Server by MTLPINE1 (envelope-from yishaih@mellanox.com) with ESMTPS (AES256-SHA encrypted); 21 Mar 2018 20:11:07 +0200 Received: from vnc17.mtl.labs.mlnx (vnc17.mtl.labs.mlnx [10.7.2.17]) by labmailer.mlnx (8.13.8/8.13.8) with ESMTP id w2LIAKZx014341; Wed, 21 Mar 2018 20:10:20 +0200 Received: from vnc17.mtl.labs.mlnx (vnc17.mtl.labs.mlnx [127.0.0.1]) by vnc17.mtl.labs.mlnx (8.13.8/8.13.8) with ESMTP id w2LIAKIP007768; Wed, 21 Mar 2018 20:10:20 +0200 Received: (from yishaih@localhost) by vnc17.mtl.labs.mlnx (8.13.8/8.13.8/Submit) id w2LIAKtR007767; Wed, 21 Mar 2018 20:10:20 +0200 From: Yishai Hadas To: linux-rdma@vger.kernel.org Cc: yishaih@mellanox.com, matanb@mellanox.com, jgg@mellanox.com, majd@mellanox.com, Boris Pismenny Subject: [PATCH rdma-core 04/11] verbs: Add a man page for flow_action_esp Date: Wed, 21 Mar 2018 20:09:53 +0200 Message-Id: <1521655800-7287-5-git-send-email-yishaih@mellanox.com> X-Mailer: git-send-email 1.8.2.3 In-Reply-To: <1521655800-7287-1-git-send-email-yishaih@mellanox.com> References: <1521655800-7287-1-git-send-email-yishaih@mellanox.com> Sender: linux-rdma-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-rdma@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP From: Boris Pismenny Added man pages for ibv_create_flow_action_esp, ibv_modify_flow_action_esp and ibv_destroy_flow_action. Signed-off-by: Boris Pismenny Signed-off-by: Matan Barak Signed-off-by: Yishai Hadas --- libibverbs/man/CMakeLists.txt | 3 + libibverbs/man/ibv_create_flow_action.3.md | 338 +++++++++++++++++++++++++++++ 2 files changed, 341 insertions(+) create mode 100644 libibverbs/man/ibv_create_flow_action.3.md diff --git a/libibverbs/man/CMakeLists.txt b/libibverbs/man/CMakeLists.txt index aa245ba..743e57b 100644 --- a/libibverbs/man/CMakeLists.txt +++ b/libibverbs/man/CMakeLists.txt @@ -13,6 +13,7 @@ rdma_man_pages( ibv_create_cq_ex.3 ibv_modify_cq.3 ibv_create_flow.3 + ibv_create_flow_action.3.md ibv_create_qp.3 ibv_create_qp_ex.3 ibv_create_rwq_ind_table.3 @@ -72,6 +73,8 @@ rdma_alias_man_pages( ibv_create_comp_channel.3 ibv_destroy_comp_channel.3 ibv_create_cq.3 ibv_destroy_cq.3 ibv_create_flow.3 ibv_destroy_flow.3 + ibv_create_flow_action.3 ibv_destroy_flow_action.3 + ibv_create_flow_action.3 ibv_modify_flow_action.3 ibv_create_qp.3 ibv_destroy_qp.3 ibv_create_rwq_ind_table.3 ibv_destroy_rwq_ind_table.3 ibv_create_srq.3 ibv_destroy_srq.3 diff --git a/libibverbs/man/ibv_create_flow_action.3.md b/libibverbs/man/ibv_create_flow_action.3.md new file mode 100644 index 0000000..16881c3 --- /dev/null +++ b/libibverbs/man/ibv_create_flow_action.3.md @@ -0,0 +1,338 @@ +--- +layout: page +title: ibv_flow_action_esp(3) +section: 3 +tagline: Verbs +--- + +# NAME + +ibv_flow_action_esp(3) -- Flow action esp for verbs(3) + +# SYNOPSIS + +```c +#include + +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); +``` + +# 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 *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. + +# ARGUMENTS + +*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 + +```c +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 + +```c +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 Paremeters 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: + +```c +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 controled 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*. + +```c +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* encyption. + + 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. + +```C +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'. + +# RETURN VALUE + +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 guarnteed 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. + +# SEE ALSO + +*ibv_create_flow(3)*, *ibv_destroy_action(3)*, *RFC 4106*