1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright (c) 2021 NVIDIA Corporation & Affiliates 3 4.. include:: <isonum.txt> 5 6MLX5 Crypto Driver 7================== 8 9The MLX5 crypto driver library 10(**librte_crypto_mlx5**) provides support for **NVIDIA ConnectX-6** 11family adapters. 12 13Overview 14-------- 15 16The device can provide disk encryption services, 17allowing data encryption and decryption towards a disk. 18Having all encryption/decryption operations done in a single device 19can reduce cost and overheads of the related FIPS certification, 20as ConnectX-6 is FIPS 140-2 level-2 ready. 21The encryption cipher is AES-XTS of 256/512 bit key size. 22 23MKEY is a memory region object in the hardware, 24that holds address translation information and attributes per memory area. 25Its ID must be tied to addresses provided to the hardware. 26The encryption operations are performed with MKEY read/write transactions, 27when the MKEY is configured to perform crypto operations. 28 29The encryption does not require text to be aligned to the AES block size (128b). 30 31See :doc:`../../platform/mlx5` guide for more design details. 32 33Configuration 34------------- 35 36See the :ref:`mlx5 common configuration <mlx5_common_env>`. 37 38A device comes out of NVIDIA factory with pre-defined import methods. 39There are two possible import methods: wrapped or plaintext. 40 41In case the device is in wrapped mode, it needs to be moved to crypto operational mode. 42In order to move the device to crypto operational mode, credential and KEK 43(Key Encrypting Key) should be set as the first step. 44The credential will be used by the software in order to perform crypto login, and the KEK is 45the AES Key Wrap Algorithm (rfc3394) key that will be used for sensitive data 46wrapping. 47The credential and the AES-XTS keys should be provided to the hardware, as ciphertext 48encrypted by the KEK. 49 50A keytag (64 bits) should be appended to the AES-XTS keys (before wrapping), 51and will be validated when the hardware attempts to access it. 52 53When crypto engines are defined to work in wrapped import method, they come out 54of the factory in Commissioning mode, and thus, cannot be used for crypto operations 55yet. A dedicated tool is used for changing the mode from Commissioning to 56Operational, while setting the first import_KEK and credential in plaintext. 57The 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 96On the other hand, in case of plaintext mode, there is no need for all the above, 97DEK 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 109Driver options 110-------------- 111 112Please refer to :ref:`mlx5 common options <mlx5_common_driver_options>` 113for 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 139Supported 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 147Limitations 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 156Prerequisites 157------------- 158 159FW Prerequisites 160~~~~~~~~~~~~~~~~ 161 162- xx.31.0328 for ConnectX-6. 163- xx.32.0108 for ConnectX-6 Dx and BlueField-2. 164 165Linux 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 173Windows Prerequisites 174~~~~~~~~~~~~~~~~~~~~~ 175 176- Mellanox WINOF-2 version: **2.60** or higher. 177 See :ref:`mlx5 common prerequisites <mlx5_windows_prerequisites>` for more details. 178