tpf_RSA_verify_final: Verify data against final digital signature value

Use this function to finalize the data in the context (CTX) structure and verify it against the digital signature value. You can use the tpf_RSA_verify_init, tpf_RSA_verify_update, and tpf_RSA_verify_final functions to verify 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_verify_final(tpf_sign_verify_CTX *ctx,
                         unsigned char *sig, 
                         size_t siglen);

ctx: A pointer to the tpf_sign_verify_CTX structure. If a valid pointer is passed into this function, the context (CTX) structure is freed and destroyed upon return.
sig: A pointer to the digital signature to verify the data against.
siglen: The length (in bytes) of the digital signature that is specified by the sig parameter.

Normal return

TPF_RSA_SIG_OK: The digital signature was created or verified successfully.

Error return

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_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.
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.
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.
For contiguous data, you can use the tpf_RSA_verify function to verify the digital signature.

Examples

The following example creates a digital signature from contiguous data by using the tpf_RSA_sign function. It then uses the tpf_RSA_verify_init, tpf_RSA_verify_update, and tpf_RSA_verify_final functions on discontiguous data to verify the signature. Alternatively, you can use the tpf_RSA_sign_init, tpf_RSA_sign_update, and tpf_RSA_sign_final functions to create a digital signature. For the verify step, this example uses the keypair name as the public key input.

LIBS := CPKL
maketpf_env += oco
#include <tpf/tpfapi.h>
{
   char key_pair_name[9];
   char contig_data[] = "ABCDEFG";
  
   size_t siglen;
   unsigned char sigret[256]; 
   tpf_sign_verify_CTX *my_verify_ctx;
   int rc;

   strcpy(key_pair_name, "PAIR1");
   size_t data_length = strlen(contig_data);
   int digest_type = TPF_SHA256;
   int padding = TPF_RSA_PKCS1_PADDING;

   /* Sign contig_data using contiguous API */
   rc = tpf_RSA_sign(key_pair_name, (unsigned char *)contig_data,
                     data_length, sigret, &siglen, digest_type, padding, 0);

   /* Verify using discontiguous APIs */
   rc = tpf_RSA_verify_init(&my_verify_ctx, TPF_RSA_USE_KEY_PAIR_NAME, 
                            key_pair_name, digest_type, padding);

   // Verify updates all but the last character of the data ("ABCDEF")
   rc = tpf_RSA_verify_update(my_verify_ctx, contig_data, data_length-1);

   // Verify updates with the last character of the data ("G")
   rc = tpf_RSA_verify_update(my_verify_ctx, contig_data+(data_length-1), 1); 

   rc = tpf_RSA_verify_final(my_verify_ctx, sigret, siglen);
   if (rc != TPF_RSA_SIG_OK) 
       printf("Verify failed.");