DOCA AES-GCM

This guide provides instructions on building and developing applications that require data encryption and decryption using the AES-GCM algorithm.

The library provides an API for executing AES-GCM operations on DOCA buffers, where the buffers reside in either local memory (i.e., within the same host) or host memory accessible by the DPU (remote memory). Using DOCA AES-GCM, complex encrypt/decrypt operations can be easily executed in an optimized, hardware-accelerated manner.

This document is intended for software developers wishing to accelerate their application's encrypt/decrypt operations.

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

• DOCA Core Execution Model

• DOCA Core Device

• DOCA Core Memory Subsystem

DOCA AES-GCM-based applications can run either on the host machine or on the NVIDIA® BlueField® DPU target.

Encrypting/decrypting from the host to DPU and vice versa can only be run when the DPU is configured in DPU mode.

DOCA AES-GCM is a DOCA Core Context. This library leverages the DOCA Core architecture to expose asynchronous tasks/events that are offloaded to hardware.

AES-GCM can be used to encrypt/decrypt data as illustrated in the following diagrams:

• Encrypt/decrypt from local memory to local memory:

  

• Using the DPU to copy memory between the host and the DPU:

  

• Using the host to copy memory between the host and the DPU:

  

Objects

Device and Representor

The library requires a DOCA device to operate. The device is used to access memory and perform the actual encrypt/decrypt. See DOCA Core Device Discovery.

For the same BlueField DPU, it does not matter which device is used (i.e., PF/VF/SF) as all these devices utilize the same hardware component. If there are multiple DPUs, then it is possible to create a AES-GCM instance per DPU, providing each instance with a device from a different DPU.

To access memory that is not local (i.e., from the host to DPU or vice versa), the DPU side of the application must pick a device with an appropriate representor (see DOCA Core Device Representor Discovery). The device must stay valid as long as AES-GCM instance is not destroyed.

Memory Buffers

The encrypt/decrypt task, requires two DOCA buffers containing the destination and the source.

Depending on the allocation pattern of the buffers, consider the DOCA Core Inventory Types table.

To find what kind of memory is supported, refer to the following table.

Buffers must not be modified or read during the encrypt/decrypt operation.

To start using the library users must 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 and retrieval of events.

Configurations

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

To find if a configuration is supported or its min/max value, refer to Device Support.

Mandatory Configurations

These configurations must be set by the application before attempting to start the context:

• At least one task/event type must be configured. See configuration of Tasks and/or Events.

• A device with appropriate support must be provided upon creation

Device Support

DOCA AES-GCM requires a device to operate. For picking a device, see DOCA Core Device Discovery.

As device capabilities may change in the future (see DOCA Core Device Support) it is recommended to select your device using the following method:

• doca_aes_gcm_cap_task_encrypt_is_supported

• doca_aes_gcm_cap_task_decrypt_is_supported

Some devices can allow different capabilities as follows:

• The maximum number of tasks

• The maximum buffer size

• The maximum supported number of elements in DOCA linked-list buffer

• The maximum initialization vector length

• Check if authentication tag of size 96-bit is supported

• Check if authentication tag of size 128-bit is supported

• Check if a given AES-GCM key type is supported

Buffer Support

Tasks support buffers with the following features:

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

Tasks

DOCA AES-GCM exposes asynchronous tasks that leverage DPU hardware according to the DOCA Core architecture.

Encrypt Task

The encrypt task allows data encryption using buffers as described in Buffer Support.

Configuration

Input

Common input as described in DOCA Core Task

Output

Common output as described in DOCA Core Task.

Task Successful Completion

After the task completes successfully, the following happens:

• The data from the source buffer is encrypted and written to the destination buffer

• The destination buffer data segment is extended to include the encrypted data

Task Failed Completion

If the task fails midway:

• The context may enter stopping state if a fatal error occurs

• The source and destination doca_buf objects are not modified

• The destination buffer contents may be modified

Limitations

• The operation is not atomic

• Once the task is submitted, the source and destination should not be read/written to

• Other limitations are described in DOCA Core Task

Decrypt Task

The decrypt task allows data decryption. Using buffers as described in Buffer Support.

Configuration

Input

Common input as described in DOCA Core Task.

Output

Common output as described in DOCA Core Task.

Task Successful Completion

After the task completes successfully, the following happens:

• The data from the source buffer is decrypted and written to the destination buffer

• The destination buffer data segment is extended to include the decrypted data

Task Failed Completion

If the task fails midway:

• The context may enter stopping state if a fatal error occurs

• The source and destination doca_buf objects is not modified

• The destination buffer contents may be modified

Limitations

• The operation is not atomic

• Once the task is submitted, the source and destination should not be read/written to

• Other limitations are described in DOCA Core Task

Events

DOCA AES-GCM exposes asynchronous events to notify about changes that happen unexpectedly according to the DOCA Core architecture.

The only events AES-GCM exposes are common events as described in DOCA Core Event.

The DOCA AES-GCM library follows the Context state machine as described in DOCA Core Context State Machine.

