tpf_keystore_add_key: Add key to keystore

This function adds a key to the master keystore and the memory keystore on all processors.

Last updated

Changed in 2022.
Changed for PUT05.
Added for PUT04.

Format

#include <tpf/tpfapi.h>
int tpf_keystore_add_key(char *encrypt_key_name,
                         char *decrypt_key_name,
                         char *key_ptr,
                         int cipher);

encrypt_key_name

A pointer to an 8-byte encryption key name. 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 an 8-byte decryption key name. 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.

key_ptr

A pointer to the key.

cipher

Specifies one of the following cipher algorithms:

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.

Normal return

TPF_KEYS_ADD_OK: The key was successfully added to the master keystore.
TPF_KEYS_ADD_PARITY_ERROR: The TDES key was added to the keystore, but the parity is not correct.

Error return

TPF_KEYS_ADD_CIPHER_NOT_VALID: The specified cipher algorithm is not valid.
TPF_KEYS_ADD_CORRUPTION_ERROR: Keystore corruption was detected when the z/TPF system attempted to update the master keystore.
TPF_KEYS_ADD_DISKIO_ERROR: A disk I/O error occurred when the z/TPF system attempted to update the master keystore.
TPF_KEYS_ADD_FILE_FULL: The master keystore is full.
TPF_KEYS_ADD_INTERNAL_ERROR: An internal processing error occurred.
TPF_KEYS_ADD_KEY_EXISTS: The decryption key name already exists.
TPF_KEYS_ADD_NAME_NOT_VALID: The encryption or decryption key name does not contain valid characters.
TPF_KEYS_ADD_NO_HARDWARE: The hardware needed to process this function is either not installed or not enabled.
TPF_KEYS_ADD_NO_SUPPORT: The keystore is not defined.
TPF_KEYS_ADD_NOT_AUTH: The application program that issued this function is not authorized to add keys to the keystore. The secure symmetric key creation user exit verifies this authorization.
TPF_KEYS_ADD_POINTER_NOT_VALID: An input parameter pointer was not valid.
TPF_KEYS_ADD_STATE_ERROR: Secure key restart processing had not completed.
TPF_KEYS_ADD_WORKLIST_FULL: The secure key management worklist is full. Retry this function when the secure key system is not overloaded.
TPF_KEYS_ADD_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 creation user exit is called when this function is issued. This user exit verifies that the application program calling this function is authorized to add keys to the keystore.
Control is returned to the application program when the key is added to the master keystore. A console message is displayed when the key is subsequently added to the memory keystore on all processors. If the key could not be added to the memory keystore on all processors, it is removed from the master keystore.
The key that is created cannot be used until you activate it (by using the ZKEYS ACTIVATE command).
You must backup the master keystore (by using the ZKEYS BACKUP command) before activating the key.

Examples

The following example adds a key to the keystore.

#include <tpf/tpfapi.h>

int app_add_key(char* key) {

   char*	encrypt_key_name = malloc(8);
   char*	decrypt_key_name = malloc(8);

   strcpy (encrypt_key_name,"ENC1");
   strcpy (decrypt_key_name,"DEC1");

   rc = tpf_keystore_add_key(encrypt_key_name, decrypt_key_name,  key, TPF_AES256_CBC);
   if (rc == 0)
     printf("Add Successful\n");
}