Generating volatile protected keys by using the pkey device driver

Edit online

7.1 LPAR mode z/VM guest KVM guest

You can generate protected keys from random data by reading the binary sysfs pkey attributes.

About this task

You do not need a Crypto Express adapter to generate a protected key from random data.

Note: The derived protected keys are based on clear key objects. To use secure key objects, see Generating secure keys using the pkey device driver.

The /sys/devices/virtual/misc/pkey/protkey directory contains an attribute for each available key type. Read an attribute to obtain a protected key token.

Traditionally, AES-XTS keys provided through the protkey_aes_128_xts and protkey_aes_256_xts sysfs attributes are simply the concatenation of two AES-128 or two AES-256 keys, respectively.

With IBM® z17 ™, CPACF introduces enhanced performance for AES-XTS encryption using a new key format referred to as full AES-XTS keys. In this format, the two AES keys are stored differently to improve both performance and security. The protkey_aes_xts_128 and protkey_aes_xts_256 sysfs attributes provide key material in this new format.

In addition, IBM z17 also adds CPACF support for HMAC. The hardware supports the following HMAC variants:
  • HMAC-SHA224
  • HMAC-SHA256
  • HMAC-SHA384
  • HMAC-SHA512
For HMAC-SHA224 and HMAC-SHA256, a 512-bit key is required. For HMAC-SHA384 and HMAC-SHA512, a 1024-bit key is needed. These keys can be generated using the protkey_hmac_512 and protkey_hmac_1024 sysfs attribute files.

Procedure

Go to the protkey subdirectory. The following attributes are available:
  • protkey_aes_128
  • protkey_aes_192
  • protkey_aes_256
  • protkey_aes_128_xts
  • protkey_aes_256_xts
  • protkey_aes_xts_128
  • protkey_aes_xts_256
  • protkey_hmac_512
  • protkey_hmac_1024

For attributes related to the XTS cipher mode, you get two concatenated protected-key tokens, that is, you get 160 bytes when using the protkey_aes_128 or 256_xts attributes. You get one "full" XTS protected key token, that is, 80 bytes when using the protkey_aes_xts_128 file or 112 bytes when using the protkey_aes_xts_256 attribute.

Important: Do not use protected keys that are generated from random data to encrypt persistent data.

Alternatively to sysfs, you can use the ioctl calls, see External programming interfaces.