'\" t
.\" Automatically generated by Pandoc 3.1.8
.\"
.TH "mlx5dv_wr_set_mkey_crypto" "3" "" "" ""
.SH NAME
mlx5dv_wr_set_mkey_crypto - Configure a MKey for crypto operation.
.SH SYNOPSIS
.IP
.EX
#include <infiniband/mlx5dv.h>

static inline void
mlx5dv_wr_set_mkey_crypto(struct mlx5dv_qp_ex *mqp,
              const struct mlx5dv_crypto_attr *attr);
.EE
.SH DESCRIPTION
Configure a MKey with crypto properties.
With this, the device will encrypt/decrypt data when transmitting data
from memory to network and when receiving data from network to memory.
.PP
In order to configure MKey with crypto properties, the MKey should be
created with \f[B]MLX5DV_MKEY_INIT_ATTR_FLAGS_CRYPTO\f[R].
MKey that was created with \f[B]MLX5DV_MKEY_INIT_ATTR_FLAGS_CRYPTO\f[R]
must have crypto properties configured to it before it can be used,
i.e.\ this setter must be called before the MKey can be used or else
traffic will fail, generating a CQE with error.
A call to this setter on a MKey that already has crypto properties
configured to it will override existing crypto properties.
.PP
Configuring crypto properties to a MKey is done by specifying the crypto
standard that should be used and its attributes, and also by providing
the Data Encryption Key (DEK) to be used for the encryption/decryption
itself.
.PP
The MKey represents a virtually contiguous memory, by configuring a
layout to it.
The crypto properties of the MKey describe whether data in this
virtually contiguous memory is encrypted or in plaintext, and whether it
should be encrypted/decrypted before transmitting it or after receiving
it.
Depending on the actual operation that happens (TX or RX), the device
will do the \[lq]right thing\[rq] based on the crypto properties
configured in the MKey.
.PP
MKeys can be configured with both crypto and signature properties at the
same time by calling both \f[B]mlx5dv_wr_set_mkey_crypto()\f[R](3) and
\f[B]mlx5dv_wr_set_mkey_sig_block()\f[R](3).
In this case, both crypto and signature operations will be performed
according to the crypto and signature properties configured in the MKey,
and the order of operations will be determined by the
\f[I]signature_crypto_order\f[R] property.
.SS Example 1 (corresponds to row F in the table below):
Memory signature domain is not configured, and memory data is encrypted.
.PP
Wire signature domain is not configured, and wire data is in plaintext.
.PP
\f[I]encrypt_on_tx\f[R] is set to false, and because signature is not
configured, \f[I]signature_crypto_order\f[R] value doesn\[cq]t matter.
.PP
A SEND is issued using the MKey as a local key.
.PP
Result: device will gather the encrypted data from the MKey (using
whatever layout configured to the MKey to locate the actual memory),
decrypt it using the supplied DEK and transmit the decrypted data to the
wire.
.SS Example 1.1:
Same as above, but a RECV is issued with the same MKey, and RX happens.
.PP
Result: device will receive the data from the wire, encrypt it using the
supplied DEK and scatter it to the MKey (using whatever layout
configured to the MKey to locate the actual memory).
.SS Example 2 (corresponds to row C in the table below):
Memory signature domain is configured for no signature, and memory data
is in plaintext.
.PP
Wire signature domain is configured for T10DIF every 512 Bytes block,
and wire data (including the T10DIF) is encrypted.
.PP
\f[I]encrypt_on_tx\f[R] is set to true and
\f[I]signature_crypto_order\f[R] is set to be
\f[B]MLX5DV_SIGNATURE_CRYPTO_ORDER_SIGNATURE_BEFORE_CRYPTO_ON_TX\f[R].
\f[I]data_unit_size\f[R] is set to \f[B]MLX5DV_BLOCK_SIZE_520\f[R].
.PP
The MKey is sent to a remote node that issues a RDMA_READ to this MKey.
.PP
Result: device will gather the data from the MKey (using whatever layout
configured to the MKey to locate the actual memory), generate an
additional T10DIF field every 512B of data, encrypt the data and the
newly generated T10DIF field using the supplied DEK, and transmit it to
the wire.
.SS Example 2.1:
Same as above, but remote node issues a RDMA_WRITE to this MKey.
.PP
Result: device will receive the data from the wire, decrypt the data
using the supplied DEK, validate each T10DIF field against the previous
512B of data, strip the T10DIF field, and scatter the data alone to the
MKey (using whatever layout configured to the MKey to locate the actual
memory).
.SH ARGUMENTS
.TP
\f[I]mqp\f[R]
The QP where an MKey configuration work request was created by
\f[B]mlx5dv_wr_mkey_configure()\f[R].
.TP
\f[I]attr\f[R]
Crypto attributes to set for the MKey.
.SS Crypto Attributes
Crypto attributes describe the format (encrypted or plaintext) and
layout of the input and output data in memory and wire domains, the
crypto standard that should be used and its attributes.
.IP
.EX
struct mlx5dv_crypto_attr {
    enum mlx5dv_crypto_standard crypto_standard;
    bool encrypt_on_tx;
    enum mlx5dv_signature_crypto_order signature_crypto_order;
    enum mlx5dv_block_size data_unit_size;
    char initial_tweak[16];
    struct mlx5dv_dek *dek;
    char keytag[8];
    uint64_t comp_mask;
};
.EE
.TP
\f[I]crypto_standard\f[R]
The encryption standard that should be used, currently can only be the
following value
.RS
.TP
\f[B]MLX5DV_CRYPTO_STANDARD_AES_XTS\f[R]
The AES-XTS encryption standard defined in IEEE Std 1619-2007.
.RE
.TP
\f[I]encrypt_on_tx\f[R]
If set, memory data will be encrypted during TX and wire data will be
decrypted during RX.
If not set, memory data will be decrypted during TX and wire data will
be encrypted during RX.
.TP
\f[I]signature_crypto_order\f[R]
Controls the order between crypto and signature operations (Please see
detailed table below).
Relevant only if signature is configured.
Can be one of the following values
.RS
.TP
\f[B]MLX5DV_SIGNATURE_CRYPTO_ORDER_SIGNATURE_AFTER_CRYPTO_ON_TX\f[R]
During TX, first perform crypto operation (encrypt/decrypt based on
\f[I]encrypt_on_tx\f[R]) and then signature operation on memory data.
During RX, first perform signature operation and then crypto operation
(encrypt/decrypt based on \f[I]encrypt_on_tx\f[R]) on wire data.
.TP
\f[B]MLX5DV_SIGNATURE_CRYPTO_ORDER_SIGNATURE_BEFORE_CRYPTO_ON_TX\f[R]
During TX, first perform signature operation and then crypto operation
(encrypt/decrypt based on \f[I]encrypt_on_tx\f[R]) on memory data.
During RX, first perform crypto operation (encrypt/decrypt based on
\f[I]encrypt_on_tx\f[R]) and then signature operation on wire data.
.PP
Table: \f[I]signature_crypto_order\f[R] and \f[I]encrypt_on_tx\f[R]
Meaning.
.PP
The table describes the possible data layouts in memory and wire
domains, and the order in which crypto and signature operations are
performed according to \f[I]signature_crypto_order\f[R],
\f[I]encrypt_on_tx\f[R] and signature configuration.
.PP
Memory column represents the data layout in the memory domain.
.PP
Wire column represents the data layout in the wire domain.
.PP
There are three possible operations that can be performed by the device
on the data when processing it from memory to wire and from wire to
memory:
.IP "1." 3
Crypto operation.
.IP "2." 3
Signature operation in memory domain.
.IP "3." 3
Signature operation in wire domain.
.PP
Op1, Op2 and Op3 columns represent these operations.
On TX, Op1, Op2 and Op3 are performed on memory data to produce the data
layout that is specified in Wire column.
On RX, Op3, Op2 and Op1 are performed on wire data to produce the data
layout specified in Memory column.
\[lq]SIG.mem\[rq] and \[lq]SIG.wire\[rq] represent the signature
operation that is performed in memory and wire domains respectively.
None means no operation is performed.
The exact signature operations are determined by the signature
attributes configured by \f[B]mlx5dv_wr_set_mkey_sig_block()\f[R].
.PP
encrypt_on_tx and signature_crypto_order columns represent the values
that \f[I]encrypt_on_tx\f[R] and \f[I]signature_crypto_order\f[R] should
have in order to achieve such behavior.
.PP
.TS
tab(@);
lw(2.7n) lw(8.5n) lw(8.5n) lw(8.5n) lw(8.5n) lw(8.5n) lw(8.0n) lw(17.0n).
T{
T}@T{
Memory
T}@T{
Op1
T}@T{
Op2
T}@T{
Op3
T}@T{
Wire
T}@T{
encrypt_on_tx
T}@T{
signature_crypto_order
T}
_
T{
A
T}@T{
data
T}@T{
Encrypt on TX
T}@T{
SIG.mem = none
T}@T{
SIG.wire = none
T}@T{
enc(data)
T}@T{
True
T}@T{
Doesn\[cq]t matter
T}
T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}
T{
B
T}@T{
data
T}@T{
Encrypt On TX
T}@T{
SIG.mem = none
T}@T{
SIG.wire = SIG
T}@T{
enc(data)+SIG
T}@T{
True
T}@T{
SIGNATURE_AFTER_CRYPTO_ON_TX
T}
T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}
T{
C
T}@T{
data
T}@T{
SIG.mem = none
T}@T{
SIG.wire = SIG
T}@T{
Encrypt on TX
T}@T{
enc(data+SIG)
T}@T{
True
T}@T{
SIGNATURE_BEFORE_CRYPTO_ON_TX
T}
T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}
T{
D
T}@T{
data+SIG
T}@T{
SIG.mem = SIG
T}@T{
SIG.wire = none
T}@T{
Encrypt on TX
T}@T{
enc(data)
T}@T{
True
T}@T{
SIGNATURE_BEFORE_CRYPTO_ON_TX
T}
T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}
T{
E
T}@T{
data+SIG1
T}@T{
SIG.mem = SIG1
T}@T{
SIG.wire = SIG2
T}@T{
Encrypt on TX
T}@T{
enc(data+SIG2)
T}@T{
True
T}@T{
SIGNATURE_BEFORE_CRYPTO_ON_TX
T}
T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}
T{
F
T}@T{
enc(data)
T}@T{
Decrypt on TX
T}@T{
SIG.mem = none
T}@T{
SIG.wire = none
T}@T{
data
T}@T{
False
T}@T{
Doesn\[cq]t matter
T}
T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}
T{
G
T}@T{
enc(data)
T}@T{
Decrypt on TX
T}@T{
SIG.mem = none
T}@T{
SIG.wire = SIG
T}@T{
data+SIG
T}@T{
False
T}@T{
SIGNATURE_AFTER_CRYPTO_ON_TX
T}
T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}
T{
H
T}@T{
enc(data+SIG)
T}@T{
Decrypt on TX
T}@T{
SIG.mem = SIG
T}@T{
SIG.wire = none
T}@T{
data
T}@T{
False
T}@T{
SIGNATURE_AFTER_CRYPTO_ON_TX
T}
T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}
T{
I
T}@T{
enc(data+SIG1)
T}@T{
Decrypt on TX
T}@T{
SIG.mem = SIG1
T}@T{
SIG.wire = SIG2
T}@T{
data+SIG2
T}@T{
False
T}@T{
SIGNATURE_AFTER_CRYPTO_ON_TX
T}
T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}@T{
T}
T{
J
T}@T{
enc(data)+SIG
T}@T{
SIG.mem = SIG
T}@T{
SIG.wire = none
T}@T{
Decrypt on TX
T}@T{
data
T}@T{
False
T}@T{
SIGNATURE_BEFORE_CRYPTO_ON_TX
T}
.TE
.PP
Notes:
.IP \[bu] 2
\[lq]Encrypt on TX\[rq] also means \[lq]Decrypt on RX\[rq], and
\[lq]Decrypt on TX\[rq] also means \[lq]Encrypt on RX\[rq].
.IP \[bu] 2
When signature properties are not configured in the MKey, only crypto
operations will be performed.
Thus, \f[I]signature_crypto_order\f[R] has no meaning in this case (rows
A and F), and it can be set to either one of its values.
.RE
.TP
\f[I]data_unit_size\f[R]
For storage, this will normally be the storage block size.
The tweak is incremented after each \f[I]data_unit_size\f[R] during the
encryption.
can be one of \f[B]enum mlx5dv_block_size\f[R].
.TP
\f[I]initial_tweak\f[R]
A value to be used during encryption of each data unit.
Must be supplied in little endian.
This value is incremented by the device for every data unit in the
message.
For storage encryption, this will normally be the LBA of the first block
in the message, so that the increments represent the LBAs of the rest of
the blocks in the message.
.TP
\f[I]dek\f[R]
The DEK to be used for the crypto operations.
This DEK must be pre-loaded to the device using
\f[B]mlx5dv_dek_create()\f[R].
.TP
\f[I]key_tag\f[R]
A tag that verifies that the correct DEK is being used.
\f[I]key_tag\f[R] is optional and is valid only if the DEK was created
with \f[B]has_keytag\f[R] set to true.
If so, it must match the key tag that was provided when the DEK was
created.
Supllied in plaintext.
.TP
\f[I]comp_mask\f[R]
Reserved for future extension, must be 0 now.
.SH RETURN VALUE
This function does not return a value.
.PP
In case of error, user will be notified later when completing the DV WRs
chain.
.SH NOTES
MKey must be created with \f[B]MLX5DV_MKEY_INIT_ATTR_FLAGS_CRYPTO\f[R]
flag.
.PP
The last operation posted on the supplied QP should be
\f[B]mlx5dv_wr_mkey_configure\f[R](3), or one of its related setters,
and the operation must still be open (no doorbell issued).
.PP
In case of \f[B]ibv_wr_complete()\f[R] failure or calling to
\f[B]ibv_wr_abort()\f[R], the MKey may be left in an unknown state.
The next configuration of it should not assume any previous state of the
MKey, i.e.\ signature/crypto should be re-configured or reset, as
required.
For example, assuming \f[B]mlx5dv_wr_set_mkey_sig_block()\f[R] and then
\f[B]ibv_wr_abort()\f[R] were called, then on the next configuration of
the MKey, if signature is not needed, it should be reset using
\f[B]MLX5DV_MKEY_CONF_FLAG_RESET_SIG_ATTR\f[R].
.PP
When configuring a MKey with AES-XTS crypto offload, and using the
former for traffic (send/receive), the amount of data to send/receive
must meet one of the following conditions for successful
encryption/decryption process (per AES-XTS spec):
.PP
Let\[cq]s refer to the amount of data to send/receive as `job_size'
1.job_size % \f[I]data_unit_size\f[R] == 0 2.(job_size % 16 == 0) &&
(job_size % \f[I]data_unit_size\f[R] <= \f[I]data_unit_size\f[R] - 16)
.PP
For example: When \f[I]data_unit_size\f[R] = 512B: 1.
job_size = 512B is valid (1 holds).
2.
job_size = 128B is valid (2 holds).
3.
job_size = 47B is invalid (neither 1 nor 2 holds).
.PP
When \f[I]data_unit_size\f[R] = 520B: 1.
job_size = 520B is valid (1 holds).
2.
job_size = 496B is valid (2 holds).
3.
job_size = 512B is invalid (neither 1 nor 2 holds).
.SH SEE ALSO
\f[B]mlx5dv_wr_mkey_configure\f[R](3),
\f[B]mlx5dv_wr_set_mkey_sig_block\f[R](3),
\f[B]mlx5dv_create_mkey\f[R](3), \f[B]mlx5dv_destroy_mkey\f[R](3),
\f[B]mlx5dv_crypto_login\f[R](3),
\f[B]mlx5dv_crypto_login_create\f[R](3), \f[B]mlx5dv_dek_create\f[R](3)
.SH AUTHORS
Oren Duer <oren@nvidia.com>
.PP
Avihai Horon <avihaih@nvidia.com>
.PP
Maher Sanalla <msanalla@nvidia.com>