tpf_RSA_sign_init: Initialize control structure for creating a digital signature of discontiguous data

Use this function to allocate and initialize the structure that is used by the tpf_RSA_sign_update and tpf_RSA_sign_final functions. You can use the tpf_RSA_sign_init, tpf_RSA_sign_update, and tpf_RSA_sign_final functions to create a digital signature from discontiguous data that is passed by the application.

Last updated

Added in 2019.

Format

LIBS := CPKL
maketpf_env += oco
#include <tpf/tpfapi.h>
int tpf_RSA_sign_init(tpf_sign_verify_CTX **ctx,
                      char *key_pair_name,
                      int digest_type,
                      int padding);

ctx

A pointer to a pointer to the tpf_sign_verify_CTX structure that is allocated and initialized by this function.

key_pair_name

A pointer to the 8-byte RSA key pair name that is created on the z/TPF system. The name must consist of letters, numbers, or both. If the name is less than 8 bytes, it must be left aligned, and null terminated or padded with blanks. All letters are converted to uppercase.

digest_type

The message digest algorithm that is used to create the digital signature. You must set it to TPF_SHA256.

padding

The RSA padding mode that is used to operate the signature. You must set it to one of the following values:

TPF_RSA_PKCS1_PADDING
TPF_RSA_PKCS1_PSS_PADDING

Normal return

TPF_RSA_SIG_OK: The digital signature was created or verified successfully.

Error return

TPF_RSA_SIG_ALGORITHM_NOT_VALID: The specified message digest algorithm is not valid.
TPF_RSA_SIG_INTERNAL_ERROR: An internal processing error occurred.
TPF_RSA_SIG_NO_HARDWARE: The hardware that is needed to process this function is not installed or not enabled.
TPF_RSA_SIG_NO_PKKEY_NAME: The specified public key pair name does not exist or the z/TPF keystore was disabled.
TPF_RSA_SIG_NOT_AUTH: The application program that issued this function is not authorized to access the private key. The private key usage user exit verifies this authorization.
TPF_RSA_SIG_PADDING_NOT_VALID: The specified padding mode is not valid.
TPF_RSA_SIG_PKKEY_NOT_ACTIVE: The specified public key pair name is not active.
TPF_RSA_SIG_POINTER_NOT_VALID: An input parameter pointer is not valid.
TPF_RSA_SIG_STATE_ERROR: Public key restart processing is not completed.

Programming considerations

To use this function, you must include the library that is specified in the prototype in your makefile.
The CPACF must be installed and support the SHA-256 algorithm on the processor that the function call is made from.
To use this function, you must install and configure the Crypto Express hardware accelerator on the z/TPF logical partition (LPAR).
To use this function, you must enable secure key management for public key cryptography.
The private key usage user exit, USKP, is called when this function is issued. This user exit verifies that the application program that calls this function is authorized to access the private key.
For contiguous data, you can use the tpf_RSA_sign function to create the digital signature.

Examples

The following example creates a digital signature from discontiguous data that is passed by an application.

LIBS := CPKL
maketpf_env += oco
#include <tpf/tpfapi.h>
{
   char key_pair_name[9];
   char data1[] = "DATA12345678AbcDefg";
   char data2[] = "hijklmnopqrstuvwxyz";

   size_t siglen;
   unsigned char sigret[256];
   tpf_sign_verify_CTX *my_ctx;
   int rc;

   strcpy(key_pair_name, "PAIR1");
   int digest_type = TPF_SHA256;
   int padding = TPF_RSA_PKCS1_PADDING;

   rc = tpf_RSA_sign_init(&my_ctx, key_pair_name, digest_type, padding);   
   rc = tpf_RSA_sign_update(my_ctx, data1, strlen((char *)data1));
   rc = tpf_RSA_sign_update(my_ctx, data2, strlen((char *)data2));
   rc = tpf_RSA_sign_final(my_ctx, sigret, &siglen);
}