mlx5dv_cryptodloginpcreatei/_mlx5dv_cryptodloginpqueryg/nmlx5dv_cryptodloginpdestroy(3)estroy(3)
NAME
mlx5dv_crypto_login_create - Creates a crypto login object
mlx5dv_crypto_login_query - Queries the given crypto login object
mlx5dv_crypto_login_destroy - Destroys the given crypto login object
SYNOPSIS
#include <infiniband/mlx5dv.h>
struct mlx5dv_crypto_login_obj *
mlx5dv_crypto_login_create(struct ibv_context *context,
struct mlx5dv_crypto_login_attr_ex *login_attr);
int mlx5dv_crypto_login_query(struct mlx5dv_crypto_login_obj *crypto_login,
struct mlx5dv_crypto_login_query_attr *query_attr);
int mlx5dv_crypto_login_destroy(struct mlx5dv_crypto_login_obj *crypto_login);
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).
A valid crypto login object is necessary only to create and query
wrapped DEKs. Existing DEKs that were previously created don’t need a
valid crypto login object in order to be used (in MKey or during traf-
fic).
mlx5dv_crypto_login_create() creates and returns a crypto login object
with the credential given in login_attr. Only one crypto login object
can be created per device context. The created crypto login object
must be provided to mlx5dv_dek_create() in order to create wrapped
DEKs.
mlx5dv_crypto_login_query() queries the crypto login object crypto_lo-
gin and returns the queried attributes in query_attr.
mlx5dv_crypto_login_destroy() destroys the given crypto login object.
ARGUMENTS
context
The device context that will be associated with the crypto login ob-
ject.
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.
struct 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;
};
credential_id
An ID of a credential, from the credentials stored on the de-
vice, that indicates the credential that should be validated
against the credential provided in credential.
import_kek_id
An ID of an import KEK, from the import KEKs stored on the de-
vice, that indicates the import KEK that will be used for un-
wrapping the credential provided in credential and also for all
other secured communications done with the crypto login object.
credential
The credential to login with. Credential is a piece of data
used to authenticate the user for crypto login. The credential
in credential is validated against the credential indicated by
credential_id, which is stored on the device. The credentials
must match in order for the crypto login to succeed. credential
must be provided wrapped by the AES key wrap algorithm using the
import KEK indicated by import_kek_id. credential 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 cre-
dential value stored on the device.
credential_len
The length of the provided credential value in bytes.
comp_mask
Reserved for future extension, must be 0 now.
query_attr
Crypto login attributes to be populated when querying a crypto login
object.
struct mlx5dv_crypto_login_query_attr {
enum mlx5dv_crypto_login_state state;
uint64_t comp_mask;
};
state The state of the crypto login object, can be one of the follow-
ing
MLX5DV_CRYPTO_LOGIN_STATE_VALID
The crypto login object is valid and can be used.
MLX5DV_CRYPTO_LOGIN_STATE_INVALID
The crypto login object is invalid and cannot be used. A
valid crypto login object can become invalid if the cre-
dential or the import KEK used in the crypto login object
were deleted while in use (for example by a crypto offi-
cer). In this case, mlx5dv_crypto_login_destroy() should
be called to destroy the invalid crypto login object and
if still necessary, mlx5dv_crypto_login_create() should
be called to create a new crypto login object with valid
credential and import KEK.
comp_mask
Reserved for future extension, must be 0 now.
RETURN VALUE
mlx5dv_crypto_login_create() returns a pointer to a new valid struct
mlx5dv_crypto_login_obj on success. On error NULL is returned and er-
rno is set.
mlx5dv_crypto_login_query() returns 0 on success and fills query_attr
with the queried attributes. On error, errno is returned.
mlx5dv_crypto_login_destroy() returns 0 on success and errno on error.
SEE ALSO
mlx5dv_dek_create(3), mlx5dv_query_device(3)
AUTHORS
Avihai Horon <avihaih@nvidia.com>
mlx5dv_crypto_login_create / mlx5dv_crypto_login_query / mlx5dv_crypto_login_destroy(3)
Generated by dwww version 1.15 on Wed Jun 26 18:06:36 CEST 2024.