tpf_encrypt_data: Encrypt data using key from keystore

This function encrypts data using a key from the keystore and returns the encrypted data and decryption key name to the application.

Last updated

Changed for PUT07
Added for PUT04

Format

#include <tpf/tpfapi.h>
int tpf_encrypt_data(char *encrypt_key_name,
                     char *data,
                     int   data_length,
                     char *encrypt_buffer,
                     char *icv_ptr,
                     char *decrypt_key_name);

encrypt_key_name: A pointer to an 8-byte encryption key name. The name must be left-justified, either null-terminated or padded with blanks, and consist of uppercase letters, numbers, or both.
data: A pointer to the data to encrypt.
data_length: The length of the data to encrypt. The minimum length is the cipher block size of the cipher algorithm being used, and the maximum length is 1 MB. The length must be a multiple of the cipher block size.
encrypt_buffer: A pointer to the buffer into which the encrypted data is placed. This can be the same address of the data to encrypt.
icv_ptr: A pointer to the initial chaining vector (ICV). The ICV length depends on the cipher algorithm being used. For CBC ciphers, this field contains a pointer to the output chaining vector (OCV) upon return. For non-CBC ciphers, set this field to NULL.
decrypt_key_name: A pointer to an 8-byte buffer that will contain the decryption key name upon return. The name will be left-justified and padded with blanks. Specify this key name on the tpf_decrypt_data function to decrypt the data that was encrypted by this function.

Normal return

TPF_ENCRYPT_OK: The data was encrypted successfully.

Error return

TPF_ENCRYPT_DATA_LENGTH_ERROR: The length of the data to be encrypted is either too large or not a multiple of the cipher block size of the cipher algorithm being used.
TPF_ENCRYPT_INACTIVE_KEY: The specified encryption key name exists but is not active.
TPF_ENCRYPT_INTERNAL_ERROR: An internal processing error occurred or the z/TPF keystore was disabled.
TPF_ENCRYPT_NO_HARDWARE: The hardware needed to process this function is either not installed or not enabled.
TPF_ENCRYPT_NO_ICV: The ICV was not specified and is required for CBC ciphers.
TPF_ENCRYPT_NO_KEY: The specified encryption key name does not exist.
TPF_ENCRYPT_NO_SUPPORT: The keystore is not defined.
TPF_ENCRYPT_NOT_AUTH: The application program that issued this function is not authorized to use the encryption key. The secure symmetric key usage user exit verifies this authorization.
TPF_ENCRYPT_POINTER_NOT_VALID: An input parameter pointer was not valid.
TPF_ENCRYPT_STATE_ERROR: Secure key restart processing had not completed.

Programming considerations

The secure symmetric key usage user exit is called when this function is issued. This user exit verifies that the application program calling this function is authorized to use the specified key.

Examples

The following example encrypts data.

#include <tpf/tpfapi.h>

int app_enc_dec() {

   char* encrypt_key_name = malloc(8);
   char* data = malloc(8);
   int   data_length = sizeof(data);

   strcpy (encrypt_key_name,"ENC1");
   strcpy (data,"ENCRYPT1");

   rc = tpf_encrypt_data(encrypt_key_name,data,data_length,data, NULL,decrypt_key_name);
   if (rc != 0)
     printf("Encrypt Failed\n");
}