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 24NVIDIA MLX5 crypto driver supports AES-XTS and AES-GCM cryption. 25 26AES-XTS 27~~~~~~~ 28 29The device can provide disk encryption services, 30allowing data encryption and decryption towards a disk. 31Having all encryption/decryption operations done in a single device 32can reduce cost and overheads of the related FIPS certification, 33as ConnectX-6 is FIPS 140-2 level-2 ready. 34The encryption cipher is AES-XTS of 256/512 bit key size. 35 36MKEY is a memory region object in the hardware, 37that holds address translation information and attributes per memory area. 38Its ID must be tied to addresses provided to the hardware. 39The encryption operations are performed with MKEY read/write transactions, 40when the MKEY is configured to perform crypto operations. 41 42The encryption does not require text to be aligned to the AES block size (128b). 43 44See :doc:`../../platform/mlx5` guide for more design details. 45 46AES-GCM 47~~~~~~~ 48 49The supported AAD/digest/key size can be read from ``dev_info``. 50 51In AES-GCM mode, the HW requires continuous input and output of 52Additional Authenticated Data (AAD), payload, and digest (if needed). 53However, the API only provides a single AAD input, 54which means that in the out-of-place mode, 55the AAD will be used in both input and output. 56This reuse of AAD in the out-of-place mode breaks the continuous output, 57which degrades the performance and introduces extra UMR WQE. 58If digest is not continuous after payload will also lead to that extra UMR WQE. 59 60To address this issue, the API provides ``min_mbuf_headroom_req`` and 61``min_mbuf_tailroom_req`` in ``rte_cryptodev_info`` as a hint to the PMD. 62It indicates the PMD can use the buffer before and after the mbuf payload 63as AAD and digest space. 64With this hint, the PMD will use the buffer before and after the mbuf payload 65directly via copying AAD and digest. 66However, the application must ensure that there is enough headroom and tailroom 67reserved for the mbuf. 68Or, for non-continuous operations, extra UMR WQE will be used. 69 70 71Configuration 72------------- 73 74See the :ref:`mlx5 common configuration <mlx5_common_env>`. 75 76A device comes out of NVIDIA factory with pre-defined import methods. 77There are two possible import methods: wrapped or plaintext (valid for AES-XTS only). 78 79In case the device is in wrapped mode, it needs to be moved to crypto operational mode. 80In order to move the device to crypto operational mode, credential and KEK 81(Key Encrypting Key) should be set as the first step. 82The credential will be used by the software in order to perform crypto login, and the KEK is 83the AES Key Wrap Algorithm (rfc3394) key that will be used for sensitive data 84wrapping. 85The credential and the AES-XTS keys should be provided to the hardware, as ciphertext 86encrypted by the KEK. 87 88A keytag (64 bits) should be appended to the AES-XTS keys (before wrapping), 89and will be validated when the hardware attempts to access it. 90 91When crypto engines are defined to work in wrapped import method, they come out 92of the factory in Commissioning mode, and thus, cannot be used for crypto operations 93yet. A dedicated tool is used for changing the mode from Commissioning to 94Operational, while setting the first import_KEK and credential in plaintext. 95The mlxreg dedicated tool should be used as follows: 96 97- Set CRYPTO_OPERATIONAL register to set the device in crypto operational mode. 98 99 The input to this tool is: 100 101 - The first credential in plaintext, 40B. 102 - The first import_KEK in plaintext: kek size 0 for 16B or 1 for 32B, kek data. 103 104 Example:: 105 106 mlxreg -d /dev/mst/mt4123_pciconf0 --reg_name CRYPTO_OPERATIONAL --get 107 108 The "wrapped_crypto_operational" value will be "0x00000000". 109 The command to set the register should be executed only once, and all the 110 values mentioned above should be specified in the same command. 111 112 Example:: 113 114 mlxreg -d /dev/mst/mt4123_pciconf0 --reg_name CRYPTO_OPERATIONAL \ 115 --set "credential[0]=0x10000000, credential[1]=0x10000000, kek[0]=0x00000000" 116 117 All values not specified will remain 0. 118 "wrapped_crypto_going_to_commissioning" and "wrapped_crypto_operational" 119 should not be specified. 120 121 All the device ports should set it in order to move to operational mode. 122 For BlueField-2, BlueField-3 the internal ports in the ARM system should also be set. 123 124- Query CRYPTO_OPERATIONAL register to make sure the device is in Operational 125 mode. 126 127 Example:: 128 129 mlxreg -d /dev/mst/mt4123_pciconf0 --reg_name CRYPTO_OPERATIONAL --get 130 131 The "wrapped_crypto_operational" value will be "0x00000001" if the mode was 132 successfully changed to operational mode. 133 134On the other hand, in case of plaintext mode, there is no need for all the above, 135DEK is passed in plaintext without keytag. 136 137 The mlx5 crypto PMD can be verified by running the test application:: 138 Wrapped mode: 139 dpdk-test -c 1 -n 1 -w <dev>,class=crypto,wcs_file=<file_path> 140 RTE>>cryptodev_mlx5_autotest 141 142 Plaintext mode: 143 dpdk-test -c 1 -n 1 -w <dev>,class=crypto 144 RTE>>cryptodev_mlx5_autotest 145 146 147Driver options 148-------------- 149 150Please refer to :ref:`mlx5 common options <mlx5_common_driver_options>` 151for an additional list of options shared with other mlx5 drivers. 152 153- ``algo`` parameter [int] 154 155 - 0. AES-XTS crypto. 156 157 - 1. AES-GCM crypto. 158 159 Set to zero (AES-XTS) by default. 160 161- ``wcs_file`` parameter [string] - mandatory in wrapped mode 162 163 File path including only the wrapped credential in string format of hexadecimal 164 numbers, represent 48 bytes (8 bytes IV added by the AES key wrap algorithm). 165 This option is valid only for AES-XTS. 166 167- ``import_kek_id`` parameter [int] 168 169 The identifier of the KEK, default value is 0 represents the operational 170 register import_kek.. 171 This option is valid only for AES-XTS. 172 173- ``credential_id`` parameter [int] 174 175 The identifier of the credential, default value is 0 represents the operational 176 register credential. 177 This option is valid only for AES-XTS. 178 179- ``keytag`` parameter [int] 180 181 The plaintext of the keytag appended to the AES-XTS keys, default value is 0. 182 This option is valid only for AES-XTS. 183 184- ``max_segs_num`` parameter [int] 185 186 Maximum number of mbuf chain segments(src or dest), default value is 8. 187 188- ``crypto_mode`` parameter [string] 189 190 Only valid in AES-GCM mode. Will be ignored in AES-XTS mode. 191 192 - ``full_capable`` 193 Use UMR WQE for inputs not as contiguous AAD/Payload/Digest. 194 195 - ``ipsec_opt`` 196 Do software AAD shrink for inputs as contiguous AAD/IV/Payload/Digest. 197 The PMD relies on the IPsec layout, expecting the memory to align 198 with AAD/IV/Payload/Digest in a contiguous manner, 199 all within a single mbuf for any given OP. 200 The PMD extracts the ESP.IV bytes from the input memory 201 and binds the AAD (ESP SPI and SN) to the payload during enqueue OP. 202 It then restores the original memory layout in the decrypt OP. 203 The ESP.IV size supported range is [0,16] bytes. 204 For OOP case, the PMD will replace the bytes preceding the OP destination address 205 to match the information found between the AAD pointer and the OP source address. 206 User should prepare this headroom in this case. 207 208 Set to ``full_capable`` by default. 209 210 211Supported NICs 212-------------- 213 214* NVIDIA\ |reg| ConnectX\ |reg|-6 200G MCX654106A-HCAT (2x200G) 215* NVIDIA\ |reg| ConnectX\ |reg|-6 Dx 216* NVIDIA\ |reg| ConnectX\ |reg|-7 217* NVIDIA\ |reg| BlueField\ |reg|-2 SmartNIC 218* NVIDIA\ |reg| BlueField\ |reg|-3 SmartNIC 219 220 221Limitations 222----------- 223 224- AES-XTS keys provided in xform must include keytag and should be wrapped. 225- The supported data-unit lengths are 512B and 4KB and 1MB. In case the `dataunit_len` 226 is not provided in the cipher xform, the OP length is limited to the above 227 values. 228- AES-GCM is supported only on BlueField-3. 229- AES-GCM supports only key import plaintext mode. 230- AES-GCM ``ipsec_opt`` mode does not support non-contiguous AAD/Payload/Digest 231 and multi-segment mode. 232 233 234Prerequisites 235------------- 236 237FW Prerequisites 238~~~~~~~~~~~~~~~~ 239 240- xx.31.0328 for ConnectX-6. 241- xx.32.0108 for ConnectX-6 Dx and BlueField-2. 242- xx.36.xxxx for ConnectX-7 and BlueField-3. 243- xx.37.3010 for BlueField-3 and newer for AES-GCM. 244 245Linux Prerequisites 246~~~~~~~~~~~~~~~~~~~ 247 248- NVIDIA MLNX_OFED version: **5.3**. 249- Compilation can be done also with rdma-core v15+. 250 251 See :ref:`mlx5 common prerequisites <mlx5_linux_prerequisites>` for more details. 252 253Windows Prerequisites 254~~~~~~~~~~~~~~~~~~~~~ 255 256- NVIDIA WINOF-2 version: **2.60** or higher. 257 See :ref:`mlx5 common prerequisites <mlx5_windows_prerequisites>` for more details. 258