API Description

IPSEC protocol offload.

Data Structures
union	odp_ipsec_test_sa_param_t
	IPSEC TEST SA parameter. More...

struct	odp_ipsec_inbound_config_t
	Configuration options for IPSEC inbound processing. More...

struct	odp_ipsec_outbound_config_t
	Configuration options for IPSEC outbound processing. More...

struct	odp_ipsec_test_capability_t
	IPSEC TEST capability. More...

struct	odp_ipsec_capability_t
	IPSEC capability. More...

struct	odp_ipsec_cipher_capability_t
	Cipher algorithm capabilities. More...

struct	odp_ipsec_auth_capability_t
	Authentication algorithm capabilities. More...

struct	odp_ipsec_config_t
	IPSEC configuration options. More...

struct	odp_ipsec_crypto_param_t
	IPSEC crypto parameters. More...

struct	odp_ipsec_ipv4_param_t
	IPv4 header parameters. More...

struct	odp_ipsec_ipv6_param_t
	IPv6 header parameters. More...

struct	odp_ipsec_tunnel_param_t
	IPSEC tunnel parameters. More...

struct	odp_ipsec_sa_opt_t
	IPSEC SA option flags. More...

struct	odp_ipsec_lifetime_t
	IPSEC SA lifetime limits. More...

struct	odp_ipsec_sa_param_t
	IPSEC Security Association (SA) parameters. More...

struct	odp_ipsec_stats_t
	IPSEC stats content. More...

struct	odp_ipsec_sa_info_t
	IPSEC SA information. More...

struct	odp_ipsec_error_t
	IPSEC errors. More...

struct	odp_ipsec_warn_t
	IPSEC warnings. More...

struct	odp_ipsec_op_status_t
	IPSEC operation status. More...

struct	odp_ipsec_op_flag_t
	IPSEC operation flags. More...

struct	odp_ipsec_out_opt_t
	IPSEC outbound operation options. More...

struct	odp_ipsec_out_param_t
	IPSEC outbound operation parameters. More...

struct	odp_ipsec_in_param_t
	IPSEC inbound operation parameters. More...

struct	odp_ipsec_out_inline_param_t
	Outbound inline IPSEC operation parameters. More...

struct	odp_ipsec_packet_result_t
	IPSEC operation result for a packet. More...

struct	odp_ipsec_status_t
	IPSEC status content. More...

Macros
#define	ODP_IPSEC_SA_INVALID ((odp_ipsec_sa_t)0)
	Invalid IPSEC SA.

#define	ODP_IPSEC_OK 0
	IPSEC operation status has no errors.

Typedefs
typedef _odp_abi_ipsec_sa_t *	odp_ipsec_sa_t
	IPSEC Security Association (SA)

typedef enum odp_ipsec_op_mode_t	odp_ipsec_op_mode_t
	IPSEC operation mode.

typedef enum odp_ipsec_test_sa_operation_t	odp_ipsec_test_sa_operation_t
	IPSEC TEST SA operation.

typedef union odp_ipsec_test_sa_param_t	odp_ipsec_test_sa_param_t
	IPSEC TEST SA parameter.

typedef struct odp_ipsec_inbound_config_t	odp_ipsec_inbound_config_t
	Configuration options for IPSEC inbound processing.

typedef struct odp_ipsec_outbound_config_t	odp_ipsec_outbound_config_t
	Configuration options for IPSEC outbound processing.

typedef struct odp_ipsec_test_capability_t	odp_ipsec_test_capability_t
	IPSEC TEST capability.

typedef struct odp_ipsec_capability_t	odp_ipsec_capability_t
	IPSEC capability.

typedef struct odp_ipsec_cipher_capability_t	odp_ipsec_cipher_capability_t
	Cipher algorithm capabilities.

typedef struct odp_ipsec_auth_capability_t	odp_ipsec_auth_capability_t
	Authentication algorithm capabilities.

typedef struct odp_ipsec_config_t	odp_ipsec_config_t
	IPSEC configuration options.

typedef enum odp_ipsec_dir_t	odp_ipsec_dir_t
	IPSEC SA direction.

typedef enum odp_ipsec_mode_t	odp_ipsec_mode_t
	IPSEC protocol mode.

typedef enum odp_ipsec_protocol_t	odp_ipsec_protocol_t
	IPSEC protocol.

typedef enum odp_ipsec_tunnel_type_t	odp_ipsec_tunnel_type_t
	IPSEC tunnel type.

typedef struct odp_ipsec_crypto_param_t	odp_ipsec_crypto_param_t
	IPSEC crypto parameters.

typedef struct odp_ipsec_ipv4_param_t	odp_ipsec_ipv4_param_t
	IPv4 header parameters.

typedef struct odp_ipsec_ipv6_param_t	odp_ipsec_ipv6_param_t
	IPv6 header parameters.

typedef struct odp_ipsec_tunnel_param_t	odp_ipsec_tunnel_param_t
	IPSEC tunnel parameters. More...

typedef struct odp_ipsec_sa_opt_t	odp_ipsec_sa_opt_t
	IPSEC SA option flags.

typedef struct odp_ipsec_lifetime_t	odp_ipsec_lifetime_t
	IPSEC SA lifetime limits. More...

typedef enum odp_ipsec_frag_mode_t	odp_ipsec_frag_mode_t
	Fragmentation mode. More...

typedef enum odp_ipsec_lookup_mode_t	odp_ipsec_lookup_mode_t
	Packet lookup mode. More...

typedef enum odp_ipsec_pipeline_t	odp_ipsec_pipeline_t
	IPSEC pipeline configuration.

typedef enum odp_ipsec_ip_version_t	odp_ipsec_ip_version_t
	IPSEC header type.

typedef struct odp_ipsec_sa_param_t	odp_ipsec_sa_param_t
	IPSEC Security Association (SA) parameters.

typedef struct odp_ipsec_stats_t	odp_ipsec_stats_t
	IPSEC stats content.

typedef struct odp_ipsec_sa_info_t	odp_ipsec_sa_info_t
	IPSEC SA information.

