Scroll to navigation

mlx5dv_crypto_login_create / mlx5dv_crypto_login_query / mlx5dv_crypto_login_destroy(3) mlx5dv_crypto_login_create / mlx5dv_crypto_login_query / mlx5dv_crypto_login_destroy(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 traffic).

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_login 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 object.

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;
};
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 credential.
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 credential and also for all other secured communications done with the crypto login object.
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 credential value stored on the device.
The length of the provided credential value in bytes.
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;
};
The state of the crypto login object, can be one of the following
The crypto login object is valid and can be used.
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, 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.
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 errno 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>