tpf_secure_key_import: Import and add symmetric key to keystore

This function imports a symmetric key that was encrypted with a z/TPF system public key, decrypts the symmetric key using the corresponding z/TPF private key, and adds the symmetric key to the symmetric keystore.

Last updated

Changed in 2022.
Changed in 2020 (information only; no code change).
Changed for PUT07.
Added for PUT06.

Format

maketpf_env += oco
LIBS := CPKL
#include  <tpf/tpfapi.h>
int tpf_secure_key_import(char *encrypted_key,
                          char *key_pair_name,
                          char *encrypt_key_name,
                          char *decrypt_key_name,
                          int cipher,
                          int padding);

encrypted_key

A pointer to the symmetric key that is encrypted with a z/TPF public key. The length of the field that contains the symmetric key is dependent on the size of the z/TPF public key.

key_pair_name

A pointer to the 8-byte z/TPF public key pair name whose public key was used to encrypt the symmetric key and whose private key will be used to decrypt the symmetric key. The name must consist of letters, numbers, or both. If the name is less than 8 bytes, it must be left-justified and either null-terminated or padded with blanks. All letters are converted to uppercase.

encrypt_key_name

A pointer to the 8-byte encryption key name of the symmetric key to be added to the keystore. The name must consist of letters, numbers, or both. If the name is less than 8 bytes, it must be left-justified and either null-terminated or padded with blanks. All letters are converted to uppercase.

decrypt_key_name

A pointer to the 8-byte decryption key name of the symmetric key to be added to the keystore. The name must consist of letters, numbers, or both. If the name is less than 8 bytes, it must be left-justified and either null-terminated or padded with blanks. All letters are converted to uppercase.

cipher

The cipher of the symmetric key. Specify one of the following values:

TPF_TDES: Triple Data Encryption Standard (TDES), which is a 64-bit block cipher algorithm with a 168-bit key.
TPF_AES128: Advanced Encryption Standard 128 (AES128), which is a 128-bit block cipher algorithm with a 128-bit key.
TPF_AES256: Advanced Encryption Standard 256 (AES256), which is a 128-bit block cipher algorithm with a 256-bit key.
TPF_TDES_CBC: The TDES cipher algorithm operating in cipher block chaining mode.
TPF_AES128_CBC: The AES128 cipher algorithm operating in cipher block chaining mode.
TPF_AES256_CBC: The AES256 cipher algorithm operating in cipher block chaining mode.

padding

The padding method that was used to encrypt the symmetric key using the z/TPF public key. Specify one of the following:

TPF_RSA_PKCS1_OAEP_PADDING: Public Key Cryptography Standards (PKCS) #1 v2.0 padding.
TPF_RSA_PKCS1_PADDING: PKCS #1 v1.5 padding.

Normal return

TPF_KEY_IMPORT_OK: The function completed successfully.
TPF_KEY_IMPORT_PARITY_ERROR: The TDES key was added to the keystore, but the parity is not correct.

Error return

TPF_KEY_IMPORT_CORRUPTION_ERROR

Keystore corruption was detected in the z/TPF keystore.

TPF_KEY_IMPORT_DECRYPT_KEY_EXISTS

The decryption key name of the symmetric key to be added to the symmetric keystore already exists.

TPF_KEY_IMPORT_DISKIO_ERROR

A disk I/O error occurred when the z/TPF system attempted to update the symmetric keystore.

TPF_KEY_IMPORT_FILE_FULL

The symmetric keystore is full.

TPF_KEY_IMPORT_INCORRECT_PRIVATE_KEY

The symmetric key decryption failed due to one of the following:

The symmetric key was encrypted with a z/TPF public key, but the wrong public key pair name was specified as input to this function.
The symmetric key was encrypted using one padding method, but a different padding method was specified as input to this function.
The z/TPF keystore was disabled

TPF_KEY_IMPORT_INTERNAL_ERROR

An internal processing error occurred.

TPF_KEY_IMPORT_INVCIPHER

The specified cipher is not valid.

TPF_KEY_IMPORT_KEY_NAME_NOT_VALID

The public key pair name, or the encryption or decryption key name of the symmetric key to be added to the symmetric keystore does not contain valid characters.

TPF_KEY_IMPORT_KEYSIZE_MISMATCH

The decrypted symmetric key is a different size than expected based on the cipher value, so the wrong cipher value was specified as input to this function.

TPF_KEY_IMPORT_NO_HARDWARE

The hardware needed to process this function is not installed.

TPF_KEY_IMPORT_NO_PKKEY_NAME

The specified public key pair name does not exist.

TPF_KEY_IMPORT_NO_SUPPORT

The PKI keystore is not defined.

TPF_KEY_IMPORT_NOT_AUTH

The application program that issued this function is not authorized to add the imported keys to the symmetric keystore. The secure symmetric key import user exit verifies this authorization.

TPF_KEY_IMPORT_PADDING_NOT_VALID

The specified padding method is not valid.

TPF_KEY_IMPORT_PKKEY_NOT_ACTIVE

The specified public key pair name is not active.

TPF_KEY_IMPORT_POINTER_NOT_VALID

An input parameter pointer is not valid.

TPF_KEY_IMPORT_STATE_ERROR

Secure key restart processing has not completed.

TPF_KEY_IMPORT_WORKLIST_FULL

The secure key management worklist is full. Retry this function later.

TPF_KEY_IMPORT_WORKLIST_IOERROR

A disk I/O error occurred when the z/TPF system attempted to update the secure key management worklist.

Programming considerations

The secure symmetric key import user exit is called when this function is issued to verify that the application program calling this function is authorized to add this imported key to the symmetric keystore.
Control is returned to the application program when the imported key is added to the symmetric master keystore. A console message is displayed when the imported key is subsequently added to the symmetric memory keystore on all processors. If the key could not be added to the symmetric memory keystore on all processors, it is removed from the symmetric master keystore.
The key that is imported cannot be used until you activate it (via the ZKEYS ACTIVATE command).
You must backup the z/TPF keystore (via the ZKEYS BACKUP command) before activating the key.
To use this function, you must include the OCO environment and CPKL library (see prototype) in your makefile.

Examples

The following example imports an encrypted symmetric key and adds it to the symmetric keystore.

maketpf_env += oco
LIBS := CPKL
#include <tpf/tpfapi.h>
#define  ERROR   -1

int dec_symmetric_key(char *symmetric_key, int cipher)
{
    char* encrypt_key_name = malloc(8);
    char* decrypt_key_name = malloc(8);
    char* keypair_name = malloc(8);
    int   rc;

    strcpy (encrypt_key_name,"ENC1");
    strcpy (decrypt_key_name,"DEC1");
    strcpy (keypair_name,"KEYPAIR");
    cipher = TPF_AES256_CBC;
    padding = TPF_RSA_PKCS1_OAEP_PADDING;

    rc = tpf_secure_key_import(symmetric_key,
                               keypair_name,
                               encrypt_key_name,
                               decrypt_key_name,
                               cipher,
                               padding);

    if (rc != 0)
       return (ERROR); 
}