typedef struct odp_ipsec_error_t	odp_ipsec_error_t
	IPSEC errors.

typedef struct odp_ipsec_warn_t	odp_ipsec_warn_t
	IPSEC warnings.

typedef struct odp_ipsec_op_status_t	odp_ipsec_op_status_t
	IPSEC operation status.

typedef struct odp_ipsec_op_flag_t	odp_ipsec_op_flag_t
	IPSEC operation flags.

typedef struct odp_ipsec_out_opt_t	odp_ipsec_out_opt_t
	IPSEC outbound operation options. More...

typedef struct odp_ipsec_out_param_t	odp_ipsec_out_param_t
	IPSEC outbound operation parameters.

typedef struct odp_ipsec_in_param_t	odp_ipsec_in_param_t
	IPSEC inbound operation parameters.

typedef struct odp_ipsec_out_inline_param_t	odp_ipsec_out_inline_param_t
	Outbound inline IPSEC operation parameters.

typedef struct odp_ipsec_packet_result_t	odp_ipsec_packet_result_t
	IPSEC operation result for a packet.

typedef enum odp_ipsec_status_id_t	odp_ipsec_status_id_t
	IPSEC status ID.

typedef struct odp_ipsec_status_t	odp_ipsec_status_t
	IPSEC status content.

Enumerations
enum	odp_ipsec_op_mode_t { ODP_IPSEC_OP_MODE_SYNC = 0 , ODP_IPSEC_OP_MODE_ASYNC , ODP_IPSEC_OP_MODE_INLINE , ODP_IPSEC_OP_MODE_DISABLED }
	IPSEC operation mode. More...

enum	odp_ipsec_test_sa_operation_t { ODP_IPSEC_TEST_SA_UPDATE_SEQ_NUM = 0 , ODP_IPSEC_TEST_SA_UPDATE_ANTIREPLAY_WINDOW_TOP }
	IPSEC TEST SA operation. More...

enum	odp_ipsec_dir_t { ODP_IPSEC_DIR_INBOUND = 0 , ODP_IPSEC_DIR_OUTBOUND }
	IPSEC SA direction. More...

enum	odp_ipsec_mode_t { ODP_IPSEC_MODE_TUNNEL = 0 , ODP_IPSEC_MODE_TRANSPORT }
	IPSEC protocol mode. More...

enum	odp_ipsec_protocol_t { ODP_IPSEC_ESP = 0 , ODP_IPSEC_AH }
	IPSEC protocol. More...

enum	odp_ipsec_tunnel_type_t { ODP_IPSEC_TUNNEL_IPV4 = 0 , ODP_IPSEC_TUNNEL_IPV6 }
	IPSEC tunnel type. More...

enum	odp_ipsec_frag_mode_t { ODP_IPSEC_FRAG_DISABLED = 0 , ODP_IPSEC_FRAG_BEFORE , ODP_IPSEC_FRAG_AFTER , ODP_IPSEC_FRAG_CHECK }
	Fragmentation mode. More...

enum	odp_ipsec_lookup_mode_t { ODP_IPSEC_LOOKUP_DISABLED = 0 , ODP_IPSEC_LOOKUP_SPI , ODP_IPSEC_LOOKUP_DSTADDR_SPI }
	Packet lookup mode. More...

enum	odp_ipsec_pipeline_t { ODP_IPSEC_PIPELINE_NONE = 0 , ODP_IPSEC_PIPELINE_CLS }
	IPSEC pipeline configuration. More...

enum	odp_ipsec_ip_version_t { ODP_IPSEC_IPV4 = 4 , ODP_IPSEC_IPV6 = 6 }
	IPSEC header type. More...

enum	odp_ipsec_status_id_t { ODP_IPSEC_STATUS_SA_DISABLE = 0 , ODP_IPSEC_STATUS_WARN }
	IPSEC status ID. More...

Functions
int	odp_ipsec_capability (odp_ipsec_capability_t *capa)
	Query IPSEC capabilities. More...

int	odp_ipsec_cipher_capability (odp_cipher_alg_t cipher, odp_ipsec_cipher_capability_t capa[], int num)
	Query supported IPSEC cipher algorithm capabilities. More...

int	odp_ipsec_auth_capability (odp_auth_alg_t auth, odp_ipsec_auth_capability_t capa[], int num)
	Query supported IPSEC authentication algorithm capabilities. More...

void	odp_ipsec_config_init (odp_ipsec_config_t *config)
	Initialize IPSEC configuration options. More...

int	odp_ipsec_config (const odp_ipsec_config_t *config)
	Global IPSEC configuration. More...

void	odp_ipsec_sa_param_init (odp_ipsec_sa_param_t *param)
	Initialize IPSEC SA parameters. More...

odp_ipsec_sa_t	odp_ipsec_sa_create (const odp_ipsec_sa_param_t *param)
	Create IPSEC SA. More...

int	odp_ipsec_sa_disable (odp_ipsec_sa_t sa)
	Disable IPSEC SA. More...

int	odp_ipsec_sa_destroy (odp_ipsec_sa_t sa)
	Destroy IPSEC SA. More...

uint64_t	odp_ipsec_sa_to_u64 (odp_ipsec_sa_t sa)
	Printable format of odp_ipsec_sa_t. More...

int	odp_ipsec_in (const odp_packet_t pkt_in[], int num_in, odp_packet_t pkt_out[], int num_out, const odp_ipsec_in_param_t param)
	Inbound synchronous IPSEC operation. More...

int	odp_ipsec_out (const odp_packet_t pkt_in[], int num_in, odp_packet_t pkt_out[], int num_out, const odp_ipsec_out_param_t param)
	Outbound synchronous IPSEC operation. More...

int	odp_ipsec_in_enq (const odp_packet_t pkt[], int num, const odp_ipsec_in_param_t *param)
	Inbound asynchronous IPSEC operation. More...

int	odp_ipsec_out_enq (const odp_packet_t pkt[], int num, const odp_ipsec_out_param_t *param)
	Outbound asynchronous IPSEC operation. More...

