[PATCH v4 8/8] doc: add guides for fips validation

[Marko Kovacevic <marko.kovacevic@intel.com>]

Document explains how to run the fips sample app
and instructions users need to parser all the request
files and generate the response files.

Signed-off-by: Marko Kovacevic <marko.kovacevic@intel.com>
Signed-off-by: Fan Zhang <roy.fan.zhang@intel.com>
---
 doc/guides/rel_notes/release_18_11.rst       |   6 ++
 doc/guides/sample_app_ug/fips_validation.rst | 105 +++++++++++++++++++++++++++
 doc/guides/sample_app_ug/index.rst           |   1 +
 3 files changed, 112 insertions(+)
 create mode 100644 doc/guides/sample_app_ug/fips_validation.rst

diff --git a/doc/guides/rel_notes/release_18_11.rst b/doc/guides/rel_notes/release_18_11.rst
index 436b20e..83ad92e 100644
--- a/doc/guides/rel_notes/release_18_11.rst
+++ b/doc/guides/rel_notes/release_18_11.rst
@@ -54,6 +54,12 @@ New Features
      Also, make sure to start the actual text at the margin.
      =========================================================
 
+* **Added Cryptodev Fips Validation Example Application.**
+
+  Added an example application to parse and perform symmetric cryptography
+  computation to the NIST Cryptographic Algorithm Validation Program (CAVP)
+  test vectors.
+
 * **Added support for using externally allocated memory in DPDK.**
 
   DPDK has gained support for creating new ``rte_malloc`` heaps referencing
diff --git a/doc/guides/sample_app_ug/fips_validation.rst b/doc/guides/sample_app_ug/fips_validation.rst
new file mode 100644
index 0000000..e67b513
--- /dev/null
+++ b/doc/guides/sample_app_ug/fips_validation.rst
@@ -0,0 +1,105 @@
+..  SPDX-License-Identifier: BSD-3-Clause
+    Copyright(c) 2018 Intel Corporation.
+
+Federal Information Processing Standards (FIPS) CryptoDev Validation
+====================================================================
+
+Overview
+--------
+
+Federal Information Processing Standards (FIPS) are publicly announced standards
+developed by the United States federal government for use in computer systems by
+non-military government agencies and government contractors.
+
+This application is used to parse and perform symmetric cryptography
+computation to the NIST Cryptographic Algorithm Validation Program (CAVP) test
+vectors.
+
+Limitations
+-----------
+
+* Only NIST CAVP request files are parsed by this application.
+* 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 head 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 `NIST
+  <https://csrc.nist.gov/projects/cryptographic-algorithm-validation-
+  program/block-ciphers>`_
+* 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
+    * AES-CMAC (128) - Generate, Verify
+    * HMAC (SHA1, SHA224, SHA256, SHA384, SHA512)
+    * TDES-CBC (1 Key, 2 Keys, 3 Keys) - MMT, Monte, Permop, Subkey, Varkey,
+      VarText
+
+Compiling the Application
+-------------------------
+
+* Compile Application
+
+    .. code-block:: console
+
+         make -C examples/cryptodev_fips_validate
+
+*  Run ``dos2unix`` on the request files
+
+    .. code-block:: console
+
+         dos2unix AES/req/*
+         dos2unix AES_GCM/req/*
+         dos2unix CCM/req/*
+         dos2unix CMAC/req/*
+         dos2unix HMAC/req/*
+         dos2unix TDES/req/*
+
+Running the Application
+-----------------------
+
+The application requires a number of command line options:
+
+    .. code-block:: console
+
+         ./cryptodev_fips_validate_app [EAL options]
+         -- --req-file FILE_PATH/FOLDER_PATH
+         --rsp-file FILE_PATH/FOLDER_PATH
+         [--cryptodev DEVICE_NAME] [--cryptodev-id ID] [--path-is-folder]
+
+where,
+  * req-file: The path of the request file or folder, separated by
+    ``path-is-folder`` option.
+
+  * rsp-file: The path that the response file or folder is stored. separated by
+    ``path-is-folder`` option.
+
+  * 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.
+
+  * path-is-folder: If presented the application expects req-file and rsp-file
+    are folder paths.
+
+To run the application in linuxapp environment to test one AES FIPS test data
+file for crypto_aesni_mb PMD, issue the command:
+
+.. code-block:: console
+
+    $ ./cryptodev_fips_validate_app --vdev crypto_aesni_mb --
+    --req-file /PATH/TO/REQUEST/FILE.req --rsp-file ./PATH/TO/RESPONSE/FILE.rsp
+    --cryptodev crypto_aesni_mb
+
+To run the application in linuxapp environment to test all AES-GCM FIPS test
+data files in one folder for crypto_aesni_gcm PMD, issue the command:
+
+.. code-block:: console
+
+    $ ./cryptodev_fips_validate_app --vdev crypto_aesni_gcm0 --
+    --req-file /PATH/TO/REQUEST/FILE/FOLDER/
+    --rsp-file ./PATH/TO/RESPONSE/FILE/FOLDER/
+    --cryptodev-id 0 --path-is-folder
diff --git a/doc/guides/sample_app_ug/index.rst b/doc/guides/sample_app_ug/index.rst
index 74b12af..65c12d9 100644
--- a/doc/guides/sample_app_ug/index.rst
+++ b/doc/guides/sample_app_ug/index.rst
@@ -57,6 +57,7 @@ Sample Applications User Guides
     performance_thread
     ipsec_secgw
     bbdev_app
+    fips_validation
 
 **Figures**
 
-- 
2.9.5