1 /* SPDX-License-Identifier: GPL-2.0 WITH Linux-syscall-note */
2 /*
3 * Userspace interface to the pkey device driver
4 *
5 * Copyright IBM Corp. 2017, 2023
6 *
7 * Author: Harald Freudenberger <freude@de.ibm.com>
8 *
9 */
10
11 #ifndef _UAPI_PKEY_H
12 #define _UAPI_PKEY_H
13
14 #include <linux/ioctl.h>
15 #include <linux/types.h>
16
17 /*
18 * Ioctl calls supported by the pkey device driver
19 */
20
21 #define PKEY_IOCTL_MAGIC 'p'
22
23 #define SECKEYBLOBSIZE 64 /* secure key blob size is always 64 bytes */
24 #define PROTKEYBLOBSIZE 80 /* protected key blob size is always 80 bytes */
25 #define MAXPROTKEYSIZE 64 /* a protected key blob may be up to 64 bytes */
26 #define MAXCLRKEYSIZE 32 /* a clear key value may be up to 32 bytes */
27 #define MAXAESCIPHERKEYSIZE 136 /* our aes cipher keys have always 136 bytes */
28 #define MINEP11AESKEYBLOBSIZE 256 /* min EP11 AES key blob size */
29 #define MAXEP11AESKEYBLOBSIZE 336 /* max EP11 AES key blob size */
30
31 /* Minimum size of a key blob */
32 #define MINKEYBLOBSIZE SECKEYBLOBSIZE
33
34 /* defines for the type field within the pkey_protkey struct */
35 #define PKEY_KEYTYPE_AES_128 1
36 #define PKEY_KEYTYPE_AES_192 2
37 #define PKEY_KEYTYPE_AES_256 3
38 #define PKEY_KEYTYPE_ECC 4
39 #define PKEY_KEYTYPE_ECC_P256 5
40 #define PKEY_KEYTYPE_ECC_P384 6
41 #define PKEY_KEYTYPE_ECC_P521 7
42 #define PKEY_KEYTYPE_ECC_ED25519 8
43 #define PKEY_KEYTYPE_ECC_ED448 9
44
45 /* the newer ioctls use a pkey_key_type enum for type information */
46 enum pkey_key_type {
47 PKEY_TYPE_CCA_DATA = (__u32) 1,
48 PKEY_TYPE_CCA_CIPHER = (__u32) 2,
49 PKEY_TYPE_EP11 = (__u32) 3,
50 PKEY_TYPE_CCA_ECC = (__u32) 0x1f,
51 PKEY_TYPE_EP11_AES = (__u32) 6,
52 PKEY_TYPE_EP11_ECC = (__u32) 7,
53 };
54
55 /* the newer ioctls use a pkey_key_size enum for key size information */
56 enum pkey_key_size {
57 PKEY_SIZE_AES_128 = (__u32) 128,
58 PKEY_SIZE_AES_192 = (__u32) 192,
59 PKEY_SIZE_AES_256 = (__u32) 256,
60 PKEY_SIZE_UNKNOWN = (__u32) 0xFFFFFFFF,
61 };
62
63 /* some of the newer ioctls use these flags */
64 #define PKEY_FLAGS_MATCH_CUR_MKVP 0x00000002
65 #define PKEY_FLAGS_MATCH_ALT_MKVP 0x00000004
66
67 /* keygenflags defines for CCA AES cipher keys */
68 #define PKEY_KEYGEN_XPRT_SYM 0x00008000
69 #define PKEY_KEYGEN_XPRT_UASY 0x00004000
70 #define PKEY_KEYGEN_XPRT_AASY 0x00002000
71 #define PKEY_KEYGEN_XPRT_RAW 0x00001000
72 #define PKEY_KEYGEN_XPRT_CPAC 0x00000800
73 #define PKEY_KEYGEN_XPRT_DES 0x00000080
74 #define PKEY_KEYGEN_XPRT_AES 0x00000040
75 #define PKEY_KEYGEN_XPRT_RSA 0x00000008
76
77 /* Struct to hold apqn target info (card/domain pair) */
78 struct pkey_apqn {
79 __u16 card;
80 __u16 domain;
81 };
82
83 /* Struct to hold a CCA AES secure key blob */
84 struct pkey_seckey {
85 __u8 seckey[SECKEYBLOBSIZE]; /* the secure key blob */
86 };
87
88 /* Struct to hold protected key and length info */
89 struct pkey_protkey {
90 __u32 type; /* key type, one of the PKEY_KEYTYPE_AES values */
91 __u32 len; /* bytes actually stored in protkey[] */
92 __u8 protkey[MAXPROTKEYSIZE]; /* the protected key blob */
93 };
94
95 /* Struct to hold an AES clear key value */
96 struct pkey_clrkey {
97 __u8 clrkey[MAXCLRKEYSIZE]; /* 16, 24, or 32 byte clear key value */
98 };
99
100 /*
101 * EP11 key blobs of type PKEY_TYPE_EP11_AES and PKEY_TYPE_EP11_ECC
102 * are ep11 blobs prepended by this header:
103 */
104 struct ep11kblob_header {
105 __u8 type; /* always 0x00 */
106 __u8 hver; /* header version, currently needs to be 0x00 */
107 __u16 len; /* total length in bytes (including this header) */
108 __u8 version; /* PKEY_TYPE_EP11_AES or PKEY_TYPE_EP11_ECC */
109 __u8 res0; /* unused */
110 __u16 bitlen; /* clear key bit len, 0 for unknown */
111 __u8 res1[8]; /* unused */
112 } __packed;
113
114 /*
115 * Generate CCA AES secure key.
116 */
117 struct pkey_genseck {
118 __u16 cardnr; /* in: card to use or FFFF for any */
119 __u16 domain; /* in: domain or FFFF for any */
120 __u32 keytype; /* in: key type to generate */
121 struct pkey_seckey seckey; /* out: the secure key blob */
122 };
123 #define PKEY_GENSECK _IOWR(PKEY_IOCTL_MAGIC, 0x01, struct pkey_genseck)
124
125 /*
126 * Construct CCA AES secure key from clear key value
127 */
128 struct pkey_clr2seck {
129 __u16 cardnr; /* in: card to use or FFFF for any */
130 __u16 domain; /* in: domain or FFFF for any */
131 __u32 keytype; /* in: key type to generate */
132 struct pkey_clrkey clrkey; /* in: the clear key value */
133 struct pkey_seckey seckey; /* out: the secure key blob */
134 };
135 #define PKEY_CLR2SECK _IOWR(PKEY_IOCTL_MAGIC, 0x02, struct pkey_clr2seck)
136
137 /*
138 * Fabricate AES protected key from a CCA AES secure key
139 */
140 struct pkey_sec2protk {
141 __u16 cardnr; /* in: card to use or FFFF for any */
142 __u16 domain; /* in: domain or FFFF for any */
143 struct pkey_seckey seckey; /* in: the secure key blob */
144 struct pkey_protkey protkey; /* out: the protected key */
145 };
146 #define PKEY_SEC2PROTK _IOWR(PKEY_IOCTL_MAGIC, 0x03, struct pkey_sec2protk)
147
148 /*
149 * Fabricate AES protected key from clear key value
150 */
151 struct pkey_clr2protk {
152 __u32 keytype; /* in: key type to generate */
153 struct pkey_clrkey clrkey; /* in: the clear key value */
154 struct pkey_protkey protkey; /* out: the protected key */
155 };
156 #define PKEY_CLR2PROTK _IOWR(PKEY_IOCTL_MAGIC, 0x04, struct pkey_clr2protk)
157
158 /*
159 * Search for matching crypto card based on the Master Key
160 * Verification Pattern provided inside a CCA AES secure key.
161 */
162 struct pkey_findcard {
163 struct pkey_seckey seckey; /* in: the secure key blob */
164 __u16 cardnr; /* out: card number */
165 __u16 domain; /* out: domain number */
166 };
167 #define PKEY_FINDCARD _IOWR(PKEY_IOCTL_MAGIC, 0x05, struct pkey_findcard)
168
169 /*
170 * Combined together: findcard + sec2prot
171 */
172 struct pkey_skey2pkey {
173 struct pkey_seckey seckey; /* in: the secure key blob */
174 struct pkey_protkey protkey; /* out: the protected key */
175 };
176 #define PKEY_SKEY2PKEY _IOWR(PKEY_IOCTL_MAGIC, 0x06, struct pkey_skey2pkey)
177
178 /*
179 * Verify the given CCA AES secure key for being able to be usable with
180 * the pkey module. Check for correct key type and check for having at
181 * least one crypto card being able to handle this key (master key
182 * or old master key verification pattern matches).
183 * Return some info about the key: keysize in bits, keytype (currently
184 * only AES), flag if key is wrapped with an old MKVP.
185 */
186 struct pkey_verifykey {
187 struct pkey_seckey seckey; /* in: the secure key blob */
188 __u16 cardnr; /* out: card number */
189 __u16 domain; /* out: domain number */
190 __u16 keysize; /* out: key size in bits */
191 __u32 attributes; /* out: attribute bits */
192 };
193 #define PKEY_VERIFYKEY _IOWR(PKEY_IOCTL_MAGIC, 0x07, struct pkey_verifykey)
194 #define PKEY_VERIFY_ATTR_AES 0x00000001 /* key is an AES key */
195 #define PKEY_VERIFY_ATTR_OLD_MKVP 0x00000100 /* key has old MKVP value */
196
197 /*
198 * Generate AES random protected key.
199 */
200 struct pkey_genprotk {
201 __u32 keytype; /* in: key type to generate */
202 struct pkey_protkey protkey; /* out: the protected key */
203 };
204
205 #define PKEY_GENPROTK _IOWR(PKEY_IOCTL_MAGIC, 0x08, struct pkey_genprotk)
206
207 /*
208 * Verify an AES protected key.
209 */
210 struct pkey_verifyprotk {
211 struct pkey_protkey protkey; /* in: the protected key to verify */
212 };
213
214 #define PKEY_VERIFYPROTK _IOW(PKEY_IOCTL_MAGIC, 0x09, struct pkey_verifyprotk)
215
216 /*
217 * Transform an key blob (of any type) into a protected key
218 */
219 struct pkey_kblob2pkey {
220 __u8 __user *key; /* in: the key blob */
221 __u32 keylen; /* in: the key blob length */
222 struct pkey_protkey protkey; /* out: the protected key */
223 };
224 #define PKEY_KBLOB2PROTK _IOWR(PKEY_IOCTL_MAGIC, 0x0A, struct pkey_kblob2pkey)
225
226 /*
227 * Generate secure key, version 2.
228 * Generate CCA AES secure key, CCA AES cipher key or EP11 AES secure key.
229 * There needs to be a list of apqns given with at least one entry in there.
230 * All apqns in the list need to be exact apqns, 0xFFFF as ANY card or domain
231 * is not supported. The implementation walks through the list of apqns and
232 * tries to send the request to each apqn without any further checking (like
233 * card type or online state). If the apqn fails, simple the next one in the
234 * list is tried until success (return 0) or the end of the list is reached
235 * (return -1 with errno ENODEV). You may use the PKEY_APQNS4KT ioctl to
236 * generate a list of apqns based on the key type to generate.
237 * The keygenflags argument is passed to the low level generation functions
238 * individual for the key type and has a key type specific meaning. When
239 * generating CCA cipher keys you can use one or more of the PKEY_KEYGEN_*
240 * flags to widen the export possibilities. By default a cipher key is
241 * only exportable for CPACF (PKEY_KEYGEN_XPRT_CPAC).
242 * The keygenflag argument for generating an EP11 AES key should either be 0
243 * to use the defaults which are XCP_BLOB_ENCRYPT, XCP_BLOB_DECRYPT and
244 * XCP_BLOB_PROTKEY_EXTRACTABLE or a valid combination of XCP_BLOB_* flags.
245 */
246 struct pkey_genseck2 {
247 struct pkey_apqn __user *apqns; /* in: ptr to list of apqn targets*/
248 __u32 apqn_entries; /* in: # of apqn target list entries */
249 enum pkey_key_type type; /* in: key type to generate */
250 enum pkey_key_size size; /* in: key size to generate */
251 __u32 keygenflags; /* in: key generation flags */
252 __u8 __user *key; /* in: pointer to key blob buffer */
253 __u32 keylen; /* in: available key blob buffer size */
254 /* out: actual key blob size */
255 };
256 #define PKEY_GENSECK2 _IOWR(PKEY_IOCTL_MAGIC, 0x11, struct pkey_genseck2)
257
258 /*
259 * Generate secure key from clear key value, version 2.
260 * Construct an CCA AES secure key, CCA AES cipher key or EP11 AES secure
261 * key from a given clear key value.
262 * There needs to be a list of apqns given with at least one entry in there.
263 * All apqns in the list need to be exact apqns, 0xFFFF as ANY card or domain
264 * is not supported. The implementation walks through the list of apqns and
265 * tries to send the request to each apqn without any further checking (like
266 * card type or online state). If the apqn fails, simple the next one in the
267 * list is tried until success (return 0) or the end of the list is reached
268 * (return -1 with errno ENODEV). You may use the PKEY_APQNS4KT ioctl to
269 * generate a list of apqns based on the key type to generate.
270 * The keygenflags argument is passed to the low level generation functions
271 * individual for the key type and has a key type specific meaning. When
272 * generating CCA cipher keys you can use one or more of the PKEY_KEYGEN_*
273 * flags to widen the export possibilities. By default a cipher key is
274 * only exportable for CPACF (PKEY_KEYGEN_XPRT_CPAC).
275 * The keygenflag argument for generating an EP11 AES key should either be 0
276 * to use the defaults which are XCP_BLOB_ENCRYPT, XCP_BLOB_DECRYPT and
277 * XCP_BLOB_PROTKEY_EXTRACTABLE or a valid combination of XCP_BLOB_* flags.
278 */
279 struct pkey_clr2seck2 {
280 struct pkey_apqn __user *apqns; /* in: ptr to list of apqn targets */
281 __u32 apqn_entries; /* in: # of apqn target list entries */
282 enum pkey_key_type type; /* in: key type to generate */
283 enum pkey_key_size size; /* in: key size to generate */
284 __u32 keygenflags; /* in: key generation flags */
285 struct pkey_clrkey clrkey; /* in: the clear key value */
286 __u8 __user *key; /* in: pointer to key blob buffer */
287 __u32 keylen; /* in: available key blob buffer size */
288 /* out: actual key blob size */
289 };
290 #define PKEY_CLR2SECK2 _IOWR(PKEY_IOCTL_MAGIC, 0x12, struct pkey_clr2seck2)
291
292 /*
293 * Verify the given secure key, version 2.
294 * Check for correct key type. If cardnr and domain are given (are not
295 * 0xFFFF) also check if this apqn is able to handle this type of key.
296 * If cardnr and/or domain is 0xFFFF, on return these values are filled
297 * with one apqn able to handle this key.
298 * The function also checks for the master key verification patterns
299 * of the key matching to the current or alternate mkvp of the apqn.
300 * For CCA AES secure keys and CCA AES cipher keys this means to check
301 * the key's mkvp against the current or old mkvp of the apqns. The flags
302 * field is updated with some additional info about the apqn mkvp
303 * match: If the current mkvp matches to the key's mkvp then the
304 * PKEY_FLAGS_MATCH_CUR_MKVP bit is set, if the alternate mkvp matches to
305 * the key's mkvp the PKEY_FLAGS_MATCH_ALT_MKVP is set. For CCA keys the
306 * alternate mkvp is the old master key verification pattern.
307 * CCA AES secure keys are also checked to have the CPACF export allowed
308 * bit enabled (XPRTCPAC) in the kmf1 field.
309 * EP11 keys are also supported and the wkvp of the key is checked against
310 * the current wkvp of the apqns. There is no alternate for this type of
311 * key and so on a match the flag PKEY_FLAGS_MATCH_CUR_MKVP always is set.
312 * EP11 keys are also checked to have XCP_BLOB_PROTKEY_EXTRACTABLE set.
313 * The ioctl returns 0 as long as the given or found apqn matches to
314 * matches with the current or alternate mkvp to the key's mkvp. If the given
315 * apqn does not match or there is no such apqn found, -1 with errno
316 * ENODEV is returned.
317 */
318 struct pkey_verifykey2 {
319 __u8 __user *key; /* in: pointer to key blob */
320 __u32 keylen; /* in: key blob size */
321 __u16 cardnr; /* in/out: card number */
322 __u16 domain; /* in/out: domain number */
323 enum pkey_key_type type; /* out: the key type */
324 enum pkey_key_size size; /* out: the key size */
325 __u32 flags; /* out: additional key info flags */
326 };
327 #define PKEY_VERIFYKEY2 _IOWR(PKEY_IOCTL_MAGIC, 0x17, struct pkey_verifykey2)
328
329 /*
330 * Transform a key blob into a protected key, version 2.
331 * There needs to be a list of apqns given with at least one entry in there.
332 * All apqns in the list need to be exact apqns, 0xFFFF as ANY card or domain
333 * is not supported. The implementation walks through the list of apqns and
334 * tries to send the request to each apqn without any further checking (like
335 * card type or online state). If the apqn fails, simple the next one in the
336 * list is tried until success (return 0) or the end of the list is reached
337 * (return -1 with errno ENODEV). You may use the PKEY_APQNS4K ioctl to
338 * generate a list of apqns based on the key.
339 * Deriving ECC protected keys from ECC secure keys is not supported with
340 * this ioctl, use PKEY_KBLOB2PROTK3 for this purpose.
341 */
342 struct pkey_kblob2pkey2 {
343 __u8 __user *key; /* in: pointer to key blob */
344 __u32 keylen; /* in: key blob size */
345 struct pkey_apqn __user *apqns; /* in: ptr to list of apqn targets */
346 __u32 apqn_entries; /* in: # of apqn target list entries */
347 struct pkey_protkey protkey; /* out: the protected key */
348 };
349 #define PKEY_KBLOB2PROTK2 _IOWR(PKEY_IOCTL_MAGIC, 0x1A, struct pkey_kblob2pkey2)
350
351 /*
352 * Build a list of APQNs based on a key blob given.
353 * Is able to find out which type of secure key is given (CCA AES secure
354 * key, CCA AES cipher key, CCA ECC private key, EP11 AES key, EP11 ECC private
355 * key) and tries to find all matching crypto cards based on the MKVP and maybe
356 * other criteria (like CCA AES cipher keys need a CEX5C or higher, EP11 keys
357 * with BLOB_PKEY_EXTRACTABLE need a CEX7 and EP11 api version 4). The list of
358 * APQNs is further filtered by the key's mkvp which needs to match to either
359 * the current mkvp (CCA and EP11) or the alternate mkvp (old mkvp, CCA adapters
360 * only) of the apqns. The flags argument may be used to limit the matching
361 * apqns. If the PKEY_FLAGS_MATCH_CUR_MKVP is given, only the current mkvp of
362 * each apqn is compared. Likewise with the PKEY_FLAGS_MATCH_ALT_MKVP. If both
363 * are given, it is assumed to return apqns where either the current or the
364 * alternate mkvp matches. At least one of the matching flags needs to be given.
365 * The flags argument for EP11 keys has no further action and is currently
366 * ignored (but needs to be given as PKEY_FLAGS_MATCH_CUR_MKVP) as there is only
367 * the wkvp from the key to match against the apqn's wkvp.
368 * The list of matching apqns is stored into the space given by the apqns
369 * argument and the number of stored entries goes into apqn_entries. If the list
370 * is empty (apqn_entries is 0) the apqn_entries field is updated to the number
371 * of apqn targets found and the ioctl returns with 0. If apqn_entries is > 0
372 * but the number of apqn targets does not fit into the list, the apqn_targets
373 * field is updated with the number of required entries but there are no apqn
374 * values stored in the list and the ioctl returns with ENOSPC. If no matching
375 * APQN is found, the ioctl returns with 0 but the apqn_entries value is 0.
376 */
377 struct pkey_apqns4key {
378 __u8 __user *key; /* in: pointer to key blob */
379 __u32 keylen; /* in: key blob size */
380 __u32 flags; /* in: match controlling flags */
381 struct pkey_apqn __user *apqns; /* in/out: ptr to list of apqn targets*/
382 __u32 apqn_entries; /* in: max # of apqn entries in the list */
383 /* out: # apqns stored into the list */
384 };
385 #define PKEY_APQNS4K _IOWR(PKEY_IOCTL_MAGIC, 0x1B, struct pkey_apqns4key)
386
387 /*
388 * Build a list of APQNs based on a key type given.
389 * Build a list of APQNs based on a given key type and maybe further
390 * restrict the list by given master key verification patterns.
391 * For different key types there may be different ways to match the
392 * master key verification patterns. For CCA keys (CCA data key and CCA
393 * cipher key) the first 8 bytes of cur_mkvp refer to the current AES mkvp value
394 * of the apqn and the first 8 bytes of the alt_mkvp refer to the old AES mkvp.
395 * For CCA ECC keys it is similar but the match is against the APKA current/old
396 * mkvp. The flags argument controls if the apqns current and/or alternate mkvp
397 * should match. If the PKEY_FLAGS_MATCH_CUR_MKVP is given, only the current
398 * mkvp of each apqn is compared. Likewise with the PKEY_FLAGS_MATCH_ALT_MKVP.
399 * If both are given, it is assumed to return apqns where either the
400 * current or the alternate mkvp matches. If no match flag is given
401 * (flags is 0) the mkvp values are ignored for the match process.
402 * For EP11 keys there is only the current wkvp. So if the apqns should also
403 * match to a given wkvp, then the PKEY_FLAGS_MATCH_CUR_MKVP flag should be
404 * set. The wkvp value is 32 bytes but only the leftmost 16 bytes are compared
405 * against the leftmost 16 byte of the wkvp of the apqn.
406 * The list of matching apqns is stored into the space given by the apqns
407 * argument and the number of stored entries goes into apqn_entries. If the list
408 * is empty (apqn_entries is 0) the apqn_entries field is updated to the number
409 * of apqn targets found and the ioctl returns with 0. If apqn_entries is > 0
410 * but the number of apqn targets does not fit into the list, the apqn_targets
411 * field is updated with the number of required entries but there are no apqn
412 * values stored in the list and the ioctl returns with ENOSPC. If no matching
413 * APQN is found, the ioctl returns with 0 but the apqn_entries value is 0.
414 */
415 struct pkey_apqns4keytype {
416 enum pkey_key_type type; /* in: key type */
417 __u8 cur_mkvp[32]; /* in: current mkvp */
418 __u8 alt_mkvp[32]; /* in: alternate mkvp */
419 __u32 flags; /* in: match controlling flags */
420 struct pkey_apqn __user *apqns; /* in/out: ptr to list of apqn targets*/
421 __u32 apqn_entries; /* in: max # of apqn entries in the list */
422 /* out: # apqns stored into the list */
423 };
424 #define PKEY_APQNS4KT _IOWR(PKEY_IOCTL_MAGIC, 0x1C, struct pkey_apqns4keytype)
425
426 /*
427 * Transform a key blob into a protected key, version 3.
428 * The difference to version 2 of this ioctl is that the protected key
429 * buffer is now explicitly and not within a struct pkey_protkey any more.
430 * So this ioctl is also able to handle EP11 and CCA ECC secure keys and
431 * provide ECC protected keys.
432 * There needs to be a list of apqns given with at least one entry in there.
433 * All apqns in the list need to be exact apqns, 0xFFFF as ANY card or domain
434 * is not supported. The implementation walks through the list of apqns and
435 * tries to send the request to each apqn without any further checking (like
436 * card type or online state). If the apqn fails, simple the next one in the
437 * list is tried until success (return 0) or the end of the list is reached
438 * (return -1 with errno ENODEV). You may use the PKEY_APQNS4K ioctl to
439 * generate a list of apqns based on the key.
440 */
441 struct pkey_kblob2pkey3 {
442 __u8 __user *key; /* in: pointer to key blob */
443 __u32 keylen; /* in: key blob size */
444 struct pkey_apqn __user *apqns; /* in: ptr to list of apqn targets */
445 __u32 apqn_entries; /* in: # of apqn target list entries */
446 __u32 pkeytype; /* out: prot key type (enum pkey_key_type) */
447 __u32 pkeylen; /* in/out: size of pkey buffer/actual len of pkey */
448 __u8 __user *pkey; /* in: pkey blob buffer space ptr */
449 };
450 #define PKEY_KBLOB2PROTK3 _IOWR(PKEY_IOCTL_MAGIC, 0x1D, struct pkey_kblob2pkey3)
451
452 #endif /* _UAPI_PKEY_H */
453
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.