ECC key APIs - zpc/ecc_key.h

Edit online

In file zpc/ecc_key.h, libzpc provides encryption APIs to support elliptic curve cryptography (ECC) using secure keys from CCA and EP11 cryptographic coprocessors.

Before using the provided ECC key functions, be sure to read the Restrictions.

Data structures

The ECC key structure zpc_ec_key is opaque for the application:
struct zpc_ec_key;

ECC key objects of type struct zpc_ec_key store a secure ECC key of either a CCA or EP11 key type.

Supported key types

The following constants for the supported key types are defined in the ecc_key.h file:


#define ZPC_EC_KEY_TYPE_CCA    0x1F
#define ZPC_EC_KEY_TYPE_EP11      7

Properties

The following enumeration identifies ECC curves in libzpc:


typedef enum {
    ZPC_EC_CURVE_NOT_SET = -2,
    ZPC_EC_CURVE_INVALID = -1,
    ZPC_EC_CURVE_P256 = 0,
    ZPC_EC_CURVE_P384,   
    ZPC_EC_CURVE_P521,    
    ZPC_EC_CURVE_ED25519,   
    ZPC_EC_CURVE_ED448        
} zpc_ec_curve_t;
Also, the ECC context structure zpc_ec_ctx is opaque for the application, like the AES context structures zpc_aes_<mode>: 
struct zpc_ec_ctx;

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

zpc_ec_key_alloc

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

Format: 

int zpc_ec_key_alloc(
    struct zpc_ec_key **key );

Parameters:

Direction Name Description
input, output key Pointer to an ECC key

Return codes:

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

zpc_ec_key_export

Purpose: Export an ECC secure key into an output buffer.

Depending on the key type, the ECC secure key is either a CCA secure key token or has an EP11 secure key structure. Refer to Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide, SC33-8294 or to Enterprise PKCS#11 (EP11) Library structure (select ep11-structure.pdf). For the header definition of an EP11 key, see file arch/s390/include/uapi/asm/pkey.h.

For EP11 type keys, a SubjectPublicKeyInfo (SPKI) encoding of the related public ECC key is appended to the secure key data if the key object has a public key.

Format: 

int zpc_ec_key_export(
    struct zpc_ec_key *key, 
    unsigned char *seckey,
    size_t *seckeylen );

Parameters:

Direction Name Description
input, output key Pointer to an ECC key
output seckey Pointer to an ECC secure key. Can be NULL to obtain the length of the secure key.
input, output seckeylen Pointer to an integer containing the ECC secure key length [bytes]

Return codes:

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

zpc_ec_key_export_public

Purpose: Export an ECC public key into an output buffer.

Format: 

int zpc_ec_key_export_public(
    struct zpc_ec_key *key, 
    unsigned char *pubkey,
    unsigned int *pubkeylen );

Parameters:

Direction Name Description
input, output key Pointer to an ECC key
output pubkey Pointer to the uncompressed ECC public key (can be NULL to obtain the length only). The output buffer contains the concatenated X and Y values of the public key without a leading byte that would indicate an uncompressed public key.
input, output pubkeylen Pointer to an integer containing the ECC public key length [bytes]

Return codes:

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

zpc_ec_key_free

Purpose: Decrease the reference count of an ECC key object and free it, if the count reaches 0.

Format: 

void zpc_ec_key_free(
     struct zpc_ec_key **key );

Parameters:

Direction Name Description
input, output key Pointer to an ECC key

Return codes:

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

zpc_ec_key_generate

Purpose: Generate an ECC secure key.

As a prerequisite, you need to specify an elliptic curve and a key type to be used for key generation. In contrast to AES keys, generation of a random protected key directly via the kernel is not supported. If you omit both the APQN or MKVP specifications, an error message is issued.

Format: 

int zpc_ec_key_generate(
    struct zpc_ec_key *key );

Parameters:

Direction Name Description
input, output key Pointer to an ECC key

Return codes:

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

zpc_ec_key_import

Purpose: Import an ECC secure key.

Before the import, you must set at least the type and the curve of the key. The imported key must match these attributes. APQN and MKVP settings must be finished before the import.

