Community articleValidateHMACWithSecret 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 determines whether an HMAC signature is valid. HMAC signatures include both Authenticated Clickwrap and Signature Pad signatures.
For Authenticated Clickwrap signatures, you must know the signer's shared secret to use this function. For Signature Pad signatures, you may use this function without the shared secret if the signature was created without one. In any case, the shared secret should be available from a corporate database or other system.
This function will also notarize (that is, digitally sign) a valid HMAC signature if you provide a digital certificate. However, notarization will not occur if the signature does not include a shared secret. Once notarized, you must use the VerifySignature function to validate the signature.

Function

   Function ValidateHMACWithSecret(
      theSecret As String, 
      theServerCert As ICertificate, 
      theStatus As Long
      ) As Integer


Parameters

Table 1. Function parameters
ExpressionTypeDescription
theSecretStringThe shared secret that identifies the user. This should be available from a corporate database or other system.
If there is more than one shared secret, you must concatenate the strings with no separating characters. For example, if the secrets were "blue" and "red", you would pass "bluered" to the function.
If there is no shared secret pass an empty string.
theServerCertICertificateThe server certificate.
If you pass null, the function will verify the HMAC signature but will not sign it.
If you pass in a certificate and if the HMAC signature is valid, the function will use the private key of the certificate to digitally sign the HMAC signature. This signature is appended to the signature item, and can be verified using UFLVerifySignature.
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 constant if the verification is successful, or throws an exception if an error occurs. The following table lists the possible return values:
Table 2. return codes
CodeNumeric ValueStatus
UFL_DS_OK0The signature is verified.
UFL_DS_ALGORITHM UNAVAILABLE13590The appropriate verification engine for the signature is not available.
UFL_DS_F2MATCHSIGNER13529The certificate does not match the signer's name.
UFL_DS_FAILED AUTHENTICATION1272The signature is invalid or the secret used is incorrect.
UFL_DS_HASHCOMPFAILED13527The document has been tampered with.
UFL_DS_NOSIGNATURE13526There is no signature.
UFL_DS_NOTAUTHENTICATED1240The signer cannot be authenticated.
UFL_DS_UNEXPECTED13589An unexpected error occurred.
UFL_DS_UNVERIFIABLE859The signature cannot be verified.


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:
FormNodeP functions