External programming interfaces

Edit online

Ubuntu 22.04 LTS LPAR mode z/VM guest KVM guest

Applications can use the protected key device driver through ioctls or corresponding kernel APIs.

Programmers: This information is intended for programmers of cryptographic applications who want to use protected keys for accelerated cryptographic operations with CPACF.

Issue ioctls on the misc character device /dev/pkey to generate and handle protected keys. The ioctl interface, including the required defines and structure definitions, is described in /usr/include/s390x-linux-gnu/asm/pkey.h. Each ioctl has a matching kernel API that is also described in this file.

Table 1. ioctls of the protected key device driver

The table has three columns, the first column lists IO controls, the second lists the structure that is passed, and the third column contains a description.
Name Structure passed Description
PKEY_GENSECK struct pkey_genseck Obtain a random CCA AES data secure key from an AP queue. The secure key is encrypted with the master key of the AP queue.
PKEY_GENSECK2 struct pkey_genseck2 Obtain a random secure key from an AP queue. The secure key is encrypted with the master key of the AP queue. Available key types are: CCA AES data secure key, CCA AES cipher secure key, and EP11 AES secure key.
PKEY_CLR2SECK struct pkey_clr2seck Obtain a CCA AES data secure key from an AP queue. The secure key is generated from a specified clear key and encrypted with the master key of the AP queue.
PKEY_CLR2SECK2 struct pkey_clr2seck2 Obtain a secure key from an AP queue. The secure key is generated from a specified clear key and encrypted with the master key of the AP queue. Available key types are: CCA AES data secure key, CCA AES cipher secure key, and EP11 AES secure key.
PKEY_SEC2PROTK struct pkey_sec2protk Obtain a protected CCA AES data key from an AP queue. The protected key is generated from a specified secure key.
PKEY_CLR2PROTK struct pkey_clr2protk Obtain a protected key. The protected key is generated from a specified clear key.
PKEY_FINDCARD struct pkey_findcard Find an AP queue that holds the applicable master key for a specified CCA AES data secure key.
PKEY_SKEY2PKEY struct pkey_skey2pkey Find an AP queue that holds the applicable master key for a specified CCA AES data secure key. Then use that AP queue to obtain a protected key that is generated from the secure key. This ioctl call combines PKEY_FINDCARD and PKEY_SEC2PROTK.
PKEY_GENPROTKEY struct pkey_genprotk Generates a volatile protected key using pkey.
PKEY_VERIFYPROTKEY struct pkey_verifyprotk Verifies an AES protected key.
PKEY_VERIFYKEY2 struct pkey_verifykey2 Verifies a key blob and returns information about the key. The key can be verified against one specific AP queue. If no AP queue is specified, all available queues are checked and the ID of a queue is returned for which the key is valid. The call ends with an error if the key is not valid for the specified queue or if no queue is available for which the key is valid.
PKEY_KBLOB2PKEY struct pkey_kblob2pkey Transforms a key blob of a protected key or of a CCA AES data secure key into a protected key.
PKEY_KBLOB2PKEY2 struct pkey_kblob2pkey2 Transforms a key blob into a protected key. The key blob can be for a protected key, a CCA AES data secure key, a CCA AES cipher secure key, or an EP11 AES secure key.
PKEY_KBLOB2PROTK3 struct pkey_kblob2pkey3 Transforms a key blob into a protected key. The key blob can be of a protected key or of one of the following types:
  • CCA AES data secure key
  • CCA AES cipher secure key
  • CCA ECC secure key
  • EP11 AES secure key
  • EP11 ECC secure key
PKEY_APQNS4K struct pkey_apqns4key Finds all available AP queues for which a specified key blob is valid.
PKEY_APQNS4KT struct pkey_apqns4keytype Finds all available AP queues for which a specified key type is valid for a particular master key.