.\"t
.\" Automatically generated by Pandoc 1.16.0.2
.\"
.TH "mlx5dv_dek_create / mlx5dv_dek_query / mlx5dv_dek_destroy" "3" "" "" ""
.hy
.SH NAME
.PP
mlx5dv_dek_create \- Creates a DEK
.PP
mlx5dv_dek_query \- Queries a DEK\[aq]s attributes
.PP
mlx5dv_dek_destroy \- Destroys a DEK
.SH SYNOPSIS
.IP
.nf
\f[C]
#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);
\f[]
.fi
.SH DESCRIPTION
.PP
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.
.PP
\f[B]mlx5dv_dek_create()\f[] creates a new DEK with the attributes
specified in \f[I]init_attr\f[].
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.
An active crypto login session must be present in order to create a DEK.
.PP
To use the created DEK in a MKey, a valid or active crypto login session
is not needed.
Revoking the import KEK or credential that were used during the login
(and therefore rendering the login session invalid) does not prevent
using a created DEK.
.PP
\f[B]mlx5dv_dek_query()\f[] queries the DEK specified by \f[I]dek\f[]
and returns the queried attributes in \f[I]attr\f[].
An active crypto login session must be present in order to query a DEK.
.PP
\f[B]mlx5dv_dek_destroy()\f[] destroys the DEK specified by
\f[I]dek\f[].
.SH ARGUMENTS
.SS context
.PP
The device context to create the DEK with.
\f[I]context\f[] must have an active crypto login session associated
with in order to create the DEK.
.SS init_attr
.IP
.nf
\f[C]
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;
};
\f[]
.fi
.TP
.B \f[I]key_size\f[]
The size of the key, can be one of the following
.RS
.TP
.B \f[B]MLX5DV_CRYPTO_KEY_SIZE_128\f[]
Key size is 128 bit.
.RS
.RE
.TP
.B \f[B]MLX5DV_CRYPTO_KEY_SIZE_256\f[]
Key size is 256 bit.
.RS
.RE
.RE
.TP
.B \f[I]has_keytag\f[]
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.
.RS
.RE
.TP
.B \f[I]key_purpose\f[]
The purpose of the key, currently can only be the following value
.RS
.TP
.B \f[B]MLX5DV_CRYPTO_KEY_PURPOSE_AES_XTS\f[]
The key will be used for AES\-XTS crypto engine.
.RS
.RE
.RE
.TP
.B \f[I]pd\f[]
The protection domain to be associated with the DEK.
.RS
.RE
.TP
.B \f[I]opaque\f[]
Plaintext metadata to describe the key.
.RS
.RE
.TP
.B \f[I]key\f[]
The key that will be used for encryption and decryption of transmitted
data.
Must be provided wrapped by the import KEK that was specified for the
crypto login session.
Actual size and layout of this field depend on the provided
\f[I]key_size\f[] and \f[I]has_keytag\f[] fields.
\f[I]key\f[] should be constructed according to the following table.
.RS
.PP
DEK \f[I]key\f[] Field Construction.
.TS
tab(@);
l l l.
T{
Key size
T}@T{
Has Keytag
T}@T{
Key Layout
T}
_
T{
128 Bit
T}@T{
No
T}@T{
ENC(iv_64b + key1_128b + key2_128b)
T}
T{
T}@T{
T}@T{
T}
T{
256 Bit
T}@T{
No
T}@T{
ENC(iv_64b + key1_256b + key2_256b)
T}
T{
T}@T{
T}@T{
T}
T{
128 Bit
T}@T{
Yes
T}@T{
ENC(iv_64b + key1_128b + key2_128b + 64b_keytag)
T}
T{
T}@T{
T}@T{
T}
T{
256 Bit
T}@T{
Yes
T}@T{
ENC(iv_64b + key1_256b + key2_256b + 64b_keytag)
T}
.TE
.PP
Where ENC() is AES key wrap algorithm and iv_64b is 0xA6A6A6A6A6A6A6A6
as per the AES key wrap spec.
.PP
The following example shows how to wrap a 128 bit key that has keytag
using a 128 bit import KEK in OpenSSL:
.IP
.nf
\f[C]
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);
\f[]
.fi
.RE
.TP
.B \f[I]comp_mask\f[]
Reserved for future extension, must be 0 now.
.RS
.RE
.SS dek
.IP
.nf
\f[C]
Pointer\ to\ an\ existing\ DEK\ to\ query\ or\ to\ destroy.
\f[]
.fi
.SS attr
.IP
.nf
\f[C]
DEK\ attributes\ to\ be\ populated\ when\ querying\ a\ DEK.
\f[]
.fi
.IP
.nf
\f[C]
struct\ mlx5dv_dek_attr\ {
\ \ \ \ enum\ mlx5dv_dek_state\ state;
\ \ \ \ char\ opaque[8];
\ \ \ \ uint64_t\ comp_mask;
};
\f[]
.fi
.TP
.B \f[I]state\f[]
The state of the DEK, can be one of the following
.RS
.TP
.B \f[B]MLX5DV_DEK_STATE_READY\f[]
The key is ready for use.
This is the state of the key when it is first created.
.RS
.RE
.TP
.B \f[B]MLX5DV_DEK_STATE_ERROR\f[]
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.
.RS
.RE
.RE
.TP
.B \f[I]opaque\f[]
Plaintext metadata to describe the key.
.RS
.RE
.TP
.B \f[I]comp_mask\f[]
Reserved for future extension, must be 0 now.
.RS
.RE
.SH RETURN VALUE
.PP
\f[B]mlx5dv_dek_create()\f[] returns a pointer to a new \f[I]struct
mlx5dv_dek\f[] on success.
On error NULL is returned and errno is set.
.PP
\f[B]mlx5dv_dek_query()\f[] returns 0 on success and updates
\f[I]attr\f[] with the queried DEK attributes.
On error errno value is returned.
.PP
\f[B]mlx5dv_dek_destroy()\f[] returns 0 on success and errno value on
error.
.SH SEE ALSO
.PP
\f[B]mlx5dv_crypto_login\f[](3)
.SH AUTHORS
.PP
Avihai Horon <avihaih@nvidia.com>
