AES key APIs - zpc/aes_key.h

Data structures

struct zpc_aes_key;

The zpc/aes_key.h file defines the following constants for the supported key types and for re-enciphering actions:

# define ZPC_AES_KEY_TYPE_CCA_DATA     1
# define ZPC_AES_KEY_TYPE_CCA_CIPHER   2
# define ZPC_AES_KEY_TYPE_EP11         3
# define ZPC_AES_KEY_TYPE_PVSECRET     9

#define ZPC_AES_KEY_REENCIPHER_OLD_TO_CURRENT    1
#define ZPC_AES_KEY_REENCIPHER_CURRENT_TO_NEW    2

Supported key types

AES key objects of type struct zpc_aes_key store a secure AES key of size 128, 192 or 256 bits and of one of the following supported key types:

• ZPC_AES_KEY_TYPE_CCA_DATA: support for CCA AES DATA keys
• ZPC_AES_KEY_TYPE_CCA_CIPHER: support for CCA AES CIPHER keys
• ZPC_AES_KEY_TYPE_EP11: support for EP11 AES keys
• ZPC_AES_KEY_TYPE_PVSECRET: support for AES retrievable secrets.

Properties

In addition, AES key objects store flags, a reference count and the corresponding protected key. You can set the flags using the API described in zpc_aes_key_set_flags.

Setting flags is optional for AES key objects and flags=0 if flags are not explicitly set.

The secure key is set by either generating it or importing it (either directly or from a clear key).

The protected key is automatically derived from the secure key (and re-derived whenever it is needed).

The protected key can also be randomly generated resulting in a protected key that is not associated to any secure key. Key objects that are not associated to a secure key become unusable when the wrapping key verification pattern (WKVP) changes. The wrapping key for a protected key is generated for the LPAR or virtual guest at boot time and is deleted when the LPAR or guest is shutting down.

Key object's reference count is 1 on allocation (zpc_aes_key_alloc()) and decremented when freed (zpc_aes_key_free()). Setting the key object in an operation context increments the reference and unsetting the key object in an operation context or freeing the operation context decrements the reference count. The key object is destroyed only if the reference count is 0. Key objects may be shared among multiple threads.

The remainder of this information unit describes the available APIs for managing AES keys.

zpc_aes_key_alloc

Purpose: Allocate a new AES key object with reference count 1.

int zpc_aes_key_alloc (
    struct zpc_aes_key **key );

Parameters:

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_aes_key_export

Purpose: Export an AES secure key, for example to archive a secure key in a file for importing it into the same or another application later.

If the secure key buffer is NULL, the byte-length of the secure key is returned in the secure key length argument.

If the secure key buffer is not NULL, and the secure key length argument is greater than or equal to the secure key's byte length, the secure key is returned in the secure key buffer. The byte-length of the secure key is returned in the secure key length argument.

int zpc_aes_key_export (
    struct zpc_aes_key *key,
    unsigned char *seckey,
    size_t *seckeylen );

Parameters:

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_aes_key_free

Purpose: Decreases the reference count of an AES key object and destroys it if the count reaches 0. This function does not prevent other functions from increasing the reference count.

void zpc_aes_key_free (
     struct zpc_aes_key **key );

The pointer to the key (*key) is set to NULL by the function.

Parameters:

zpc_aes_key_generate

Purpose: Generate a random AES secure/protected key pair or a random protected key.

A prerequisite for generating a key is that the key size must have been set before using the zpc_aes_key_set_size() function.

If you did not associate any APQNs with the key object, either directly or setting a matching MKVP, or if no key type is set before, a random protected key is generated. Otherwise, a secure key is generated on one of the defined APQNs with the attributes that you set before in your application. The applicable protected key is then always automatically derived whenever required.

int zpc_aes_key_generate (
    struct zpc_aes_key *key );

Parameters:

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_aes_key_import

Purpose: Import an AES secure key.

Before the import, you must set at least the type and the size of the key. The imported key must match these attributes. You can define new APQN settings for the new key either before or after the import. However, APQNs must be set at the latest before the key can be used for an operation.

No secure key can be imported, if the key object is in use (reference count greater than 1).

The corresponding protected key is automatically derived.

int zpc_aes_key_import (
    struct zpc_aes_key *key,
    const unsigned char *seckey,
    size_t seckeylen );

Parameters:

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_aes_key_import_clear

Purpose: Import an AES clear key.

The imported key must match the key object's key size setting.

Before the import, you must set at least the type and the size of the key. The imported key must match these attributes. You can define new APQN settings for the new key either before or after the import. However, APQNs must be set at the latest before the key can be used for an operation.

No clear key can be imported, if the key object is in use (reference count greater than 1).

The corresponding secure/protected key pair is automatically derived.

int zpc_aes_key_import_clear (
    struct zpc_aes_key *key 
    const unsigned char *clearkey );

