mlx5dv_dek_create - Man Page

The device context to create the DEK with.

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 Method	Has Keytag	Key size	Key Layout
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

Pointer to an existing DEK to query or to destroy.

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.