Community articleUFLGetEngineCertificateList function
Added by IBM contributorIBM on May 2, 2012
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

No abstract provided.



Description

This function locates all available certificates for a particular signing engine.
Note that each certificate in the list is tracked by reference counts. Once you are done with the certificates, you must release the reference counts to the certificates and free the array (see the example for details).

Function

   r_error UFLGetEngineCertificateList(
      r_charP engineName,
      SecurityUserStatusType *theStatus,
      Certificate ***theCertificate,
      r_long *certCount);


Parameters

Table 1. get engine certificate list parameters
ExpressionTypeDescription
engineNamer_charPThe name of the signing engine. Valid signing engines include: Generic RSA, CryptoAPI, Netscape, and Entrust. (Note that Generic RSA is the union of CryptoAPI and Netscape.)
theStatusSecurityUserStatusType*This is a status flag that reports whether the operation was successful. Possible values are:
SUSTATUS_OK — the operation was successful.
SUSTATUS_CANCELLED — the operation was cancelled by the user.
SUSTATUS_INPUT_REQUIRED — the operation required user input, but could not receive it (for example, it was run on a server with no user).
certList Certificate***The list of certificates that the function locates. Note that each certificate object is tracked by reference counts, and must be released. Furthermore, the array must also be freed.
certCount r_long*The number of certificates that the funtion located.


Returns

OK on success or an error code on failure.

Example

The following function uses UFLGetEngineCertificateList to get a list of valid certificates for the CryptoAPI signing engine. Next, the function cycles through the returned certificates and uses Certificate_GetDataByPath to find the certificate with a common name of “IBM® Forms Server”. Signature_GetDataByPath is then used to retrieve the common name from the existing signature, which is used to retrieve a shared secret from a database. The function then uses UFLValidateHMACWithSecret to validate the signature and notarize it using the server certificate. Finally, the example frees the memory.
   r_error serverNotarize(formNodeP theSignatureNode, r_short *validation)
   {
   SecurityUserStatusType theStatus;
   Certificate **certList;
   Signature *theSignatureObject;
   r_charP signerCommonName;
   r_charP theSecret;
   r_charP signerCommonName;
   SecurityUserStatusType theStatus;
   r_boolean encodedData;
   r_long certCount;
   r_long correctCert = -1;
   r_error error;
   r_long i;
 
      if ((error = UFLGetEngineCertificateList("CryptoAPI", &theStatus, 
         &certList, &certCount)) != OK)
      {
         fprintf(stderr, "UFLGetCertificateList error %hd.\n", error);
         return(NOTOK);
      }
 
      /* Check the status, in case the process required user input. */
 
      if (theStatus != SUSTATUS_OK)
      {
         fprintf(stderr, "User input required to retrieve certificate list.
            /n");
         return(NOTOK);
      }
 
      /* Loop through the certificates to find the IBM Forms Server
         certificate */
 
      for (i=0; i<certCount; i++)
      {
         if ((error = Certificate_GetDataByPath(certList [i], 
            "SigningCert: Subject: CN", NOTOK, &encodedData, 
            &signerCommonName)) != OK)
         {
            fprintf(stderr, "Certificate_GetDataByPath error %hd./n", 
               error);
            return(NOTOK);
         }
         if (cp_strcmp(signerCommonName, "IBM Forms Server") == OK)
         {
            correctCert = i;
            cp_free(signerCommonName);
            break;
         }
         cp_free(signerCommonName);
      }
      if (correctCert == -1)
      {
         fprintf(stderr, "Could not locate required certificate.");
         return(NOTOK);
      }
 
      /* Get the signature object. */
            
      if ((error = UFLGetSignature(theSignatureNode, &theSignatureObject))
         != OK)
      {
         fprintf(stderr, "UFLGetSignature error %ld.\n", error);
         return(error);
      }
 
      /* Get the signer's common name from the signature object */
 
      if ((error = Signature_GetDataByPath(theSignatureObject, 
         "SigningCert: Subject: CN", NOTOK, &encodedData, 
         &signerCommonName)) != OK)
      {
         fprintf(stderr, "Signature_GetDataByPath error %ld./n", error);
         return(error);
      }
 
      /* Include external code that matches the signer's identity to a shared 
         secret, and sets theSecret to match.  This is most likely a
         database lookup. */
 
      /* Validate the signature and notarize using the server certificate */
      
      if ((error = UFLValidateHMACWithSecret(theSignatureNode, theSecret, 
         certList [correctCert], &theStatus, validation)) != OK)
      {
         fprintf(stderr, "UFLValidateHMACWithSecret error %ld.\n", error);
         return(error);
      }
 
      /* Check the status in case the process required user input. */
 
      if (theStatus != SUSTATUS_OK)
      {
         fprintf(stderr, "User input required to sign form./n");
         return(NOTOK);
      }
      cp_free(signerCommonName);
 
      /* Release each certificate object in the array */
 
      for(i=0; i<certCount; i++)
      {
         IFSObject_ReleaseRef((IFSObject*)certList [i]);
      }
 
      /* Free the array */
 
      pe_free(certList);
 
      /* Release the signature object */
 
      IFSObject_ReleaseRef((IFSObject*)theSignature);
 
      return(OK);
   }


Parent topic:
XFDL functions