Community articlegetEngineCertificateList method
Added by IBM contributorIBM on July 26, 2013
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

Description

This method locates all available certificates for a particular signing engine.

Method

   public Certificate [ ] getEngineCertificateList(
      String engineName,
      IntHolder theStatus,
      ) throws UWIException;


Parameters

Table 1. get engine certificate list parameters
ExpressionTypeDescription
engineNameStringThe 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.)
theStatusIntHolderThis is a status flag that reports whether the operation was successful. Possible values are:
SecurityUserStatusType.SUSTATUS_OK — the operation was successful.
SecurityUserStatusType.SUSTATUS_ CANCELLED — the operation was cancelled by the user.
SecurityUserStatusType.SUSTATUS_INPUT_ REQUIRED — the operation required user input, but could not receive it (for example, it was run on a server with no user).


Returns

An array containing the list of certificates objects.

Example

The following method uses getXFDL and getEngineCertificateList to get a list of valid certificates for the CryptoAPI signing engine. Next, the method cycles through the returned certificates and uses getDataByPath to find the certificate with a common name of “IBM® Forms Server”. getDataByPath is then used to retrieve the common name from the existing signature, which is used to retrieve the a shared secret from a database. The method then uses validateHMACWithSecret to validate the signature and notarize it using the server certificate.
   public short serverNotarize(FormNodeP theSignatureNode) throws UWIException
   {
   XFDL theXFDL;
   IntHolder theCertStatus;
   IntHolder theSigStatus;
   Certificate [] certList;
   Signature theSignatureObject;
   String theSecret;
   String signerCommonName;
   booleanHolder encodedData;
   int certCount;
   int correctCert = -1;
   int i;
   short validation;
 
      if ((theXFDL = IFSSingleton.getXFDL()) == null)
      {
         throw new Exception("Could not find interface");
      }
      theCertStatus = new IntHolder();
      if ((certList = theXFDL.getEngineCertificateList("CryptoAPI", 
         theCertStatus)) == null)
      {
         throw new Exception("Could not locate any certificates.");
      }   
      if (theStatus.value == SecurityUserStatusType.SUSTATUS_INPUT_REQUIRED)
      {
         throw new UWIException("User input required to sign form.");
      }
 
      /* Loop through the certificates to find the IBM Forms Server
         certificate */
 
      certCount = certList.length;
      encodedData = new BooleanHolder();
      for (i=0; i<certCount; i++)
      {
         signerCommonName = certList[i].getDataByPath(
            "SigningCert: Subject: CN", false, encodedData);
         if (signerCommonName.equals("IBM Forms Server"))
         {
            correctCert = i;
            break;
         }
      }
      if (correctCert == -1)
      {
         throw new UWIException("Could not locate required certificate");
      }
 
      /* Get the signature object. */
 
      theSignatureObject = theSignatureNode.getSignature();
 
      /* Get the signer's common name from the signature object */
 
      encodedData = new BooleanHolder();
      if ((signerCommonName = theSignatureObject.getDataByPath(
         "SigningCert: Subject: CN", false, encodedData)) == null)
      {
         throw new UWIException("Could not determine signer's name.");
      }
 
      /* 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. */
 
      theSigStatus = new IntHolder();
      
      /* Validate the signature and notarize using the server certificate */
 
      validation = theSignatureNode.validateHMACWithSecret(theSecret, 
         certList[correctCert], theSigStatus);
 
      /* Check the status in case the process required user input. */
 
      if (theStatus.value != SecurityUserStatusType.SUSTATUS_OK)
      {
         throw new UWIException("Validation required user input.");
      }
      return(validation);
   }


Parent topic:
XFDL class