app/testpmd: fix statistics after reset
[dpdk.git] / doc / guides / sample_app_ug / fips_validation.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2018 Intel Corporation.
3
4 Federal Information Processing Standards (FIPS) CryptoDev Validation
5 ====================================================================
6
7 Overview
8 --------
9
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.
13
14 This application is used to parse and perform symmetric cryptography
15 computation to the NIST Cryptographic Algorithm Validation Program (CAVP) test
16 vectors.
17
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 and must
21 successfully complete the cryptographic algorithm validation process.
22
23 Limitations
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
51 Application Information
52 -----------------------
53
54 If a ``.req`` is used as the input file after the application is finished
55 running it will generate a response file or ``.rsp``. Differences between the
56 two files are, the ``.req`` file has missing information for instance if doing
57 encryption you will not have the cipher text and that will be generated in the
58 response file. Also if doing decryption it will not have the plain text until it
59 finished the work and in the response file it will be added onto the end of each
60 operation.
61
62 The application can be run with a ``.rsp`` file and what the outcome of that
63 will be is it will add a extra line in the generated ``.rsp`` which should be
64 the same as the ``.rsp`` used to run the application, this is useful for
65 validating if the application has done the operation correctly.
66
67
68 Compiling the Application
69 -------------------------
70
71 * Compile Application
72
73     .. code-block:: console
74
75          make -C examples/fips_validation
76
77 *  Run ``dos2unix`` on the request files
78
79     .. code-block:: console
80
81          dos2unix AES/req/*
82          dos2unix AES_GCM/req/*
83          dos2unix CCM/req/*
84          dos2unix CMAC/req/*
85          dos2unix HMAC/req/*
86          dos2unix TDES/req/*
87
88 Running the Application
89 -----------------------
90
91 The application requires a number of command line options:
92
93     .. code-block:: console
94
95          ./fips_validation [EAL options]
96          -- --req-file FILE_PATH/FOLDER_PATH
97          --rsp-file FILE_PATH/FOLDER_PATH
98          [--cryptodev DEVICE_NAME] [--cryptodev-id ID] [--path-is-folder]
99
100 where,
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
115 To run the application in linux environment to test one AES FIPS test data
116 file for crypto_aesni_mb PMD, issue the command:
117
118 .. code-block:: console
119
120     $ ./fips_validation --vdev crypto_aesni_mb --
121     --req-file /PATH/TO/REQUEST/FILE.req --rsp-file ./PATH/TO/RESPONSE/FILE.rsp
122     --cryptodev crypto_aesni_mb
123
124 To run the application in linux environment to test all AES-GCM FIPS test
125 data files in one folder for crypto_aesni_gcm PMD, issue the command:
126
127 .. code-block:: console
128
129     $ ./fips_validation --vdev crypto_aesni_gcm0 --
130     --req-file /PATH/TO/REQUEST/FILE/FOLDER/
131     --rsp-file ./PATH/TO/RESPONSE/FILE/FOLDER/
132     --cryptodev-id 0 --path-is-folder