Lifecycle of key objects

Performing AES cryptographic operations

In your application program, you normally start with using a function to allocate an empty container for an AES key object. For this purpose, use function zpc_aes_key_alloc() as described in AES key APIs - zpc/aes_key.h. Then you continue to fill the container by setting desired key attributes by using functions like zpc_aes_key_set_size(), zpc_aes_key_set_type(), or zpc_aes_key_set_apqns(). The key size must always be set before generating a protected key.

To generate a protected key, you normally use function zpc_aes_key_generate() (zpc_aes_key_generate). You can distinguish the following use cases:

If you use this function, and no attributes have been specified before, besides the required key size and an optional key type, a random volatile protected key is generated on the CPACF. You can use such volatile protected keys in use cases within the lifetime of an LPAR, virtual server, or z/VM® or KVM guest, for example, for encrypting swap disks.

If you want to make permanent use of protected-key cryptography across the lifetime of an LPAR, virtual server, or z/VM or KVM guest, you use this function to generate a secure key/protected key pair. In this case, further attributes, in addition to size and key type, must be known to the application before the key pair generation, for example, to decide whether a CCA AES DATA secure key should be generated on a cryptographic coprocessor and on which APQNs the key pair generation should happen. The function then generates a secure key with the specified attributes, unwraps the secure key's effective key and re-wraps the effective key with the wrapping key generated by the firmware. The result is a protected key with the same effective key as wrapped in the secure key. A new protected key is automatically derived from the secure key using a new firmware wrapping key when required. This happens in cases where for example an LPAR has been rebooted in the meanwhile and thus the old firmware wrapping key is no longer available.

If you decide to generate a secure key/protected key pair you can select from two ways how to associate the secure key to certain APQNs:

• You can directly specify the APQNs before generating the key by using the zpc_aes_key_set_apqns() function.
• You can have libzpc retrieve the appropriate APQNs from a given master key verification pattern (MKVP) by using the zpc_aes_key_set_mkvp() function.

After specifying the attributes, you can select from several APIs to generate or import a key into this container. To generate a new random protected key or a secure key/protected key pair, use function zpc_aes_key_generate(). You can also import either a clear key which is wrapped by the master key to become a secure key which in turn is transformed into a protected key. This is achieved by function zpc_aes_key_import_clear(). Or you can directly import an existing secure key for transformation into a protected key with function zpc_aes_key_import(). For more information, see AES key APIs - zpc/aes_key.h.

Performing ECC cryptographic operations

Similar as for AES key objects, you use the corresponding function zpc_ec_key_alloc() to allocate an empty container for an ECC key object. Set the desired ECC key attributes similar to AES. However, instead of setting the key size, you must define the desired elliptic curve for your ECC operations by using the function zpc_ec_key_set_curve().

To generate a protected ECC key (zpc_ec_key_generate()), the only available method is to use either a CCA or an EP11 cryptographic coprocessor. The process is analogous to that for AES keys. See the ECC sample program in Generating an ECC secure key and create and verify a signature.

You cannot directly generate a random volatile protected ECC key via the kernel on the CPACF.

Using and managing keys with a reference count

The functions of the libzpc library care for the lifetime of your key object. When allocating a key object, an internal reference count is set to 1 to indicate that the key is in use.

Now you can use this key to perform your required cryptographic operations using the appropriate functions from the library. Each cryptographic operation that uses this key, increments this reference count at the beginning and decreases it after successful processing. This ensures that the reference count is always at least greater than zero as long as the AES key object is in use by any operation.

Finally, you use functions zpc_aes_key_free() or zpc_ec_key_free()to free the space for the key object. This function decrements the reference count by 1 and frees it only if the count reaches 0. This function can run before the last cryptographic operation finishes, because in this case the reference count is not yet zero, due to the incrementation by the running operation. Each operation checks the reference count when finishing and frees the key object if the count reaches 0.

Reuse of a key object context

You can reuse the context (that is, the container) for generating a new key of the same type. For AES keys with an initialization vector, you set a new vector to overwrite the old one. The reference count of the old key is decremented by one, and incremented by one for the new key.