tpf_cryptc: Encrypt and Decrypt Data

Use this function to encrypt and decrypt data.

This function uses one of the following cipher algorithms to encrypt and decrypt data:
  • Data Encryption Standard (DES)
  • Triple Data Encryption Standard (TDES or 3DES)
  • DES_CBC, which is the DES cipher algorithm operating in cipher block chaining mode
  • TDES_CBC, which is the TDES cipher algorithm operating in cipher block chaining mode
  • Advanced Encryption Standard - 128-bit key (AES128)
  • AES128_CBC, which is the AES128 cipher algorithm operating in cipher block chaining mode
  • Advanced Encryption Standard - 256-bit key (AES256)
  • AES256_CBC, which is the AES256 cipher algorithm operating in cipher block chaining mode.

Last updated

  • Changed in 2019.
  • Changed for PUT03.
  • Added for PUT02.

Format

#include <tpfapi.h>
int tpf_cryptc(int function, int cipher, struct tpf_crypt_parms *parms);
function
Specifies whether you want to encrypt or decrypt data.
TPF_ENC
Encrypts data.
TPF_DEC
Decrypts data.
cipher
Specifies the cipher algorithm that is used to encrypt or decrypt data. Specify one of the following:
TPF_DES
Is a 64-bit block cipher algorithm with a 56-bit key.
TPF_TDES
Is a 64-bit block cipher algorithm with a 168-bit key.
TPF_AES128
Is a block cipher algorithm with a 128-bit key.
TPF_AES256
Is a block cipher algorithm with a 256-bit key.
TPF_DES_CBC
Is the DES cipher algorithm operating in cipher block chaining mode.
TPF_TDES_CBC
Is the TDES cipher algorithm operating in cipher block chaining mode.
TPF_AES128_CBC
Is the AES128 cipher algorithm operating in cipher block chaining mode.
TPF_AES256_CBC
Is the AES256 cipher algorithm operating in cipher block chaining mode.
parms
A pointer to the tpf_crypt_parms structure, which contains the following required parameters:
  • A pointer to the data to be ciphered.
  • The length of the data to be ciphered. Valid values for this parameter are 8 - 1000000 bytes, in multiples of 8 bytes for DES and TDES ciphers, 16 bytes for AES ciphers.
  • A pointer to the ciphered data. This address can be the same address of the data to be ciphered, in which case the same storage is used for input and output. The ECB must have write access to this storage.
  • A pointer to the key used to cipher the data. For the DES and DES_CBC cipher algorithms, this address points to an 8-byte key. For the TDES and TDES_CBC cipher algorithms, this address points to three 8-byte keys (24 consecutive bytes). For the AES128 and AES128_CBC cipher algorithms, this address points to a 16-byte key. For the AES256 and AES256_CBC cipher algorithms, this address points to a 32-byte key.
  • A pointer to the initial chaining vector.
    • For DES_CBC and TDES_CBC, this parameter contains the address of an 8-byte initial chaining vector (ICV) that is used to cipher the data.
    • For AES128_CBC and AES256_CBC, this parameter contains the address of a 16-byte initial chaining vector (ICV) that is used to cipher the data.

    For CBC ciphers, this field contains a pointer to the output chaining vector (OCV) upon return.

See tpfapi.h for more details about the tpf_crypt_parms structure.

Normal return

Table 1. tpf_cyrptc Normal Return
Value Name Return Code Description
TPF_CRYPT_OK 0 The function was completed successfully.

Error return

Table 2. tpf_cyrptc Error Return
Value Name Return Code Description
TPF_CRYPT_NOADDR 4 The address of the data to be ciphered or the address where the ciphered data is placed was not specified.
TPF_CRYPT_BADLENG 8 The length of the data to be ciphered is not valid.
TPF_CRYPT_NOKEY 12 The address of the key used to cipher the data was not specified.
TPF_CRYPT_NOICV 16 The address of the initial chaining vector was not specified.
TPF_CRYPT_INVREQ 20 The specified function is not valid.
TPF_CRYPT_INVCIPHER 24 The specified cipher algorithm is not valid or the TPF_DES or TPF_DES_CBC is specified, but the necessary CP Assist for Cryptographic Function (CPACF) hardware is not available..
TPF_CRYPT_CIPH_ERROR 28 An internal error occurred when the data was ciphered.

Programming considerations

  • If the CPACF is installed and the specified cipher is enabled, data is ciphered by the CPACF. Otherwise, data is ciphered by z/TPF system software. Enter the ZCPAC QUERY command to display the ciphers that are enabled on the CPACF.
  • You can specify the TPF_DES or TPF_DES_CBC parameter only when the CPACF hardware is available, otherwise a TPF_CRYPT_INVCIPHER error is returned.

Examples

The following example uses the TDES cipher algorithm to encrypt data at the address pointed to by plain_text: 
#include <tpfapi.h>

....
struct tpf_crypt_parms parms;
char *plain_text;
char *ciphered_text;
int size;
char TDES_key[24];
.....
.....
parms.tpf_crypt_in = plain_text;
parms.tpf_crypt_len = size;   
parms.tpf_crypt_out = ciphered_text;  
parms.tpf_crypt_key = TDES_key;                   
                                                  

rc = tpf_cryptc(TPF_ENC, TPF_TDES, &parms);