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