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, 2019
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
29 /* Minimum and maximum size of a key blob */
30 #define MINKEYBLOBSIZE SECKEYBLOBSIZE
31 #define MAXKEYBLOBSIZE MAXAESCIPHERKEYSIZE
32
33 /* defines for the type field within the pkey_protkey struct */
34 #define PKEY_KEYTYPE_AES_128 1
35 #define PKEY_KEYTYPE_AES_192 2
36 #define PKEY_KEYTYPE_AES_256 3
37
38 /* the newer ioctls use a pkey_key_type enum for type information */
39 enum pkey_key_type {
40 PKEY_TYPE_CCA_DATA = (__u32) 1,
41 PKEY_TYPE_CCA_CIPHER = (__u32) 2,
42 };
43
44 /* the newer ioctls use a pkey_key_size enum for key size information */
45 enum pkey_key_size {
46 PKEY_SIZE_AES_128 = (__u32) 128,
47 PKEY_SIZE_AES_192 = (__u32) 192,
48 PKEY_SIZE_AES_256 = (__u32) 256,
49 PKEY_SIZE_UNKNOWN = (__u32) 0xFFFFFFFF,
50 };
51
52 /* some of the newer ioctls use these flags */
53 #define PKEY_FLAGS_MATCH_CUR_MKVP 0x00000002
54 #define PKEY_FLAGS_MATCH_ALT_MKVP 0x00000004
55
56 /* keygenflags defines for CCA AES cipher keys */
57 #define PKEY_KEYGEN_XPRT_SYM 0x00008000
58 #define PKEY_KEYGEN_XPRT_UASY 0x00004000
59 #define PKEY_KEYGEN_XPRT_AASY 0x00002000
60 #define PKEY_KEYGEN_XPRT_RAW 0x00001000
61 #define PKEY_KEYGEN_XPRT_CPAC 0x00000800
62 #define PKEY_KEYGEN_XPRT_DES 0x00000080
63 #define PKEY_KEYGEN_XPRT_AES 0x00000040
64 #define PKEY_KEYGEN_XPRT_RSA 0x00000008
65
66 /* Struct to hold apqn target info (card/domain pair) */
67 struct pkey_apqn {
68 __u16 card;
69 __u16 domain;
70 };
71
72 /* Struct to hold a CCA AES secure key blob */
73 struct pkey_seckey {
74 __u8 seckey[SECKEYBLOBSIZE]; /* the secure key blob */
75 };
76
77 /* Struct to hold protected key and length info */
78 struct pkey_protkey {
79 __u32 type; /* key type, one of the PKEY_KEYTYPE_AES values */
80 __u32 len; /* bytes actually stored in protkey[] */
81 __u8 protkey[MAXPROTKEYSIZE]; /* the protected key blob */
82 };
83
84 /* Struct to hold an AES clear key value */
85 struct pkey_clrkey {
86 __u8 clrkey[MAXCLRKEYSIZE]; /* 16, 24, or 32 byte clear key value */
87 };
88
89 /*
90 * Generate CCA AES secure key.
91 */
92 struct pkey_genseck {
93 __u16 cardnr; /* in: card to use or FFFF for any */
94 __u16 domain; /* in: domain or FFFF for any */
95 __u32 keytype; /* in: key type to generate */
96 struct pkey_seckey seckey; /* out: the secure key blob */
97 };
98 #define PKEY_GENSECK _IOWR(PKEY_IOCTL_MAGIC, 0x01, struct pkey_genseck)
99
100 /*
101 * Construct CCA AES secure key from clear key value
102 */
103 struct pkey_clr2seck {
104 __u16 cardnr; /* in: card to use or FFFF for any */
105 __u16 domain; /* in: domain or FFFF for any */
106 __u32 keytype; /* in: key type to generate */
107 struct pkey_clrkey clrkey; /* in: the clear key value */
108 struct pkey_seckey seckey; /* out: the secure key blob */
109 };
110 #define PKEY_CLR2SECK _IOWR(PKEY_IOCTL_MAGIC, 0x02, struct pkey_clr2seck)
111
112 /*
113 * Fabricate AES protected key from a CCA AES secure key
114 */
115 struct pkey_sec2protk {
116 __u16 cardnr; /* in: card to use or FFFF for any */
117 __u16 domain; /* in: domain or FFFF for any */
118 struct pkey_seckey seckey; /* in: the secure key blob */
119 struct pkey_protkey protkey; /* out: the protected key */
120 };
121 #define PKEY_SEC2PROTK _IOWR(PKEY_IOCTL_MAGIC, 0x03, struct pkey_sec2protk)
122
123 /*
124 * Fabricate AES protected key from clear key value
125 */
126 struct pkey_clr2protk {
127 __u32 keytype; /* in: key type to generate */
128 struct pkey_clrkey clrkey; /* in: the clear key value */
129 struct pkey_protkey protkey; /* out: the protected key */
130 };
131 #define PKEY_CLR2PROTK _IOWR(PKEY_IOCTL_MAGIC, 0x04, struct pkey_clr2protk)
132
133 /*
134 * Search for matching crypto card based on the Master Key
135 * Verification Pattern provided inside a CCA AES secure key.
136 */
137 struct pkey_findcard {
138 struct pkey_seckey seckey; /* in: the secure key blob */
139 __u16 cardnr; /* out: card number */
140 __u16 domain; /* out: domain number */
141 };
142 #define PKEY_FINDCARD _IOWR(PKEY_IOCTL_MAGIC, 0x05, struct pkey_findcard)
143
144 /*
145 * Combined together: findcard + sec2prot
146 */
147 struct pkey_skey2pkey {
148 struct pkey_seckey seckey; /* in: the secure key blob */
149 struct pkey_protkey protkey; /* out: the protected key */
150 };
151 #define PKEY_SKEY2PKEY _IOWR(PKEY_IOCTL_MAGIC, 0x06, struct pkey_skey2pkey)
152
153 /*
154 * Verify the given CCA AES secure key for being able to be useable with
155 * the pkey module. Check for correct key type and check for having at
156 * least one crypto card being able to handle this key (master key
157 * or old master key verification pattern matches).
158 * Return some info about the key: keysize in bits, keytype (currently
159 * only AES), flag if key is wrapped with an old MKVP.
160 */
161 struct pkey_verifykey {
162 struct pkey_seckey seckey; /* in: the secure key blob */
163 __u16 cardnr; /* out: card number */
164 __u16 domain; /* out: domain number */
165 __u16 keysize; /* out: key size in bits */
166 __u32 attributes; /* out: attribute bits */
167 };
168 #define PKEY_VERIFYKEY _IOWR(PKEY_IOCTL_MAGIC, 0x07, struct pkey_verifykey)
169 #define PKEY_VERIFY_ATTR_AES 0x00000001 /* key is an AES key */
170 #define PKEY_VERIFY_ATTR_OLD_MKVP 0x00000100 /* key has old MKVP value */
171
172 /*
173 * Generate AES random protected key.
174 */
175 struct pkey_genprotk {
176 __u32 keytype; /* in: key type to generate */
177 struct pkey_protkey protkey; /* out: the protected key */
178 };
179
180 #define PKEY_GENPROTK _IOWR(PKEY_IOCTL_MAGIC, 0x08, struct pkey_genprotk)
181
182 /*
183 * Verify an AES protected key.
184 */
185 struct pkey_verifyprotk {
186 struct pkey_protkey protkey; /* in: the protected key to verify */
187 };
188
189 #define PKEY_VERIFYPROTK _IOW(PKEY_IOCTL_MAGIC, 0x09, struct pkey_verifyprotk)
190
191 /*
192 * Transform an key blob (of any type) into a protected key
193 */
194 struct pkey_kblob2pkey {
195 __u8 __user *key; /* in: the key blob */
196 __u32 keylen; /* in: the key blob length */
197 struct pkey_protkey protkey; /* out: the protected key */
198 };
199 #define PKEY_KBLOB2PROTK _IOWR(PKEY_IOCTL_MAGIC, 0x0A, struct pkey_kblob2pkey)
200
201 /*
202 * Generate secure key, version 2.
203 * Generate either a CCA AES secure key or a CCA AES cipher key.
204 * There needs to be a list of apqns given with at least one entry in there.
205 * All apqns in the list need to be exact apqns, 0xFFFF as ANY card or domain
206 * is not supported. The implementation walks through the list of apqns and
207 * tries to send the request to each apqn without any further checking (like
208 * card type or online state). If the apqn fails, simple the next one in the
209 * list is tried until success (return 0) or the end of the list is reached
210 * (return -1 with errno ENODEV). You may use the PKEY_APQNS4KT ioctl to
211 * generate a list of apqns based on the key type to generate.
212 * The keygenflags argument is passed to the low level generation functions
213 * individual for the key type and has a key type specific meaning. Currently
214 * only CCA AES cipher keys react to this parameter: Use one or more of the
215 * PKEY_KEYGEN_* flags to widen the export possibilities. By default a cipher
216 * key is only exportable for CPACF (PKEY_KEYGEN_XPRT_CPAC).
217 */
218 struct pkey_genseck2 {
219 struct pkey_apqn __user *apqns; /* in: ptr to list of apqn targets*/
220 __u32 apqn_entries; /* in: # of apqn target list entries */
221 enum pkey_key_type type; /* in: key type to generate */
222 enum pkey_key_size size; /* in: key size to generate */
223 __u32 keygenflags; /* in: key generation flags */
224 __u8 __user *key; /* in: pointer to key blob buffer */
225 __u32 keylen; /* in: available key blob buffer size */
226 /* out: actual key blob size */
227 };
228 #define PKEY_GENSECK2 _IOWR(PKEY_IOCTL_MAGIC, 0x11, struct pkey_genseck2)
229
230 /*
231 * Generate secure key from clear key value, version 2.
232 * Construct a CCA AES secure key or CCA AES cipher key from a given clear key
233 * value.
234 * There needs to be a list of apqns given with at least one entry in there.
235 * All apqns in the list need to be exact apqns, 0xFFFF as ANY card or domain
236 * is not supported. The implementation walks through the list of apqns and
237 * tries to send the request to each apqn without any further checking (like
238 * card type or online state). If the apqn fails, simple the next one in the
239 * list is tried until success (return 0) or the end of the list is reached
240 * (return -1 with errno ENODEV). You may use the PKEY_APQNS4KT ioctl to
241 * generate a list of apqns based on the key type to generate.
242 * The keygenflags argument is passed to the low level generation functions
243 * individual for the key type and has a key type specific meaning. Currently
244 * only CCA AES cipher keys react to this parameter: Use one or more of the
245 * PKEY_KEYGEN_* flags to widen the export possibilities. By default a cipher
246 * key is only exportable for CPACF (PKEY_KEYGEN_XPRT_CPAC).
247 */
248 struct pkey_clr2seck2 {
249 struct pkey_apqn __user *apqns; /* in: ptr to list of apqn targets */
250 __u32 apqn_entries; /* in: # of apqn target list entries */
251 enum pkey_key_type type; /* in: key type to generate */
252 enum pkey_key_size size; /* in: key size to generate */
253 __u32 keygenflags; /* in: key generation flags */
254 struct pkey_clrkey clrkey; /* in: the clear key value */
255 __u8 __user *key; /* in: pointer to key blob buffer */
256 __u32 keylen; /* in: available key blob buffer size */
257 /* out: actual key blob size */
258 };
259 #define PKEY_CLR2SECK2 _IOWR(PKEY_IOCTL_MAGIC, 0x12, struct pkey_clr2seck2)
260
261 /*
262 * Verify the given secure key, version 2.
263 * Check for correct key type. If cardnr and domain are given (are not
264 * 0xFFFF) also check if this apqn is able to handle this type of key.
265 * If cardnr and/or domain is 0xFFFF, on return these values are filled
266 * with one apqn able to handle this key.
267 * The function also checks for the master key verification patterns
268 * of the key matching to the current or alternate mkvp of the apqn.
269 * Currently CCA AES secure keys and CCA AES cipher keys are supported.
270 * The flags field is updated with some additional info about the apqn mkvp
271 * match: If the current mkvp matches to the key's mkvp then the
272 * PKEY_FLAGS_MATCH_CUR_MKVP bit is set, if the alternate mkvp matches to
273 * the key's mkvp the PKEY_FLAGS_MATCH_ALT_MKVP is set. For CCA keys the
274 * alternate mkvp is the old master key verification pattern.
275 * CCA AES secure keys are also checked to have the CPACF export allowed
276 * bit enabled (XPRTCPAC) in the kmf1 field.
277 * The ioctl returns 0 as long as the given or found apqn matches to
278 * matches with the current or alternate mkvp to the key's mkvp. If the given
279 * apqn does not match or there is no such apqn found, -1 with errno
280 * ENODEV is returned.
281 */
282 struct pkey_verifykey2 {
283 __u8 __user *key; /* in: pointer to key blob */
284 __u32 keylen; /* in: key blob size */
285 __u16 cardnr; /* in/out: card number */
286 __u16 domain; /* in/out: domain number */
287 enum pkey_key_type type; /* out: the key type */
288 enum pkey_key_size size; /* out: the key size */
289 __u32 flags; /* out: additional key info flags */
290 };
291 #define PKEY_VERIFYKEY2 _IOWR(PKEY_IOCTL_MAGIC, 0x17, struct pkey_verifykey2)
292
293 /*
294 * Transform a key blob (of any type) into a protected key, version 2.
295 * There needs to be a list of apqns given with at least one entry in there.
296 * All apqns in the list need to be exact apqns, 0xFFFF as ANY card or domain
297 * is not supported. The implementation walks through the list of apqns and
298 * tries to send the request to each apqn without any further checking (like
299 * card type or online state). If the apqn fails, simple the next one in the
300 * list is tried until success (return 0) or the end of the list is reached
301 * (return -1 with errno ENODEV). You may use the PKEY_APQNS4K ioctl to
302 * generate a list of apqns based on the key.
303 */
304 struct pkey_kblob2pkey2 {
305 __u8 __user *key; /* in: pointer to key blob */
306 __u32 keylen; /* in: key blob size */
307 struct pkey_apqn __user *apqns; /* in: ptr to list of apqn targets */
308 __u32 apqn_entries; /* in: # of apqn target list entries */
309 struct pkey_protkey protkey; /* out: the protected key */
310 };
311 #define PKEY_KBLOB2PROTK2 _IOWR(PKEY_IOCTL_MAGIC, 0x1A, struct pkey_kblob2pkey2)
312
313 /*
314 * Build a list of APQNs based on a key blob given.
315 * Is able to find out which type of secure key is given (CCA AES secure
316 * key or CCA AES cipher key) and tries to find all matching crypto cards
317 * based on the MKVP and maybe other criterias (like CCA AES cipher keys
318 * need a CEX5C or higher). The list of APQNs is further filtered by the key's
319 * mkvp which needs to match to either the current mkvp or the alternate mkvp
320 * (which is the old mkvp on CCA adapters) of the apqns. The flags argument may
321 * be used to limit the matching apqns. If the PKEY_FLAGS_MATCH_CUR_MKVP is
322 * given, only the current mkvp of each apqn is compared. Likewise with the
323 * PKEY_FLAGS_MATCH_ALT_MKVP. If both are given, it is assumed to
324 * return apqns where either the current or the alternate mkvp
325 * matches. At least one of the matching flags needs to be given.
326 * The list of matching apqns is stored into the space given by the apqns
327 * argument and the number of stored entries goes into apqn_entries. If the list
328 * is empty (apqn_entries is 0) the apqn_entries field is updated to the number
329 * of apqn targets found and the ioctl returns with 0. If apqn_entries is > 0
330 * but the number of apqn targets does not fit into the list, the apqn_targets
331 * field is updatedd with the number of reqired entries but there are no apqn
332 * values stored in the list and the ioctl returns with ENOSPC. If no matching
333 * APQN is found, the ioctl returns with 0 but the apqn_entries value is 0.
334 */
335 struct pkey_apqns4key {
336 __u8 __user *key; /* in: pointer to key blob */
337 __u32 keylen; /* in: key blob size */
338 __u32 flags; /* in: match controlling flags */
339 struct pkey_apqn __user *apqns; /* in/out: ptr to list of apqn targets*/
340 __u32 apqn_entries; /* in: max # of apqn entries in the list */
341 /* out: # apqns stored into the list */
342 };
343 #define PKEY_APQNS4K _IOWR(PKEY_IOCTL_MAGIC, 0x1B, struct pkey_apqns4key)
344
345 /*
346 * Build a list of APQNs based on a key type given.
347 * Build a list of APQNs based on a given key type and maybe further
348 * restrict the list by given master key verification patterns.
349 * For different key types there may be different ways to match the
350 * master key verification patterns. For CCA keys (CCA data key and CCA
351 * cipher key) the first 8 bytes of cur_mkvp refer to the current mkvp value
352 * of the apqn and the first 8 bytes of the alt_mkvp refer to the old mkvp.
353 * The flags argument controls if the apqns current and/or alternate mkvp
354 * should match. If the PKEY_FLAGS_MATCH_CUR_MKVP is given, only the current
355 * mkvp of each apqn is compared. Likewise with the PKEY_FLAGS_MATCH_ALT_MKVP.
356 * If both are given, it is assumed to return apqns where either the
357 * current or the alternate mkvp matches. If no match flag is given
358 * (flags is 0) the mkvp values are ignored for the match process.
359 * The list of matching apqns is stored into the space given by the apqns
360 * argument and the number of stored entries goes into apqn_entries. If the list
361 * is empty (apqn_entries is 0) the apqn_entries field is updated to the number
362 * of apqn targets found and the ioctl returns with 0. If apqn_entries is > 0
363 * but the number of apqn targets does not fit into the list, the apqn_targets
364 * field is updatedd with the number of reqired entries but there are no apqn
365 * values stored in the list and the ioctl returns with ENOSPC. If no matching
366 * APQN is found, the ioctl returns with 0 but the apqn_entries value is 0.
367 */
368 struct pkey_apqns4keytype {
369 enum pkey_key_type type; /* in: key type */
370 __u8 cur_mkvp[32]; /* in: current mkvp */
371 __u8 alt_mkvp[32]; /* in: alternate mkvp */
372 __u32 flags; /* in: match controlling flags */
373 struct pkey_apqn __user *apqns; /* in/out: ptr to list of apqn targets*/
374 __u32 apqn_entries; /* in: max # of apqn entries in the list */
375 /* out: # apqns stored into the list */
376 };
377 #define PKEY_APQNS4KT _IOWR(PKEY_IOCTL_MAGIC, 0x1C, struct pkey_apqns4keytype)
378
379 #endif /* _UAPI_PKEY_H */