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 **Mellanox 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 For security reasons and to increase robustness, this driver only deals with virtual
  32 memory addresses. The way resources allocations are handled by the kernel,
  33 combined with hardware specifications that allow handling virtual memory
  34 addresses directly, ensure that DPDK applications cannot access random
  35 physical memory (or memory that does not belong to the current process).
  36
  37 The PMD uses ``libibverbs`` and ``libmlx5`` to access the device firmware
  38 or to access the hardware components directly.
  39 There are different levels of objects and bypassing abilities.
  40 To get the best performances:
  41
  42 - Verbs is a complete high-level generic API.
  43 - Direct Verbs is a device-specific API.
  44 - DevX allows to access firmware objects.
  45
  46 Enabling ``librte_crypto_mlx5`` causes DPDK applications
  47 to be linked against libibverbs.
  48
  49 In order to move the device to crypto operational mode, credential and KEK
  50 (Key Encrypting Key) should be set as the first step.
  51 The credential will be used by the software in order to perform crypto login, and the KEK is
  52 the AES Key Wrap Algorithm (rfc3394) key that will be used for sensitive data
  53 wrapping.
  54 The credential and the AES-XTS keys should be provided to the hardware, as ciphertext
  55 encrypted by the KEK.
  56
  57 When crypto engines are defined to work in wrapped import method, they come out
  58 of the factory in Commissioning mode, and thus, cannot be used for crypto operations
  59 yet. A dedicated tool is used for changing the mode from Commissioning to
  60 Operational, while setting the first import_KEK and credential in plaintext.
  61 The mlxreg dedicated tool should be used as follows:
  62
  63 - Set CRYPTO_OPERATIONAL register to set the device in crypto operational mode.
  64
  65   The input to this tool is:
  66
  67   - The first credential in plaintext, 40B.
  68   - The first import_KEK in plaintext: kek size 0 for 16B or 1 for 32B, kek data.
  69
  70   Example::
  71
  72      mlxreg -d /dev/mst/mt4123_pciconf0 --reg_name CRYPTO_OPERATIONAL --get
  73
  74   The "wrapped_crypto_operational" value will be "0x00000000".
  75   The command to set the register should be executed only once, and all the
  76   values mentioned above should be specified in the same command.
  77
  78   Example::
  79
  80      mlxreg -d /dev/mst/mt4123_pciconf0 --reg_name CRYPTO_OPERATIONAL \
  81      --set "credential[0]=0x10000000, credential[1]=0x10000000, kek[0]=0x00000000"
  82
  83   All values not specified will remain 0.
  84   "wrapped_crypto_going_to_commissioning" and  "wrapped_crypto_operational"
  85   should not be specified.
  86
  87   All the device ports should set it in order to move to operational mode.
  88
  89 - Query CRYPTO_OPERATIONAL register to make sure the device is in Operational
  90   mode.
  91
  92   Example::
  93
  94      mlxreg -d /dev/mst/mt4123_pciconf0 --reg_name CRYPTO_OPERATIONAL --get
  95
  96   The "wrapped_crypto_operational" value will be "0x00000001" if the mode was
  97   successfully changed to operational mode.
  98
  99
 100 Driver options
 101 --------------
 102
 103 - ``class`` parameter [string]
 104
 105   Select the class of the driver that should probe the device.
 106   `crypto` for the mlx5 crypto driver.
 107
 108 - ``wcs_file`` parameter [string] - mandatory
 109
 110   File path including only the wrapped credential in string format of hexadecimal
 111   numbers, represent 48 bytes (8 bytes IV added by the AES key wrap algorithm).
 112
 113 - ``import_kek_id`` parameter [int]
 114
 115   The identifier of the KEK, default value is 0 represents the operational
 116   register import_kek..
 117
 118 - ``credential_id`` parameter [int]
 119
 120   The identifier of the credential, default value is 0 represents the operational
 121   register credential.
 122
 123
 124 Supported NICs
 125 --------------
 126
 127 * Mellanox\ |reg| ConnectX\ |reg|-6 200G MCX654106A-HCAT (2x200G)
 128
 129
 130 Limitations
 131 -----------
 132
 133 - AES-XTS keys provided in xform must include keytag and should be wrapped.
 134 - The supported data-unit lengths are 512B and 1KB. In case the `dataunit_len`
 135   is not provided in the cipher xform, the OP length is limited to the above
 136   values and 1MB.
 137
 138
 139 Prerequisites
 140 -------------
 141
 142 - Mellanox OFED version: **5.3**
 143   see :doc:`../../nics/mlx5` guide for more Mellanox OFED details.
 144
 145 - Compilation can be done also with rdma-core v15+.
 146   see :doc:`../../nics/mlx5` guide for more rdma-core details.