int	odp_ipsec_out_inline (const odp_packet_t pkt[], int num, const odp_ipsec_out_param_t param, const odp_ipsec_out_inline_param_t inline_param)
	Outbound inline IPSEC operation. More...

odp_packet_t	odp_ipsec_packet_from_event (odp_event_t ev)
	Convert IPSEC processed packet event to packet handle. More...

odp_event_t	odp_ipsec_packet_to_event (odp_packet_t pkt)
	Convert IPSEC processed packet handle to event. More...

int	odp_ipsec_result (odp_ipsec_packet_result_t *result, odp_packet_t packet)
	Get IPSEC operation results from an IPSEC processed packet. More...

int	odp_ipsec_status (odp_ipsec_status_t *status, odp_event_t event)
	Get IPSEC status information from an ODP_EVENT_IPSEC_STATUS event. More...

int	odp_ipsec_test_sa_update (odp_ipsec_sa_t sa, odp_ipsec_test_sa_operation_t op, const odp_ipsec_test_sa_param_t *param)
	IPSEC test API for modifying internal state of an SA. More...

int	odp_ipsec_sa_mtu_update (odp_ipsec_sa_t sa, uint32_t mtu)
	Update MTU for outbound IP fragmentation. More...

void *	odp_ipsec_sa_context (odp_ipsec_sa_t sa)
	Get user defined SA context pointer. More...

void	odp_ipsec_print (void)
	Print global IPSEC configuration info. More...

void	odp_ipsec_sa_print (odp_ipsec_sa_t sa)
	Print IPSEC SA info. More...

int	odp_ipsec_stats (odp_ipsec_sa_t sa, odp_ipsec_stats_t *stats)
	Get IPSEC stats for the IPSEC SA handle. More...

int	odp_ipsec_stats_multi (odp_ipsec_sa_t sa[], odp_ipsec_stats_t stats[], int num)
	Get IPSEC stats for multiple IPSEC SA handles. More...

int	odp_ipsec_sa_info (odp_ipsec_sa_t sa, odp_ipsec_sa_info_t *sa_info)
	Retrieve information about an IPSEC SA. More...

Typedef Documentation

◆ odp_ipsec_tunnel_param_t

typedef struct odp_ipsec_tunnel_param_t odp_ipsec_tunnel_param_t

IPSEC tunnel parameters.

These parameters are used to build outbound tunnel headers. All values are passed in CPU native byte / bit order if not specified otherwise. IP addresses must be in NETWORK byte order as those are passed in with pointers and copied byte-by-byte from memory to the packet.

◆ odp_ipsec_lifetime_t

typedef struct odp_ipsec_lifetime_t odp_ipsec_lifetime_t

IPSEC SA lifetime limits.

These limits are used for setting up SA lifetime. IPSEC operations check against the limits and output a status code (e.g. soft_exp_bytes) when a limit is crossed. It's implementation defined how many times soft lifetime expiration is reported: only once, first N or all packets following the limit crossing. Any number of limits may be used simultaneously. Use zero when there is no limit.

The default value is zero (i.e. no limit) for all the limits.

◆ odp_ipsec_frag_mode_t

typedef enum odp_ipsec_frag_mode_t odp_ipsec_frag_mode_t

Fragmentation mode.

These options control outbound IP packet fragmentation offload. When offload is enabled, IPSEC operation will determine if fragmentation is needed and does it according to the mode.

◆ odp_ipsec_lookup_mode_t

typedef enum odp_ipsec_lookup_mode_t odp_ipsec_lookup_mode_t

Packet lookup mode.

Lookup mode controls how an SA participates in SA lookup offload. Inbound operations perform SA lookup if application does not provide a SA as a parameter. In inline mode, a lookup miss directs the packet back to normal packet input interface processing. SA lookup failure status (status.error.sa_lookup) is reported through odp_ipsec_packet_result_t.

◆ odp_ipsec_out_opt_t

typedef struct odp_ipsec_out_opt_t odp_ipsec_out_opt_t

IPSEC outbound operation options.

These may be used to override some SA level options

Enumeration Type Documentation

◆ odp_ipsec_op_mode_t

enum odp_ipsec_op_mode_t

IPSEC operation mode.

Enumerator
ODP_IPSEC_OP_MODE_SYNC	Synchronous IPSEC operation. Application uses synchronous IPSEC operations, which output all results on function return.
ODP_IPSEC_OP_MODE_ASYNC	Asynchronous IPSEC operation. Application uses asynchronous IPSEC operations, which return results via events.
ODP_IPSEC_OP_MODE_INLINE	Inline IPSEC operation. Packet input/output is connected directly to IPSEC inbound/outbound processing. Application uses asynchronous or inline IPSEC operations. Inline processed inbound packets are delivered to the application in the same way as packets processed by odp_ipsec_in_enq().
ODP_IPSEC_OP_MODE_DISABLED	IPSEC is disabled in inbound / outbound direction.

Definition at line 44 of file api/spec/ipsec_types.h.

◆ odp_ipsec_test_sa_operation_t

enum odp_ipsec_test_sa_operation_t

IPSEC TEST SA operation.

Enumerator

ODP_IPSEC_TEST_SA_UPDATE_SEQ_NUM

Update next sequence number.

The seq_num parameter is an outbound SA specific parameter. Invoking the odp_ipsec_test_sa_update() API to update this field on an inbound SA will cause the API to return failure.

ODP_IPSEC_TEST_SA_UPDATE_ANTIREPLAY_WINDOW_TOP

Update highest authenticated sequence number.

The antireplay_window_top parameter is inbound SA specific. Invoking the odp_ipsec_test_sa_update() API to update this field on an outbound SA will cause the API to return failure.

Definition at line 78 of file api/spec/ipsec_types.h.

◆ odp_ipsec_dir_t

enum odp_ipsec_dir_t

IPSEC SA direction.

Enumerator
ODP_IPSEC_DIR_INBOUND	Inbound IPSEC SA.
ODP_IPSEC_DIR_OUTBOUND	Outbound IPSEC SA.

