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