tpf_decrypt_data: Decrypt data using key from keystore

This function decrypts data using a key from the keystore and returns the decrypted data to the application.

Last updated

  • Changed for PUT07
  • Added for PUT04

Format

#include <tpf/tpfapi.h>
int tpf_decrypt_data(char *decrypt_key_name,
                     char *data,
                     int   data_length,
                     char *decrypt_buffer,
                     char *icv_ptr);
decrypt_key_name
A pointer to an 8-byte decryption 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 decrypt.
data_length
The length of the data to decrypt. 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.
decrypt_buffer
A pointer to the buffer into which the decrypted data is placed. This can be the same address of the data to decrypt.
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.

Normal return

TPF_DECRYPT_OK
The data was decrypted successfully.

Error return

TPF_DECRYPT_DATA_LENGTH_ERROR
The length of the data to be decrypted is either too large or not a multiple of the cipher block size of the cipher algorithm being used.
TPF_DECRYPT_INTERNAL_ERROR
An internal processing error occurred or the z/TPF keystore was disabled.
TPF_DECRYPT_NO_HARDWARE
The hardware needed to process this function is either not installed or not enabled.
TPF_DECRYPT_NO_ICV
The ICV was not specified and is required for CBC ciphers.
TPF_DECRYPT_NO_KEY
The specified decryption key name does not exist.
TPF_DECRYPT_NO_SUPPORT
The keystore is not defined.
TPF_DECRYPT_NOT_AUTH
The application program that issued this function is not authorized to use the decryption key. The secure symmetric key usage user exit verifies this authorization.
TPF_DECRYPT_POINTER_NOT_VALID
An input parameter pointer was not valid.
TPF_DECRYPT_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 decrypts data.
#include <tpf/tpfapi.h>

int app_enc_dec() {                   

   char* encrypt_key_name = malloc(8);
   char* decrypt_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");

   //Use decryption key name passed from encrypt function to decrypt the data
   rc = tpf_decrypt_data(decrypt_key_name,data,data_length,data, NULL);
   if (rc != 0)
     printf("Decrypt Failed\n");
}

Related information