# mlx5dv_crypto_login_create

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


* * *