summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorMarko Kovacevic <marko.kovacevic@intel.com>2018-11-02 09:55:28 +0000
committerAkhil Goyal <akhil.goyal@nxp.com>2018-11-02 12:26:06 +0100
commit3d0fad56b74a02fe6c1bb2b3ee752646c34cfbc5 (patch)
tree9118d24e761948a4c77cd210c7457980d091bfd3 /doc
parent1713ad8bc5578db230830c3713d140184b364a3d (diff)
downloaddpdk-3d0fad56b74a02fe6c1bb2b3ee752646c34cfbc5.zip
dpdk-3d0fad56b74a02fe6c1bb2b3ee752646c34cfbc5.tar.gz
dpdk-3d0fad56b74a02fe6c1bb2b3ee752646c34cfbc5.tar.xz
examples/fips_validation: add crypto FIPS application
Added FIPS application into the examples to allow users to use a simple sample app to validate their systems and be able to get FIPS certification. 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> Reviewed-by: Akhil Goyal <akhil.goyal@nxp.com>
Diffstat (limited to 'doc')
-rw-r--r--doc/guides/rel_notes/release_18_11.rst6
-rw-r--r--doc/guides/sample_app_ug/fips_validation.rst125
-rw-r--r--doc/guides/sample_app_ug/index.rst1
3 files changed, 132 insertions, 0 deletions
diff --git a/doc/guides/rel_notes/release_18_11.rst b/doc/guides/rel_notes/release_18_11.rst
index 11a2740..c60879c 100644
--- a/doc/guides/rel_notes/release_18_11.rst
+++ b/doc/guides/rel_notes/release_18_11.rst
@@ -285,6 +285,12 @@ New Features
this application doesn't need to launch dedicated worker threads for vhost
enqueue/dequeue operations.
+* **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 0000000..9ca6ffe
--- /dev/null
+++ b/doc/guides/sample_app_ug/fips_validation.rst
@@ -0,0 +1,125 @@
+.. 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 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 `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 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
+
+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.
+
+
+Compiling the Application
+-------------------------
+
+* Compile Application
+
+ .. code-block:: console
+
+ make -C examples/fips_validation
+
+* 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
+
+ ./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]
+
+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
+
+ $ ./fips_validation --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
+
+ $ ./fips_validation --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..b2455e0 100644
--- a/doc/guides/sample_app_ug/index.rst
+++ b/doc/guides/sample_app_ug/index.rst
@@ -55,6 +55,7 @@ Sample Applications User Guides
tep_termination
ptpclient
performance_thread
+ fips_validation
ipsec_secgw
bbdev_app