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

[Stephen Hemminger]

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 at 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:
 
 .. code-block:: console
 
-- 
2.51.0