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;
              };

       credential_id
              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.

       import_kek_id
              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.

       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 credential 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 following

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

       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 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

                                                          mlx5dv_crypto_login_crea...5dv_crypto_login_destroy(3)