DOCA IPsec

1.0

This guide provides developers with instructions on building and developing applications that require IPsec objects for DOCA Flow encryption and decryption.

IPsec is used to set up encrypted connections between different devices. It helps secure data sent over public networks. DOCA IPsec provides an API to create the security association ( SA) object required for flow encryption and decryption hardware acceleration.

Using DOCA IPsec can accelerate various IPsec actions in hardware such as:

  • IPsec Crypto Offload – accelerate ciphering ( encryption and decryption) only

  • IPsec Full Offload – accelerate all IPsec actions (i.e., encap/decap, ciphering, and replay protection so sequence numbers are done in the NIC hardware)

  • Partial – doing some IPsec actions in hardware and others in software

  • Transparent IPsec – a variant of IPsec full offload, data-path endpoint is not aware of IPsec (only available in NVIDIA® BlueField®)

This document is intended for software developers wishing to accelerate their application's flow encryption and decryption operations.

This library follows the architecture of a DOCA Core Context, it is recommended read the following sections before:

For more information about flow encryption and decryption, please refer to the DOCA Flow.

Warning

If your target application utilizes 100Gb/s or higher bandwidth, where a substantial part of the bandwidth is allocated for IPsec traffic, please refer to the NVIDIA BlueField-2 DPUs Product Release Notes or NVIDIA ConnectX-6 Dx Adapters Product Release Notes to learn about a potential bandwidth limitation. To access the relevant product release notes, please contact your NVIDIA sales representative.

Warning

NVIDIA® ConnectX®-6 Dx only supports Full Offload: Encrypted Overlay (where a Hypervisor controls IPsec offload) in a Linux OS with NVIDIA drivers.

DOCA IPsec is a DOCA Context as defined by DOCA Core. It leverages DOCA Core architecture to expose asynchronous tasks/events that are offloaded to hardware.

ipsec-on-dpu-version-1-modificationdate-1702941260297-api-v2.png

ipsec-on-host-version-1-modificationdate-1702941259707-api-v2.png

To start using a library, make sure to go through a configuration phase as described in DOCA Core Context Configuration Phase.

This section describes how to configure and start the context to allow execution of tasks.

Configurations

The context can be configured to match the application use case.

To find if a configuration is supported, or what the allowed min/max value for it is, please refer to section "Device Support".

Mandatory Configurations

The following configurations are mandatory and must be set by the application before attempting to start the context:

  • At least 1 task/event type must be configured. See configuration of Tasks and Events for information.

  • A device with appropriate support must be provided

Device Support

DOCA IPsec needs a device to operate. To pick a device, refer to DOCA Core Device Discovery.

DOCA IPsec-based applications can run either on the host machine or on the BlueField DPU target, or ConnectX for some functionality.

Confirm that the BlueField DPU is crypto-enabled:

Copy
Copied!
            

mlxfwmanager | grep Crypto # expected "Crypto Enabled;"

Warning

Make sure IPsec is supported using the doca_ipsec_cap_task_sa_create_is_supported function. IPsec is supported in the DPU or on the host when the DPU is in NIC mode only.

If a hardware sequence number or hardware antireplay are used, IPsec support is enabled using doca_ipsec_sequence_number_get_supported and doca_ipsec_antireplay_get_supported respectively.


This section describes execution on CPU using DOCA Core Progress Engine.

Tasks

DOCA IPsec exposes asynchronous tasks that leverage the DPU hardware according to the DOCA Core architecture. See DOCA Core Task for details.

SA Create Task

This task allows creating an SA object.

Configuration

Description

API to Set the Configuration

API to Query Support

Enable the task

doca_ipsec_task_sa_create_set_conf

doca_ipsec_cap_task_sa_create_is_supported


Input

Common input as described in DOCA Core Task.

Name

Description

Notes

SA attributes

A pointer to the intended SA attributes

-


Output

SA object in addition to the c ommon output as described in DOCA Core Task.

Task Successful Completion

After the task completes successfully, an SA object is created.

Task Failed Completion

If the task fails midway:

  • The task fails to allocate

  • The task is not submitted

  • The task fails to progress

Limitations

In addition to all the limitations described in DOCA Core Task, depending on how you set the offload (Crypto/Full), the acceleration varies:

  • IPsec Crypto Offload – accelerate ciphering ( encryption and decryption) only

  • IPsec Full Offload – accelerate all IPsec actions (e.g., encap/decap, ciphering, and replay protection so sequence numbers are done in the NIC hardware)

SA Destroy Task

This task allows destroying an SA object.

Configuration

Description

API to Set the Configuration

API to Query Support

Enable the task

doca_ipsec_task_sa_destroy_set_conf

-


Input

Common input as described in DOCA Core Task.

Name

Description

Notes

SA object

-

-


Output

Common output as described in DOCA Core Task.

Task Successful Completion

After the task completes successfully, the SA object is destroyed.

Task Failed Completion

If the task fails midway, an SA object is not destroyed.

The DOCA IPsec library follows the context state machine as described in DOCA Core Context State Machine.

The following section describes how to move to the state and what is allowed in each state.

Idle

In this state, it is expected that application will either:

  • Destroy the context

  • Start the context

Allowed operations:

  • Configuring the context according to section "Configurations"

  • Starting the context

It is possible to reach this state as follows:

Previous State

Transition Action

None

Create the context

Running

Call stop after making sure all tasks have been freed

Stopping

Call progress until all tasks are completed, and then freed


Starting

In this state, it is expected that application will c all progress to allow transition to next state.

It is possible to reach this state as follows:

Previous State

Transition Action

Idle

Call start after configuration


Running

In this state, it is expected that application will:

  • Allocate and submit tasks

  • Call progress to complete tasks and/or receive events

Allowed operations:

  • Allocating a previously configured task

  • Submitting an allocated task

  • Calling stop

It is possible to reach this state as follows:

Previous State

Transition Action

Idle

Call start after configuration

Starting

Call progress until the context state transitions


Stopping

In this state, it is expected that application will free any completed tasks.

Allowed operations:

  • Allocating previously configured task

  • Submitting an allocated task

  • Calling stop

It is possible to reach this state as follows:

Previous State

Transition Action

Running

Call progress and fatal error occurs

Running

Call stop without freeing all tasks


© Copyright 2023, NVIDIA. Last updated on Feb 9, 2024.