1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2018 Intel Corporation. 3 4Federal Information Processing Standards (FIPS) CryptoDev Validation 5==================================================================== 6 7Overview 8-------- 9 10Federal Information Processing Standards (FIPS) are publicly announced standards 11developed by the United States federal government for use in computer systems by 12non-military government agencies and government contractors. 13 14This application is used to parse and perform symmetric cryptography 15computation to the NIST Cryptographic Algorithm Validation Program (CAVP) and 16Automated Crypto Validation Protocol (ACVP) test vectors. 17 18For an algorithm implementation to be listed on a cryptographic module 19validation certificate as an Approved security function, the algorithm 20implementation must meet all the requirements of FIPS 140-2 (in case of CAVP) 21and FIPS 140-3 (in case of ACVP) and must successfully complete the 22cryptographic algorithm validation process. 23 24Limitations 25----------- 26 27CAVP 28---- 29 30* The version of request file supported is ``CAVS 21.0``. 31* If the header comment in a ``.req`` file does not contain a Algo tag 32 i.e ``AES,TDES,GCM`` you need to manually add it into the header comment for 33 example:: 34 35 # VARIABLE KEY - KAT for CBC / # TDES VARIABLE KEY - KAT for CBC 36 37* The application does not supply the test vectors. The user is expected to 38 obtain the test vector files from `CAVP 39 <https://csrc.nist.gov/projects/cryptographic-algorithm-validation- 40 program/block-ciphers>`_ website. To obtain the ``.req`` files you need to 41 email a person from the NIST website and pay for the ``.req`` files. 42 The ``.rsp`` files from the site can be used to validate and compare with 43 the ``.rsp`` files created by the FIPS application. 44 45* Supported test vectors 46 * AES-CBC (128,192,256) - GFSbox, KeySbox, MCT, MMT 47 * AES-GCM (128,192,256) - EncryptExtIV, Decrypt 48 * AES-CCM (128) - VADT, VNT, VPT, VTT, DVPT 49 * AES-CMAC (128) - Generate, Verify 50 * HMAC (SHA1, SHA224, SHA256, SHA384, SHA512) 51 * TDES-CBC (1 Key, 2 Keys, 3 Keys) - MMT, Monte, Permop, Subkey, Varkey, 52 VarText 53 54ACVP 55---- 56 57* The application does not supply the test vectors. The user is expected to 58 obtain the test vector files from `ACVP <https://pages.nist.gov/ACVP>`_ 59 website. 60* Supported test vectors 61 * AES-CBC (128,192,256) - AFT, MCT 62 * AES-GCM (128,192,256) - AFT 63 * AES-CCM (128,192,256) - AFT 64 * AES-CMAC (128,192,256) - AFT 65 * AES-CTR (128,192,256) - AFT, CTR 66 * AES-GMAC (128,192,256) - AFT 67 * AES-XTS (128,256) - AFT 68 * HMAC (SHA1, SHA224, SHA256, SHA384, SHA512, SHA3_224, SHA3_256, SHA3_384, SHA3_512) 69 * SHA (1, 224, 256, 384, 512) - AFT, MCT 70 * SHA3 (224, 256, 384, 512) - AFT, MCT 71 * SHAKE (128, 256) - AFT, MCT, VOT 72 * TDES-CBC - AFT, MCT 73 * TDES-ECB - AFT, MCT 74 * RSA 75 * ECDSA 76 77 78Application Information 79----------------------- 80 81If a ``.req`` is used as the input file after the application is finished 82running it will generate a response file or ``.rsp``. Differences between the 83two files are, the ``.req`` file has missing information for instance if doing 84encryption you will not have the cipher text and that will be generated in the 85response file. Also if doing decryption it will not have the plain text until it 86finished the work and in the response file it will be added onto the end of each 87operation. 88 89The application can be run with a ``.rsp`` file and what the outcome of that 90will be is it will add a extra line in the generated ``.rsp`` which should be 91the same as the ``.rsp`` used to run the application, this is useful for 92validating if the application has done the operation correctly. 93 94 95Compiling the Application 96------------------------- 97 98* Compile Application 99 100 To compile the sample application see :doc:`compiling`. 101 102* Run ``dos2unix`` on the request files 103 104 .. code-block:: console 105 106 dos2unix AES/req/* 107 dos2unix GCM/req/* 108 dos2unix CCM/req/* 109 dos2unix CMAC/req/* 110 dos2unix HMAC/req/* 111 dos2unix TDES/req/* 112 dos2unix SHA/req/* 113 114Running the Application 115----------------------- 116 117The application requires a number of command line options: 118 119 .. code-block:: console 120 121 ./dpdk-fips_validation [EAL options] 122 -- --req-file FILE_PATH/FOLDER_PATH 123 --rsp-file FILE_PATH/FOLDER_PATH 124 [--cryptodev DEVICE_NAME] [--cryptodev-id ID] [--path-is-folder] 125 --mbuf-dataroom DATAROOM_SIZE 126 127where, 128 * req-file: The path of the request file or folder, separated by 129 ``path-is-folder`` option. 130 131 * rsp-file: The path that the response file or folder is stored. separated by 132 ``path-is-folder`` option. 133 134 * cryptodev: The name of the target DPDK Crypto device to be validated. 135 136 * cryptodev-id: The id of the target DPDK Crypto device to be validated. 137 138 * path-is-folder: If presented the application expects req-file and rsp-file 139 are folder paths. 140 141 * mbuf-dataroom: By default the application creates mbuf pool with maximum 142 possible data room (65535 bytes). If the user wants to test scatter-gather 143 list feature of the PMD he or she may set this value to reduce the dataroom 144 size so that the input data may be divided into multiple chained mbufs. 145 146 147To run the application in linux environment to test one AES FIPS test data 148file for crypto_aesni_mb PMD, issue the command: 149 150.. code-block:: console 151 152 $ ./dpdk-fips_validation --vdev crypto_aesni_mb -- 153 --req-file /PATH/TO/REQUEST/FILE.req --rsp-file ./PATH/TO/RESPONSE/FILE.rsp 154 --cryptodev crypto_aesni_mb 155 156To run the application in linux environment to test all AES-GCM FIPS test 157data files in one folder for crypto_aesni_gcm PMD, issue the command: 158 159.. code-block:: console 160 161 $ ./dpdk-fips_validation --vdev crypto_aesni_gcm0 -- 162 --req-file /PATH/TO/REQUEST/FILE/FOLDER/ 163 --rsp-file ./PATH/TO/RESPONSE/FILE/FOLDER/ 164 --cryptodev-id 0 --path-is-folder 165