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. An active crypto login session must be
33 present in order to create a DEK.
34 To use the created DEK in a MKey, a valid or active crypto login ses‐
36 sion is not needed. Revoking the import KEK or credential that were
37 used during the login (and therefore rendering the login session in‐
38 valid) does not prevent using a created DEK.
39 mlx5dv_dek_query() queries the DEK specified by dek and returns the
41 queried attributes in attr. An active crypto login session must be
42 present in order to query a DEK.
43 mlx5dv_dek_destroy() destroys the DEK specified by dek.
45
47 context
48 The device context to create the DEK with. context must have an active
49 crypto login session associated with in order to create the DEK.
50 init_attr
52 struct mlx5dv_dek_init_attr {
53 enum mlx5dv_crypto_key_size key_size;
54 bool has_keytag;
55 enum mlx5dv_crypto_key_purpose key_purpose;
56 struct ibv_pd *pd;
57 char opaque[8];
58 char key[128];
59 uint64_t comp_mask;
60 };
61 key_size
63 The size of the key, can be one of the following
64 MLX5DV_CRYPTO_KEY_SIZE_128
66 Key size is 128 bit.
67 MLX5DV_CRYPTO_KEY_SIZE_256
69 Key size is 256 bit.
70 has_keytag
72 Whether the DEK has a keytag or not. If set, the key should in‐
73 clude a 8 Bytes keytag. Keytag is used to verify that the DEK
74 being used by a MKey is the expected DEK. This is done by com‐
75 paring the keytag that was defined during DEK creation with the
76 keytag provided in the MKey crypto configuration, and failing
77 the operation if they are different.
78 key_purpose
80 The purpose of the key, currently can only be the following val‐
81 ue
82 MLX5DV_CRYPTO_KEY_PURPOSE_AES_XTS
84 The key will be used for AES-XTS crypto engine.
85 pd The protection domain to be associated with the DEK.
87 opaque Plaintext metadata to describe the key.
89 key The key that will be used for encryption and decryption of
91 transmitted data. Must be provided wrapped by the import KEK
92 that was specified for the crypto login session. Actual size
93 and layout of this field depend on the provided key_size and
94 has_keytag fields. key should be constructed according to the
95 following table.
96 DEK key Field Construction.
98 Key size Has Keytag Key Layout
100 ────────────────────────────────────────────
101 128 Bit No ENC(iv_64b +
102 key1_128b +
103 key2_128b)
104 256 Bit No ENC(iv_64b +
106 key1_256b +
107 key2_256b)
108 128 Bit Yes ENC(iv_64b +
110 key1_128b +
111 key2_128b +
112 64b_keytag)
113 256 Bit Yes ENC(iv_64b +
115 key1_256b +
116 key2_256b +
117 64b_keytag)
118 Where ENC() is AES key wrap algorithm and iv_64b is
120 0xA6A6A6A6A6A6A6A6 as per the AES key wrap spec.
121 The following example shows how to wrap a 128 bit key that has
123 keytag using a 128 bit import KEK in OpenSSL:
124 unsigned char import_kek[16]; /* 128 bit import KEK in plaintext for wrapping */
126 unsigned char iv[8] = {0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6, 0xA6};
127 /*
129 * Indexes 0-15 are key1 in plaintext, indexes 16-31 are key2 in plaintext,
130 * and indexes 32-39 are key_tag in plaintext.
131 */
132 unsigned char key[40];
133 unsigned char wrapped_key[48];
135 EVP_CIPHER_CTX *ctx;
136 int len;
137 ctx = EVP_CIPHER_CTX_new();
139 EVP_CIPHER_CTX_set_flags(ctx, EVP_CIPHER_CTX_FLAG_WRAP_ALLOW);
140 EVP_EncryptInit_ex(ctx, EVP_aes_128_wrap(), NULL, import_kek, iv);
141 EVP_EncryptUpdate(ctx, wrapped_key, &len, key, sizeof(key));
142 EVP_EncryptFinal_ex(ctx, wrapped_key + len, &len);
143 EVP_CIPHER_CTX_free(ctx);
144 comp_mask
146 Reserved for future extension, must be 0 now.
147 dek
149 Pointer to an existing DEK to query or to destroy.
150 attr
152 DEK attributes to be populated when querying a DEK.
153 struct mlx5dv_dek_attr {
155 enum mlx5dv_dek_state state;
156 char opaque[8];
157 uint64_t comp_mask;
158 };
159 state The state of the DEK, can be one of the following
161 MLX5DV_DEK_STATE_READY
163 The key is ready for use. This is the state of the key
164 when it is first created.
165 MLX5DV_DEK_STATE_ERROR
167 The key is unusable. The key needs to be destroyed and
168 re-created in order to be used. This can happen, for ex‐
169 ample, due to DEK memory corruption.
170 opaque Plaintext metadata to describe the key.
172 comp_mask
174 Reserved for future extension, must be 0 now.
175
177 mlx5dv_dek_create() returns a pointer to a new struct mlx5dv_dek on
178 success. On error NULL is returned and errno is set.
179 mlx5dv_dek_query() returns 0 on success and updates attr with the
181 queried DEK attributes. On error errno value is returned.
182 mlx5dv_dek_destroy() returns 0 on success and errno value on error.
184
186 mlx5dv_crypto_login(3)
187
189 Avihai Horon <avihaih@nvidia.com>
190 mlx5dv_dek_create / mlx5dv_dek_query / mlx5dv_dek_destroy(3)