Definition at line 473 of file api/spec/ipsec_types.h.

◆ odp_ipsec_mode_t

enum odp_ipsec_mode_t

IPSEC protocol mode.

Enumerator
ODP_IPSEC_MODE_TUNNEL	IPSEC tunnel mode.
ODP_IPSEC_MODE_TRANSPORT	IPSEC transport mode.

Definition at line 485 of file api/spec/ipsec_types.h.

◆ odp_ipsec_protocol_t

enum odp_ipsec_protocol_t

IPSEC protocol.

Enumerator
ODP_IPSEC_ESP	ESP protocol.
ODP_IPSEC_AH	AH protocol.

Definition at line 497 of file api/spec/ipsec_types.h.

◆ odp_ipsec_tunnel_type_t

enum odp_ipsec_tunnel_type_t

IPSEC tunnel type.

Enumerator
ODP_IPSEC_TUNNEL_IPV4	Outer header is IPv4.
ODP_IPSEC_TUNNEL_IPV6	Outer header is IPv6.

Definition at line 509 of file api/spec/ipsec_types.h.

◆ odp_ipsec_frag_mode_t

enum odp_ipsec_frag_mode_t

Fragmentation mode.

These options control outbound IP packet fragmentation offload. When offload is enabled, IPSEC operation will determine if fragmentation is needed and does it according to the mode.

Enumerator
ODP_IPSEC_FRAG_DISABLED	Do not fragment IP packets.
ODP_IPSEC_FRAG_BEFORE	Fragment IP packet before IPSEC operation.
ODP_IPSEC_FRAG_AFTER	Fragment IP packet after IPSEC operation.
ODP_IPSEC_FRAG_CHECK	Only check if IP fragmentation is needed, do not fragment packets.

Definition at line 769 of file api/spec/ipsec_types.h.

◆ odp_ipsec_lookup_mode_t

enum odp_ipsec_lookup_mode_t

Packet lookup mode.

Lookup mode controls how an SA participates in SA lookup offload. Inbound operations perform SA lookup if application does not provide a SA as a parameter. In inline mode, a lookup miss directs the packet back to normal packet input interface processing. SA lookup failure status (status.error.sa_lookup) is reported through odp_ipsec_packet_result_t.

Enumerator

ODP_IPSEC_LOOKUP_DISABLED

Inbound SA lookup is disabled for the SA.

ODP_IPSEC_LOOKUP_SPI

Inbound SA lookup is enabled.

Lookup matches only SPI value.

ODP_IPSEC_LOOKUP_DSTADDR_SPI

Inbound SA lookup is enabled.

Lookup matches both SPI value and destination IP address. Functionality is otherwise identical to ODP_IPSEC_LOOKUP_SPI.

Definition at line 793 of file api/spec/ipsec_types.h.

◆ odp_ipsec_pipeline_t

enum odp_ipsec_pipeline_t

IPSEC pipeline configuration.

Enumerator

ODP_IPSEC_PIPELINE_NONE

Do not pipeline.

Send all resulting events to the application.

ODP_IPSEC_PIPELINE_CLS

Send resulting packets to the classifier.

IPSEC capability 'pipeline_cls' determines if pipelined
classification is supported.

Definition at line 810 of file api/spec/ipsec_types.h.

◆ odp_ipsec_ip_version_t

enum odp_ipsec_ip_version_t

IPSEC header type.

Enumerator
ODP_IPSEC_IPV4	Header is IPv4.
ODP_IPSEC_IPV6	Header is IPv6.

Definition at line 825 of file api/spec/ipsec_types.h.

◆ odp_ipsec_status_id_t

enum odp_ipsec_status_id_t

IPSEC status ID.

Enumerator

ODP_IPSEC_STATUS_SA_DISABLE

Response to SA disable command.

Following status event (odp_ipsec_status_t) fields have valid
content, other fields must be ignored:
- sa:       The SA that was requested to be disabled
- result:   Operation result

ODP_IPSEC_STATUS_WARN

Warning from inline IPSEC processing.

Following status event (odp_ipsec_status_t) fields have valid
content, other fields must be ignored:
- sa:       The SA that caused the warning
- warn:     The warning(s) reported by this event

This status event is generated only for outbound SAs in
ODP_IPSEC_OP_MODE_INLINE mode.

Definition at line 1440 of file api/spec/ipsec_types.h.

Function Documentation

◆ odp_ipsec_capability()

int odp_ipsec_capability ( odp_ipsec_capability_t * capa )

Query IPSEC capabilities.

Outputs IPSEC capabilities on success.

Parameters

[out] capa Pointer to capability structure for output

Return values

0	on success
<0	on failure

Examples: ipsec_api/odp_ipsec.c, odp_ipsec.c, odp_ipsecfwd.c, and odp_sysinfo.c.

◆ odp_ipsec_cipher_capability()

int odp_ipsec_cipher_capability	(	odp_cipher_alg_t	cipher,
		odp_ipsec_cipher_capability_t	capa[],
		int	num
	)

Query supported IPSEC cipher algorithm capabilities.

Outputs all supported configuration options for the algorithm. Output is sorted (from the smallest to the largest) first by key length, then by IV length. Use this information to select key lengths, etc cipher algorithm options for SA creation (odp_ipsec_crypto_param_t).

Parameters

	cipher	Cipher algorithm
[out]	capa	Array of capability structures for output
	num	Maximum number of capability structures to output

Returns: Number of capability structures for the algorithm. If this is larger than 'num', only 'num' first structures were output and application may call the function again with a larger value of 'num'.

Return values

<0	on failure

Examples: odp_ipsecfwd.c.

◆ odp_ipsec_auth_capability()

int odp_ipsec_auth_capability	(	odp_auth_alg_t	auth,
		odp_ipsec_auth_capability_t	capa[],
		int	num
	)

Query supported IPSEC authentication algorithm capabilities.

Outputs all supported configuration options for the algorithm. Output is sorted (from the smallest to the largest) first by ICV length, then by key length. Use this information to select key lengths, etc authentication algorithm options for SA creation (odp_ipsec_crypto_param_t).

