rte_swx_ipsec.h - Man Page
Synopsis
#include <stdint.h>
#include <stdio.h>
#include <netinet/in.h>
#include <rte_compat.h>
#include <rte_crypto_sym.h>
Data Structures
struct rte_swx_ipsec_burst_size
struct rte_swx_ipsec_params
struct rte_swx_ipsec_input_packet_metadata
struct rte_swx_ipsec_sa_cipher_params
struct rte_swx_ipsec_sa_authentication_params
struct rte_swx_ipsec_sa_aead_params
struct rte_swx_ipsec_sa_encap_params
struct rte_swx_ipsec_sa_params
Macros
#define RTE_SWX_IPSEC_NAME_SIZE 64
#define RTE_SWX_IPSEC_BURST_SIZE_MAX 256
#define RTE_SWX_IPSEC_KEY_SIZE_MAX 64
Functions
__rte_experimental struct rte_swx_ipsec * rte_swx_ipsec_find (const char *name)
__rte_experimental int rte_swx_ipsec_create (struct rte_swx_ipsec **ipsec, const char *name, struct rte_swx_ipsec_params *params, int numa_node)
__rte_experimental void rte_swx_ipsec_free (struct rte_swx_ipsec *ipsec)
__rte_experimental void rte_swx_ipsec_run (struct rte_swx_ipsec *ipsec)
__rte_experimental int rte_swx_ipsec_sa_add (struct rte_swx_ipsec *ipsec, struct rte_swx_ipsec_sa_params *sa_params, uint32_t *sa_id)
__rte_experimental void rte_swx_ipsec_sa_delete (struct rte_swx_ipsec *ipsec, uint32_t sa_id)
__rte_experimental struct rte_swx_ipsec_sa_params * rte_swx_ipsec_sa_read (struct rte_swx_ipsec *ipsec, const char *string, int *is_blank_or_comment, const char **errmsg)
Detailed Description
RTE SWX Internet Protocol Security (IPsec)
The IPsec block is a companion block for the SWX pipeline used to provide IPsec support to the pipeline. The block is external to the pipeline, hence it needs to be explicitly instantiated by the user and connected to a pipeline instance through the pipeline I/O ports.
Main features:
- IPsec inbound (encrypted input packets -> clear text output packets) and outbound (clear text input packets -> encrypted output packets) processing support for tunnel and transport modes.
Security Association (SA):
- Each IPsec block instance has its own set of SAs used to process the input packets. Each SA is identified by its unique SA ID. The IPsec inbound and outbound SAs share the same ID space.
- Each input packet is first mapped to one of the existing SAs by using the SA ID and then processed according to the identified SA. The SA ID is read from input packet. The SA ID field is typically written by the pipeline before sending the packet to the IPsec block.
Packet format:
- ·
IPsec block input packet (i.e. pipeline output packet):
- ·
IPsec block meta-data header:
- See also
struct rte_swx_ipsec_input_packet_metadata.
- ·
IPv4 header.
- ·
IPv4 payload: on the inbound path, it includes the encrypted ESP packet.
- ·
IPsec block output packet (i.e. pipeline input packet):
- ·
IPv4 header.
- ·
IPv4 payload: on the outbound path, it includes the encrypted ESP packet.
SA update procedure:
- To add a new SA,
- See also
function rte_swx_ipsec_sa_add().
- To delete an existing SA,
- See also
function rte_swx_ipsec_sa_delete().
- ·
To update an existing SA, the control plane has to follow the following steps:
- 1.
Add a new SA with potentially a different set of configuration parameters. This step can fail, for example when the SA table is full.
- 2.
Wait until no more packets are using the old SA.
- 3.
Delete the old SA.
Definition in file rte_swx_ipsec.h.
Macro Definition Documentation
#define RTE_SWX_IPSEC_NAME_SIZE 64
Name size.
Definition at line 65 of file rte_swx_ipsec.h.
#define RTE_SWX_IPSEC_BURST_SIZE_MAX 256
Maximum burst size.
Definition at line 70 of file rte_swx_ipsec.h.
#define RTE_SWX_IPSEC_KEY_SIZE_MAX 64
Maximum key size in bytes.
Definition at line 185 of file rte_swx_ipsec.h.
Function Documentation
__rte_experimental struct rte_swx_ipsec * rte_swx_ipsec_find (const char * name)
IPsec instance find
- Parameters
name IPsec instance name.
- Returns
Valid IPsec instance handle if found or NULL otherwise.
__rte_experimental int rte_swx_ipsec_create (struct rte_swx_ipsec ** ipsec, const char * name, struct rte_swx_ipsec_params * params, int numa_node)
IPsec instance create
- Parameters
ipsec IPsec instance handle. Must point to valid memory. Contains valid pipeline handle once this function returns successfully.
name IPsec instance unique name.
params IPsec instance configuration parameters.
numa_node Non-Uniform Memory Access (NUMA) node.
Returns
0 on success or the following error codes otherwise: -EINVAL: Invalid argument; -ENOMEM: Not enough space/cannot allocate memory; -EEXIST: Pipeline with this name already exists.
__rte_experimental void rte_swx_ipsec_free (struct rte_swx_ipsec * ipsec)
IPsec instance free
- Parameters
ipsec IPsec instance handle.
__rte_experimental void rte_swx_ipsec_run (struct rte_swx_ipsec * ipsec)
IPsec Data Plane API IPsec instance run
- Parameters
ipsec IPsec instance handle.
__rte_experimental int rte_swx_ipsec_sa_add (struct rte_swx_ipsec * ipsec, struct rte_swx_ipsec_sa_params * sa_params, uint32_t * sa_id)
IPsec SA add
- Parameters
ipsec IPsec instance handle.
sa_params SA parameters.
sa_id On success, the SA ID.
Returns
0 on success or error code otherwise.
__rte_experimental void rte_swx_ipsec_sa_delete (struct rte_swx_ipsec * ipsec, uint32_t sa_id)
IPsec SA delete
It is the responibility of the Control Plane to make sure the SA to be deleted is no longer used by the Data Plane.
- Parameters
ipsec IPsec instance handle.
sa_id The SA ID.
__rte_experimental struct rte_swx_ipsec_sa_params * rte_swx_ipsec_sa_read (struct rte_swx_ipsec * ipsec, const char * string, int * is_blank_or_comment, const char ** errmsg)
IPsec SA read from string
IPsec SA syntax:
<sa> : encrypt <crypto_params> <encap_params> | decrypt <crypto_params> <encap_params> ;
<crypto_params> : <cipher> <auth> | <aead> ;
<cipher> : cipher <ciher_alg> key <cipher_key> | cipher <cipher_alg> ;
<auth> : auth <authentication_alg> key <authentication_key> | auth <authentication_alg> ;
<aead> : aead <aead_alg> key <aead_key> ;
<encap_params> : esp spi <spi> tunnel ipv4 srcaddr <ipv4_src_addr> dstaddr <ipv4_dst_addr> | esp spi <spi> tunnel ipv6 srcaddr <ipv6_src_addr> dstaddr <ipv6_dst_addr> | esp spi <spi> transport ;
- Parameters
ipsec IPsec instance handle.
string String containing the SA.
is_blank_or_comment On error, when its input value is not NULL, this argument is set to a non-zero value when string contains a blank or comment line and to zero otherwise.
errmsg On error, when its input value is not NULL, this argument points to a string with details on the detected error.- Returns
Pointer to valid IPsec SA parameters data structure on success or NULL on error.
Author
Generated automatically by Doxygen for DPDK from the source code.
Referenced By
The man pages RTE_SWX_IPSEC_BURST_SIZE_MAX(3), rte_swx_ipsec_create(3), rte_swx_ipsec_find(3), rte_swx_ipsec_free(3), RTE_SWX_IPSEC_KEY_SIZE_MAX(3), RTE_SWX_IPSEC_NAME_SIZE(3), rte_swx_ipsec_run(3), rte_swx_ipsec_sa_add(3), rte_swx_ipsec_sa_delete(3) and rte_swx_ipsec_sa_read(3) are aliases of rte_swx_ipsec.h(3).