This guide provides developers with instructions on building and developing applications that require IPsec objects for DOCA Flow encryption and decryption.
The DOCA IPsec library is supported at beta level.
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.
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.
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.
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:
mlxfwmanager | grep Crypto # expected "Crypto Enabled;"
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 |