Parameters

	auth	Authentication algorithm
[out]	capa	Array of capability structures for output
	num	Maximum number of capability structures to output

Returns: Number of capability structures for the algorithm. If this is larger than 'num', only 'num' first structures were output and application may call the function again with a larger value of 'num'.

Return values

<0	on failure

Examples: odp_ipsecfwd.c.

◆ odp_ipsec_config_init()

void odp_ipsec_config_init ( odp_ipsec_config_t * config )

Initialize IPSEC configuration options.

Initialize an odp_ipsec_config_t to its default values.

Parameters

[out] config Pointer to IPSEC configuration structure

Examples: ipsec_api/odp_ipsec.c, odp_ipsec.c, and odp_ipsecfwd.c.

◆ odp_ipsec_config()

int odp_ipsec_config ( const odp_ipsec_config_t * config )

Global IPSEC configuration.

Initialize and configure IPSEC offload with global configuration options. This must be called before any SAs are created. Use odp_ipsec_capability() to examine which features and modes are supported. This function must be called before creating the first SA with odp_ipsec_sa_create(). Calling this function multiple times results in undefined behaviour.

Parameters

config Pointer to IPSEC configuration structure

Return values

0	on success
<0	on failure

See also: odp_ipsec_capability(), odp_ipsec_config_init()

Examples: ipsec_api/odp_ipsec.c, odp_ipsec.c, and odp_ipsecfwd.c.

◆ odp_ipsec_sa_param_init()

void odp_ipsec_sa_param_init ( odp_ipsec_sa_param_t * param )

Initialize IPSEC SA parameters.

Initialize an odp_ipsec_sa_param_t to its default values for all fields.

Parameters

param Pointer to the parameter structure

Examples: odp_ipsec.c, and odp_ipsecfwd.c.

◆ odp_ipsec_sa_create()

odp_ipsec_sa_t odp_ipsec_sa_create ( const odp_ipsec_sa_param_t * param )

Create IPSEC SA.

Create a new IPSEC SA according to the parameters.

The parameter structure as well as all key, address and other memory buffers pointed to by it can be freed after the call.

Parameters

param IPSEC SA parameters

Returns: IPSEC SA handle

Return values

ODP_IPSEC_SA_INVALID on failure

See also: odp_ipsec_sa_param_init()

Examples: odp_ipsec.c, and odp_ipsecfwd.c.

◆ odp_ipsec_sa_disable()

int odp_ipsec_sa_disable ( odp_ipsec_sa_t sa )

Disable IPSEC SA.

Application must use this call to disable a SA before destroying it. The call marks the SA disabled, so that IPSEC implementation stops using it. For example, inbound SPI lookups will not match any more. Application must stop providing the SA as parameter to new IPSEC input/output operations before calling disable. Packets in progress during the call may still match the SA and be processed successfully.

When in synchronous operation mode, the call will return when it's possible to destroy the SA. In asynchronous mode, the same is indicated by an ODP_EVENT_IPSEC_STATUS event sent to the queue specified for the SA. The status event is guaranteed to be the last event for the SA, i.e. all in-progress operations have completed and resulting events (including status events) have been enqueued before it.

Parameters

sa	IPSEC SA to be disabled

Return values

0	On success
<0	On failure

See also: odp_ipsec_sa_destroy()

Examples: odp_ipsec.c, and odp_ipsecfwd.c.

◆ odp_ipsec_sa_destroy()

int odp_ipsec_sa_destroy ( odp_ipsec_sa_t sa )

Destroy IPSEC SA.

Destroy an unused IPSEC SA. Result is undefined if the SA is being used (i.e. asynchronous operation is in progress).

Parameters

sa	IPSEC SA to be destroyed

Return values

0	On success
<0	On failure

See also: odp_ipsec_sa_create()

Examples: odp_ipsec.c, and odp_ipsecfwd.c.

◆ odp_ipsec_sa_to_u64()

uint64_t odp_ipsec_sa_to_u64 ( odp_ipsec_sa_t sa )

Printable format of odp_ipsec_sa_t.

Parameters

sa	IPSEC SA handle

Returns: uint64_t value that can be used to print/display this handle

Examples: ipsec_api/odp_ipsec.c.

◆ odp_ipsec_in()

int odp_ipsec_in	(	const odp_packet_t	pkt_in[],
		int	num_in,
		odp_packet_t	pkt_out[],
		int *	num_out,
		const odp_ipsec_in_param_t *	param
	)

Inbound synchronous IPSEC operation.

This operation does inbound IPSEC processing in synchronous mode (ODP_IPSEC_OP_MODE_SYNC). A successful operation returns the number of packets consumed and outputs a new packet handle for each outputted packet. Outputted packets contain IPSEC result metadata (odp_ipsec_packet_result_t), which should be checked for transformation errors, etc. Outputted packets with error status have undefined content, except that in case of sa_lookup error the original input packet data is returned. The operation does not modify packets that it does not consume. It cannot consume all input packets if 'num_out' is smaller than 'num_in'.

Packet context pointer and user area content are copied from input to output packets. Output packets are allocated from the same pool(s) as input packets.

When 'param.num_sa' is zero, this operation performs SA look up for each packet. Otherwise, application must provide the SA(s) as part of operation input parameters (odp_ipsec_in_param_t). The operation outputs used SA(s) as part of per packet results (odp_ipsec_packet_result_t), or an error status if a SA was not found.

Each input packet must have a valid value for these metadata (other metadata is ignored):

L3 offset: Offset to the first byte of the (outmost) IP header
L4 offset: When udp_encap is enabled, offset to the first byte of the encapsulating UDP header

Additionally, implementation checks input IP packet length (odp_packet_len() minus odp_packet_l3_offset()) against protocol headers and reports an error (status.error.proto) if packet data length is less than protocol headers indicate.

Packets are processed in the input order. Packet order is maintained from input 'pkt' array to output 'pkt' array. Packet order is not guaranteed between calling threads.

