Provided by: libibverbs-dev_50.0-2build2_amd64 bug

NAME

       mlx5dv_dek_create - Creates a DEK

       mlx5dv_dek_query - Queries a DEK’s attributes

       mlx5dv_dek_destroy - Destroys a DEK

SYNOPSIS

              #include <infiniband/mlx5dv.h>

              struct mlx5dv_dek *mlx5dv_dek_create(struct ibv_context *context,
                                   struct mlx5dv_dek_init_attr *init_attr);

              int mlx5dv_dek_query(struct mlx5dv_dek *dek, struct mlx5dv_dek_attr *attr);

              int mlx5dv_dek_destroy(struct mlx5dv_dek *dek);

DESCRIPTION

       Data Encryption Keys (DEKs) are used to encrypt and decrypt transmitted data.  After a DEK
       is created, it can be configured in MKeys for crypto offload  operations.   DEKs  are  not
       persistent  and are destroyed upon process exit.  Therefore, software process needs to re-
       create all needed DEKs on startup.

       mlx5dv_dek_create() creates a new DEK with  the  attributes  specified  in  init_attr.   A
       pointer  to  the  newly  created  dek  is  returned,  which can be used for DEK query, DEK
       destruction and when configuring a MKey for crypto offload operations.

       The DEK can be either wrapped or in plaintext and  the  format  that  should  be  used  is
       determined by the specified crypto_login object.

       To  create  a  wrapped DEK, the application must have a valid crypto login object prior to
       creating the DEK.  Creating a  wrapped  DEK  can  be  performed  in  two  ways:  1.   Call
       mlx5dv_crypto_login_create()  to  obtain  a crypto login object.  Indicate that the DEK is
       wrapped by setting MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN value in comp_mask  and  passing  the
       crypto login object in crypto_login field of init_attr.  Fill the other DEK attributes and
       create the DEK.

       2. Call mlx5dv_crypto_login() i.e., the old API.  Supply credential, import_kek_id

       To create a plaintext DEK, the application must indicate that the DEK is in  plaintext  by
       setting  MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN  value  in  comp_mask and passing NULL value in
       crypto_login field of init_attr, fill the other DEK attributes and create the DEK.

       To use the created DEK (either wrapped or plaintext) in  a  MKey,  a  valid  crypto  login
       object or session is not needed.  Revoking the import KEK or credential that were used for
       the crypto login object or session (and therefore rendering the crypto login invalid) does
       not prevent using a created DEK.

       mlx5dv_dek_query()  queries the DEK specified by dek and returns the queried attributes in
       attr.  A valid crypto login object or session is not required to query  a  plaintext  DEK.
       On  the  other hand, to query a wrapped DEK a valid crypto login object or session must be
       present.

       mlx5dv_dek_destroy() destroys the DEK specified by dek.