Depending on the key type, the ECC secure key buffer must contain either a CCA secure key token or has an EP11 secure key structure. Refer to Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide Secure Key Solution with the Common Cryptographic Architecture Application Programmer's Guide, SC33-8294 or to Enterprise PKCS#11 (EP11) Library structure (select ep11-structure.pdf). For the header definition of an EP11 key, see file arch/s390/include/uapi/asm/pkey.h.

For EP11 type keys, a SubjectPublicKeyInfo (SPKI) encoding of the related public ECC key may be appended to the secure key data.

Format: 

int zpc_ec_key_import (
    struct zpc_ec_key *key,
    const unsigned char *seckey,
    unsigned int  seckeylen );

Parameters:

Direction Name Description
input, output key Pointer to an ECC key object
input seckey Pointer to an ECC secure key buffer
input seckeylen ECC secure key length [bytes]

Return codes:

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

zpc_ec_key_import_clear

Purpose: Import an ECC clear key pair. At least one of the key parts must be non-NULL.

A NULL key part leaves a previously set key part untouched, so for example, it is possible to import a secure key at first by using the zpc_ec_key_import() function, and then add the corresponding public key with a subsequent zpc_ec_key_import_clear() call. No integrity check is performed on the imported key material, except of a plausibility check on the length of the provided key parts. The application is responsible for providing valid key parts or pairs. Public keys are considered to be the concatenated X and Y values without a leading 0x04 byte that would indicate an uncompressed public key.

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.

Format: 

int zpc_ec_key_import_clear (
    struct zpc_ec_key *key,    
    const unsigned char *pubkey, 
    unsigned int publen,
    const unsigned char *privkey, 
    unsigned int privlen );

Parameters:

Direction Name Description
input, output key Pointer to an ECC key
input pubkey Pointer to an uncompressed ECC public key (can be NULL)
input publen ECC public key length [bytes]
input privkey Pointer to an ECC private key (can be NULL)
input privlen ECC private key length [bytes]

Return codes:

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

zpc_ec_key_reencipher

Purpose: Re-encipher an ECC secure key.

Notes:
  • CCA APQNs have three master key registers: OLD, CURRENT, and NEW. Therefore, re-enciphering of CCA keys is possible from an old master key to the current master key and from the current master key to the new master key.
  • EP11 APQNs have only two master key registers: CURRENT and NEW. Re-enciphering of EP11 keys is therefore only possible from the current to the new master key. When trying to re-encipher an EP11 key from old to current, an error code is returned.

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

Format: 

int zpc_ec_key_reencipher(
    struct zpc_ec_key *key, 
    unsigned int reenc );

Parameters:

Direction Name Description
input, output key Pointer to an ECC key
input reenc
  • ZPC_EC_KEY_REENCIPHER_CURRENT_TO_NEW (for CCA and EP11 ECC keys).
  • ZPC_EC_KEY_REENCIPHER_OLD_TO_CURRENT (for CCA ECC keys only)

Return codes:

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

zpc_ec_key_set_apqns

Purpose: Set the ECC key APQNs. For information on how to specify the APQNs in this API, see zpc_aes_key_set_apqns.

Format: 
int zpc_ec_key_set_apqns (
    struct zpc_ec_key *key, 
    const char *apqns[] );

Parameters:

Direction Name Description
input, output key Pointer to an ECC key object
input apqns NULL-terminated APQN list

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_ec_key_set_curve

Purpose: Set the ECC curve.

Format: 

int zpc_ec_key_set_curve(
    struct zpc_ec_key *key, 
    zpc_ec_curve_t curve );

Parameters:

Direction Name Description
input, output key Pointer to an ECC key
input, output curve One of: zpc_ec_curve_t (Data structures)

Return codes:

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

zpc_ec_key_set_flags

Purpose: Set the ECC key flags.