Input packets must not be IP fragments.

The operation does packet transformation according to IPSEC standards (see e.g. RFC 4302 and 4303). Resulting packets are well formed, reconstructed original IP packets, with IPSEC headers removed and valid header field values restored. The amount and content of packet data before the IP header is undefined. Some amount of TFC padding may follow the IP packet payload, in which case packet length is larger than protocol headers indicate. TFC dummy packets have l3_type set to ODP_PROTO_L3_TYPE_NONE in tunnel mode or l4_type set to ODP_PROTO_L4_TYPE_NO_NEXT in transport mode. Dummy packets contain implementation specific amount of (dummy) data. Furthermore, inline IPSEC processing may drop dummy packets.

Each successfully transformed packet has a valid value for these metadata regardless of the inner packet parse configuration (odp_ipsec_inbound_config_t):

l3_offset: Offset to the first byte of the original IP packet. The value is implementation specific for tunnel mode TFC dummy packets.
l3_type: Specifies if the original packet is IPv4 or IPv6. For tunnel mode TFC dummy packets set to ODP_PROTO_L3_TYPE_NONE.
l4_type: Always set to ODP_PROTO_L4_TYPE_NO_NEXT for transport mode dummy packets. Otherwise, depends on parse configuration. Default value is ODP_PROTO_L4_TYPE_NONE.
pktio: For inline IPSEC processed packets, original packet input interface

Other metadata for parse results and error checks depend on configuration (selected parse and error check levels).

Parameters

	pkt_in	Packets to be processed
	num_in	Number of packets to be processed
[out]	pkt_out	Packet handle array for resulting packets
[in,out]	num_out	Number of resulting packets. Application sets this to 'pkt_out' array size. A successful operation sets this to the number of outputted packets (1 ... num_out).
	param	Inbound operation parameters

Returns: Number of input packets consumed (0 ... num_in)

Return values

<0	On failure

See also: odp_packet_user_ptr(), odp_packet_user_area(), odp_packet_l3_offset(), odp_packet_l4_offset()

Examples: ipsec_api/odp_ipsec.c, and odp_ipsecfwd.c.

◆ odp_ipsec_out()

int odp_ipsec_out	(	const odp_packet_t	pkt_in[],
		int	num_in,
		odp_packet_t	pkt_out[],
		int *	num_out,
		const odp_ipsec_out_param_t *	param
	)

Outbound synchronous IPSEC operation.

This operation does outbound IPSEC processing in synchronous mode (ODP_IPSEC_OP_MODE_SYNC). A successful operation returns the number of packets consumed and outputs a new packet handle for each outputted packet. Outputted packets contain IPSEC result metadata (odp_ipsec_packet_result_t), which should be checked for transformation errors, etc. Outputted packets with error status have undefined content, except that in case of MTU error the original input packet data is returned. The operation does not modify packets that it does not consume. It cannot consume all input packets if 'num_out' is smaller than 'num_in'.

Packet context pointer and user area content are copied from input to output packets. Output packets are allocated from the same pool(s) as input packets.

When outbound IP fragmentation offload is enabled, the number of outputted packets may be greater than the number of input packets.

Each input packet must have a valid value for these metadata (other metadata is ignored):

L3 offset: Offset to the first byte of the (outmost) IP header
L4 offset: Offset to the L4 header if L4 checksum offload is requested

Additionally, input IP packet length (odp_packet_len() minus odp_packet_l3_offset()) must match values in protocol headers. Otherwise results are undefined.

Packets are processed in the input order. Packet order is maintained from input 'pkt' array to output 'pkt' array. Packet order is not guaranteed between calling threads.

The operation does packet transformation according to IPSEC standards (see e.g. RFC 4302 and 4303). Resulting packets are well formed IP packets with IPSEC, etc headers constructed according to the standards. The amount and content of packet data before the IP header is undefined. Use outbound operation parameters to specify the amount of TFC padding appended to the packet during IPSEC transformation. Options can be used also to create TFC dummy packets. Packet data content is ignored in tunnel mode TFC dummy packet creation as tfc_pad_len option defines solely the packet length. In all other cases, payload length for the IPSEC transformation is specified by odp_packet_len() minus odp_packet_l3_offset() plus tfc_pad_len option.

Each successfully transformed packet has a valid value for these metadata:

L3 offset: Offset to the first byte of the (outmost) IP header

Parameters

	pkt_in	Packets to be processed
	num_in	Number of packets to be processed
[out]	pkt_out	Packet handle array for resulting packets
[in,out]	num_out	Number of resulting packets. Application sets this to 'pkt_out' array size. A successful operation sets this to the number of outputted packets (1 ... num_out).
	param	Outbound operation parameters

Returns: Number of input packets consumed (0 ... num_in)

Return values

<0	On failure

See also: odp_packet_user_ptr(), odp_packet_user_area(), odp_packet_l3_offset()

Examples: ipsec_api/odp_ipsec.c, odp_ipsec.c, and odp_ipsecfwd.c.

◆ odp_ipsec_in_enq()

int odp_ipsec_in_enq	(	const odp_packet_t	pkt[],
		int	num,
		const odp_ipsec_in_param_t *	param
	)

Inbound asynchronous IPSEC operation.

This operation does inbound IPSEC processing in asynchronous mode. It processes packets otherwise identically to odp_ipsec_in(), but outputs resulting packets as ODP_EVENT_PACKET events (with ODP_EVENT_PACKET_IPSEC subtype). The following ordering considerations apply to the events.

Asynchronous mode maintains packet order per SA when application calls the operation within an ordered or atomic scheduler context of the same queue. Resulting events for the same SA are enqueued in order. Packet order per SA at a destination queue is the same as if application would have enqueued packets there with odp_queue_enq_multi().

Packet order is also maintained when application otherwise guarantees (e.g. using locks) that the operation is not called simultaneously from multiple threads for the same SA(s).

Logically, packet processing (e.g. sequence number check) happens in the output order as defined above.

