[PATCH 17/29] doc/guides: improve FIPS validation sample app guide

Stephen Hemminger
2026-01-14T22:26:56Z

Improve the FIPS validation sample application documentation:
- restructure CAVP and ACVP as subsections under Limitations
- fix indentation of code blocks and bullet lists
- improve grammar and clarify explanations
- use consistent formatting for options

Signed-off-by: Stephen Hemminger <stephen@networkplumber.org>
---
doc/guides/sample_app_ug/fips_validation.rst | 117 ++++++++++---------
1 file changed, 60 insertions(+), 57 deletions(-)

diff --git a/doc/guides/sample_app_ug/fips_validation.rst b/doc/guides/sample_app_ug/fips_validation.rst
index 613c5afd19..4c96452b65 100644
--- a/doc/guides/sample_app_ug/fips_validation.rst
+++ b/doc/guides/sample_app_ug/fips_validation.rst
@@ -17,32 +17,35 @@ Automated Crypto Validation Protocol (ACVP) test vectors.

For an algorithm implementation to be listed on a cryptographic module
validation certificate as an Approved security function, the algorithm
-implementation must meet all the requirements of FIPS 140-2 (in case of CAVP)
-and FIPS 140-3 (in case of ACVP) and must successfully complete the
+implementation must meet all the requirements of FIPS 140-2 (in the case of CAVP)
+and FIPS 140-3 (in the case of ACVP) and must successfully complete the
cryptographic algorithm validation process.

Limitations
-----------

+The following sections describe limitations for CAVP and ACVP.
+
CAVP
-----
+~~~~

* The version of request file supported is ``CAVS 21.0``.
-* If the header comment in a ``.req`` file does not contain a Algo tag
- i.e ``AES,TDES,GCM`` you need to manually add it into the header comment for
- example::
+* If the header comment in a ``.req`` file does not contain an Algo tag
+ (i.e., ``AES,TDES,GCM``), you need to manually add it into the header comment.
+ For example::

# VARIABLE KEY - KAT for CBC / # TDES VARIABLE KEY - KAT for CBC

* The application does not supply the test vectors. The user is expected to
- obtain the test vector files from `CAVP
- <https://csrc.nist.gov/projects/cryptographic-algorithm-validation-
- program/block-ciphers>`_ website. To obtain the ``.req`` files you need to
+ obtain the test vector files from the `CAVP
+ <https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/block-ciphers>`_
+ website. To obtain the ``.req`` files, you need to
email a person from the NIST website and pay for the ``.req`` files.
The ``.rsp`` files from the site can be used to validate and compare with
the ``.rsp`` files created by the FIPS application.

-* Supported test vectors
+* Supported test vectors:
+
* AES-CBC (128,192,256) - GFSbox, KeySbox, MCT, MMT
* AES-GCM (128,192,256) - EncryptExtIV, Decrypt
* AES-CCM (128) - VADT, VNT, VPT, VTT, DVPT
@@ -52,12 +55,14 @@ CAVP
VarText

ACVP
-----
+~~~~

* The application does not supply the test vectors. The user is expected to
- obtain the test vector files from `ACVP <https://pages.nist.gov/ACVP>`_
+ obtain the test vector files from the `ACVP <https://pages.nist.gov/ACVP>`_
website.
-* Supported test vectors
+
+* Supported test vectors:
+
* AES-CBC (128,192,256) - AFT, MCT
* AES-GCM (128,192,256) - AFT
* AES-CCM (128,192,256) - AFT
@@ -78,74 +83,72 @@ ACVP
Application Information
-----------------------

-If a ``.req`` is used as the input file after the application is finished
-running it will generate a response file or ``.rsp``. Differences between the
-two files are, the ``.req`` file has missing information for instance if doing
-encryption you will not have the cipher text and that will be generated in the
-response file. Also if doing decryption it will not have the plain text until it
-finished the work and in the response file it will be added onto the end of each
-operation.
-
-The application can be run with a ``.rsp`` file and what the outcome of that
-will be is it will add a extra line in the generated ``.rsp`` which should be
-the same as the ``.rsp`` used to run the application, this is useful for
-validating if the application has done the operation correctly.
+If a ``.req`` file is used as the input file, after the application finishes
+running it generates a response file (``.rsp``). The differences between
+the two files are as follows: the ``.req`` file has missing information (for instance,
+if performing encryption, you do not have the cipher text, and that is
+generated in the response file); and if performing decryption, it does not
+have plain text until the work has finished. In the response file, this information
+is added onto the end of each operation.