ARGUMENTS

   context
       The device context to create the DEK with.

   init_attr
              enum mlx5dv_dek_init_attr_mask {
                  MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN = 1 << 0,
              };

              struct mlx5dv_dek_init_attr {
                  enum mlx5dv_crypto_key_size key_size;
                  bool has_keytag;
                  enum mlx5dv_crypto_key_purpose key_purpose;
                  struct ibv_pd *pd;
                  char opaque[8];
                  char key[128];
                  uint64_t comp_mask; /* Use enum mlx5dv_dek_init_attr_mask */
                  struct mlx5dv_crypto_login_obj *crypto_login;
              };

       key_size
              The size of the key, can be one of the following

              MLX5DV_CRYPTO_KEY_SIZE_128
                     Key size is 128 bit.

              MLX5DV_CRYPTO_KEY_SIZE_256
                     Key size is 256 bit.

       has_keytag
              Whether the DEK has a keytag or not.  If set, the key  should  include  a  8  Bytes
              keytag.  Keytag is used to verify that the DEK being used by a MKey is the expected
              DEK.  This is done by comparing the keytag that was  defined  during  DEK  creation
              with  the  keytag  provided  in  the  MKey  crypto  configuration,  and failing the
              operation if they are different.

       key_purpose
              The purpose of the key, currently can only be the following value

              MLX5DV_CRYPTO_KEY_PURPOSE_AES_XTS
                     The key will be used for AES-XTS crypto engine.

       pd     The protection domain to be associated with the DEK.

       opaque Plaintext metadata to describe the key.

       key    The key that will be used for encryption and decryption of transmitted  data.   For
              plaintext  DEK  key  must  be  provided  in plaintext.  For wrapped DEK key must be
              provided wrapped by the import KEK that was specified in the crypto login.   Actual
              size  and  layout  of  this  field  depend  on the provided key_size and has_keytag
              fields, as well as on the format of the key (plaintext or wrapped).  key should  be
              constructed according to the following table.

              DEK key Field Construction.

              Import         Has Keytag   Key size     Key Layout
              Method
              ─────────────────────────────────────────────────────────────────────────────────
              Plaintext      No           128 Bit      key1_128b + key2_128b

              Plaintext      No           256 Bit      key1_256b + key2_256b

              Plaintext      Yes          128 Bit      key1_128b + key2_128b + keytag_64b

              Plaintext      Yes          256 Bit      key1_256b + key2_256b + keytag_64b

              Wrapped        No           128 Bit      ENC(iv_64b + key1_128b + key2_128b)

              Wrapped        No           256 Bit      ENC(iv_64b + key1_256b + key2_256b)

              Wrapped        Yes          128 Bit      ENC(iv_64b + key1_128b  +  key2_128b  +
                                                       keytag_64b)

              Wrapped        Yes          256 Bit      ENC(iv_64b  +  key1_256b  + key2_256b +
                                                       keytag_64b)

              Where ENC() is AES key wrap algorithm and iv_64b is 0xA6A6A6A6A6A6A6A6 as  per  the
              NIST SP 800-38F AES key wrap spec.

              The  following  example shows how to wrap a 128 bit key that has keytag using a 128
              bit import KEK in OpenSSL:

                     #include <openssl/evp.h>

                     unsigned char import_kek[16]; /* 128 bit import KEK in plaintext for wrapping */
                     unsigned char iv[8] = {0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6};

                     /*
                      * Indexes 0-15 are key1 in plaintext, indexes 16-31 are key2 in plaintext,
                      * and indexes 32-39 are key_tag in plaintext.
                      */
                     unsigned char key[40];

                     unsigned char wrapped_key[48];
                     EVP_CIPHER_CTX *ctx;
                     int len;

                     ctx = EVP_CIPHER_CTX_new();
                     EVP_CIPHER_CTX_set_flags(ctx, EVP_CIPHER_CTX_FLAG_WRAP_ALLOW);
                     EVP_EncryptInit_ex(ctx, EVP_aes_128_wrap(), NULL, import_kek, iv);
                     EVP_EncryptUpdate(ctx, wrapped_key, &len, key, sizeof(key));
                     EVP_EncryptFinal_ex(ctx, wrapped_key + len, &len);
                     EVP_CIPHER_CTX_free(ctx);

       comp_mask
              Currently can be the following value:

              MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN,  which  indicates  that  crypto_login  field  is
              applicable.

       crypto_login
              Pointer to a crypto login object.  If set to a valid crypto login object, indicates
              that this is a wrapped DEK that will  be  created  using  the  given  crypto  login
              object.   If  set to NULL, indicates that this is a plaintext DEK.  Must be NULL if
              MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN is not set.  Only relevant when comp_mask is  set
              with MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN

   dek
              Pointer to an existing DEK to query or to destroy.

   attr
              DEK attributes to be populated when querying a DEK.

              struct mlx5dv_dek_attr {
                  enum mlx5dv_dek_state state;
                  char opaque[8];
                  uint64_t comp_mask;
              };

       state  The state of the DEK, can be one of the following

              MLX5DV_DEK_STATE_READY
                     The  key  is  ready  for use.  This is the state of the key when it is first
                     created.

              MLX5DV_DEK_STATE_ERROR
                     The key is unusable.  The key needs to be destroyed and re-created in  order
                     to be used.  This can happen, for example, due to DEK memory corruption.

       opaque Plaintext metadata to describe the key.

       comp_mask
              Reserved for future extension, must be 0 now.

RETURN VALUE

       mlx5dv_dek_create()  returns  a  pointer  to a new struct mlx5dv_dek on success.  On error
       NULL is returned and errno is set.

       mlx5dv_dek_query() returns 0 on success and updates attr with the queried DEK  attributes.
       On error errno value is returned.

       mlx5dv_dek_destroy() returns 0 on success and errno value on error.

SEE ALSO

       mlx5dv_crypto_login(3), mlx5dv_crypto_login_create(3), mlx5dv_query_device(3)

AUTHORS

       Avihai Horon <avihaih@nvidia.com>

                                     mlx5dv_dek_create / mlx5dv_dek_query / mlx5dv_dek_destroy(3)