Parameters:

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_aes_key_reencipher

Purpose: Re-encipher an AES secure key with another master key.

Prerequisite for all re-encipher operations is that the related master key registers contain valid master keys.

Secure keys of type ZPC_AES_KEY_TYPE_EP11 only support ZPC_AES_KEY_REENCIPHER_CURRENT_TO_NEW.

A backup of the previous secure key is kept in case the new secure key is not yet usable. This backup is kept until the next re-encipher operation and replaced by the updated backup secure key.

int zpc_aes_key_reencipher (
struct zpc_aes_key *key,
int reenc );

Parameters:

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_aes_key_set_apqns

Purpose: Set the AES key APQNs.

Associate all given APQNs with the key object. This overrides the key object's current APQN settings.

The APQNs cannot be changed, if the key object is in use (reference count greater than 1).

int zpc_aes_key_set_apqns (
    struct zpc_aes_key *key,
    const char *apqns[ ] );

Parameters:

The input APQN parameter is a NULL terminated array of strings, in the following syntax: "<optional_whitespace><card_hex>.<domain_hex><optional_whitespace>". Whitespaces at the beginning or at the end of an APQN string are ignored. The list must be terminated by NULL, like shown in the following examples:

char *apqns1[] = {"01.0037","02.0037","03.0020","0a.0031","0b.0031",NULL};
rc = zpc_aes_key_set_apqns(key, apqns1);
char *apqns2[] = {" 01.0037 "," 02.0037 "," 03.0020 "," 0a.0031 "," 0b.0031 ",NULL};
rc = zpc_aes_key_set_apqns(key, apqns2);

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_aes_key_set_flags

Purpose: Set the AES key flags. Setting flags is optional. If no flags are set, a default is applied.

By setting flags, you can apply certain properties to the key to be generated. The flags have a key-type specific meaning and provide a fine grained control of the kernel's key generation ioctls.

• For CCA AES DATA keys, there are no flags. Any flags setting is ignored.
• For CCA AES CIPHER keys, there are the following flags (see also kernel file arch/s390/include/uapi/asm/pkey.h):

  Flag	Value	Description
  PKEY_KEYGEN_XPRT_SYM	0x00008000	Allow export using symmetric key. This is the default.
  PKEY_KEYGEN_XPRT_UASY	0x00004000	Allow export using an unauthenticated asymmetric key (not a trusted block).
  PKEY_KEYGEN_XPRT_AASY	0x00002000	Allow export using an authenticated asymmetric key (trusted block).
  PKEY_KEYGEN_XPRT_RAW	0x00001000	Allow export using a raw key. Defined for future use. Currently ignored.
  PKEY_KEYGEN_XPRT_CPAC	0x00000800	Allow export of key to CPACF.
  PKEY_KEYGEN_XPRT_DES	0x00000080	Allow export using a DES key.
  PKEY_KEYGEN_XPRT_AES	0x00000040	Allow export using an AES key.
  PKEY_KEYGEN_XPRT_RSA	0x00000008	Allow export using an RSA key.

• For EP11 AES keys there are the following flags (see also /usr/include/ep11-host-devel/ep11.h).

  If the flags parameter is 0, which is the default, the following flags are set:

  • XCP_BLOB_ENCRYPT
  • XCP_BLOB_DECRYPT
  • XCP_BLOB_PROTKEY_EXTRACTABLE

  If the flags parameter is not 0, those flags are set, that correspond to the provided input decimal integer. For example, if flags=200008, the flags XCP_BLOB_NEVER_MODIFIABLE (=0x00000008) and XCP_BLOB_PROTKEY_EXTRACTABLE (=0x00200000) are set, because 0x8 + 0x200000 = 0x200008.

  Flag	Value	Description
  XCP_BLOB_EXTRACTABLE	0x00000001	This key may be encrypted by other keys. Cannot be reset.
  XCP_BLOB_NEVER_EXTRACTABLE	0x00000002	Set this flag if the key was created non-extractable. Can be set only initially and cannot be modified.
  XCP_BLOB_MODIFIABLE	0x00000004	Attributes of the key may be changed
  XCP_BLOB_NEVER_MODIFIABLE	0x00000008	The key object was created read-only. Can be set only initially and cannot be modified.
  XCP_BLOB_RESTRICTABLE	0x00000010	The attributes of the key may be removed, but may not be made more permissive.
  XCP_BLOB_LOCAL	0x00000020	The key was created inside this CSP, and not imported. This flag is set upon object creation and may not be modified.
  XCP_BLOB_ATTRBOUND	0x00000040	This key may be transported only in attribute-bound formats, but not pure PKCS11 formats. May not be modified.
  XCP_BLOB_USE_AS_DATA	0x00000080	Raw key bytes may be input to other processing as data, such as hashed, or deriving keys from them.
  XCP_BLOB_SIGN	0x00000100	This key may generate signatures
  XCP_BLOB_SIGN_RECOVER	0x00000200	This key may generate (asymmetric) signatures with message recovery.
  XCP_BLOB_DECRYPT	0x00000400	This key may decrypt data.
  XCP_BLOB_ENCRYPT	0x00000800	This key may encrypt data.
  XCP_BLOB_DERIVE	0x00001000	This key may derive other keys.
  XCP_BLOB_UNWRAP	0x00002000	This key may decrypt (transport) other keys.
  XCP_BLOB_WRAP	0x00004000	This key may encrypt (transport) other keys.
  XCP_BLOB_VERIFY	0x00008000	This key may verify signatures.
  XCP_BLOB_VERIFY_RECOVER	0x00010000	This key may verify signatures and recover signed messages.
  XCP_BLOB_TRUSTED	0x00020000	This key is a PKCS11 CKA_TRUSTED key
  XCP_BLOB_WRAP_W_TRUSTED	0x00040000	This key needs a CKA_TRUSTED key-encrypting key. Note: _TRUSTED enforcement does not provide security guarantees. It is only tracked inside the HSM to assist hosts.
  XCP_BLOB_RETAINED	0x00080000	The key blob resides within a backend, not on the host.
  XCP_BLOB_ALWAYS_RETAINED	0x00100000	This key blob has been generated inside.
  XCP_BLOB_PROTKEY_EXTRACTABLE	0x00200000	This key may be imported as protected key. May not be reset.
  XCP_BLOB_PROTKEY_NEVER_EXTRACTABLE	0x00400000	This flag is set if the key was created non-extractable as a protected key. It is set only initially, and may not be modified.

