NVIDIA DOCA File Integrity Application Guide

This guide provides a file integrity implementation on top of NVIDIA® BlueField® DPU.

Introduction

The file integrity application exhibits how to use the DOCA Comm Channel and DOCA SHA libraries to send and receive a file securely.

The application's logic includes both a client and a server:

Client side – the application opens a file, calculates the SHA (secure hash algorithm) digest on it, and sends the digest of the source file alongside the file itself to the server
Server side – the application calculates the SHA on the received file and compares the received digest to the calculated one to check if the file has been compromised

Warning

SHA hardware acceleration is only available on the BlueField-2 DPU. This application is not supported on BlueField-3.

System Design

The file integrity application runs in client mode (host) and server mode (DPU).

sys-design-version-1-modificationdate-1707420886197-api-v2.png

Application Architecture

The file integrity application runs on top of the DOCA Comm Channel API to send and receive files from the host and DPU.

app-arch-version-1-modificationdate-1707420886730-api-v2.png

Connection is established on both sides by the Comm Channel API.
Client submits SHA job with the DOCA SHA library and sends the result to the server.
Client sends the number of messages required to send the content of the file.
Client sends data segments in size of up to 4032 bytes.
Server submits a partial SHA job on each received segment.
Server sends an ACK message to the client when all parts of the file are received successfully.
Server compares the received SHA to the calculated SHA.

DOCA Libraries

This application leverages the following DOCA libraries:

Refer to their respective programming guide for more information.

Installation

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

Application Execution

The file integrity application is provided in both source and binary forms, and the binary is located under /opt/mellanox/doca/applications/file_integrity/bin/doca_file_integrity.

Application usage instructions:

