1mlx5dv_wr_set_mkey_crypto(3) mlx5dv_wr_set_mkey_crypto(3)
2
6 mlx5dv_wr_set_mkey_crypto - Configure a MKey for crypto operation.
7
9 #include <infiniband/mlx5dv.h>
10 static inline void
12 mlx5dv_wr_set_mkey_crypto(struct mlx5dv_qp_ex *mqp,
13 const struct mlx5dv_crypto_attr *attr);
14
16 Configure a MKey with crypto properties. With this, the device will
17 encrypt/decrypt data when transmitting data from memory to network and
18 when receiving data from network to memory.
19 In order to configure MKey with crypto properties, the MKey should be
21 created with MLX5DV_MKEY_INIT_ATTR_FLAGS_CRYPTO. MKey that was created
22 with MLX5DV_MKEY_INIT_ATTR_FLAGS_CRYPTO must have crypto properties
23 configured to it before it can be used, i.e. this setter must be called
24 before the MKey can be used or else traffic will fail, generating a CQE
25 with error. A call to this setter on a MKey that already has crypto
26 properties configured to it will override existing crypto properties.
27 Configuring crypto properties to a MKey is done by specifying the cryp‐
29 to standard that should be used and its attributes, and also by provid‐
30 ing the Data Encryption Key (DEK) to be used for the encryption/decryp‐
31 tion itself.
32 The MKey represents a virtually contiguous memory, by configuring a
34 layout to it. The crypto properties of the MKey describe whether data
35 in this virtually contiguous memory is encrypted or in plaintext, and
36 whether it should be encrypted/decrypted before transmitting it or af‐
37 ter receiving it. Depending on the actual operation that happens (TX
38 or RX), the device will do the “right thing” based on the crypto prop‐
39 erties configured in the MKey.
40 MKeys can be configured with both crypto and signature properties at
42 the same time by calling both mlx5dv_wr_set_mkey_crypto()[22m(3) and
43 mlx5dv_wr_set_mkey_sig_block()[22m(3). In this case, both crypto and sig‐
44 nature operations will be performed according to the crypto and signa‐
45 ture properties configured in the MKey, and the order of operations
46 will be determined by the signature_crypto_order property.
47 Example 1 (corresponds to row F in the table below):
49 Memory signature domain is not configured, and memory data is encrypt‐
50 ed.
51 Wire signature domain is not configured, and wire data is in plaintext.
53 encrypt_on_tx is set to false, and because signature is not configured,
55 signature_crypto_order value doesn’t matter.
56 A SEND is issued using the MKey as a local key.
58 Result: device will gather the encrypted data from the MKey (using
60 whatever layout configured to the MKey to locate the actual memory),
61 decrypt it using the supplied DEK and transmit the decrypted data to
62 the wire.
63 Example 1.1:
65 Same as above, but a RECV is issued with the same MKey, and RX happens.
66 Result: device will receive the data from the wire, encrypt it using
68 the supplied DEK and scatter it to the MKey (using whatever layout con‐
69 figured to the MKey to locate the actual memory).
70 Example 2 (corresponds to row C in the table below):
72 Memory signature domain is configured for no signature, and memory data
73 is in plaintext.
74 Wire signature domain is configured for T10DIF every 512 Bytes block,
76 and wire data (including the T10DIF) is encrypted.
77 encrypt_on_tx is set to true and signature_crypto_order is set to be
79 MLX5DV_SIGNATURE_CRYPTO_ORDER_SIGNATURE_BEFORE_CRYPTO_ON_TX. da‐
80 ta_unit_size is set to MLX5DV_BLOCK_SIZE_520.
81 The MKey is sent to a remote node that issues a RDMA_READ to this MKey.
83 Result: device will gather the data from the MKey (using whatever lay‐
85 out configured to the MKey to locate the actual memory), generate an
86 additional T10DIF field every 512B of data, encrypt the data and the
87 newly generated T10DIF field using the supplied DEK, and transmit it to
88 the wire.
89 Example 2.1:
91 Same as above, but remote node issues a RDMA_WRITE to this MKey.
92 Result: device will receive the data from the wire, decrypt the data
94 using the supplied DEK, validate each T10DIF field against the previous
95 512B of data, strip the T10DIF field, and scatter the data alone to the
96 MKey (using whatever layout configured to the MKey to locate the actual
97 memory).
98
100 mqp The QP where an MKey configuration work request was created by
101 mlx5dv_wr_mkey_configure().
102 attr Crypto attributes to set for the MKey.
104 Crypto Attributes
106 Crypto attributes describe the format (encrypted or plaintext) and lay‐
107 out of the input and output data in memory and wire domains, the crypto
108 standard that should be used and its attributes.
109 struct mlx5dv_crypto_attr {
111 enum mlx5dv_crypto_standard crypto_standard;
112 bool encrypt_on_tx;
113 enum mlx5dv_signature_crypto_order signature_crypto_order;
114 enum mlx5dv_block_size data_unit_size;
115 char initial_tweak[16];
116 struct mlx5dv_dek *dek;
117 char keytag[8];
118 uint64_t comp_mask;
119 };
120 crypto_standard
122 The encryption standard that should be used, currently can only
123 be the following value
124 MLX5DV_CRYPTO_STANDARD_AES_XTS
126 The AES-XTS encryption standard defined in IEEE Std
127 1619-2007.
128 encrypt_on_tx
130 If set, memory data will be encrypted during TX and wire data
131 will be decrypted during RX. If not set, memory data will be
132 decrypted during TX and wire data will be encrypted during RX.
133 signature_crypto_order
135 Controls the order between crypto and signature operations
136 (Please see detailed table below). Relevant only if signature
137 is configured. Can be one of the following values
138 MLX5DV_SIGNATURE_CRYPTO_ORDER_SIGNATURE_AFTER_CRYPTO_ON_TX
140 During TX, first perform crypto operation (encrypt/de‐
141 crypt based on encrypt_on_tx) and then signature opera‐
142 tion on memory data. During RX, first perform signature
143 operation and then crypto operation (encrypt/decrypt
144 based on encrypt_on_tx) on wire data.
145 MLX5DV_SIGNATURE_CRYPTO_ORDER_SIGNATURE_BEFORE_CRYPTO_ON_TX
147 During TX, first perform signature operation and then
148 crypto operation (encrypt/decrypt based on encrypt_on_tx)
149 on memory data. During RX, first perform crypto opera‐
150 tion (encrypt/decrypt based on encrypt_on_tx) and then
151 signature operation on wire data.
152 Table: signature_crypto_order and encrypt_on_tx Meaning.
154 The table describes the possible data layouts in memory and wire
156 domains, and the order in which crypto and signature operations
157 are performed according to signature_crypto_order, encrypt_on_tx
158 and signature configuration.
159 Memory column represents the data layout in the memory domain.
161 Wire column represents the data layout in the wire domain.
163 There are three possible operations that can be performed by the
165 device on the data when processing it from memory to wire and
166 from wire to memory:
167 1. Crypto operation.
169 2. Signature operation in memory domain.
171 3. Signature operation in wire domain.
173 Op1, Op2 and Op3 columns represent these operations. On TX,
175 Op1, Op2 and Op3 are performed on memory data to produce the da‐
176 ta layout that is specified in Wire column. On RX, Op3, Op2 and
177 Op1 are performed on wire data to produce the data layout speci‐
178 fied in Memory column. “SIG.mem” and “SIG.wire” represent the
179 signature operation that is performed in memory and wire domains
180 respectively. None means no operation is performed. The exact
181 signature operations are determined by the signature attributes
182 configured by mlx5dv_wr_set_mkey_sig_block().
183 encrypt_on_tx and signature_crypto_order columns represent the
185 values that encrypt_on_tx and signature_crypto_order should have
186 in order to achieve such behavior.
187 Memory Op1 Op2 Op3 Wire en‐ signature_cryp‐
189 crypt_on_tx to_order
190 ───────────────────────────────────────────────────────────────────────────────────────────────
191 A data Encrypt SIG.mem SIG.wire enc(da‐ True Doesn’t matter
192 on TX = none = none ta)
193 B data Encrypt SIG.mem SIG.wire enc(da‐ True SIGNATURE_AF‐
195 On TX = none = SIG ta)+SIG TER_CRYPTO_ON_TX
196 C data SIG.mem SIG.wire Encrypt enc(da‐ True SIGNATURE_BE‐
200 = none = SIG on TX ta+SIG) FORE_CRYPTO_ON_TX
201 D data+SIG SIG.mem SIG.wire Encrypt enc(da‐ True SIGNATURE_BE‐
203 = SIG = none on TX ta) FORE_CRYPTO_ON_TX
204 E da‐ SIG.mem SIG.wire Encrypt enc(da‐ True SIGNATURE_BE‐
206 ta+SIG1 = SIG1 = SIG2 on TX ta+SIG2) FORE_CRYPTO_ON_TX
207 F enc(da‐ Decrypt SIG.mem SIG.wire data False Doesn’t matter
209 ta) on TX = none = none
210 G enc(da‐ Decrypt SIG.mem SIG.wire data+SIG False SIGNATURE_AF‐
212 ta) on TX = none = SIG TER_CRYPTO_ON_TX
213 H enc(da‐ Decrypt SIG.mem SIG.wire data False SIGNATURE_AF‐
215 ta+SIG) on TX = SIG = none TER_CRYPTO_ON_TX
216 I enc(da‐ Decrypt SIG.mem SIG.wire da‐ False SIGNATURE_AF‐
218 ta+SIG1) on TX = SIG1 = SIG2 ta+SIG2 TER_CRYPTO_ON_TX
219 J enc(da‐ SIG.mem SIG.wire Decrypt data False SIGNATURE_BE‐
221 ta)+SIG = SIG = none on TX FORE_CRYPTO_ON_TX
222 Notes:
224 • “Encrypt on TX” also means “Decrypt on RX”, and “Decrypt on
226 TX” also means “Encrypt on RX”.
227 • When signature properties are not configured in the MKey, only
229 crypto operations will be performed. Thus, signature_cryp‐
230 to_order has no meaning in this case (rows A and F), and it
231 can be set to either one of its values.
232 data_unit_size
234 For storage, this will normally be the storage block size. The
235 tweak is incremented after each data_unit_size during the en‐
236 cryption. can be one of enum mlx5dv_block_size.
237 initial_tweak
239 A value to be used during encryption of each data unit. Must be
240 supplied in little endian. This value is incremented by the de‐
241 vice for every data unit in the message. For storage encryp‐
242 tion, this will normally be the LBA of the first block in the
243 message, so that the increments represent the LBAs of the rest
244 of the blocks in the message.
245 dek The DEK to be used for the crypto operations. This DEK must be
247 pre-loaded to the device using mlx5dv_dek_create().
248 key_tag
250 A tag that verifies that the correct DEK is being used. key_tag
251 is optional and is valid only if the DEK was created with
252 has_keytag set to true. If so, it must match the key tag that
253 was provided when the DEK was created. Supllied in plaintext.
254 comp_mask
256 Reserved for future extension, must be 0 now.
257
259 This function does not return a value.
260 In case of error, user will be notified later when completing the DV
262 WRs chain.
263
265 MKey must be created with MLX5DV_MKEY_INIT_ATTR_FLAGS_CRYPTO flag.
266 The last operation posted on the supplied QP should be
268 mlx5dv_wr_mkey_configure(3), or one of its related setters, and the op‐
269 eration must still be open (no doorbell issued).
270 In case of ibv_wr_complete() failure or calling to ibv_wr_abort(), the
272 MKey may be left in an unknown state. The next configuration of it
273 should not assume any previous state of the MKey, i.e. signature/crypto
274 should be re-configured or reset, as required. For example, assuming
275 mlx5dv_wr_set_mkey_sig_block() and then ibv_wr_abort() were called,
276 then on the next configuration of the MKey, if signature is not needed,
277 it should be reset using MLX5DV_MKEY_CONF_FLAG_RESET_SIG_ATTR.
278 When configuring a MKey with AES-XTS crypto offload, and using the for‐
280 mer for traffic (send/receive), the amount of data to send/receive must
281 meet one of the following conditions for successful encryption/decryp‐
282 tion process (per AES-XTS spec):
283 Let’s refer to the amount of data to send/receive as `job_size'
285 1.job_size % data_unit_size == 0 2.(job_size % 16 == 0) && (job_size %
286 data_unit_size <= data_unit_size - 16)
287 For example: When data_unit_size = 512B: 1. job_size = 512B is valid
289 (1 holds). 2. job_size = 128B is valid (2 holds). 3. job_size = 47B
290 is invalid (neither 1 nor 2 holds).
291 When data_unit_size = 520B: 1. job_size = 520B is valid (1 holds). 2.
293 job_size = 496B is valid (2 holds). 3. job_size = 512B is invalid
294 (neither 1 nor 2 holds).
295
297 mlx5dv_wr_mkey_configure(3), mlx5dv_wr_set_mkey_sig_block(3),
298 mlx5dv_create_mkey(3), mlx5dv_destroy_mkey(3), mlx5dv_crypto_login(3),
299 mlx5dv_crypto_login_create(3), mlx5dv_dek_create(3)
300
302 Oren Duer <oren@nvidia.com>
303 Avihai Horon <avihaih@nvidia.com>
305 Maher Sanalla <msanalla@nvidia.com>
307 mlx5dv_wr_set_mkey_crypto(3)