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