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