C programs must include the header file csfbext.h, which contains stubs for calling the ICSF services. This file is installed in the HFS directory /usr/include and is copied to SYS1.SIEAHDR.H(CSFBEXT).

Information on creating C applications that call ICSF PKCS #11 services is available in z/OS Cryptographic Services ICSF Writing PKCS #11 Applications.

In addition, C applications that include csfbext.h must be link edited with the appropriate DLL sidedeck for the addressing model:

Standard 31-bit

Link with /usr/lib/CSFDLL31.x or SYS1.SIEASID(CSFDLL31)

31-bit with XPLINK

Link with /usr/lib/CSFDLL3X.x or SYS1.SIEASID(CSFDLL3X)

64-bit

Link with /usr/lib/CSFDLL64.x or SYS1.SIEASID(CSFDLL64)

Information on creating C applications that call ICSF PKCS #11 services is available in z/OS Cryptographic Services ICSF Writing PKCS #11 Applications.

/*-------------------------------------------------------------------*
 * Example using C:                                                  *
 *   Invokes CSNBKGN (key generate), CSNBENC (DES encipher) and      *
 *   CSNBDEC (DES decipher)                                          *
 *-------------------------------------------------------------------*/
#include <stdio.h>
#include "csfbext.h"

/*-------------------------------------------------------------------*
 * Prototypes for functions in this example                          *
 *-------------------------------------------------------------------*/

/*-------------------------------------------------------------------*
 * Utility for printing hex strings                                  *
 *-------------------------------------------------------------------*/
void printHex(unsigned char *, unsigned int);

/*********************************************************************/
/* Main Function                                                     */
/*********************************************************************/
int main(void) {

  /*-----------------------------------------------------------------*
   * Constant inputs to ICSF services                                *
   *-----------------------------------------------------------------*/
  static int textLen = 24;
  static unsigned char clearText[24]="ABCDEFGHIJKLMN0987654321";
  static unsigned char cipherProcessRule[8]="CUSP    ";
  static unsigned char keyForm[4]="OP  ";
  static unsigned char keyLength[8]="SINGLE  ";
  static unsigned char dataKeyType[8]="DATA    ";
  static unsigned char nullKeyType[8]="        ";
  static unsigned char ICV[8]={0};
  static int *pad=0;
  static int exitDataLength = 0;
  static unsigned char exitData[4]={0};
  static int ruleArrayCount = 1;

  /*-----------------------------------------------------------------*
   * Variable inputs/outputs for ICSF services           *
   *-----------------------------------------------------------------*/
  unsigned char cipherText[24]={0};
  unsigned char compareText[24]={0};
  unsigned char dataKeyId[64]={0};
  unsigned char nullKeyId[64]={0};
  unsigned char dummyKEKKeyId1[64]={0};
  unsigned char dummyKEKKeyId2[64]={0};
  int returnCode = 0;
  int reasonCode = 0;
  unsigned char OCV[18]={0};

  /*-----------------------------------------------------------------*
   * Begin executable code                                           *
   *-----------------------------------------------------------------*/
  do {
    /*---------------------------------------------------------------*
     * Call key generate                                             *
     *---------------------------------------------------------------*/
    if ((returnCode = CSNBKGN(&returnCode,
                              &reasonCode,
                              &exitDataLength,
                              exitData,
                              keyForm,
                              keyLength,
                              dataKeyType,
                              nullKeyType,
                              dummyKEKKeyId1,
                              dummyKEKKeyId2,
                              dataKeyId,
                              nullKeyId)) != 0) {
      printf("\nKey Generate failed:\n");
      printf("   Return Code = %04d\n",returnCode);
      printf("   Reason Code = %04d\n",reasonCode);
      break;
      }
   /*---------------------------------------------------------------*
    * Call encipher                                                 *
    *---------------------------------------------------------------*/
   printf("\nClear Text\n");
   printHex(clearText,sizeof(clearText));

   if ((returnCode = CSNBENC(&returnCode,
                             &reasonCode,
                             &exitDataLength,
                             exitData,
                             dataKeyId,
                             &textLen,
                             clearText,
                             ICV,
                             &ruleArrayCount,
                             cipherProcessRule,
                             &pad,
                             OCV,
                             cipherText)) != 0) {
     printf("\nReturn from Encipher:\n");
     printf("   Return Code = %04d\n",returnCode);
     printf("   Reason Code = %04d\n",reasonCode);
     if (returnCode > 4)
       break;
     }

   /*---------------------------------------------------------------*
    * Call decipher                                                 *
    *---------------------------------------------------------------*/
   printf("\nCipher Text\n");
   printHex(cipherText,sizeof(cipherText));

   if ((returnCode = CSNBDEC(&returnCode,
                             &reasonCode,
                             &exitDataLength,
                             exitData,
                             dataKeyId,
                             &textLen,
                             cipherText,
                             ICV,
                             &ruleArrayCount,
                             cipherProcessRule,
                             OCV,
                             compareText)) != 0) {
     printf("\nReturn from Decipher:\n");
     printf("   Return Code = %04d\n",returnCode);
     printf("   Reason Code = %04d\n",reasonCode);
     if (returnCode > 4)
       break;
     }

   /*---------------------------------------------------------------*
    * End                                                           *
    *---------------------------------------------------------------*/
   printf("\nClear Text after decipher\n");
   printHex(compareText,sizeof(compareText));

   } while(0);

   return returnCode;

} /* end main */

void printHex (unsigned char * text, unsigned int len)
/*------------------------------------------------------------------*
 * Prints a string as hex characters                                *
 *------------------------------------------------------------------*/

{
  unsigned int i;

  for (i = 0; i < len; ++i)
    if ( ((i & 7) == 7) || (i == (len - 1)) )
      printf ("  %02x\n", text[i]);
    else
      printf ("  %02x", text[i]);
  printf ("\n");
} /* end printHex */