1 .. SPDX-License-Identifier: BSD-3-Clause
2 Copyright(c) 2018 Intel Corporation.
4 Federal Information Processing Standards (FIPS) CryptoDev Validation
5 ====================================================================
10 Federal Information Processing Standards (FIPS) are publicly announced standards
11 developed by the United States federal government for use in computer systems by
12 non-military government agencies and government contractors.
14 This application is used to parse and perform symmetric cryptography
15 computation to the NIST Cryptographic Algorithm Validation Program (CAVP) and
16 Automated Crypto Validation Protocol (ACVP) test vectors.
18 For an algorithm implementation to be listed on a cryptographic module
19 validation certificate as an Approved security function, the algorithm
20 implementation must meet all the requirements of FIPS 140-2 (in case of CAVP)
21 and FIPS 140-3 (in case of ACVP) and must successfully complete the
22 cryptographic algorithm validation process.
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
35 # VARIABLE KEY - KAT for CBC / # TDES VARIABLE KEY - KAT for CBC
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.
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,
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>`_
60 * Supported test vectors
61 * AES-CBC (128,192,256) - AFT, MCT
62 * AES-GCM (128,192,256) - AFT
63 * AES-CMAC (128,192,256) - AFT
64 * HMAC (SHA1, SHA224, SHA256, SHA384, SHA512)
67 Application Information
68 -----------------------
70 If a ``.req`` is used as the input file after the application is finished
71 running it will generate a response file or ``.rsp``. Differences between the
72 two files are, the ``.req`` file has missing information for instance if doing
73 encryption you will not have the cipher text and that will be generated in the
74 response file. Also if doing decryption it will not have the plain text until it
75 finished the work and in the response file it will be added onto the end of each
78 The application can be run with a ``.rsp`` file and what the outcome of that
79 will be is it will add a extra line in the generated ``.rsp`` which should be
80 the same as the ``.rsp`` used to run the application, this is useful for
81 validating if the application has done the operation correctly.
84 Compiling the Application
85 -------------------------
89 To compile the sample application see :doc:`compiling`.
91 * Run ``dos2unix`` on the request files
93 .. code-block:: console
103 Running the Application
104 -----------------------
106 The application requires a number of command line options:
108 .. code-block:: console
110 ./dpdk-fips_validation [EAL options]
111 -- --req-file FILE_PATH/FOLDER_PATH
112 --rsp-file FILE_PATH/FOLDER_PATH
113 [--cryptodev DEVICE_NAME] [--cryptodev-id ID] [--path-is-folder]
114 --mbuf-dataroom DATAROOM_SIZE
117 * req-file: The path of the request file or folder, separated by
118 ``path-is-folder`` option.
120 * rsp-file: The path that the response file or folder is stored. separated by
121 ``path-is-folder`` option.
123 * cryptodev: The name of the target DPDK Crypto device to be validated.
125 * cryptodev-id: The id of the target DPDK Crypto device to be validated.
127 * path-is-folder: If presented the application expects req-file and rsp-file
130 * mbuf-dataroom: By default the application creates mbuf pool with maximum
131 possible data room (65535 bytes). If the user wants to test scatter-gather
132 list feature of the PMD he or she may set this value to reduce the dataroom
133 size so that the input data may be divided into multiple chained mbufs.
136 To run the application in linux environment to test one AES FIPS test data
137 file for crypto_aesni_mb PMD, issue the command:
139 .. code-block:: console
141 $ ./dpdk-fips_validation --vdev crypto_aesni_mb --
142 --req-file /PATH/TO/REQUEST/FILE.req --rsp-file ./PATH/TO/RESPONSE/FILE.rsp
143 --cryptodev crypto_aesni_mb
145 To run the application in linux environment to test all AES-GCM FIPS test
146 data files in one folder for crypto_aesni_gcm PMD, issue the command:
148 .. code-block:: console
150 $ ./dpdk-fips_validation --vdev crypto_aesni_gcm0 --
151 --req-file /PATH/TO/REQUEST/FILE/FOLDER/
152 --rsp-file ./PATH/TO/RESPONSE/FILE/FOLDER/
153 --cryptodev-id 0 --path-is-folder