Copy
Copied!

            
            Usage: doca_file_integrity [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 Comm Channel device PCI address
  -r, --rep-pci                     DOCA Comm Channel device representor PCI address
  -f, --file                        File to send by the client / File to write by the server
  -t, --timeout                     Application timeout for receiving file content messages, default is 5 sec

Note

This usage printout can be printed to the command line using the -h (or --help) options:

Copy
Copied!

            
            /opt/mellanox/doca/applications/file_integrity/bin/doca_file_integrity -h

Note

For additional information, refer to section "Command Line Flags".

CLI example for running the application on BlueField:
Copy

Copied!
```
            
            /opt/mellanox/doca/applications/file_integrity/bin/doca_file_integrity -p 03:00.0 -r 3b:00.0 -f received.txt
        
```
Warning

Both the DOCA Comm Channel device PCIe address (03:00.0) and the DOCA Comm Channel device representor PCIe address (3b:00.0) should match the addresses of the desired PCIe devices.
CLI example for running the application on the host:
Copy

Copied!
```
            
            /opt/mellanox/doca/applications/file_integrity/bin/doca_file_integrity -p 3b:00.0 -f send.txt
        
```
Warning

The DOCA Comm Channel device PCIe address (3b:00.0) should match the address of the desired PCIe device.
The application also supports a JSON-based deployment mode, in which all command-line arguments are provided through a JSON file:
Copy

Copied!
```
            
            doca_file_integrity --json [json_file]
        
```
For example:
Copy

Copied!
```
            
            cd /opt/mellanox/doca/applications/file_integrity/bin
./doca_file_integrity --json ./file_integrity_params.json
        
```
Warning

Before execution, ensure that the used JSON file contains the correct configuration parameters, and especially the PCIe addresses necessary for the deployment .

Command Line Flags

Flag Type	Short Flag	Long Flag/JSON Key	Description	JSON Content
General flags	`h`	`help`	Prints a help synopsis	N/A
	`v`	`version`	Prints program version information	N/A
	`l`	`log-level`	Set the log level for the application: DISABLE=10 CRITICAL=20 ERROR=30 WARNING=40 INFO=50 DEBUG=60 TRACE=70 ( requires compilation with `TRACE` log level support )	Copy Copied! `"log-level": 60`
	N/A	`sdk-log-level`	Sets the log level for the program: DISABLE=10 CRITICAL=20 ERROR=30 WARNING=40 INFO=50 DEBUG=60 TRACE=70	Copy Copied! `"sdk-log-level": 40`
	`j`	`json`	Parse all command flags from an input JSON file	N/A
Program flags	`f`	`file`	For client – path to the file to be sent For server – path to write the file into Warning This is a mandatory flag.	Copy Copied! `"file": "/tmp/data.txt"`
	`p`	`pci-addr`	Comm Channel DOCA device PCIe address Warning This is a mandatory flag.	Copy Copied! `"pci-addr": 03:00.1`
	`r`	`rep-pci`	Comm Channel DOCA device representor PCIe address Warning This flag is mandatory only on the DPU.	Copy Copied! `"rep-pci": b1:00.1`

Note

Refer to DOCA Arg Parser for more information regarding the supported flags and execution modes.

Troubleshooting

Please refer to the NVIDIA DOCA Troubleshooting Guide for any issue encountered with the installation or execution of the DOCA applications .

In addition to providing the application in binary form, the installation also includes all of the application sources and compilation instructions so as to allow modifying the sources and recompiling the application. For more information about the applications, as well as development and compilation tips, refer to the DOCA Applications page.

The sources of the application can be found under the /opt/mellanox/doca/applications/file_integrity/src directory.

Recompiling All Applications

The applications are all defined under a single meson project, so the default compilation recompiles all the DOCA applications.

To build all the applications together, run:

Copy
Copied!

            
            cd /opt/mellanox/doca/applications/
meson /tmp/build 
ninja -C /tmp/build

Note

doca_file_integrity is created under /tmp/build/file_integrity/src/.

Recompiling File Integrity Application Only

To directly build only the file integrity application:

Copy
Copied!

            
            cd /opt/mellanox/doca/applications/
meson /tmp/build -Denable_all_applications=false -Denable_file_integrity=true
ninja -C /tmp/build

Note

doca_file_integrity is created under /tmp/build/file_integrity/src/.

Alternatively, one can set the desired flags in the meson_options.txt file instead of providing them in the compilation command line:

Edit the following flags in /opt/mellanox/doca/applications/meson_options.txt:
- Set enable_all_applications to false
- Set enable_file_integrity to true

Run the following compilation commands :

Copy
Copied!

            
            cd /opt/mellanox/doca/applications/
meson /tmp/build 
ninja -C /tmp/build

Note

doca_file_integrity is created under /tmp/build/file_integrity/src/.

Troubleshooting

Refer to the NVIDIA DOCA Troubleshooting Guide for any issue encountered with the compilation of the application.

Application Code Flow

Parse application argument.

Initialize the arg parser resources and register DOCA general parameters.

Copy
Copied!

            
            doca_arg_init();

Register file integrity application parameters.

Copy
Copied!

            
            register_file_integrity_params();

Parse application parameters.

Copy
Copied!

            
            doca_argp_start();

Set endpoint attributes.
Copy

Copied!
```
            
            set_endpoint_properties();
        
```
1. Set maximum message size of 4032 bytes.
2. Set number of maximum messages allowed per connection.

Create Comm Channel endpoint.

Copy
Copied!

            
            doca_comm_channel_ep_create();

Create endpoint for client/server.

Create SHA context.
Copy

Copied!
```
            
            doca_sha_create();
        
```
1. Create SHA context for submitting SHA jobs for client/server.

Run client/server main logic.

Copy
Copied!

            
            file_integrity_client/server();

Clean up the File Integrity app.

Copy
Copied!

            
            file_integrity_cleanup();

Free all application resources.

References

/opt/mellanox/doca/applications/file_integrity/src
/opt/mellanox/doca/applications/file_integrity/bin/file_integrity_params.json

NVIDIA DOCA File Integrity Application Guide

On This Page

Introduction

System Design

Application Architecture

DOCA Libraries

Running the Application

Installation

Application Execution

Command Line Flags

Troubleshooting

Recompiling the Application

Recompiling All Applications

Recompiling File Integrity Application Only

Troubleshooting

Application Code Flow

References