Community articleGetEngineCertificateList function
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 function locates all available certificates for a particular signing engine.

Function

   Function GetEngineCertificateList(
      engineName As String, 
      theStatus As Long 
      ) As CertificateList


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.)
theStatusLongThis 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).


Returns

A collection containing the list of certificates objects.

Example

The following function uses DereferenceEx and GetLiteralByRefEx to locate the signature item in a form. It then uses GetEngineCertificateList and GetDataByPath to locate a server signing certificate. Next, it uses GetSignature and GetDataByPath to get the signer's common name. Finally, it uses ValidateHMACWithSecret to determine if the HMAC signature is valid, and returns “Valid” or “Invalid”, as appropriate.
   Function ValidateHMACSig(Form)
 
      Dim SigObject, XFDL  ' Objects
      Dim TheCerts  ' CertificateList
      Dim Cert, SigningCert  ' ICertificate
      Dim SignerName, SharedSecret, CommonName, SigItemRef  ' Strings
      Dim Validation  ' Integer
      Dim TempNode, SigNode  ' IFormNodeP
 
      Set TempNode = Form
 
      ' Get the SignatureButton node
      
      Set TempNode = Form.DereferenceEx(vbNullString, _
         "PAGE1.HMACSignatureButton", 0, UFL_ITEM_REFERENCE, Nothing)
 
      ' Get the name of the signature item
 
      SigItemRef = TempNode.GetLiteralByRefEx(vbNullString, "signature", _
         0, vbNullString, Nothing)
 
      ' Get the signature item node
 
      Set SigNode = TempNode.DereferenceEx(vbNullString, SigItemRef, 0, _
         UFL_ITEM_REFERENCE, Nothing)
 
      ' Get available server certificates for Generic RSA signing
 
      Set XFDL = CreateObject("PureEdge.xfdl_XFDL")
      Set TheCerts = XFDL.GetEngineCertificateList("Generic RSA", 1) 
         ' vbNull
 
      ' Locate the certificate that has a common name of "User1-CP.02.01".
      ' This is the certificate we will use when verifying the signature.
 
      For Each Cert in TheCerts
         CommonName = Cert.GetDataByPath("SigningCert: Subject: CN", _
            False, 1) ' vbNull
         If CommonName = "User1-CP.02.01" Then
            Set SigningCert = Cert
         End If
 
      Next
 
      ' Get the signature object from the signature node
 
      Set SigObject = SigNode.GetSignature
 
      ' Get the signer's name from the signature object
 
      SignerName = SigObject.GetDataByPath("SigningCert: Subject: CN", _
         False, 1) ' vbNull
 
      ' Include code that matches the signer's identity to a shared secret,
      ' and sets SharedSecret to match. In most cases, this would be a
      ' database lookup. For the purposes of this example, we will simply
      ' assign a value to SharedSecret.
 
      SharedSecret = "secret"
 
      ' Validate the signature
 
      Validation = SigNode.ValidateHMACWithSecret(SharedSecret, _
         SigningCert, 1) ' vbNull
 
      ' Check the validation code and return either "Valid" or "Invalid"
 
      If Validation = UFL_DS_OK Then
         ValidateHMACSig = "Valid"
      Else
         ValidateHMACSig = "Invalid"
      End If
 
   End Function


Parent topic:
XFDL functions