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 */ 46enum 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 */ 56enum 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) */ 78struct pkey_apqn { 79 __u16 card; 80 __u16 domain; 81}; 82 83/* Struct to hold a CCA AES secure key blob */ 84struct pkey_seckey { 85 __u8 seckey[SECKEYBLOBSIZE]; /* the secure key blob */ 86}; 87 88/* Struct to hold protected key and length info */ 89struct 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 */ 96struct 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 */ 104struct 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 */ 117struct 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 */ 128struct 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 */ 140struct 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 */ 151struct 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 */ 162struct 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 */ 172struct 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 */ 186struct 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 */ 200struct 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 */ 210struct 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 */ 219struct 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 */ 246struct 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 */ 279struct 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 */ 318struct 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 */ 342struct 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 */ 377struct 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 */ 415struct 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 */ 441struct 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