[v5,8/8] doc/guides/sample_app_ug: add guides for fips validation

  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>
Acked-by: Arek Kusztal <arkadiuszx.kusztal@intel.com>
---
 MAINTAINERS                                  |   4 +
 doc/guides/rel_notes/release_18_11.rst       |   6 ++
 doc/guides/sample_app_ug/fips_validation.rst | 119 +++++++++++++++++++++++++++
 doc/guides/sample_app_ug/index.rst           |   1 +
 4 files changed, 130 insertions(+)
 create mode 100644 doc/guides/sample_app_ug/fips_validation.rst
  

++ John

On 10/17/2018 6:19 PM, Marko Kovacevic wrote:
> 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>
> Acked-by: Arek Kusztal <arkadiuszx.kusztal@intel.com>
> ---
>   MAINTAINERS                                  |   4 +
>   doc/guides/rel_notes/release_18_11.rst       |   6 ++
>   doc/guides/sample_app_ug/fips_validation.rst | 119 +++++++++++++++++++++++++++
>   doc/guides/sample_app_ug/index.rst           |   1 +
>   4 files changed, 130 insertions(+)
>   create mode 100644 doc/guides/sample_app_ug/fips_validation.rst
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 5d73756..31c9c65 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1314,3 +1314,7 @@ F: examples/tep_termination/
>   F: examples/vmdq/
>   F: examples/vmdq_dcb/
>   F: doc/guides/sample_app_ug/vmdq_dcb_forwarding.rst
> +
> +M: Marko Kovacevic <marko.kovacevic@intel.com>
> +F: examples/cryptodev_fips_validate
> +F: 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..9e0db23
> --- /dev/null
> +++ b/doc/guides/sample_app_ug/fips_validation.rst
> @@ -0,0 +1,119 @@
> +..  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.
> +
> +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 and must
> +successfully complete the cryptographic algorithm validation process.
> +
> +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>`_ website. To obtain the ``.req`` files you need to
> +  email a person from the NIST webiste 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
> +    * 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.
> +
> +.. note::
> +
> +    The .req file is optional and the application can be run without it, but
> +    .req files are the only ones that will be parsed by the application.
I am a bit confused here, I believe .rsp files downloaded from the 
website can be used to run the application
as it has both the cipher as well as plain text. So the application will 
be able to compare the data from .rsp file only.
Could you please elaborate both the scenarios of running the application 
with and without .req file.
> +
> +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**
>