.\" Automatically generated by Pandoc 3.1.3
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "mlx5dv_crypto_login / mlx5dv_crypto_login_query_state / mlx5dv_crypto_logout" "3" "" "" ""
.hy
.SH NAME
.PP
mlx5dv_crypto_login - Creates a crypto login session
.PP
mlx5dv_crypto_login_query_state - Queries the state of the current
crypto login session
.PP
mlx5dv_crypto_logout - Logs out from the current crypto login session
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <infiniband/mlx5dv.h>

int mlx5dv_crypto_login(struct ibv_context *context,
            struct mlx5dv_crypto_login_attr *login_attr);

int mlx5dv_crypto_login_query_state(struct ibv_context *context,
                    enum mlx5dv_crypto_login_state *state);

int mlx5dv_crypto_logout(struct ibv_context *context);
\f[R]
.fi
.SH DESCRIPTION
.PP
When using a crypto engine that is in wrapped import method, an active
crypto login session must be present in order to create and query Data
Encryption Keys (DEKs).
.PP
\f[B]mlx5dv_crypto_login()\f[R] Creates a crypto login session with the
credential given in \f[I]login_attr\f[R] and associates it with
\f[I]context\f[R].
Only one active crypto login session can be associated per device
context.
.PP
\f[B]mlx5dv_crypto_login_query_state()\f[R] queries the state of the
crypto login session associated with \f[I]context\f[R] and returns the
state in \f[I]state\f[R], which indicates whether it is valid, invalid
or doesn\[cq]t exist.
A valid crypto login session can become invalid if the credential or the
import KEK used in the crypto login session were deleted during the
login session (for example by a crypto officer).
In this case, \f[B]mlx5dv_crypto_logout()\f[R] should be called to
destroy the current invalid crypto login session and if still necessary,
\f[B]mlx5dv_crypto_login()\f[R] should be called to create a new crypto
login session with valid credential and import KEK.
.PP
\f[B]mlx5dv_crypto_logout()\f[R] logs out from the current crypto login
session associated with \f[I]context\f[R].
.PP
Existing DEKs that were previously loaded to the device during a crypto
login session don\[cq]t need an active crypto login session in order to
be used (in MKey or during traffic).
.SH ARGUMENTS
.SS context
.PP
The device context to associate the crypto login session with.
.SS login_attr
.PP
Crypto login attributes specify the credential to login with and the
import KEK to be used for secured communications during the crypto login
session.
.IP
.nf
\f[C]
struct mlx5dv_crypto_login_attr {
    uint32_t credential_id;
    uint32_t import_kek_id;
    char credential[48];
    uint64_t comp_mask;
};
\f[R]
.fi
.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 during the crypto login session.
.TP
\f[I]credential\f[R]
The credential to login with.
Must be provided wrapped by the AES key wrap algorithm using the import
KEK indicated by \f[I]import_kek_id\f[R].
.TP
\f[I]comp_mask\f[R]
Reserved For future extension, must be 0 now.
.SS state
.PP
Indicates the state of the current crypto login session.
can be one of MLX5DV_CRYPTO_LOGIN_STATE_VALID,
MLX5DV_CRYPTO_LOGIN_STATE_NO_LOGIN and
MLX5DV_CRYPTO_LOGIN_STATE_INVALID.
.SH RETURN VALUE
.PP
\f[B]mlx5dv_crypto_login()\f[R] returns 0 on success and errno value on
error.
.PP
\f[B]mlx5dv_crypto_login_query_state()\f[R] returns 0 on success and
updates \f[I]state\f[R] with the queried state.
On error, errno value is returned.
.PP
\f[B]mlx5dv_crypto_logout()\f[R] returns 0 on success and errno value on
error.
.SH ERRORS
.TP
EEXIST
A crypto login session already exists.
.TP
EINVAL
Invalid attributes were provided, or one or more of
\f[I]credential\f[R], \f[I]credential_id\f[R] and
\f[I]import_kek_id\f[R] are invalid.
.TP
ENOENT
No crypto login session exists.
.SH AUTHORS
.PP
Avihai Horon <avihaih@nvidia.com>