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) and
  16 Automated Crypto Validation Protocol (ACVP) test 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 (in case of CAVP)
  21 and FIPS 140-3 (in case of ACVP) and must successfully complete the
  22 cryptographic algorithm validation process.
  23
  24 Limitations
  25 -----------
  26
  27 CAVP
  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
  54 ACVP
  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-CMAC (128,192,256) - AFT
  64     * AES-XTS (128,256) - AFT
  65     * HMAC (SHA1, SHA224, SHA256, SHA384, SHA512)
  66
  67
  68 Application Information
  69 -----------------------
  70
  71 If a ``.req`` is used as the input file after the application is finished
  72 running it will generate a response file or ``.rsp``. Differences between the
  73 two files are, the ``.req`` file has missing information for instance if doing
  74 encryption you will not have the cipher text and that will be generated in the
  75 response file. Also if doing decryption it will not have the plain text until it
  76 finished the work and in the response file it will be added onto the end of each
  77 operation.
  78
  79 The application can be run with a ``.rsp`` file and what the outcome of that
  80 will be is it will add a extra line in the generated ``.rsp`` which should be
  81 the same as the ``.rsp`` used to run the application, this is useful for
  82 validating if the application has done the operation correctly.
  83
  84
  85 Compiling the Application
  86 -------------------------
  87
  88 * Compile Application
  89
  90     To compile the sample application see :doc:`compiling`.
  91
  92 *  Run ``dos2unix`` on the request files
  93
  94     .. code-block:: console
  95
  96          dos2unix AES/req/*
  97          dos2unix GCM/req/*
  98          dos2unix CCM/req/*
  99          dos2unix CMAC/req/*
 100          dos2unix HMAC/req/*
 101          dos2unix TDES/req/*
 102          dos2unix SHA/req/*
 103
 104 Running the Application
 105 -----------------------
 106
 107 The application requires a number of command line options:
 108
 109     .. code-block:: console
 110
 111          ./dpdk-fips_validation [EAL options]
 112          -- --req-file FILE_PATH/FOLDER_PATH
 113          --rsp-file FILE_PATH/FOLDER_PATH
 114          [--cryptodev DEVICE_NAME] [--cryptodev-id ID] [--path-is-folder]
 115          --mbuf-dataroom DATAROOM_SIZE
 116
 117 where,
 118   * req-file: The path of the request file or folder, separated by
 119     ``path-is-folder`` option.
 120
 121   * rsp-file: The path that the response file or folder is stored. separated by
 122     ``path-is-folder`` option.
 123
 124   * cryptodev: The name of the target DPDK Crypto device to be validated.
 125
 126   * cryptodev-id: The id of the target DPDK Crypto device to be validated.
 127
 128   * path-is-folder: If presented the application expects req-file and rsp-file
 129     are folder paths.
 130
 131   * mbuf-dataroom: By default the application creates mbuf pool with maximum
 132     possible data room (65535 bytes). If the user wants to test scatter-gather
 133     list feature of the PMD he or she may set this value to reduce the dataroom
 134     size so that the input data may be divided into multiple chained mbufs.
 135
 136
 137 To run the application in linux environment to test one AES FIPS test data
 138 file for crypto_aesni_mb PMD, issue the command:
 139
 140 .. code-block:: console
 141
 142     $ ./dpdk-fips_validation --vdev crypto_aesni_mb --
 143     --req-file /PATH/TO/REQUEST/FILE.req --rsp-file ./PATH/TO/RESPONSE/FILE.rsp
 144     --cryptodev crypto_aesni_mb
 145
 146 To run the application in linux environment to test all AES-GCM FIPS test
 147 data files in one folder for crypto_aesni_gcm PMD, issue the command:
 148
 149 .. code-block:: console
 150
 151     $ ./dpdk-fips_validation --vdev crypto_aesni_gcm0 --
 152     --req-file /PATH/TO/REQUEST/FILE/FOLDER/
 153     --rsp-file ./PATH/TO/RESPONSE/FILE/FOLDER/
 154     --cryptodev-id 0 --path-is-folder