To have your BSAFE application access the ICSF, S/390, and IBM zSeries Cryptographic Coprocessor Feature services, you need to add several new elements to your program. These elements are explained with examples in the steps that follow.

1. At the beginning of your program, declare one or more session choosers and also the hardware table list. For information about choosers and the hardware table list, see BSAFE User’s Manual.

   /*-------------------------------------------------------------*
    * SESSION_CHOOSER will replace OLD_CHOOSER.                   *
    *-------------------------------------------------------------*/
   B_ALGORITHM_METHOD **SESSION_CHOOSER = NULL_PTR;
   
   
   /*-------------------------------------------------------------*
    * CCA_VTABLE is a vector table of functions that will be      *
    * substituted for BSAFE equivalents.  It is supplied by IBM   *
    * and will be loaded into your application when you invoke    *
    * QueryCrypto.                                                *
    *-------------------------------------------------------------*/
   HW_TABLE_LIST CCA_VTABLE = (HW_TABLE_LIST)NULL_PTR;                

2. Declare a tag list. The content of the tag list is supplied by BSAFE at the B_CreateSessionChooser call, which is discussed in a later step.

   unsigned char **taglist = (unsigned char **)NULL_PTR;

3. For random number generation, DES encryption or decryption or RSA encryption or decryption, you need to define and declare an additional chooser wherever your current chooser is defined and declared. For instance, suppose your application is doing an RSA encryption, and OLD_CHOOSER is defined as follows:

    /*--------------------------------------------------------------*
     * OLD_CHOOSER is used for this application when ICSF and       *
     * the crypto hardware is not available.                        *
     *--------------------------------------------------------------*/
    B_ALGORITHM_METHOD *OLD_CHOOSER[] = {
      &AM_SHA,
      &AM_RSA_ENCRYT,
      (B_ALGORITHM_METHOD *)NULL_PTR
    };
   
    /*--------------------------------------------------------------*
     * ICSF_CHOOSER is a 'skeleton' for SESSION_CHOOSER.            *
     * SESSION_CHOOSER will be used for this application if         *
     * ICSF and the crypto hardware are not available.              *
     *--------------------------------------------------------------*/
    B_ALGORITHM_METHOD *ICSF_CHOOSER[]  = {
      &AM_SHA,
      &AM_TOKEN_RSA_PUB_ENCRYPT,
      (B_ALGORITHM_METHOD *)NULL_PTR
    };                              

4. At the beginning of the main function in your application, add a call to the ICSF QueryCrypto function followed by a conditional call to the BSAFE B_CreateSessionChooser function.

   /*-------------------------------------------------------------*
    * Check for the existence of crypto hardware.  If it's there, *
    * QueryCrypto will supply CCA_VTABLE                          *
    *-------------------------------------------------------------*/
   if ((status = QueryCrypto(CRYPTO_Q_DES_AND_RSA,&CCA_VTABLE)) == 0)
   /*---------------------------------------------*
                    * B_CreateSessionChooser will replace the     *
                    * BSAFE software functions with their CCA     *
                    * hardware equivalents.                       *
                    *                                             *
                    * Note that the last three parameters are not *
                    * used with CCA                               *
                    *---------------------------------------------*/
     if ((status = B_CreateSessionChooser(ICSF_CHOOSER,
                                         &SESSION_CHOOSER,
                                          CCA_VTABLE,
                                          (ITEM *)NULL_PTR,
                                          (POINTER *)NULL_PTR,
                                            &taglist)) != 0)
       break;

5. Set up the conditions under which any alternate choosers are used to initialize the appropriate algorithm object. For information about initializing algorithm objects, see BSAFE User’s Manual.

    /*-------------------------------------------------------*
     * Initialize the algorithm object with the appropriate  *
     * chooser.                                              *
     *-------------------------------------------------------*/
    if (SESSION_CHOOSER != NULL_PTR)
      if ((status = B_xxxxxxInit
           (xxxxxxObject,SESSION_CHOOSER,
            (A_SURRENDER_CTX *)NULL_PTR)) != 0)
        break;
      else ;
    else
      if ((status = B_xxxxxxInit
           (xxxxxxObject,OLD_CHOOSER,
            (A_SURRENDER_CTX *)NULL_PTR)) != 0)
        break;
      else ;

6. When your application no longer needs the session chooser, program a call to the BSAFE B_FreeSessionChooser function.

   if (SESSION_CHOOSER != NULL_PTR)
     B_FreeSessionChooser(&SESSION_CHOOSER,&taglist);