tpf_RSA_verify: Verify a digital signature of contiguous data by using an RSA public key

Use this function to verify a digital signature of 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_verify(unsigned char *data,
                   size_t data_len,
                   unsigned char *signature,
                   int key_type,
                   void *pubkey_input,
                   int digest_type,
                   int padding,
                   int options);
data
A pointer to the data to which the signature is verified.
data_len
The length (in bytes) of the signed data. Valid values are 1 - 1000000.
signature
A pointer to the digital signature to verify.
key_type
The location from which the pubkey_input parameter is retrieved. You must set it to one of the following values:
TPF_RSA_USE_KEY_PAIR_NAME
The public key is retrieved from the z/TPF keystore by using a key pair name that is pointed to by the pubkey_input parameter.
TPF_RSA_USE_RSA
The public key is retrieved from an RSA structure that is pointed to by the pubkey_input parameter.
TPF_RSA_USE_PUBLIC_KEY_FILE
The public key is retrieved from a file on the z/TPF file system that is pointed to by the pubkey_input parameter. The public key file must be in PKCS #1 format.
TPF_RSA_USE_CERTIFICATE_FILE
The public key is retrieved from a certificate on the z/TPF file system that is pointed to by the pubkey_input parameter.
TPF_RSA_USE_X509
The public key is retrieved from an X509 structure that is pointed to by the pubkey_input parameter.
pubkey_input
You must set it to one of the following values:
key_pair_name
A pointer to the 8-byte RSA key pair name that is created on 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.
rsa
A pointer to the RSA structure that contains the public key.
public_key_file_name
A pointer to a null-terminated string that specifies the file that contains the public key. The public key needs to be encoded in a PKCS#1 RSAPublicKey structure. The maximum length of the file name is 1024 characters.
certificate_file_name
A pointer to a null-terminated string that specifies the file that contains the digital certificate that contains the public key. The certificate must be in X509 format. The maximum length of the file name is 1024 characters.
X509
A pointer to the X509 structure that contains the public key.
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_POINTER_NOT_VALID
An input parameter pointer is not valid.
TPF_RSA_SIG_FILE_READ_ERROR
The file containing the public key or certificate cannot be read.
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_LIBRARY_ERROR
An encryption library function did not produce a valid return.
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_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_STATE_ERROR
TPF_RSA_USE_PUBLIC_KEY_FILE or TPF_RSA_USE_CERTIFICATE_FILE was specified, and file system restart is not completed, or public key restart processing is not completed.
TPF_RSA_SIG_TYPE_NOT_VALID
The specified key type is not valid.
TPF_RSA_SIG_VERIFY_FAILED
The digital signature is not valid because data is corrupted or the wrong public key was specified.

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.
  • The Crypto Express hardware accelerator must be installed and configured to the z/TPF Logical partition (LPAR) to use this function.
  • If the key_type parameter is set to TPF_RSA_USE_KEY_PAIR_NAME, secure key management for public key cryptography must be enabled to use this function.
  • If the data is not contiguous, use the tpf_RSA_verify_init, tpf_RSA_verify_update, and tpf_RSA_verify_final functions to verify the digital signature.

Examples

The following example verifies a digital signature of 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");
   else{
     rc = tpf_RSA_verify((unsigned char *)data, data_length, sigret,
                              TPF_RSA_USE_KEY_PAIR_NAME, key_pair_name, 
                              digest_type, padding, 0);
     if (rc != TPF_RSA_SIG_OK)
       printf("data signature verification failed\n");
   }

   return(rc);
}