arch/s390/include/uapi/asm/pkey.h

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