1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* 3 * Kernelspace interface to the pkey device driver 4 * 5 * Copyright IBM Corp. 2016 6 * 7 * Author: Harald Freudenberger <freude@de.ibm.com> 8 * 9 */ 10 11 #ifndef _KAPI_PKEY_H 12 #define _KAPI_PKEY_H 13 14 #include <linux/ioctl.h> 15 #include <linux/types.h> 16 #include <uapi/asm/pkey.h> 17 18 /* 19 * Generate (AES) random secure key. 20 * @param cardnr may be -1 (use default card) 21 * @param domain may be -1 (use default domain) 22 * @param keytype one of the PKEY_KEYTYPE values 23 * @param seckey pointer to buffer receiving the secure key 24 * @return 0 on success, negative errno value on failure 25 */ 26 int pkey_genseckey(__u16 cardnr, __u16 domain, 27 __u32 keytype, struct pkey_seckey *seckey); 28 29 /* 30 * Generate (AES) secure key with given key value. 31 * @param cardnr may be -1 (use default card) 32 * @param domain may be -1 (use default domain) 33 * @param keytype one of the PKEY_KEYTYPE values 34 * @param clrkey pointer to buffer with clear key data 35 * @param seckey pointer to buffer receiving the secure key 36 * @return 0 on success, negative errno value on failure 37 */ 38 int pkey_clr2seckey(__u16 cardnr, __u16 domain, __u32 keytype, 39 const struct pkey_clrkey *clrkey, 40 struct pkey_seckey *seckey); 41 42 /* 43 * Derive (AES) proteced key from the (AES) secure key blob. 44 * @param cardnr may be -1 (use default card) 45 * @param domain may be -1 (use default domain) 46 * @param seckey pointer to buffer with the input secure key 47 * @param protkey pointer to buffer receiving the protected key and 48 * additional info (type, length) 49 * @return 0 on success, negative errno value on failure 50 */ 51 int pkey_sec2protkey(__u16 cardnr, __u16 domain, 52 const struct pkey_seckey *seckey, 53 struct pkey_protkey *protkey); 54 55 /* 56 * Derive (AES) protected key from a given clear key value. 57 * @param keytype one of the PKEY_KEYTYPE values 58 * @param clrkey pointer to buffer with clear key data 59 * @param protkey pointer to buffer receiving the protected key and 60 * additional info (type, length) 61 * @return 0 on success, negative errno value on failure 62 */ 63 int pkey_clr2protkey(__u32 keytype, 64 const struct pkey_clrkey *clrkey, 65 struct pkey_protkey *protkey); 66 67 /* 68 * Search for a matching crypto card based on the Master Key 69 * Verification Pattern provided inside a secure key. 70 * @param seckey pointer to buffer with the input secure key 71 * @param cardnr pointer to cardnr, receives the card number on success 72 * @param domain pointer to domain, receives the domain number on success 73 * @param verify if set, always verify by fetching verification pattern 74 * from card 75 * @return 0 on success, negative errno value on failure. If no card could be 76 * found, -ENODEV is returned. 77 */ 78 int pkey_findcard(const struct pkey_seckey *seckey, 79 __u16 *cardnr, __u16 *domain, int verify); 80 81 /* 82 * Find card and transform secure key to protected key. 83 * @param seckey pointer to buffer with the input secure key 84 * @param protkey pointer to buffer receiving the protected key and 85 * additional info (type, length) 86 * @return 0 on success, negative errno value on failure 87 */ 88 int pkey_skey2pkey(const struct pkey_seckey *seckey, 89 struct pkey_protkey *protkey); 90 91 /* 92 * Verify the given secure key for being able to be useable with 93 * the pkey module. Check for correct key type and check for having at 94 * least one crypto card being able to handle this key (master key 95 * or old master key verification pattern matches). 96 * Return some info about the key: keysize in bits, keytype (currently 97 * only AES), flag if key is wrapped with an old MKVP. 98 * @param seckey pointer to buffer with the input secure key 99 * @param pcardnr pointer to cardnr, receives the card number on success 100 * @param pdomain pointer to domain, receives the domain number on success 101 * @param pkeysize pointer to keysize, receives the bitsize of the key 102 * @param pattributes pointer to attributes, receives additional info 103 * PKEY_VERIFY_ATTR_AES if the key is an AES key 104 * PKEY_VERIFY_ATTR_OLD_MKVP if key has old mkvp stored in 105 * @return 0 on success, negative errno value on failure. If no card could 106 * be found which is able to handle this key, -ENODEV is returned. 107 */ 108 int pkey_verifykey(const struct pkey_seckey *seckey, 109 u16 *pcardnr, u16 *pdomain, 110 u16 *pkeysize, u32 *pattributes); 111 112 /* 113 * In-kernel API: Generate (AES) random protected key. 114 * @param keytype one of the PKEY_KEYTYPE values 115 * @param protkey pointer to buffer receiving the protected key 116 * @return 0 on success, negative errno value on failure 117 */ 118 int pkey_genprotkey(__u32 keytype, struct pkey_protkey *protkey); 119 120 /* 121 * In-kernel API: Verify an (AES) protected key. 122 * @param protkey pointer to buffer containing the protected key to verify 123 * @return 0 on success, negative errno value on failure. In case the protected 124 * key is not valid -EKEYREJECTED is returned 125 */ 126 int pkey_verifyprotkey(const struct pkey_protkey *protkey); 127 128 /* 129 * In-kernel API: Transform an key blob (of any type) into a protected key. 130 * @param key pointer to a buffer containing the key blob 131 * @param keylen size of the key blob in bytes 132 * @param protkey pointer to buffer receiving the protected key 133 * @return 0 on success, negative errno value on failure 134 */ 135 int pkey_keyblob2pkey(const __u8 *key, __u32 keylen, 136 struct pkey_protkey *protkey); 137 138 #endif /* _KAPI_PKEY_H */ 139