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