From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) by dpdk.org (Postfix) with ESMTP id 02CC61B144 for ; Wed, 17 Oct 2018 14:49:55 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga004.jf.intel.com ([10.7.209.38]) by orsmga101.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 17 Oct 2018 05:49:55 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.54,392,1534834800"; d="scan'208";a="242043539" Received: from silpixa00399502.ir.intel.com (HELO silpixa00399502.ger.corp.intel.com) ([10.237.223.218]) by orsmga004.jf.intel.com with ESMTP; 17 Oct 2018 05:49:54 -0700 From: Marko Kovacevic To: dev@dpdk.org Cc: roy.fan.zhang@intel.com, akhil.goyal@nxp.com, arkadiuszx.kusztal@intel.com, Marko Kovacevic Date: Wed, 17 Oct 2018 13:49:37 +0100 Message-Id: <20181017124937.38052-9-marko.kovacevic@intel.com> X-Mailer: git-send-email 2.9.5 In-Reply-To: <20181017124937.38052-1-marko.kovacevic@intel.com> References: <20181012144501.19562-1-marko.kovacevic@intel.com> <20181017124937.38052-1-marko.kovacevic@intel.com> Subject: [dpdk-dev] [PATCH v5 8/8] doc/guides/sample_app_ug: add guides for fips validation X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 17 Oct 2018 12:49:56 -0000 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 Signed-off-by: Fan Zhang Acked-by: Arek Kusztal --- 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 +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 + `_ 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. + +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