[v4,8/8] doc: add guides for fips validation
Checks
Commit Message
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
@@ -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
new file mode 100644
@@ -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
@@ -57,6 +57,7 @@ Sample Applications User Guides
performance_thread
ipsec_secgw
bbdev_app
+ fips_validation
**Figures**