|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | SYNOPSIS | DESCRIPTION | ARGUMENTS | RETURN VALUE | SEE ALSO | AUTHORS | COLOPHON |
|
|
|
mlx5dv_dek_cre...5dv_dek_destroy(3) mlx5dv_dek_cre...5dv_dek_destroy(3)
mlx5dv_dek_create - Creates a DEK
mlx5dv_dek_query - Queries a DEK’s attributes
mlx5dv_dek_destroy - Destroys a DEK
#include <infiniband/mlx5dv.h>
struct mlx5dv_dek *mlx5dv_dek_create(struct ibv_context *context,
struct mlx5dv_dek_init_attr *init_attr);
int mlx5dv_dek_query(struct mlx5dv_dek *dek, struct mlx5dv_dek_attr *attr);
int mlx5dv_dek_destroy(struct mlx5dv_dek *dek);
Data Encryption Keys (DEKs) are used to encrypt and decrypt
transmitted data. After a DEK is created, it can be configured in
MKeys for crypto offload operations. DEKs are not persistent and
are destroyed upon process exit. Therefore, software process
needs to re-create all needed DEKs on startup.
mlx5dv_dek_create() creates a new DEK with the attributes
specified in init_attr. A pointer to the newly created dek is
returned, which can be used for DEK query, DEK destruction and
when configuring a MKey for crypto offload operations.
The DEK can be either wrapped or in plaintext and the format that
should be used is determined by the specified crypto_login object.
To create a wrapped DEK, the application must have a valid crypto
login object prior to creating the DEK. Creating a wrapped DEK
can be performed in two ways: 1. Call
mlx5dv_crypto_login_create() to obtain a crypto login object.
Indicate that the DEK is wrapped by setting
MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN value in comp_mask and passing
the crypto login object in crypto_login field of init_attr. Fill
the other DEK attributes and create the DEK.
2. Call mlx5dv_crypto_login() i.e., the old API. Supply
credential, import_kek_id
To create a plaintext DEK, the application must indicate that the
DEK is in plaintext by setting MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN
value in comp_mask and passing NULL value in crypto_login field of
init_attr, fill the other DEK attributes and create the DEK.
To use the created DEK (either wrapped or plaintext) in a MKey, a
valid crypto login object or session is not needed. Revoking the
import KEK or credential that were used for the crypto login
object or session (and therefore rendering the crypto login
invalid) does not prevent using a created DEK.
mlx5dv_dek_query() queries the DEK specified by dek and returns
the queried attributes in attr. A valid crypto login object or
session is not required to query a plaintext DEK. On the other
hand, to query a wrapped DEK a valid crypto login object or
session must be present.
mlx5dv_dek_destroy() destroys the DEK specified by dek.
context
The device context to create the DEK with.
init_attr
enum mlx5dv_dek_init_attr_mask {
MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN = 1 << 0,
};
struct mlx5dv_dek_init_attr {
enum mlx5dv_crypto_key_size key_size;
bool has_keytag;
enum mlx5dv_crypto_key_purpose key_purpose;
struct ibv_pd *pd;
char opaque[8];
char key[128];
uint64_t comp_mask; /* Use enum mlx5dv_dek_init_attr_mask */
struct mlx5dv_crypto_login_obj *crypto_login;
};
key_size
The size of the key, can be one of the following
MLX5DV_CRYPTO_KEY_SIZE_128
Key size is 128 bit.
MLX5DV_CRYPTO_KEY_SIZE_256
Key size is 256 bit.
has_keytag
Whether the DEK has a keytag or not. If set, the key
should include a 8 Bytes keytag. Keytag is used to verify
that the DEK being used by a MKey is the expected DEK.
This is done by comparing the keytag that was defined
during DEK creation with the keytag provided in the MKey
crypto configuration, and failing the operation if they are
different.
key_purpose
The purpose of the key, currently can only be the following
value
MLX5DV_CRYPTO_KEY_PURPOSE_AES_XTS
The key will be used for AES-XTS crypto engine.
pd The protection domain to be associated with the DEK.
opaque Plaintext metadata to describe the key.
key The key that will be used for encryption and decryption of
transmitted data. For plaintext DEK key must be provided
in plaintext. For wrapped DEK key must be provided wrapped
by the import KEK that was specified in the crypto login.
Actual size and layout of this field depend on the provided
key_size and has_keytag fields, as well as on the format of
the key (plaintext or wrapped). key should be constructed
according to the following table.
DEK key Field Construction.
Import Has Keytag Key size Key Layout
Method
────────────────────────────────────────────────────────────────────────────────
Plaintext No 128 Bit key1_128b + key2_128b
Plaintext No 256 Bit key1_256b + key2_256b
Plaintext Yes 128 Bit key1_128b + key2_128b + keytag_64b
Plaintext Yes 256 Bit key1_256b + key2_256b + keytag_64b
Wrapped No 128 Bit ENC(iv_64b + key1_128b + key2_128b)
Wrapped No 256 Bit ENC(iv_64b + key1_256b + key2_256b)
Wrapped Yes 128 Bit ENC(iv_64b + key1_128b + key2_128b +
keytag_64b)
Wrapped Yes 256 Bit ENC(iv_64b + key1_256b + key2_256b +
keytag_64b)
Where ENC() is AES key wrap algorithm and iv_64b is
0xA6A6A6A6A6A6A6A6 as per the NIST SP 800-38F AES key wrap
spec.
The following example shows how to wrap a 128 bit key that
has keytag using a 128 bit import KEK in OpenSSL:
#include <openssl/evp.h>
unsigned char import_kek[16]; /* 128 bit import KEK in plaintext for wrapping */
unsigned char iv[8] = {0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6};
/*
* Indexes 0-15 are key1 in plaintext, indexes 16-31 are key2 in plaintext,
* and indexes 32-39 are key_tag in plaintext.
*/
unsigned char key[40];
unsigned char wrapped_key[48];
EVP_CIPHER_CTX *ctx;
int len;
ctx = EVP_CIPHER_CTX_new();
EVP_CIPHER_CTX_set_flags(ctx, EVP_CIPHER_CTX_FLAG_WRAP_ALLOW);
EVP_EncryptInit_ex(ctx, EVP_aes_128_wrap(), NULL, import_kek, iv);
EVP_EncryptUpdate(ctx, wrapped_key, &len, key, sizeof(key));
EVP_EncryptFinal_ex(ctx, wrapped_key + len, &len);
EVP_CIPHER_CTX_free(ctx);
comp_mask
Currently can be the following value:
MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN, which indicates that
crypto_login field is applicable.
crypto_login
Pointer to a crypto login object. If set to a valid crypto
login object, indicates that this is a wrapped DEK that
will be created using the given crypto login object. If
set to NULL, indicates that this is a plaintext DEK. Must
be NULL if MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN is not set.
Only relevant when comp_mask is set with
MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN
dek
Pointer to an existing DEK to query or to destroy.
attr
DEK attributes to be populated when querying a DEK.
struct mlx5dv_dek_attr {
enum mlx5dv_dek_state state;
char opaque[8];
uint64_t comp_mask;
};
state The state of the DEK, can be one of the following
MLX5DV_DEK_STATE_READY
The key is ready for use. This is the state of the
key when it is first created.
MLX5DV_DEK_STATE_ERROR
The key is unusable. The key needs to be destroyed
and re-created in order to be used. This can
happen, for example, due to DEK memory corruption.
opaque Plaintext metadata to describe the key.
comp_mask
Reserved for future extension, must be 0 now.
mlx5dv_dek_create() returns a pointer to a new struct mlx5dv_dek
on success. On error NULL is returned and errno is set.
mlx5dv_dek_query() returns 0 on success and updates attr with the
queried DEK attributes. On error errno value is returned.
mlx5dv_dek_destroy() returns 0 on success and errno value on
error.
mlx5dv_crypto_login(3), mlx5dv_crypto_login_create(3),
mlx5dv_query_device(3)
Avihai Horon ⟨avihaih@nvidia.com⟩
This page is part of the rdma-core (RDMA Core Userspace Libraries
and Daemons) project. Information about the project can be found
at ⟨https://github.com/linux-rdma/rdma-core⟩. If you have a bug
report for this manual page, send it to
linux-rdma@vger.kernel.org. This page was obtained from the
project's upstream Git repository
⟨https://github.com/linux-rdma/rdma-core.git⟩ on 2025-08-11. (At
that time, the date of the most recent commit that was found in
the repository was 2025-08-04.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
mlx5dv_dek_cre...5dv_dek_destroy(3)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|