+The application can be run with a ``.rsp`` file as input. The outcome is that
+an extra line in the generated ``.rsp`` file is added. This should be the same
+as the ``.rsp`` used to run the application. This is useful for validating if
+the application has performed the operation correctly.

Compiling the Application
-------------------------

-* Compile Application
+To compile the sample application, see :doc:`compiling`.

- To compile the sample application see :doc:`compiling`.
+Run ``dos2unix`` on the request files:

-* Run ``dos2unix`` on the request files
-
- .. code-block:: console
+.. code-block:: console

- dos2unix AES/req/*
- dos2unix GCM/req/*
- dos2unix CCM/req/*
- dos2unix CMAC/req/*
- dos2unix HMAC/req/*
- dos2unix TDES/req/*
- dos2unix SHA/req/*
+ dos2unix AES/req/*
+ dos2unix GCM/req/*
+ dos2unix CCM/req/*
+ dos2unix CMAC/req/*
+ dos2unix HMAC/req/*
+ dos2unix TDES/req/*
+ dos2unix SHA/req/*

Running the Application
-----------------------

The application requires a number of command line options:

- .. code-block:: console
+.. code-block:: console
+
+ ./dpdk-fips_validation [EAL options]
+ -- --req-file FILE_PATH/FOLDER_PATH
+ --rsp-file FILE_PATH/FOLDER_PATH
+ [--cryptodev DEVICE_NAME] [--cryptodev-id ID] [--path-is-folder]
+ --mbuf-dataroom DATAROOM_SIZE

- ./dpdk-fips_validation [EAL options]
- -- --req-file FILE_PATH/FOLDER_PATH
- --rsp-file FILE_PATH/FOLDER_PATH
- [--cryptodev DEVICE_NAME] [--cryptodev-id ID] [--path-is-folder]
- --mbuf-dataroom DATAROOM_SIZE
+where:

-where,
- * req-file: The path of the request file or folder, separated by
+* req-file: The path of the request file or folder, separated by the
``path-is-folder`` option.

- * rsp-file: The path that the response file or folder is stored. separated by
+* rsp-file: The path that the response file or folder is stored, separated by the
``path-is-folder`` option.

- * cryptodev: The name of the target DPDK Crypto device to be validated.
+* cryptodev: The name of the target DPDK Crypto device to be validated.

- * cryptodev-id: The id of the target DPDK Crypto device to be validated.
+* cryptodev-id: The ID of the target DPDK Crypto device to be validated.

- * path-is-folder: If presented the application expects req-file and rsp-file
- are folder paths.
+* path-is-folder: If present, the application expects req-file and rsp-file
+ to be folder paths.

- * mbuf-dataroom: By default the application creates mbuf pool with maximum
- possible data room (65535 bytes). If the user wants to test scatter-gather
- list feature of the PMD he or she may set this value to reduce the dataroom
+* mbuf-dataroom: By default, the application creates an mbuf pool with maximum
+ possible data room (65535 bytes). If the user wants to test the scatter-gather
+ list feature of the PMD, this value can be set to reduce the dataroom
size so that the input data may be divided into multiple chained mbufs.

-To run the application in linux environment to test one AES FIPS test data
-file for crypto_aesni_mb PMD, issue the command:
+To run the application in a Linux environment to test one AES FIPS test data
+file for the crypto_aesni_mb PMD, issue the command:

.. code-block:: console

@@ -153,8 +156,8 @@ file for crypto_aesni_mb PMD, issue the command:
--req-file /PATH/TO/REQUEST/FILE.req --rsp-file ./PATH/TO/RESPONSE/FILE.rsp
--cryptodev crypto_aesni_mb

-To run the application in linux environment to test all AES-GCM FIPS test
-data files in one folder for crypto_aesni_gcm PMD, issue the command:
+To run the application in a Linux environment to test all AES-GCM FIPS test
+data files in one folder for the crypto_aesni_gcm PMD, issue the command: