DOCA Documentation v2.5.1 LTS
1.0

DOCA AES-GCM

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

Warning

The DOCA AES-GCM library is supported at alpha level.

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 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:

    image-2023-10-19_13-47-37-1-version-1-modificationdate-1702684787623-api-v2.png

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

    image-2023-10-19_13-47-47-1-version-1-modificationdate-1702684788100-api-v2.png

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

    image-2023-10-19_13-47-54-1-version-1-modificationdate-1702684788350-api-v2.png

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

Note

AES-GCM tasks can also support encrypt/decrypt in place.

Tasks support buffers with the following features:

Buffer Type

Source Buffer

Destination Buffer

Local mmap buffer

Yes

Yes

Mmap from PCIe export buffer

Yes

Yes

Mmap from RDMA export buffer

No

No

Linked list buffer

Yes

No


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

Description

API to Set Configuration

API to Query Support

Enable the task

doca_aes_gcm_task_encrypt_set_conf

doca_aes_gcm_cap_task_encrypt_is_supported

Number of tasks

doca_aes_gcm_task_encrypt_set_conf

doca_aes_gcm_cap_get_max_num_tasks

Maximal buffer size

-

doca_aes_gcm_cap_task_encrypt_get_max_buf_size

Maximum buffer list size

-

doca_aes_gcm_cap_task_encrypt_get_max_list_buf_num_elem

Maximum initialization vector length

-

doca_aes_gcm_cap_task_encrypt_get_max_iv_length

Enable authentication tag size

-

doca_aes_gcm_cap_task_encrypt_is_tag_96_supported

doca_aes_gcm_cap_task_encrypt_is_tag_128_supported

Enable key type

-

doca_aes_gcm_cap_task_encrypt_is_key_type_supported


Input

Common input as described in DOCA Core Task

Name

Description

Notes

source buffer

Buffer pointing to the memory to be encrypted

Only the data residing in the data segment is encrypted

destination buffer

Buffer pointing to where memory is encrypted to

The encrypted data is appended to the tail segment

key

Key to encrypt the data

Created by the function doca_aes_gcm_key_create

Users should use the same key to encrypt and decrypt the data

initialization vector (IV)

Initialization vector to be used by the AES-GCM algorithm

Users should use the same IV to encrypt and decrypt the data

initialization vector length

Initialization vector length that must be supplied for the AES-GCM algorithm

Represented in bytes, 0B-12B values are supported

authentication tag size

Authentication tag size to be supplied for the AES-GCM algorithm. The tag is automatically calculated and appended to the result buffer.

Represented in bytes, only 12B and 16B values are supported

additional authenticated data size

Additional authenticated data size to be supplied for the AES-GCM algorithm. This data, which should be present at the beginning of the source buffer, is will not encrypted but is authenticated.

Represented in bytes


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

Description

API to Set Configuration

API to Query Support

Enable the task

doca_aes_gcm_task_decrypt_set_conf

doca_aes_gcm_cap_task_decrypt_is_supported

Number of tasks

doca_aes_gcm_task_decrypt_set_conf

doca_aes_gcm_cap_get_max_num_tasks

Maximal buffer size

doca_aes_gcm_cap_task_decrypt_get_max_buf_size

Maximum buffer list size

doca_aes_gcm_cap_task_decrypt_get_max_list_buf_num_elem

Maximum initialization vector length

doca_aes_gcm_cap_task_decrypt_get_max_iv_length

Enable authentication tag size

doca_aes_gcm_cap_task_decrypt_is_tag_96_supported

doca_aes_gcm_cap_task_decrypt_is_tag_128_supported

Enable key type

doca_aes_gcm_cap_task_decrypt_is_key_type_supported


Input

Common input as described in DOCA Core Task.

Name

Description

Notes

Source buffer

Buffer pointing to the memory to be decrypted

Only the data residing in the data segment is decrypted

Destination buffer

Buffer pointing to where memory is decrypted to

The decrypted data is appended to the tail segment extending the data segment

Key

Key to decrypt the data

Created by the function doca_aes_gcm_key_create

The user should use the same key to encrypt and decrypt the data

Initialization vector (IV)

Initialization vector to be used by the AES-GCM algorithm

The user should use the same IV to encrypt and decrypt the data

Initialization vector length

Initialization vector length that must be supplied for the AES-GCM algorithm

Represented in bytes, 0B-12B values are supported

Authentication tag size

Authentication tag size to be supplied for the AES-GCM algorithm. The tag, present at the end of the source buffer, is verified and is not present in the destination buffer.

Represented in bytes, only 12B and 16B values are supported

Additional authenticated data size

Additional authenticated data size to be supplied for the AES-GCM algorithm. This data, present at the beginning of the source buffer, is not encrypted but is authenticated.

Represented in bytes


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:

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 freed


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:

Previous State

Transition Action

Idle

Call start after configuration


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:

Previous State

Transition Action

Running

Call progress and fatal error occurs

Running

Call stop without freeing all tasks


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:

  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

© Copyright 2023, NVIDIA. Last updated on Mar 5, 2024.