tpf_RSA_sign: Create a digital signature from contiguous data by using an RSA private key

Use this function to create a digital signature from contiguous 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(char *key_pair_name,
                 unsigned char *data,
                 size_t data_len,
                 unsigned char *sigret,
                 size_t *siglen,                                            
                 int digest_type,
                 int padding,
                 int options);
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.
data
A pointer to the data to be signed.
data_len
The length (in bytes) of the data to be signed. Valid values are 1 - 1000000.
sigret
A pointer to the buffer that the signed data is placed in. The buffer size must be at least the size of the RSA key.
siglen
A pointer to an integer that, upon return, will contain the length (in bytes) of the digital signature that was created.
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
options
Reserved for future use; specify a value of 0.

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_LENGTH_ERROR
The length of the data to be signed is too large or less than 1.
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_OPTIONS_NOT_VALID
The specified options are not valid.
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.
  • Use this function when the data to create a digital signature exists in contiguous storage. If the data is not contiguous, use the tpf_RSA_sign_init, tpf_RSA_sign_update, and tpf_RSA_sign_final functions to create the digital signature.

Examples

The following example creates a digital signature from data that is passed by an application.
LIBS := CPKL
maketpf_env += oco
#include <tpf/tpfapi.h>
{
   char key_pair_name[9];
   char data[] = "DATA12345678AbcDefg";

   unsigned char sigret[256];
   int rc;
   size_t data_length;
   size_t siglen;

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

   rc = tpf_RSA_sign(key_pair_name, (unsigned char *)data,
                     data_length, sigret, &siglen, digest_type, padding, 0);
   if (rc != TPF_RSA_SIG_OK)
     printf("data signature failed\n");

   return(rc);
}