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     * HMAC (SHA1, SHA224, SHA256, SHA384, SHA512)
  46     * TDES-CBC (1 Key, 2 Keys, 3 Keys) - MMT, Monte, Permop, Subkey, Varkey,
  47       VarText
  48
  49 Application Information
  50 -----------------------
  51
  52 If a ``.req`` is used as the input file after the application is finished
  53 running it will generate a response file or ``.rsp``. Differences between the
  54 two files are, the ``.req`` file has missing information for instance if doing
  55 encryption you will not have the cipher text and that will be generated in the
  56 response file. Also if doing decryption it will not have the plain text until it
  57 finished the work and in the response file it will be added onto the end of each
  58 operation.
  59
  60 The application can be run with a ``.rsp`` file and what the outcome of that
  61 will be is it will add a extra line in the generated ``.rsp`` which should be
  62 the same as the ``.rsp`` used to run the application, this is useful for
  63 validating if the application has done the operation correctly.
  64
  65
  66 Compiling the Application
  67 -------------------------
  68
  69 * Compile Application
  70
  71     .. code-block:: console
  72
  73          make -C examples/fips_validation
  74
  75 *  Run ``dos2unix`` on the request files
  76
  77     .. code-block:: console
  78
  79          dos2unix AES/req/*
  80          dos2unix AES_GCM/req/*
  81          dos2unix CCM/req/*
  82          dos2unix CMAC/req/*
  83          dos2unix HMAC/req/*
  84          dos2unix TDES/req/*
  85
  86 Running the Application
  87 -----------------------
  88
  89 The application requires a number of command line options:
  90
  91     .. code-block:: console
  92
  93          ./fips_validation [EAL options]
  94          -- --req-file FILE_PATH/FOLDER_PATH
  95          --rsp-file FILE_PATH/FOLDER_PATH
  96          [--cryptodev DEVICE_NAME] [--cryptodev-id ID] [--path-is-folder]
  97
  98 where,
  99   * req-file: The path of the request file or folder, separated by
 100     ``path-is-folder`` option.
 101
 102   * rsp-file: The path that the response file or folder is stored. separated by
 103     ``path-is-folder`` option.
 104
 105   * cryptodev: The name of the target DPDK Crypto device to be validated.
 106
 107   * cryptodev-id: The id of the target DPDK Crypto device to be validated.
 108
 109   * path-is-folder: If presented the application expects req-file and rsp-file
 110     are folder paths.
 111
 112
 113 To run the application in linuxapp environment to test one AES FIPS test data
 114 file for crypto_aesni_mb PMD, issue the command:
 115
 116 .. code-block:: console
 117
 118     $ ./fips_validation --vdev crypto_aesni_mb --
 119     --req-file /PATH/TO/REQUEST/FILE.req --rsp-file ./PATH/TO/RESPONSE/FILE.rsp
 120     --cryptodev crypto_aesni_mb
 121
 122 To run the application in linuxapp environment to test all AES-GCM FIPS test
 123 data files in one folder for crypto_aesni_gcm PMD, issue the command:
 124
 125 .. code-block:: console
 126
 127     $ ./fips_validation --vdev crypto_aesni_gcm0 --
 128     --req-file /PATH/TO/REQUEST/FILE/FOLDER/
 129     --rsp-file ./PATH/TO/RESPONSE/FILE/FOLDER/
 130     --cryptodev-id 0 --path-is-folder