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) test 16vectors. 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 and must 21successfully complete the cryptographic algorithm validation process. 22 23Limitations 24----------- 25 26* Only NIST CAVP request files are parsed by this application. 27* The version of request file supported is ``CAVS 21.0`` 28* If the header comment in a ``.req`` file does not contain a Algo tag 29 i.e ``AES,TDES,GCM`` you need to manually add it into the header comment for 30 example:: 31 32 # VARIABLE KEY - KAT for CBC / # TDES VARIABLE KEY - KAT for CBC 33 34* The application does not supply the test vectors. The user is expected to 35 obtain the test vector files from `NIST 36 <https://csrc.nist.gov/projects/cryptographic-algorithm-validation- 37 program/block-ciphers>`_ website. To obtain the ``.req`` files you need to 38 email a person from the NIST website and pay for the ``.req`` files. 39 The ``.rsp`` files from the site can be used to validate and compare with 40 the ``.rsp`` files created by the FIPS application. 41 42* Supported test vectors 43 * AES-CBC (128,192,256) - GFSbox, KeySbox, MCT, MMT 44 * AES-GCM (128,192,256) - EncryptExtIV, Decrypt 45 * AES-CCM (128) - VADT, VNT, VPT, VTT, DVPT 46 * AES-CMAC (128) - Generate, Verify 47 * HMAC (SHA1, SHA224, SHA256, SHA384, SHA512) 48 * TDES-CBC (1 Key, 2 Keys, 3 Keys) - MMT, Monte, Permop, Subkey, Varkey, 49 VarText 50 51Application Information 52----------------------- 53 54If a ``.req`` is used as the input file after the application is finished 55running it will generate a response file or ``.rsp``. Differences between the 56two files are, the ``.req`` file has missing information for instance if doing 57encryption you will not have the cipher text and that will be generated in the 58response file. Also if doing decryption it will not have the plain text until it 59finished the work and in the response file it will be added onto the end of each 60operation. 61 62The application can be run with a ``.rsp`` file and what the outcome of that 63will be is it will add a extra line in the generated ``.rsp`` which should be 64the same as the ``.rsp`` used to run the application, this is useful for 65validating if the application has done the operation correctly. 66 67 68Compiling the Application 69------------------------- 70 71* Compile Application 72 73 To compile the sample application see :doc:`compiling`. 74 75* Run ``dos2unix`` on the request files 76 77 .. code-block:: console 78 79 dos2unix AES/req/* 80 dos2unix GCM/req/* 81 dos2unix CCM/req/* 82 dos2unix CMAC/req/* 83 dos2unix HMAC/req/* 84 dos2unix TDES/req/* 85 dos2unix SHA/req/* 86 87Running the Application 88----------------------- 89 90The application requires a number of command line options: 91 92 .. code-block:: console 93 94 ./dpdk-fips_validation [EAL options] 95 -- --req-file FILE_PATH/FOLDER_PATH 96 --rsp-file FILE_PATH/FOLDER_PATH 97 [--cryptodev DEVICE_NAME] [--cryptodev-id ID] [--path-is-folder] 98 --mbuf-dataroom DATAROOM_SIZE 99 100where, 101 * req-file: The path of the request file or folder, separated by 102 ``path-is-folder`` option. 103 104 * rsp-file: The path that the response file or folder is stored. separated by 105 ``path-is-folder`` option. 106 107 * cryptodev: The name of the target DPDK Crypto device to be validated. 108 109 * cryptodev-id: The id of the target DPDK Crypto device to be validated. 110 111 * path-is-folder: If presented the application expects req-file and rsp-file 112 are folder paths. 113 114 * mbuf-dataroom: By default the application creates mbuf pool with maximum 115 possible data room (65535 bytes). If the user wants to test scatter-gather 116 list feature of the PMD he or she may set this value to reduce the dataroom 117 size so that the input data may be divided into multiple chained mbufs. 118 119 120To run the application in linux environment to test one AES FIPS test data 121file for crypto_aesni_mb PMD, issue the command: 122 123.. code-block:: console 124 125 $ ./dpdk-fips_validation --vdev crypto_aesni_mb -- 126 --req-file /PATH/TO/REQUEST/FILE.req --rsp-file ./PATH/TO/RESPONSE/FILE.rsp 127 --cryptodev crypto_aesni_mb 128 129To run the application in linux environment to test all AES-GCM FIPS test 130data files in one folder for crypto_aesni_gcm PMD, issue the command: 131 132.. code-block:: console 133 134 $ ./dpdk-fips_validation --vdev crypto_aesni_gcm0 -- 135 --req-file /PATH/TO/REQUEST/FILE/FOLDER/ 136 --rsp-file ./PATH/TO/RESPONSE/FILE/FOLDER/ 137 --cryptodev-id 0 --path-is-folder 138