.\" Automatically generated by Pandoc 3.6.1
.\"
.TH "mlx5dv_crypto_login_create / mlx5dv_crypto_login_query / mlx5dv_crypto_login_destroy" "3" "" ""
.SH NAME
mlx5dv_crypto_login_create \- Creates a crypto login object
.PP
mlx5dv_crypto_login_query \- Queries the given crypto login object
.PP
mlx5dv_crypto_login_destroy \- Destroys the given crypto login object
.SH SYNOPSIS
.IP
.EX
#include \f[B]<infiniband/mlx5dv.h>\f[R]

\f[B]struct\f[R] mlx5dv_crypto_login_obj *
mlx5dv_crypto_login_create(\f[B]struct\f[R] ibv_context *context,
               \f[B]struct\f[R] mlx5dv_crypto_login_attr_ex *login_attr);

int mlx5dv_crypto_login_query(\f[B]struct\f[R] mlx5dv_crypto_login_obj *crypto_login,
                  \f[B]struct\f[R] mlx5dv_crypto_login_query_attr *query_attr);

int mlx5dv_crypto_login_destroy(\f[B]struct\f[R] mlx5dv_crypto_login_obj *crypto_login);
.EE
.SH DESCRIPTION
When using a crypto engine that is in wrapped import method, a valid
crypto login object must be provided in order to create and query
wrapped Data Encryption Keys (DEKs).
.PP
A valid crypto login object is necessary only to create and query
wrapped DEKs.
Existing DEKs that were previously created don\[cq]t need a valid crypto
login object in order to be used (in MKey or during traffic).
.PP
\f[B]mlx5dv_crypto_login_create()\f[R] creates and returns a crypto
login object with the credential given in \f[I]login_attr\f[R].
Only one crypto login object can be created per device context.
The created crypto login object must be provided to
\f[B]mlx5dv_dek_create()\f[R] in order to create wrapped DEKs.
.PP
\f[B]mlx5dv_crypto_login_query()\f[R] queries the crypto login object
\f[I]crypto_login\f[R] and returns the queried attributes in
\f[I]query_attr\f[R].
.PP
\f[B]mlx5dv_crypto_login_destroy()\f[R] destroys the given crypto login
object.
.SH ARGUMENTS
.SS context
The device context that will be associated with the crypto login object.
.SS login_attr
Crypto extended login attributes specify the credential to login with
and the import KEK to be used for secured communications done with the
crypto login object.
.IP
.EX
\f[B]struct\f[R] mlx5dv_crypto_login_attr_ex {
    uint32_t credential_id;
    uint32_t import_kek_id;
    const void *credential;
    size_t credential_len;
    uint64_t comp_mask;
};
.EE
.TP
\f[I]credential_id\f[R]
An ID of a credential, from the credentials stored on the device, that
indicates the credential that should be validated against the credential
provided in \f[I]credential\f[R].
.TP
\f[I]import_kek_id\f[R]
An ID of an import KEK, from the import KEKs stored on the device, that
indicates the import KEK that will be used for unwrapping the credential
provided in \f[I]credential\f[R] and also for all other secured
communications done with the crypto login object.
.TP
\f[I]credential\f[R]
The credential to login with.
Credential is a piece of data used to authenticate the user for crypto
login.
The credential in \f[I]credential\f[R] is validated against the
credential indicated by \f[I]credential_id\f[R], which is stored on the
device.
The credentials must match in order for the crypto login to succeed.
\f[I]credential\f[R] must be provided wrapped by the AES key wrap
algorithm using the import KEK indicated by \f[I]import_kek_id\f[R].
\f[I]credential\f[R] format is ENC(iv_64b + plaintext_credential) where
ENC() is AES key wrap algorithm and iv_64b is 0xA6A6A6A6A6A6A6A6 as per
the NIST SP 800\-38F AES key wrap spec, and plaintext_credential is the
credential value stored on the device.
.TP
\f[I]credential_len\f[R]
The length of the provided \f[I]credential\f[R] value in bytes.
.TP
\f[I]comp_mask\f[R]
Reserved for future extension, must be 0 now.
.SS query_attr
.IP
.EX
Crypto login attributes to be populated when querying a crypto login
object.
.EE
.IP
.EX
\f[B]struct\f[R] mlx5dv_crypto_login_query_attr {
    \f[B]enum\f[R] mlx5dv_crypto_login_state state;
    uint64_t comp_mask;
};
.EE
.TP
\f[I]state\f[R]
The state of the crypto login object, can be one of the following
.RS
.TP
\f[B]MLX5DV_CRYPTO_LOGIN_STATE_VALID\f[R]
The crypto login object is valid and can be used.
.TP
\f[B]MLX5DV_CRYPTO_LOGIN_STATE_INVALID\f[R]
The crypto login object is invalid and cannot be used.
A valid crypto login object can become invalid if the credential or the
import KEK used in the crypto login object were deleted while in use
(for example by a crypto officer).
In this case, \f[B]mlx5dv_crypto_login_destroy()\f[R] should be called
to destroy the invalid crypto login object and if still necessary,
\f[B]mlx5dv_crypto_login_create()\f[R] should be called to create a new
crypto login object with valid credential and import KEK.
.RE
.TP
\f[I]comp_mask\f[R]
Reserved for future extension, must be 0 now.
.SH RETURN VALUE
\f[B]mlx5dv_crypto_login_create()\f[R] returns a pointer to a new valid
\f[I]struct mlx5dv_crypto_login_obj\f[R] on success.
On error NULL is returned and errno is set.
.PP
\f[B]mlx5dv_crypto_login_query()\f[R] returns 0 on success and fills
\f[I]query_attr\f[R] with the queried attributes.
On error, errno is returned.
.PP
\f[B]mlx5dv_crypto_login_destroy()\f[R] returns 0 on success and errno
on error.
.SH SEE ALSO
\f[B]mlx5dv_dek_create\f[R](3), \f[B]mlx5dv_query_device\f[R](3)
.SH AUTHORS
Avihai Horon \c
.MT avihaih@nvidia.com
.ME \c