1mlx5dv_wr_set_mkey_crypto(3)                      mlx5dv_wr_set_mkey_crypto(3)
2
3
4

NAME

6       mlx5dv_wr_set_mkey_crypto - Configure a MKey for crypto operation.
7

SYNOPSIS

9              #include <infiniband/mlx5dv.h>
10
11              static inline void
12              mlx5dv_wr_set_mkey_crypto(struct mlx5dv_qp_ex *mqp,
13                            const struct mlx5dv_crypto_attr *attr);
14

DESCRIPTION

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
20       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
28       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
33       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
41       MKeys can be configured with both crypto and  signature  properties  at
42       the  same  time  by  calling  both  mlx5dv_wr_set_mkey_crypto()(3)  and
43       mlx5dv_wr_set_mkey_sig_block()(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
48   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
52       Wire signature domain is not configured, and wire data is in plaintext.
53
54       encrypt_on_tx is set to false, and because signature is not configured,
55       signature_crypto_order value doesn’t matter.
56
57       A SEND is issued using the MKey as a local key.
58
59       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
64   Example 1.1:
65       Same as above, but a RECV is issued with the same MKey, and RX happens.
66
67       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
71   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
75       Wire  signature  domain is configured for T10DIF every 512 Bytes block,
76       and wire data (including the T10DIF) is encrypted.
77
78       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
82       The MKey is sent to a remote node that issues a RDMA_READ to this MKey.
83
84       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
90   Example 2.1:
91       Same as above, but remote node issues a RDMA_WRITE to this MKey.
92
93       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

ARGUMENTS

100       mqp    The QP where an MKey configuration work request was  created  by
101              mlx5dv_wr_mkey_configure().
102
103       attr   Crypto attributes to set for the MKey.
104
105   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
110              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
121       crypto_standard
122              The  encryption standard that should be used, currently can only
123              be the following value
124
125              MLX5DV_CRYPTO_STANDARD_AES_XTS
126                     The AES-XTS  encryption  standard  defined  in  IEEE  Std
127                     1619-2007.
128
129       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
134       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
139              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
146              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
153              Table: signature_crypto_order and encrypt_on_tx Meaning.
154
155              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
160              Memory column represents the data layout in the memory domain.
161
162              Wire column represents the data layout in the wire domain.
163
164              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
168              1. Crypto operation.
169
170              2. Signature operation in memory domain.
171
172              3. Signature operation in wire domain.
173
174              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
184              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
188                    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
194              B     data       Encrypt     SIG.mem    SIG.wire    enc(da‐    True          SIGNATURE_AF‐
195                               On TX       = none     = SIG       ta)+SIG                  TER_CRYPTO_ON_TX
196
197
198
199              C     data       SIG.mem     SIG.wire   Encrypt     enc(da‐    True          SIGNATURE_BE‐
200                               = none      = SIG      on TX       ta+SIG)                  FORE_CRYPTO_ON_TX
201
202              D     data+SIG   SIG.mem     SIG.wire   Encrypt     enc(da‐    True          SIGNATURE_BE‐
203                               = SIG       = none     on TX       ta)                      FORE_CRYPTO_ON_TX
204
205              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
208              F     enc(da‐    Decrypt     SIG.mem    SIG.wire    data       False         Doesn’t matter
209                    ta)        on TX       = none     = none
210
211              G     enc(da‐    Decrypt     SIG.mem    SIG.wire    data+SIG   False         SIGNATURE_AF‐
212                    ta)        on TX       = none     = SIG                                TER_CRYPTO_ON_TX
213
214              H     enc(da‐    Decrypt     SIG.mem    SIG.wire    data       False         SIGNATURE_AF‐
215                    ta+SIG)    on TX       = SIG      = none                               TER_CRYPTO_ON_TX
216
217              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
220              J     enc(da‐    SIG.mem     SIG.wire   Decrypt     data       False         SIGNATURE_BE‐
221                    ta)+SIG    = SIG       = none     on TX                                FORE_CRYPTO_ON_TX
222
223              Notes:
224
225              • “Encrypt  on  TX”  also means “Decrypt on RX”, and “Decrypt on
226                TX” also means “Encrypt on RX”.
227
228              • 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
233       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
238       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
246       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
249       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
255       comp_mask
256              Reserved for future extension, must be 0 now.
257

RETURN VALUE

259       This function does not return a value.
260
261       In case of error, user will be notified later when  completing  the  DV
262       WRs chain.
263

NOTES

265       MKey must be created with MLX5DV_MKEY_INIT_ATTR_FLAGS_CRYPTO flag.
266
267       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
271       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
279       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
284       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
288       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
292       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

SEE ALSO

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

AUTHORS

302       Oren Duer <oren@nvidia.com>
303
304       Avihai Horon <avihaih@nvidia.com>
305
306       Maher Sanalla <msanalla@nvidia.com>
307
308
309
310                                                  mlx5dv_wr_set_mkey_crypto(3)
Impressum