zcrypt_ep11misc.h

  1/* SPDX-License-Identifier: GPL-2.0+ */
  2/*
  3 *  Copyright IBM Corp. 2019
  4 *  Author(s): Harald Freudenberger <freude@linux.ibm.com>
  5 *
  6 *  Collection of EP11 misc functions used by zcrypt and pkey
  7 */
  8
  9#ifndef _ZCRYPT_EP11MISC_H_
 10#define _ZCRYPT_EP11MISC_H_
 11
 12#include <asm/zcrypt.h>
 13#include <asm/pkey.h>
 14
 15#define EP11_API_V1 1  /* min EP11 API, default if no higher api required */
 16#define EP11_API_V4 4  /* supported EP11 API for the ep11misc cprbs */
 17#define EP11_API_V6 6  /* min EP11 API for some cprbs in SE environment */
 18#define EP11_STRUCT_MAGIC 0x1234
 19#define EP11_BLOB_PKEY_EXTRACTABLE 0x00200000
 20
 21/*
 22 * Internal used values for the version field of the key header.
 23 * Should match to the enum pkey_key_type in pkey.h.
 24 */
 25#define TOKVER_EP11_AES  0x03  /* EP11 AES key blob (old style) */
 26#define TOKVER_EP11_AES_WITH_HEADER 0x06 /* EP11 AES key blob with header */
 27#define TOKVER_EP11_ECC_WITH_HEADER 0x07 /* EP11 ECC key blob with header */
 28
 29/* inside view of an EP11 secure key blob */
 30struct ep11keyblob {
 31	union {
 32		u8 session[32];
 33		/* only used for PKEY_TYPE_EP11: */
 34		struct ep11kblob_header head;
 35	};
 36	u8  wkvp[16];  /* wrapping key verification pattern */
 37	u64 attr;      /* boolean key attributes */
 38	u64 mode;      /* mode bits */
 39	u16 version;   /* 0x1234, EP11_STRUCT_MAGIC */
 40	u8  iv[14];
 41	u8  encrypted_key_data[144];
 42	u8  mac[32];
 43} __packed;
 44
 45/* check ep11 key magic to find out if this is an ep11 key blob */
 46static inline bool is_ep11_keyblob(const u8 *key)
 47{
 48	struct ep11keyblob *kb = (struct ep11keyblob *)key;
 49
 50	return (kb->version == EP11_STRUCT_MAGIC);
 51}
 52
 53/*
 54 * For valid ep11 keyblobs, returns a reference to the wrappingkey verification
 55 * pattern. Otherwise NULL.
 56 */
 57const u8 *ep11_kb_wkvp(const u8 *kblob, u32 kbloblen);
 58
 59/*
 60 * Simple check if the key blob is a valid EP11 AES key blob with header.
 61 * If checkcpacfexport is enabled, the key is also checked for the
 62 * attributes needed to export this key for CPACF use.
 63 * Returns 0 on success or errno value on failure.
 64 */
 65int ep11_check_aes_key_with_hdr(debug_info_t *dbg, int dbflvl,
 66				const u8 *key, u32 keylen, int checkcpacfexp);
 67
 68/*
 69 * Simple check if the key blob is a valid EP11 ECC key blob with header.
 70 * If checkcpacfexport is enabled, the key is also checked for the
 71 * attributes needed to export this key for CPACF use.
 72 * Returns 0 on success or errno value on failure.
 73 */
 74int ep11_check_ecc_key_with_hdr(debug_info_t *dbg, int dbflvl,
 75				const u8 *key, u32 keylen, int checkcpacfexp);
 76
 77/*
 78 * Simple check if the key blob is a valid EP11 AES key blob with
 79 * the header in the session field (old style EP11 AES key).
 80 * If checkcpacfexport is enabled, the key is also checked for the
 81 * attributes needed to export this key for CPACF use.
 82 * Returns 0 on success or errno value on failure.
 83 */
 84int ep11_check_aes_key(debug_info_t *dbg, int dbflvl,
 85		       const u8 *key, u32 keylen, int checkcpacfexp);
 86
 87/* EP11 card info struct */
 88struct ep11_card_info {
 89	u32  API_ord_nr;    /* API ordinal number */
 90	u16  FW_version;    /* Firmware major and minor version */
 91	char serial[16];    /* serial number string (16 ascii, no 0x00 !) */
 92	u64  op_mode;	    /* card operational mode(s) */
 93};
 94
 95/* EP11 domain info struct */
 96struct ep11_domain_info {
 97	char cur_wk_state;  /* '0' invalid, '1' valid */
 98	char new_wk_state;  /* '0' empty, '1' uncommitted, '2' committed */
 99	u8   cur_wkvp[32];  /* current wrapping key verification pattern */
100	u8   new_wkvp[32];  /* new wrapping key verification pattern */
101	u64  op_mode;	    /* domain operational mode(s) */
102};
103
104/*
105 * Provide information about an EP11 card.
106 */
107int ep11_get_card_info(u16 card, struct ep11_card_info *info, u32 xflags);
108
109/*
110 * Provide information about a domain within an EP11 card.
111 */
112int ep11_get_domain_info(u16 card, u16 domain,
113			 struct ep11_domain_info *info, u32 xflags);
114
115/*
116 * Generate (random) EP11 AES secure key.
117 */
118int ep11_genaeskey(u16 card, u16 domain, u32 keybitsize, u32 keygenflags,
119		   u8 *keybuf, u32 *keybufsize, u32 keybufver, u32 xflags);
120
121/*
122 * Generate EP11 AES secure key with given clear key value.
123 */
124int ep11_clr2keyblob(u16 cardnr, u16 domain, u32 keybitsize, u32 keygenflags,
125		     const u8 *clrkey, u8 *keybuf, u32 *keybufsize,
126		     u32 keytype, u32 xflags);
127
128/*
129 * Build a list of ep11 apqns meeting the following constrains:
130 * - apqn is online and is in fact an EP11 apqn
131 * - if cardnr is not FFFF only apqns with this cardnr
132 * - if domain is not FFFF only apqns with this domainnr
133 * - if minhwtype > 0 only apqns with hwtype >= minhwtype
134 * - if minapi > 0 only apqns with API_ord_nr >= minapi
135 * - if wkvp != NULL only apqns where the wkvp (EP11_WKVPLEN bytes) matches
136 *   to the first EP11_WKVPLEN bytes of the wkvp of the current wrapping
137 *   key for this domain. When a wkvp is given there will always be a re-fetch
138 *   of the domain info for the potential apqn - so this triggers an request
139 *   reply to each apqn eligible.
140 * The caller should set *nr_apqns to the nr of elements available in *apqns.
141 * On return *nr_apqns is then updated with the nr of apqns filled into *apqns.
142 * The return value is either 0 for success or a negative errno value.
143 * If no apqn meeting the criteria is found, -ENODEV is returned.
144 */
145int ep11_findcard2(u32 *apqns, u32 *nr_apqns, u16 cardnr, u16 domain,
146		   int minhwtype, int minapi, const u8 *wkvp, u32 xflags);
147
148/*
149 * Derive proteced key from EP11 key blob (AES and ECC keys).
150 */
151int ep11_kblob2protkey(u16 card, u16 dom, const u8 *key, u32 keylen,
152		       u8 *protkey, u32 *protkeylen, u32 *protkeytype,
153		       u32 xflags);
154
155int zcrypt_ep11misc_init(void);
156void zcrypt_ep11misc_exit(void);
157
158#endif /* _ZCRYPT_EP11MISC_H_ */