In contrast to AES keys, protected ECC keys are created or imported via the CCA and EP11 host libraries, where libzpc must explicitly specify the default key usage. In order to get the same key usage behavior for ECC as for AES, libzpc specifies the following key usage:

  • CCA:

    Key usage is specified via CCA rule array keywords when building the skeleton token via the CCA service API called CSNDPKB. You can set the following flag for CCA ECC keys with this API:

    libzpc flag CCA rule array keyword Description
    PKEY_KEYGEN_XPRT_AES AES1ECOK Allow export of the key under an AES key encrypting key
  • EP11:

    Key usage is specified via the PKCS#11 attributes. You can set the following flag for EP11 ECC keys with this API:

    libzpc flag PKCS#11 attribute
    XCP_BLOB_PROTKEY_EXTRACTABLE CKA_IBM_PROTKEY_EXTRACTABLE (default)
    XCP_BLOB_SIGN CKA_SIGN (default)
    XCP_BLOB_MODIFIABLE CKA_MODIFIABLE
    XCP_BLOB_RESTRICTABLE CKA_IBM_RESTRICTABLE
    XCP_BLOB_USE_AS_DATA CKA_IBM_USE_AS_DATA
    XCP_BLOB_WRAP CKA_WRAP
    XCP_BLOB_TRUSTED CKA_TRUSTED
    XCP_BLOB_WRAP_W_TRUSTED CKA_WRAP_WITH_TRUSTED

ECC verify operations are performed with the public key, which has no key usage flags. All flags apply to the private secure key blob only.

Format: 

int zpc_ec_key_set_flags(
    struct zpc_ec_key *key, 
    unsigned int flags );

Parameters:

Direction Name Description
input, output key Pointer to an ECC key
input flags Key flags

Return codes:

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

zpc_ec_key_set_mkvp

Purpose: Set the ECC key master key verification pattern (MKVP).

Format: 

int zpc_ec_key_set_mkvp(
    struct zpc_ec_key *key, 
    const char *mkvp );

Parameters:

Direction Name Description
input, output key Pointer to an ECC key
input mkvp Pointer to a master key verification pattern (MKVP). 8 bytes for CCA master keys, 16 or 32 bytes for EP11 master keys .

For CCA and ECC keys, you can obtain the MKVP from the sys file system:

Example for a CCA key MKVP:
# cat /sys/bus/ap/devices/0f.004c/mkvps  /* example for a CCA coprocessor */
AES NEW: full 0x71ecf46a35bd8924
AES CUR: valid 0x71ecf46a35bd8924 <- applicable for AES keys
AES OLD: valid 0x44185b7673bb43d1
APKA NEW: full 0x71772e2bf9e44214
APKA CUR: valid 0x71772e2bf9e44214 <- applicable for ECC keys
APKA OLD: valid 0x44185b7673bb43d1
Example for an EP11 key MKVP:
# cat /sys/devices/ap/card10/10.004c/mkvps     /* example for anvEP11 coprocessor */
WK CUR: valid 0x8b8f5cb64a0b5ffb69849be2959b9fe89eab896877b87bf43abf121878ad3587
WK NEW: committed 0x30a56ddde64c79ef69bb0928e0575aca278af88b1fa156ccd25cc57ca2dd1fed

MKVPs on EP11 coprocessors are not distinguished between AES keys or ECC keys.

Only the first 16 bytes of an EP11 MKVP are relevant. The second 16 bytes can be omitted.

Return codes:

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

zpc_ec_key_set_type

Purpose: Set the ECC key type.

The following ECC key types are defined: 

#define ZPC_EC_KEY_TYPE_CCA     0x1F
#define ZPC_EC_KEY_TYPE_EP11    7
Format: 

int zpc_ec_key_set_type(
    struct zpc_ec_key *key, 
    int type );

Parameters:

Direction Name Description
input, output key Pointer to an ECC key
input type ZPC_EC_KEY_TYPE_CCA for an ECC key supported on a CCA cryptographic coprocessor or ZPC_EC_KEY_TYPE_EP11 for an ECC key supported on an EP11 cryptographic coprocessor.

Make sure the appropriate cryptographic library EP11 or CCA host library is installed. Otherwise, the adequate error code (ZPC_ERROR_CCA_HOST_LIB_NOT_AVAILABLE or ZPC_ERROR_EP11_HOST_LIB_NOT_AVAILABLE) is issued.

Return codes:

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