The function may be used also in inline processing mode, e.g. for IPSEC packets for which inline processing is not possible. Packets for the same SA may be processed simultaneously in both modes (initiated by this function and inline operation).

Post-processing may be required after the reception of an IPsec packet event to complete IPsec processing for the packet. The post-processing happens in the odp_ipsec_result() function that must be called at least once before packet data or metadata (other than packet type and subtype) may be accessed.

If reassembly is attempted but fails, the result packet delivered to the application will have reassembly status as ODP_PACKET_REASS_INCOMPLETE and will not have ODP_EVENT_PACKET_IPSEC subtype. In that case, the application can call odp_packet_reass_partial_state() to get fragments of the packet. The fragments will have subtype as ODP_EVENT_PACKET_IPSEC and the application must call odp_ipsec_result() for such a fragment before accessing its packet data.

Parameters

pkt	Packets to be processed
num	Number of packets to be processed
param	Inbound operation parameters

Returns: Number of input packets consumed (0 ... num)

Return values

<0	On failure

See also: odp_ipsec_in(), odp_ipsec_result()

Examples: ipsec_api/odp_ipsec.c, and odp_ipsecfwd.c.

◆ odp_ipsec_out_enq()

int odp_ipsec_out_enq	(	const odp_packet_t	pkt[],
		int	num,
		const odp_ipsec_out_param_t *	param
	)

Outbound asynchronous IPSEC operation.

This operation does outbound IPSEC processing in asynchronous mode. It processes packets otherwise identically to odp_ipsec_out(), but outputs resulting packets as ODP_EVENT_PACKET events (with ODP_EVENT_PACKET_IPSEC subtype). The following ordering considerations apply to the events.

Asynchronous mode maintains packet order per SA when application calls the operation within an ordered or atomic scheduler context of the same queue. Resulting events for the same SA are enqueued in order. Packet order per SA at a destination queue is the same as if application would have enqueued packets there with odp_queue_enq_multi().

Packet order is also maintained when application otherwise guarantees (e.g. using locks) that the operation is not called simultaneously from multiple threads for the same SA(s).

Logically, packet processing (e.g. sequence number assignment) happens in the output order as defined above.

The function may be used also in inline processing mode, e.g. for IPSEC packets for which inline processing is not possible.

Post-processing may be required after the reception of an IPsec packet event to complete IPsec processing for the packet. The post-processing happens in the odp_ipsec_result() function that must be called at least once before packet data or metadata (other than packet type and subtype) may be accessed.

Parameters

pkt	Packets to be processed
num	Number of packets to be processed
param	Outbound operation parameters

Returns: Number of input packets consumed (0 ... num)

Return values

<0	On failure

See also: odp_ipsec_out(), odp_ipsec_result()

Examples: ipsec_api/odp_ipsec.c, odp_ipsec.c, and odp_ipsecfwd.c.

◆ odp_ipsec_out_inline()

int odp_ipsec_out_inline	(	const odp_packet_t	pkt[],
		int	num,
		const odp_ipsec_out_param_t *	param,
		const odp_ipsec_out_inline_param_t *	inline_param
	)

Outbound inline IPSEC operation.

This operation does outbound inline IPSEC processing for the packets. It's otherwise identical to odp_ipsec_out_enq(), but outputs all successfully transformed packets to the specified output interface (or tm_queue), instead of generating events for those.

Inline operation parameters are defined per packet. The array of parameters must have 'num' elements and is pointed to by 'inline_param'.

Parameters

pkt	Packets to be processed
num	Number of packets to be processed
param	Outbound operation parameters
inline_param	Outbound inline operation specific parameters

Returns: Number of packets consumed (0 ... num)

Return values

<0	On failure

See also: odp_ipsec_out_enq()

Examples: ipsec_api/odp_ipsec.c.

◆ odp_ipsec_packet_from_event()

odp_packet_t odp_ipsec_packet_from_event ( odp_event_t ev )

Convert IPSEC processed packet event to packet handle.

Get packet handle to an IPSEC processed packet event. Event subtype must be ODP_EVENT_IPSEC_PACKET. IPSEC operation results can be examined with odp_ipsec_result().

Parameters

ev	Event handle

Returns: Packet handle

See also: odp_event_subtype(), odp_ipsec_result()

Examples: odp_ipsec.c.

◆ odp_ipsec_packet_to_event()

odp_event_t odp_ipsec_packet_to_event ( odp_packet_t pkt )

Convert IPSEC processed packet handle to event.

The packet handle must be an output of an IPSEC operation.

Parameters

pkt	Packet handle from IPSEC operation

Returns: Event handle

◆ odp_ipsec_result()

int odp_ipsec_result	(	odp_ipsec_packet_result_t *	result,
		odp_packet_t	packet
	)

Get IPSEC operation results from an IPSEC processed packet.

Successful IPSEC operations of all types (SYNC, ASYNC and INLINE) produce packets which contain IPSEC result metadata. This function copies the operation results from an IPSEC processed packet. Event subtype of this kind of packet is ODP_EVENT_PACKET_IPSEC. Results are undefined if a non-IPSEC processed packet is passed as input.

Some packet API operations output a new packet handle (e.g. odp_packet_concat()). IPSEC metadata remain valid as long as the packet handle is not changed from the original (output of e.g. odp_ipsec_in() or odp_ipsec_packet_from_event() call) IPSEC processed packet handle.

Parameters

[out]	result	Pointer to operation result for output
	packet	An IPSEC processed packet (ODP_EVENT_PACKET_IPSEC)

Return values

0	On success
<0	On failure

See also: odp_ipsec_in(), odp_ipsec_in_enq(), odp_ipsec_out(), odp_ipsec_out_enq(), odp_ipsec_packet_from_event()

Examples: ipsec_api/odp_ipsec.c, odp_ipsec.c, and odp_ipsecfwd.c.

◆ odp_ipsec_status()

int odp_ipsec_status	(	odp_ipsec_status_t *	status,
		odp_event_t	event
	)

Get IPSEC status information from an ODP_EVENT_IPSEC_STATUS event.

