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