Re: [dpdk-dev] [PATCH v3 8/8] doc: add guides for fips validation

["Zhang, Roy Fan" <roy.fan.zhang@intel.com>]

Hi Akhil,

To obtain request files the applicant has to fill the validation request to FIPS lab.
However to test the application the response files can be used. 
The application will attach an extra line with computed results of the test cases and it will be fairly easy to check :-).
Please be sure to use dos2unix to convert the formatting of the files first.

Regards,
Fan

> -----Original Message-----
> From: Akhil Goyal [mailto:akhil.goyal@nxp.com]
> Sent: Tuesday, October 9, 2018 8:02 AM
> To: Zhang, Roy Fan <roy.fan.zhang@intel.com>; dev@dpdk.org
> Cc: Kovacevic, Marko <marko.kovacevic@intel.com>
> Subject: Re: [dpdk-dev] [PATCH v3 8/8] doc: add guides for fips validation
> 
> 
> 
> On 10/4/2018 6:42 PM, Fan Zhang wrote:
> > From: 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 | 97
> ++++++++++++++++++++++++++++
> >   doc/guides/sample_app_ug/index.rst           |  5 ++
> >   3 files changed, 108 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 2133a5b9b..db1579b6e 100644
> > --- a/doc/guides/rel_notes/release_18_11.rst
> > +++ b/doc/guides/rel_notes/release_18_11.rst
> > @@ -104,6 +104,12 @@ New Features
> >     the specified port. The port must be stopped before the command call in
> order
> >     to reconfigure queues.
> >
> > +* **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.
> > +
> >
> >   API Changes
> >   -----------
> > 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 000000000..0e06aab99
> > --- /dev/null
> > +++ b/doc/guides/sample_app_ug/fips_validation.rst
> > @@ -0,0 +1,97 @@
> > +..  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``
> > +* 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-pr
> > +ogram/block-ciphers>`_
> I cannot find the .req files in the above link. It only has .rsp files which has
> both cipher text as well as plain text.
> 
> > +* 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 (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 5bedf4f6f..146296b7a 100644
> > --- a/doc/guides/sample_app_ug/index.rst
> > +++ b/doc/guides/sample_app_ug/index.rst
> > @@ -56,6 +56,7 @@ Sample Applications User Guides
> >       performance_thread
> >       ipsec_secgw
> >       bbdev_app
> > +    fips_validation
> >
> >   **Figures**
> >
> > @@ -83,6 +84,10 @@ Sample Applications User Guides
> >
> >   :numref:`figure_client_svr_sym_multi_proc_app`
> > :ref:`figure_client_svr_sym_multi_proc_app`
> >
> > +:numref:`figure_master_slave_proc` :ref:`figure_master_slave_proc`
> > +
> > +:numref:`figure_slave_proc_recov` :ref:`figure_slave_proc_recov`
> > +
> >   :numref:`figure_qos_sched_app_arch` :ref:`figure_qos_sched_app_arch`
> >
> >   :numref:`figure_pipeline_overview` :ref:`figure_pipeline_overview`