4
Using the Oracle Cryptographic Toolkit

This chapter shows you how to program using the Oracle Cryptographic Toolkit. The following topics are discussed:

4.1 Basic Oracle Cryptographic Toolkit Program Flow

The following section describes the typical program flow for those who want to use the Oracle Cryptographic Toolkit and provides program code examples for calling the available functions. Refer to Figure 4-1, "Oracle Cryptographic Toolkit Program Flow", below, for an illustration of how a typical program flows using the Oracle Cryptographic Toolkit.

Figure 4-1 Oracle Cryptographic Toolkit Program Flow

4.2 A Programming Example

This section first lists the programming steps to follow when you use the Oracle Cryptographic Toolkit. The balance of this chapter provides the following sample code for your use:

"An Example: Generating a detached signature for an array of bytes"

4.2.1 Using the Oracle Cryptographic Toolkit

Follow steps 1 - 5 to access the Oracle Security Server.

Once the OCI process has been initialized with OCIInitialize and the environment has been initialized with OCIEnvInit (refer to the Programmer's Guide to the Oracle Call Interface), the security handle can be created with OCIHandleAlloc and initialized with OCISecurityInitialize. The security handle is used with subsequent calls to the Oracle Cryptographic Toolkit.

      ... 
      OCIError    *error_handle = (OCIError *) NULL;
      OCISecurity *security_handle = (OCISecurity *) NULL;
      ... 
 
      /* 
       * The OCI process and environment have already been initialized.
       */ 
 
      OCIHandleAlloc((dvoid *) env_handle, (dvoid **) &error_handle, 
                     (ub4) OCI_HTYPE_ERROR,
                     (size_t) 0,(dvoid **) 0),
 
      OCIHandleAlloc((dvoid *) env_handle,
                     (dvoid **) &security_handle,
                     (ub4) OCI_HTYPE_SECURITY, (size_t) 0,
                     (dvoid **) 0);
 
      OCISecurityInitialize(security_handle, error_handle);

Typically, an application will first need to open a wallet in order to get its persona and gain access to the list of trusted identities. The wallet location is specified through a Wallet Resource Locator (WRL), and if the contents have been protected with a password, the correct password must be provided as well.

      ... 
      nzttWallet wallet;
      ... 
 
      OCISecurityOpenWallet(security_handle, error_handle,
                            wrllen, wrl,
                            passlen, password,
                            &wallet)

Next, an application will choose a persona from the wallet and open it to prepare it for use.

      ...
      nzttPersona *persona;
      ...
 
      /*
       * Use the first persona in the wallet.
       */
      persona = &wallet.list_nzttWallet[0];
 
      OCISecurityOpenPersona(security_handle, error_handle, persona);

The application can now perform a cryptographic function such as signing some data:

      ...
      nzttBufferBlock signature;
      ...
 
      memset(&signature, 0, sizeof(signature));
      OCISecuritySign(security_handle, error_handle, persona,
                      NZTTCES_END, strlen((char *)"Some data"),
                      "Some data", &signature);

During termination, the application should call OCIHandleFree to deallocate the security handle once the wallet has been closed and the security subsystem has been terminated.

      OCISecurityCloseWallet(security_handle, error_handle, &wallet); 
      OCISecurityTerminate(security_handle, error_handle); 
      OCIHandleFree((dvoid *) security_handle, OCI_HTYPE_SECURITY);

4.2.2 An Example: Generating a detached signature for an array of bytes

The following code sample shows you how to generate a detached signature for an array of bytes. For brevity, errors are checked but are not displayed. Refer to Part III, "Appendices", for a complete code example.

#include <oratypes.h> 
 
#ifndef OCI_ORACLE 
#include <oci.h> 
#endif 
 
#ifndef OCIDFN 
#include <ocidfn.h> 
#endif 
 
#ifdef __STDC__ 
#include <ociap.h> 
#else 
#include <ocikp.h> 
#endif 
 
static text phrase[] = "This is a static text phrase"; 
 
int main(argc, argv) 
int argc; 
char *argv[]; 
{ 
   nzttWallet wallet;                          /* Wallet structure */ 
   nzttBufferBlock signature;                  /* Detached signature */ 
   nzttPersona *persona = (nzttPersona *)NULL; /* Persona used to sign */  
   OCIEnv *env_handle = (OCIEnv *)NULL;        /* OCI environement handle */ 
   OCIError *error_handle = (OCIError *)NULL;  /* OCI error handle */ 
   OCISecurity *security_handle = (OCISecurity *)NULL; /* OCI security handle*/ 
 
   /* 
    * Clear out the wallet and signature structures so that if an 
    * error occurs before they are used, they are not mistaken for 
    * holding allocated memory. 
    */ 
   memset(&wallet, 0, sizeof(wallet)); 
   memset(&signature, 0, sizeof(signature)); 
    /* 
    * Initialize the OCI process.  
    */ 
   if (OCI_SUCCESS  
       != OCIInitialize((ub4) OCI_DEFAULT,(dvoid *)0,(dvoid *(*)())0, 
                        (dvoid *(*)())0, (void(*)())0)) 
   { 
      goto exit; 
   } 
  
   /* 
    * Initialize the OCI environment. 
    */ 
   if (OCI_SUCCESS  
       != OCIEnvInit((OCIEnv **)&env_handle,(ub4)OCI_DEFAULT, (size_t)0, 
                     (dvoid **)0)) 
   { 
      goto exit; 
   } 
 
   /* 
    * Create an error handle. 
    */ 
   if (OCI_SUCCESS 
       != OCIHandleAlloc((dvoid *)env_handle, (dvoid **)&error_handle, 
                         (ub4)OCI_HTYPE_ERROR, (size_t)0, (dvoid **)0)) 
   { 
      goto exit; 
   } 
 
   /* 
    * Create a security handle 
    */ 
   if (OCI_SUCCESS 
       != OCIHandleAlloc((dvoid *)env_handle, (dvoid **)&security_handle, 
                         (ub4)OCI_HTYPE_SECURITY, (size_t)0, (dvoid **)0)) 
   { 
      goto exit; 
   } 
 

   /* 
    * Initialize the security subsystem. 
    */ 
   if (OCI_SUCCESS != OCISecurityInitialize(security_handle, error_handle)) 
   { 
      goto exit; 
   } 
     
   /* 
    * Open the wallet.  Since NZT_DEFAULT_WRL is used as the wallet 
    * WRL, the platform specific default wallet will be used.  Note, 
    * as well, that this wallet has no password (NZT_NO_PASSWORD).   
    */ 
   if (OCI_SUCCESS  
       != OCISecurityOpenWallet(security_handle, error_handle,  
                                strlen(NZT_DEFAULT_WRL), NZT_DEFAULT_WRL, 
                                strlen(NZT_NO_PASSWORD), NZT_NO_PASSWORD, 
                                &wallet)) 
   { 
      goto exit; 
   } 
    
   /* 
    * Use the first persona in the wallet. 
    */ 
   persona = &wallet->list_nzttWallet[0]; 
 
   /* 
    * Open the persona and prepare it for use. 
    */ 
   if (OCI_SUCCESS  
       != OCISecurityOpenPersona(security_handle, error_handle, persona)) 
   { 
      goto exit; 
   } 
 
   /* 
    * Create a detached signature for the phrase.  This means that 
    * when the signature is verified, the original phrase will need to 
    * be provided since it is not attached to the signature.  The 
    * variable signature contains the output. 
    */ 
   if (OCI_SUCCESS 
       != OCISecuritySignDetached(security_handle, error_handle, persona, 
                                  NZTTCES_END, strlen((char *)phrase),  
                                  phrase, &signature)) 
   { 
      goto exit; 
   } 
 
exit: 
   DISCARD OCISecurityPurgeBlock(security_handle, error_handle, &signature); 
 
   DISCARD OCISecurityCloseWallet(security_handle, error_handle, &wallet); 
 
   /* 
    * Free the various handles (if allocated). Delay freeing the error 
    * handle so that errors can be generated until the last possible 
    * moment. 
    */ 
   if (security_handle) 
   { 
      DISCARD OCISecurityTerminate(security_handle, error_handle); 
      DISCARD OCIHandleFree((dvoid *)security_handle, OCI_HTYPE_SECURITY); 
   } 
 
   if (error_handle) 
   { 
      DISCARD OCIHandleFree((dvoid *)error_handle, OCI_HTYPE_ERROR); 
   } 
 
   if (env_handle) 
   { 
      DISCARD OCIHandleFree((dvoid *)env_handle, OCI_HTYPE_ENV); 
   } 
     
   return 0; 
}

4 Using the Oracle Cryptographic Toolkit