Community articleUFLValidateHMACWithSecret function
Added by IBM contributorIBM on August 16, 2011
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

No abstract provided.


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 UFLVerifySignature function to validate the signature.


   r_error  UFLValidateHMACWithSecret(
      formNodeP theObject,
      r_charP theSecret,
      Certificate *theServerCert,
      SecurityUserStatusType *functionStatus,
      r_short *validateStatus


Table 1. Function parameters
theObject formNodePThe node that represents the signature item.
theSecretr_charPThe 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.
theServerCertCertificate*The 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.
functionStatusSecurityUserStatusType*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).
validateStatus r_short*A constant that indicates whether the HMAC signature is valid. See the Returns section for a complete list.


OK on success or an error code on failure.
Additionally, the validateStatus pointer will contain one of the following codes, depending on the status of the signature::
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.


The following example uses UFLGetSignature to get the signature object, and uses Signature_GetDataByPath to get the signer's identity from the signature object. It then calls UFLValidateHMACWithSecret to validate the signature. Finally, it releases the signature object.
   r_error checkSignature(formNodeP theSignatureNode, Certificate *theServerCert, 
      r_short *validation)
   Signature *theSignatureObject;
   r_charP theSecret;
   r_charP signerCommonName;
   r_boolean encodedData;
   SecurityUserStatusType theStatus;
   r_error error;
      if ((error = UFLGetSignature(theSignatureNode, &theSignatureObject))
         != OK)
         fprintf(stderr, "UFLGetSignature error %ld.\n", error);
      if ((error = Signature_GetDataByPath(theSignatureObject, 
         "SigningCert: Subject: CN", NOTOK, &encodedData, 
         &signerCommonName)) != OK)
         fprintf(stderr, "Signature_GetDataByPath error %ld./n", 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. */
      if ((error = UFLValidateHMACWithSecret(theSignatureNode, theSecret, 
         theServerCert, &theStatus, validation)) != OK)
         fprintf(stderr, "UFLValidateHMACWithSecret error %ld.\n", error);
      /* Check the status in case the process required user input. */
      if (theStatus != SUSTATUS_OK)
         fprintf(stderr, "User input required to sign form./n");
      /* Release the reference to the signature object. */

Parent topic:
FormNodeP functions