Copies IPSEC status information from an event. The event must be of type ODP_EVENT_IPSEC_STATUS.

Parameters

[out]	status	Pointer to status information structure for output.
	event	An ODP_EVENT_IPSEC_STATUS event

Return values

0	On success
<0	On failure

See also: odp_ipsec_sa_disable()

Examples: ipsec_api/odp_ipsec.c, odp_ipsec.c, and odp_ipsecfwd.c.

◆ odp_ipsec_test_sa_update()

int odp_ipsec_test_sa_update	(	odp_ipsec_sa_t	sa,
		odp_ipsec_test_sa_operation_t	op,
		const odp_ipsec_test_sa_param_t *	param
	)

IPSEC test API for modifying internal state of an SA.

This function is not meant to be used by normal applications but by special test applications that test or debug the operation of the underlying ODP implementation. Calling this function may degrade the performance of the calling thread, other threads or the IPSEC implementation in general.

Calling this function for an SA at the same time when the SA is used for processing traffic or when the SA is being modified through other parts of IPSEC API may result in undefined behaviour.

SA state update through this function may not be supported by all ODP implementations, ODP instances or SA instances or at every moment. This function may return failure for unspecified reasons even when the capability call indicated support for updating a particular parameter and previous similar calls succeeded.

Parameters

sa	IPSEC SA to be updated
op	Specifies operation to be performed
param	Pointer to IPSEC TEST SA param structure to be used for the operation

Returns: 0 On success

Return values

<0	On failure

◆ odp_ipsec_sa_mtu_update()

int odp_ipsec_sa_mtu_update	(	odp_ipsec_sa_t	sa,
		uint32_t	mtu
	)

Update MTU for outbound IP fragmentation.

When IP fragmentation offload is enabled, the SA is created with an MTU. This call may be used to update MTU at any time. MTU updates are not expected to happen very frequently.

Parameters

sa	IPSEC SA to be updated
mtu	The new MTU value

Return values

0	On success
<0	On failure

◆ odp_ipsec_sa_context()

void* odp_ipsec_sa_context ( odp_ipsec_sa_t sa )

Get user defined SA context pointer.

Parameters

sa	IPSEC SA handle

Returns: User defined SA context pointer value

Return values

NULL	On failure

◆ odp_ipsec_print()

void odp_ipsec_print ( void )

Print global IPSEC configuration info.

Print implementation-defined information about the global IPSEC configuration.

Examples: odp_debug.c.

◆ odp_ipsec_sa_print()

void odp_ipsec_sa_print ( odp_ipsec_sa_t sa )

Print IPSEC SA info.

Parameters

sa SA handle

Print implementation-defined IPSEC SA debug information to the ODP log.

◆ odp_ipsec_stats()

int odp_ipsec_stats	(	odp_ipsec_sa_t	sa,
		odp_ipsec_stats_t *	stats
	)

Get IPSEC stats for the IPSEC SA handle.

Parameters

	sa	IPSEC SA handle
[out]	stats	Stats output

Return values

0	on success
<0	on failure

◆ odp_ipsec_stats_multi()

int odp_ipsec_stats_multi	(	odp_ipsec_sa_t	sa[],
		odp_ipsec_stats_t	stats[],
		int	num
	)

Get IPSEC stats for multiple IPSEC SA handles.

Parameters

	sa	Array of IPSEC SA handles
[out]	stats	Stats array for output
	num	Number of SA handles

Return values

0	on success
<0	on failure

◆ odp_ipsec_sa_info()

int odp_ipsec_sa_info	(	odp_ipsec_sa_t	sa,
		odp_ipsec_sa_info_t *	sa_info
	)

Retrieve information about an IPSEC SA.

The cipher and auth key data(including key extra) will not be exposed and the corresponding pointers will be set to NULL. The IP address pointers will point to the corresponding buffers available in the SA info structure.

The user defined SA context pointer is an opaque field and hence the value provided during the SA creation will be returned.

Parameters

	sa	The IPSEC SA for which to retrieve information
[out]	sa_info	Pointer to caller allocated SA info structure to be filled in

Return values

0	On success
<0	On failure

API Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Typedef Documentation

◆ odp_ipsec_tunnel_param_t

◆ odp_ipsec_lifetime_t

◆ odp_ipsec_frag_mode_t

◆ odp_ipsec_lookup_mode_t

◆ odp_ipsec_out_opt_t

Enumeration Type Documentation

◆ odp_ipsec_op_mode_t

◆ odp_ipsec_test_sa_operation_t

◆ odp_ipsec_dir_t

◆ odp_ipsec_mode_t

◆ odp_ipsec_protocol_t

◆ odp_ipsec_tunnel_type_t

◆ odp_ipsec_frag_mode_t

◆ odp_ipsec_lookup_mode_t

◆ odp_ipsec_pipeline_t

◆ odp_ipsec_ip_version_t

◆ odp_ipsec_status_id_t

Function Documentation

◆ odp_ipsec_capability()

◆ odp_ipsec_cipher_capability()

◆ odp_ipsec_auth_capability()

◆ odp_ipsec_config_init()

◆ odp_ipsec_config()

◆ odp_ipsec_sa_param_init()

◆ odp_ipsec_sa_create()

◆ odp_ipsec_sa_disable()

◆ odp_ipsec_sa_destroy()

◆ odp_ipsec_sa_to_u64()

◆ odp_ipsec_in()

◆ odp_ipsec_out()

◆ odp_ipsec_in_enq()

◆ odp_ipsec_out_enq()

◆ odp_ipsec_out_inline()

◆ odp_ipsec_packet_from_event()

◆ odp_ipsec_packet_to_event()

◆ odp_ipsec_result()

◆ odp_ipsec_status()

◆ odp_ipsec_test_sa_update()

◆ odp_ipsec_sa_mtu_update()

◆ odp_ipsec_sa_context()

◆ odp_ipsec_print()

◆ odp_ipsec_sa_print()

◆ odp_ipsec_stats()

◆ odp_ipsec_stats_multi()

◆ odp_ipsec_sa_info()