rte_swx_ipsec.h(3)

📦
version 25.11.3 · 9 versions
, in ubuntu resolute, ubuntu stonking

💖 rte_swx_ipsec.h 💖

okay bestie, gather round, because we're doing the RTE SWX Internet Protocol Security header file and it's genuinely iconic ✨ It's a Library Functions Manual page, DPDK's own, and I'm gonna walk you through every single line like we're decoding a group chat at 2am 🫶

✨ NAME ✨

rte_swx_ipsec.h — the header, the moment, the whole vibe 💅

🦋 SYNOPSIS 🦋

So first things first, you gotta pull in your includes, no cap:

#include <stdint.h>
#include <stdio.h>
#include <netinet/in.h>
#include <rte_compat.h>
#include <rte_crypto_sym.h>
#include <rte_ip6.h>

🌸 Data Structures 🌸

these are the little structs, the building blocks, the main characters:

  • 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 💜

the defined constants, short and sweet:

#define RTE_SWX_IPSEC_NAME_SIZE   64
#define RTE_SWX_IPSEC_BURST_SIZE_MAX   256
#define RTE_SWX_IPSEC_KEY_SIZE_MAX   64

⭐ Functions ⭐

and the functions!! every one of them tagged __rte_experimental (iykyk, that means "try it but don't be shocked if the API shifts"):

__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)

bestie. the IPsec block is the companion block for the SWX pipeline, and its whole job is to give that pipeline IPsec support 💖 It lives outside the pipeline, which means you — yes you, the user — have to explicitly instantiate it and then wire it up to a pipeline instance through the pipeline I/O ports. no shortcuts, no autopilot, that's just how it is.

Main features:

  • IPsec inbound (encrypted input packets → clear text output packets) and outbound (clear text input packets → encrypted output packets) processing support, for both tunnel and transport modes. both modes, bestie, we contain multitudes 🦋

Security Association (SA):

  • Every IPsec block instance rolls with its own set of SAs used to process the input packets. Each SA is identified by its own unique SA ID. And here's the tea: the IPsec inbound and outbound SAs share the same ID space. one space, no overlap, periodt.
  • Every input packet gets mapped to one of the existing SAs first, using the SA ID, and then it's processed according to whichever SA got identified. The SA ID is read from the input packet itself. Usually the pipeline writes that SA ID field before it hands the packet over to the IPsec block — so the SA ID is basically the packet's ✨name tag✨ at the door.

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 these steps, in order, no skipping 🫶:
    1. Add a new SA with potentially a different set of configuration parameters. Heads up: 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 66 of file rte_swx_ipsec.h.

#define RTE_SWX_IPSEC_BURST_SIZE_MAX 256

Maximum burst size.

Definition at line 71 of file rte_swx_ipsec.h.

#define RTE_SWX_IPSEC_KEY_SIZE_MAX 64

Maximum key size in bytes.

Definition at line 186 of file rte_swx_ipsec.h.

💅 Function Documentation 💅

__rte_experimental struct rte_swx_ipsec * rte_swx_ipsec_find (const char * name)

IPsec instance find 🔍 — go look up the instance, bestie.

Parameters

  • name — IPsec instance name.

Returns

A valid IPsec instance handle if it's 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 ✨ — make the whole thing exist.

Parameters

  • ipsec — IPsec instance handle. Must point to valid memory. Contains a 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 one of these 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 🕊️ — let it go, it's free now.

Parameters

  • ipsec — IPsec instance handle.

__rte_experimental void rte_swx_ipsec_run (struct rte_swx_ipsec * ipsec)

IPsec Data Plane API IPsec instance run 🔥 — the data plane doing its thing.

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 🌸 — new SA, who dis.

Parameters

  • ipsec — IPsec instance handle.
  • sa_params — SA parameters.
  • sa_id — On success, the SA ID.

Returns

0 on success or an error code otherwise.

__rte_experimental void rte_swx_ipsec_sa_delete (struct rte_swx_ipsec * ipsec, uint32_t sa_id)

IPsec SA delete 💀 — bye bye SA.

It is the responsibility of the Control Plane to make sure the SA to be deleted is no longer used by the Data Plane. no, seriously, this one's on you. delete a live SA and it's giving undefined behaviour energy 😭

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 📖 — hand it a string, get params back.

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 ;
ngl, yes, <ciher_alg> right there is spelled exactly like the original says it. it's giving typo but it's also giving canon, so we keep it character for character 💅

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 a valid IPsec SA parameters data structure on success, or NULL on error.

👑 Author 👑

Generated automatically by Doxygen for DPDK from the source code. yes bestie, the robots wrote the docs, we just gave them the vibe check 🫶

okay that's the whole page, you ate 💖 This was DPDK Version 25.11.3, page rte_swx_ipsec.h(3), and it's been a pleasure, mwah 🎀✨🦋

📦 where this page comes from