The key flags cannot be changed, if the key object is in use (reference count greater than 1).

int zpc_aes_key_set_flags (
    struct zpc_aes_key *key,
    unsigned int flags );

Parameters:

zpc_aes_key_set_flags (&aes_key, 0x200008)
zpc_aes_key_set_flags (&aes_key, 0x8 | 0x200000)
zpc_aes_key_set_flags (&aes_key, XCP_BLOB_NEVER_MODIFIABLE |  XCP_BLOB_PROTKEY_EXTRACTABLE)

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_aes_key_set_mkvp

Purpose: Set the AES key master key verification pattern (MKVP) to retrieve all matching APQNs.

Instead of specifying the APQNs associated to a secure key directly, you can set a master key verification pattern (MKVP). This function then will associate all APQNs with the key object to be generated, where the master key matches the given MKVP. The value of the MKVP is no longer relevant after this call.

Before calling this function, the key type must be set.

This function overrides the key object's current APQN settings.

The MKVP cannot be set, if the key object is in use (reference count greater than 1).

int zpc_aes_key_set_mkvp (
    struct zpc_aes_key *key,
    const char *mkvp );

Parameters:

To retrieve the required master key verification pattern, you can check appropriate files on your system. For example, if you want to associate all APQNs where the current MKVP is the same as on the coprocessor card 1 on domain 37 (APQN: 01.0037) for a CCA coprocessor, view the content of the following file:

# cat /sys/bus/ap/devices/01.0037/mkvps  /* example for a CCA coprocessor */

AES NEW: full 0x125efe03d9b1e4a3
AES CUR: valid 0x5bba02a0d7b07924
AES OLD: valid 0x40910b8c96ef4c8f
APKA NEW: full 0xe2a46e45db5f47e4
APKA CUR: valid 0xe2a46e45db5f47e4
APKA OLD: valid 0xe2a46e45db5f47e4
  

You can specify the string for the mkvp parameter with or without the hexadecimal signature, for example, "0x5bba02a0d7b07924" or "5bba02a0d7b07924" .

A sample for a Crypto Express EP11 coprocessor looks like follows:

cat /sys/bus/ap/devices/02.0037/mkvps

 WK CUR: valid 0xef490ddfce10b330b86cfe6db2ae2db98d65e8c19d9cb7a1b378dec93e398eb0
 WK NEW: committed 0x523072cacc0fb7fd0e1f050da3ea8fed035b59ea4b8432b4ac53f66861ea88e1
 

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_aes_key_set_size

Purpose: Set the AES key size.

The key size cannot be changed, if the key object is in use (reference count greater than 1).

int zpc_aes_key_set_size (
    struct zpc_aes_key *key,
    int size );

Parameters:

Return codes:

0 on success. Otherwise, a non-zero error code is returned.

zpc_aes_key_set_type

Purpose: Set the AES key type.

The key type cannot be changed, if the key object is in use (reference count greater than 1).

int zpc_aes_key_set_type (
    struct zpc_aes_key *key,
    int type );

Parameters:

Return codes:

0 on success. Otherwise, a non-zero error code is returned.