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 */ 380