1mlx5dv_dek_create /mlmxl5xd5vd_vd_edke_kc_rqeuaetrey//mmllxx55ddvv__ddeekk__qdueesrtyro/y(m3l)x5dv_dek_destroy(3)
2
6 mlx5dv_dek_create - Creates a DEK
7 mlx5dv_dek_query - Queries a DEK’s attributes
9 mlx5dv_dek_destroy - Destroys a DEK
11
13 #include <infiniband/mlx5dv.h>
14 struct mlx5dv_dek *mlx5dv_dek_create(struct ibv_context *context,
16 struct mlx5dv_dek_init_attr *init_attr);
17 int mlx5dv_dek_query(struct mlx5dv_dek *dek, struct mlx5dv_dek_attr *attr);
19 int mlx5dv_dek_destroy(struct mlx5dv_dek *dek);
21
23 Data Encryption Keys (DEKs) are used to encrypt and decrypt transmitted
24 data. After a DEK is created, it can be configured in MKeys for crypto
25 offload operations. DEKs are not persistent and are destroyed upon
26 process exit. Therefore, software process needs to re-create all need‐
27 ed DEKs on startup.
28 mlx5dv_dek_create() creates a new DEK with the attributes specified in
30 init_attr. A pointer to the newly created dek is returned, which can
31 be used for DEK query, DEK destruction and when configuring a MKey for
32 crypto offload operations.
33 The DEK can be either wrapped or in plaintext and the format that
35 should be used is determined by the specified crypto_login object.
36 To create a wrapped DEK, the application must have a valid crypto login
38 object prior to creating the DEK. Creating a wrapped DEK can be per‐
39 formed in two ways: 1. Call mlx5dv_crypto_login_create() to obtain a
40 crypto login object. Indicate that the DEK is wrapped by setting
41 MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN value in comp_mask and passing the
42 crypto login object in crypto_login field of init_attr. Fill the other
43 DEK attributes and create the DEK.
44 2. Call mlx5dv_crypto_login() i.e., the old API. Supply credential,
46 import_kek_id
47 To create a plaintext DEK, the application must indicate that the DEK
49 is in plaintext by setting MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN value in
50 comp_mask and passing NULL value in crypto_login field of init_attr,
51 fill the other DEK attributes and create the DEK.
52 To use the created DEK (either wrapped or plaintext) in a MKey, a valid
54 crypto login object or session is not needed. Revoking the import KEK
55 or credential that were used for the crypto login object or session
56 (and therefore rendering the crypto login invalid) does not prevent us‐
57 ing a created DEK.
58 mlx5dv_dek_query() queries the DEK specified by dek and returns the
60 queried attributes in attr. A valid crypto login object or session is
61 not required to query a plaintext DEK. On the other hand, to query a
62 wrapped DEK a valid crypto login object or session must be present.
63 mlx5dv_dek_destroy() destroys the DEK specified by dek.
65
67 context
68 The device context to create the DEK with.
69 init_attr
71 enum mlx5dv_dek_init_attr_mask {
72 MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN = 1 << 0,
73 };
74 struct mlx5dv_dek_init_attr {
76 enum mlx5dv_crypto_key_size key_size;
77 bool has_keytag;
78 enum mlx5dv_crypto_key_purpose key_purpose;
79 struct ibv_pd *pd;
80 char opaque[8];
81 char key[128];
82 uint64_t comp_mask; /* Use enum mlx5dv_dek_init_attr_mask */
83 struct mlx5dv_crypto_login_obj *crypto_login;
84 };
85 key_size
87 The size of the key, can be one of the following
88 MLX5DV_CRYPTO_KEY_SIZE_128
90 Key size is 128 bit.
91 MLX5DV_CRYPTO_KEY_SIZE_256
93 Key size is 256 bit.
94 has_keytag
96 Whether the DEK has a keytag or not. If set, the key should in‐
97 clude a 8 Bytes keytag. Keytag is used to verify that the DEK
98 being used by a MKey is the expected DEK. This is done by com‐
99 paring the keytag that was defined during DEK creation with the
100 keytag provided in the MKey crypto configuration, and failing
101 the operation if they are different.
102 key_purpose
104 The purpose of the key, currently can only be the following val‐
105 ue
106 MLX5DV_CRYPTO_KEY_PURPOSE_AES_XTS
108 The key will be used for AES-XTS crypto engine.
109 pd The protection domain to be associated with the DEK.
111 opaque Plaintext metadata to describe the key.
113 key The key that will be used for encryption and decryption of
115 transmitted data. For plaintext DEK key must be provided in
116 plaintext. For wrapped DEK key must be provided wrapped by the
117 import KEK that was specified in the crypto login. Actual size
118 and layout of this field depend on the provided key_size and
119 has_keytag fields, as well as on the format of the key (plain‐
120 text or wrapped). key should be constructed according to the
121 following table.
122 DEK key Field Construction.
124 Import Method Has Keytag Key size Key Layout
126 ─────────────────────────────────────────────────────────
127 Plaintext No 128 Bit key1_128b +
128 key2_128b
129 Plaintext No 256 Bit key1_256b +
131 key2_256b
132 Plaintext Yes 128 Bit key1_128b +
134 key2_128b + key‐
135 tag_64b
136 Plaintext Yes 256 Bit key1_256b +
140 key2_256b + key‐
141 tag_64b
142 Wrapped No 128 Bit ENC(iv_64b +
144 key1_128b +
145 key2_128b)
146 Wrapped No 256 Bit ENC(iv_64b +
148 key1_256b +
149 key2_256b)
150 Wrapped Yes 128 Bit ENC(iv_64b +
152 key1_128b +
153 key2_128b + key‐
154 tag_64b)
155 Wrapped Yes 256 Bit ENC(iv_64b +
157 key1_256b +
158 key2_256b + key‐
159 tag_64b)
160 Where ENC() is AES key wrap algorithm and iv_64b is
162 0xA6A6A6A6A6A6A6A6 as per the NIST SP 800-38F AES key wrap spec.
163 The following example shows how to wrap a 128 bit key that has
165 keytag using a 128 bit import KEK in OpenSSL:
166 #include <openssl/evp.h>
168 unsigned char import_kek[16]; /* 128 bit import KEK in plaintext for wrapping */
170 unsigned char iv[8] = {0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6};
171 /*
173 * Indexes 0-15 are key1 in plaintext, indexes 16-31 are key2 in plaintext,
174 * and indexes 32-39 are key_tag in plaintext.
175 */
176 unsigned char key[40];
177 unsigned char wrapped_key[48];
179 EVP_CIPHER_CTX *ctx;
180 int len;
181 ctx = EVP_CIPHER_CTX_new();
183 EVP_CIPHER_CTX_set_flags(ctx, EVP_CIPHER_CTX_FLAG_WRAP_ALLOW);
184 EVP_EncryptInit_ex(ctx, EVP_aes_128_wrap(), NULL, import_kek, iv);
185 EVP_EncryptUpdate(ctx, wrapped_key, &len, key, sizeof(key));
186 EVP_EncryptFinal_ex(ctx, wrapped_key + len, &len);
187 EVP_CIPHER_CTX_free(ctx);
188 comp_mask
190 Currently can be the following value:
191 MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN, which indicates that cryp‐
193 to_login field is applicable.
194 crypto_login
196 Pointer to a crypto login object. If set to a valid crypto lo‐
197 gin object, indicates that this is a wrapped DEK that will be
198 created using the given crypto login object. If set to NULL,
199 indicates that this is a plaintext DEK. Must be NULL if
200 MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN is not set. Only relevant
201 when comp_mask is set with MLX5DV_DEK_INIT_ATTR_CRYPTO_LOGIN
202 dek
204 Pointer to an existing DEK to query or to destroy.
205 attr
207 DEK attributes to be populated when querying a DEK.
208 struct mlx5dv_dek_attr {
210 enum mlx5dv_dek_state state;
211 char opaque[8];
212 uint64_t comp_mask;
213 };
214 state The state of the DEK, can be one of the following
216 MLX5DV_DEK_STATE_READY
218 The key is ready for use. This is the state of the key
219 when it is first created.
220 MLX5DV_DEK_STATE_ERROR
222 The key is unusable. The key needs to be destroyed and
223 re-created in order to be used. This can happen, for ex‐
224 ample, due to DEK memory corruption.
225 opaque Plaintext metadata to describe the key.
227 comp_mask
229 Reserved for future extension, must be 0 now.
230
232 mlx5dv_dek_create() returns a pointer to a new struct mlx5dv_dek on
233 success. On error NULL is returned and errno is set.
234 mlx5dv_dek_query() returns 0 on success and updates attr with the
236 queried DEK attributes. On error errno value is returned.
237 mlx5dv_dek_destroy() returns 0 on success and errno value on error.
239
241 mlx5dv_crypto_login(3), mlx5dv_crypto_login_create(3), mlx5dv_query_de‐
242 vice(3)
243
245 Avihai Horon <avihaih@nvidia.com>
246 mlx5dv_dek_create / mlx5dv_dek_query / mlx5dv_dek_destroy(3)