doc/guides/cryptodevs/mlx5.rst

   1 .. SPDX-License-Identifier: BSD-3-Clause
   2    Copyright (c) 2021 NVIDIA Corporation & Affiliates
   3
   4 .. include:: <isonum.txt>
   5
   6 MLX5 Crypto Driver
   7 ==================
   8
   9 The MLX5 crypto driver library
  10 (**librte_crypto_mlx5**) provides support for **NVIDIA ConnectX-6**
  11 family adapters.
  12
  13 Overview
  14 --------
  15
  16 The device can provide disk encryption services,
  17 allowing data encryption and decryption towards a disk.
  18 Having all encryption/decryption operations done in a single device
  19 can reduce cost and overheads of the related FIPS certification,
  20 as ConnectX-6 is FIPS 140-2 level-2 ready.
  21 The encryption cipher is AES-XTS of 256/512 bit key size.
  22
  23 MKEY is a memory region object in the hardware,
  24 that holds address translation information and attributes per memory area.
  25 Its ID must be tied to addresses provided to the hardware.
  26 The encryption operations are performed with MKEY read/write transactions,
  27 when the MKEY is configured to perform crypto operations.
  28
  29 The encryption does not require text to be aligned to the AES block size (128b).
  30
  31 See :doc:`../../platform/mlx5` guide for more design details.
  32
  33 Configuration
  34 -------------
  35
  36 See the :ref:`mlx5 common configuration <mlx5_common_env>`.
  37
  38 A device comes out of NVIDIA factory with pre-defined import methods.
  39 There are two possible import methods: wrapped or plaintext.
  40
  41 In case the device is in wrapped mode, it needs to be moved to crypto operational mode.
  42 In order to move the device to crypto operational mode, credential and KEK
  43 (Key Encrypting Key) should be set as the first step.
  44 The credential will be used by the software in order to perform crypto login, and the KEK is
  45 the AES Key Wrap Algorithm (rfc3394) key that will be used for sensitive data
  46 wrapping.
  47 The credential and the AES-XTS keys should be provided to the hardware, as ciphertext
  48 encrypted by the KEK.
  49
  50 A keytag (64 bits) should be appended to the AES-XTS keys (before wrapping),
  51 and will be validated when the hardware attempts to access it.
  52
  53 When crypto engines are defined to work in wrapped import method, they come out
  54 of the factory in Commissioning mode, and thus, cannot be used for crypto operations
  55 yet. A dedicated tool is used for changing the mode from Commissioning to
  56 Operational, while setting the first import_KEK and credential in plaintext.
  57 The mlxreg dedicated tool should be used as follows:
  58
  59 - Set CRYPTO_OPERATIONAL register to set the device in crypto operational mode.
  60
  61   The input to this tool is:
  62
  63   - The first credential in plaintext, 40B.
  64   - The first import_KEK in plaintext: kek size 0 for 16B or 1 for 32B, kek data.
  65
  66   Example::
  67
  68      mlxreg -d /dev/mst/mt4123_pciconf0 --reg_name CRYPTO_OPERATIONAL --get
  69
  70   The "wrapped_crypto_operational" value will be "0x00000000".
  71   The command to set the register should be executed only once, and all the
  72   values mentioned above should be specified in the same command.
  73
  74   Example::
  75
  76      mlxreg -d /dev/mst/mt4123_pciconf0 --reg_name CRYPTO_OPERATIONAL \
  77      --set "credential[0]=0x10000000, credential[1]=0x10000000, kek[0]=0x00000000"
  78
  79   All values not specified will remain 0.
  80   "wrapped_crypto_going_to_commissioning" and  "wrapped_crypto_operational"
  81   should not be specified.
  82
  83   All the device ports should set it in order to move to operational mode.
  84   For BlueField-2, the internal ports in the ARM system should also be set.
  85
  86 - Query CRYPTO_OPERATIONAL register to make sure the device is in Operational
  87   mode.
  88
  89   Example::
  90
  91      mlxreg -d /dev/mst/mt4123_pciconf0 --reg_name CRYPTO_OPERATIONAL --get
  92
  93   The "wrapped_crypto_operational" value will be "0x00000001" if the mode was
  94   successfully changed to operational mode.
  95
  96 On the other hand, in case of plaintext mode, there is no need for all the above,
  97 DEK is passed in plaintext without keytag.
  98
  99   The mlx5 crypto PMD can be verified by running the test application::
 100     Wrapped mode:
 101       dpdk-test -c 1 -n 1 -w <dev>,class=crypto,wcs_file=<file_path>
 102       RTE>>cryptodev_mlx5_autotest
 103
 104     Plaintext mode:
 105       dpdk-test -c 1 -n 1 -w <dev>,class=crypto
 106       RTE>>cryptodev_mlx5_autotest
 107
 108
 109 Driver options
 110 --------------
 111
 112 Please refer to :ref:`mlx5 common options <mlx5_common_driver_options>`
 113 for an additional list of options shared with other mlx5 drivers.
 114
 115 - ``wcs_file`` parameter [string] - mandatory in wrapped mode
 116
 117   File path including only the wrapped credential in string format of hexadecimal
 118   numbers, represent 48 bytes (8 bytes IV added by the AES key wrap algorithm).
 119
 120 - ``import_kek_id`` parameter [int]
 121
 122   The identifier of the KEK, default value is 0 represents the operational
 123   register import_kek..
 124
 125 - ``credential_id`` parameter [int]
 126
 127   The identifier of the credential, default value is 0 represents the operational
 128   register credential.
 129
 130 - ``keytag`` parameter [int]
 131
 132   The plaintext of the keytag appended to the AES-XTS keys, default value is 0.
 133
 134 - ``max_segs_num`` parameter [int]
 135
 136   Maximum number of mbuf chain segments(src or dest), default value is 8.
 137
 138
 139 Supported NICs
 140 --------------
 141
 142 * NVIDIA\ |reg| ConnectX\ |reg|-6 200G MCX654106A-HCAT (2x200G)
 143 * NVIDIA\ |reg| ConnectX\ |reg|-6 Dx
 144 * NVIDIA\ |reg| BlueField-2 SmartNIC
 145
 146
 147 Limitations
 148 -----------
 149
 150 - AES-XTS keys provided in xform must include keytag and should be wrapped.
 151 - The supported data-unit lengths are 512B and 4KB and 1MB. In case the `dataunit_len`
 152   is not provided in the cipher xform, the OP length is limited to the above
 153   values.
 154
 155
 156 Prerequisites
 157 -------------
 158
 159 FW Prerequisites
 160 ~~~~~~~~~~~~~~~~
 161
 162 - xx.31.0328 for ConnectX-6.
 163 - xx.32.0108 for ConnectX-6 Dx and BlueField-2.
 164
 165 Linux Prerequisites
 166 ~~~~~~~~~~~~~~~~~~~
 167
 168 - Mellanox OFED version: **5.3**.
 169 - Compilation can be done also with rdma-core v15+.
 170
 171   See :ref:`mlx5 common prerequisites <mlx5_linux_prerequisites>` for more details.
 172
 173 Windows Prerequisites
 174 ~~~~~~~~~~~~~~~~~~~~~
 175
 176 - Mellanox WINOF-2 version: **2.60** or higher.
 177   See :ref:`mlx5 common prerequisites <mlx5_windows_prerequisites>` for more details.