The following section describes moving states and what is allowed in each state.

Idle

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

• Destroys the context

• Starts the context

Allowed operations:

• Configuring the context according to Configurations

• Starting the context

It is possible to reach this state as follows:

Starting

This state cannot be reached.

Running

In this state, it is expected that the application:

• Allocates and submits tasks

• Calls progress to complete tasks and/or receive events

Allowed operations:

• Allocating previously configured task

• Submitting a task

• Calling stop

It is possible to reach this state as follows:

Stopping

In this state, it is expected that the application:

• Calls progress to complete all inflight tasks (tasks complete with failure)

• Frees any completed tasks

Allowed operations:

• Calling progress

It is possible to reach this state as follows:

DOCA AES-GCM only supports datapath on the CPU. See Execution Phase.

This section describes DOCA AES-GCM samples based on the DOCA AES-GCM library.

The samples in this section illustrate how to use the DOCA AES-GCM API to do the following:

• Encrypt contents of a buffer to another buffer

• Decrypt contents of a buffer to another buffer

Running the Samples

1. Refer to the following documents:

   • NVIDIA DOCA Installation Guide for Linux for details on how to install BlueField-related software.

   • NVIDIA DOCA Troubleshooting Guide for any issue you may encounter with the installation, compilation, or execution of DOCA samples.

2. To build a given sample:

   Copy

   Copied!

               
   
               
   cd /opt/mellanox/doca/samples/doca_aes_gcm/<sample_name>
   meson/tmp/build
   ninja -C/tmp/build
           

   Note

   The binary doca_<sample_name> is created under /tmp/build/.

3. Sample (e.g., doca_aes_gcm_encrypt) usage:

   Copy

   Copied!

               
   
               
   Usage: doca_aes_gcm_encrypt [DOCA Flags] [Program Flags]
    
   DOCA Flags:
     -h, --help                        Print a help synopsis
     -v, --version                     Print program version information
     -l, --log-level                   Set the (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
     --sdk-log-level                   Set the SDK (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
     -j, --json <path>                 Parse all command flags from an input json file
    
   Program Flags:
     -p, --pci-addr                    DOCA device PCI device address - default: 03:00.0
     -f, --file                        Input file to encrypt/decrypt
     -o, --output                      Output file - default: /tmp/out.txt
     -k, --key                         Raw key to encrypt/decrypt with, represented in hex format (32 characters for 128-bit key, and 64 for 256-bit key) - default: 256-bit key, equals to zero
     -i, --iv                          Initialization vector, represented in hex format (0-24 characters for 0-96-bit IV) - default: 96-bit IV, equals to zero
     -t, --tag size                    Authentication tag size. Tag size is in bytes and can be 12B or 16B - default: 12
     -a, --aad size                    Additional authenticated data size - default: 0
           

4. For additional information per sample, use the -h option:

   Copy

   Copied!

               
   
               
   /tmp/build/doca_<sample_name>-h
           

Samples

AES-GCM Encrypt

This sample illustrates how to encrypt data with AES-GCM.

The sample logic includes:

1. Locating DOCA device.

2. Initializing required DOCA Core structures.

3. Setting the AES-GCM encrypt tasks configuration.

4. Populating DOCA memory map with two relevant buffers.

5. Allocating element in DOCA buffer inventory for each buffer.

6. Creating DOCA AES-GCM key.

7. Allocating and initializing AES-GCM encrypt task.

8. Submitting AES-GCM encrypt task.

9. Retrieving AES-GCM encrypt task once it is done.

10. Checking task result.

11. Destroying all AES-GCM and DOCA Core structures.

Reference:

• /opt/mellanox/doca/samples/doca_aes_gcm/aes_gcm_encrypt/aes_gcm_encrypt_sample.c

• /opt/mellanox/doca/samples/doca_aes_gcm/aes_gcm_encrypt/aes_gcm_encrypt_main.c

• /opt/mellanox/doca/samples/doca_aes_gcm/aes_gcm_encrypt/meson.build

AES-GCM Decrypt

This sample illustrates how to decrypt data with AES-GCM.

The sample logic includes:

1. Locating DOCA device.

2. Initializing needed DOCA Core structures.

3. Setting the AES-GCM decrypt tasks configuration.

4. Populating DOCA memory map with two relevant buffers.

5. Allocating element in DOCA buffer inventory for each buffer.

6. Creating DOCA AES-GCM key.

7. Allocating and initializing AES-GCM decrypt task.

8. Submitting AES-GCM decrypt task.

9. Retrieving AES-GCM decrypt task once it is done.

10. Checking task result.

11. Destroying all AES-GCM and DOCA Core structures.

Reference:

• /opt/mellanox/doca/samples/doca_aes_gcm/aes_gcm_decrypt/aes_gcm_decrypt_sample.c

• /opt/mellanox/doca/samples/doca_aes_gcm/aes_gcm_decrypt/aes_gcm_decrypt_main.c

• /opt/mellanox/doca/samples/doca_aes_gcm/aes_gcm_decrypt/meson.build