Community articleUFLValidateHMACWithHashedSecret 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 hash of 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  UFLValidateHMACWithHashedSecret(
			formNodeP theObject,
      r_byte *hashedSecret,
      r_long secretSize,
      Certificate *theCertificate,
      SecurityUserStatusType *theStatus,
      r_short *validateStatus


Table 1. Function parameters
theObject formNodePThe node that represents the signature item.
hashedSecretr_byte*The hash of the 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 and then hash the combined secret. For example, if the secrets were "blue" and "red", you would pass the hash of "bluered" to the function.
If there is no shared secret, pass an empty string.
You must encode the byte array as follows:
Authenticated Clickwrap (HMAC) UTF-8
Signature Pad UTF-16LE
The method for doing this depends on the C library you are using to interface with the API.
secretSize r_longThe size of the hashed secret, measured in bytes.
theCertificateCertificate*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.
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).
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_NOT AUTHENTICATED1240The signer cannot be authenticated.
UFL_DS_UNEXPECTED13589An unexpected error occurred.
UFL_DS_UNVERIFIABLE859The signature cannot be verified.


The following example uses UFLGetSignature to get a signature object, and uses Signature_GetDataByPath to get the signer's identity from the signature object. Next, it calls UFLValidateHMACWithHashedSecret to validate the signature. Finally, it releases the signature object.
   r_error checkSignature(formNodeP theSignatureNode, Certificate *theServerCert, 
      r_short *validation)
   Signature *theSignatureObject;
   r_byte *hashedSecret;
   r_long secretSize;
   r_boolean encodedData;
   r_charP signerCommonName;
   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 hashed 
         shared secret, sets *hashedSecret to match, and sets secretSize to 
         the size of the hashed secret.  This is most likely a database 
         lookup. */
      if ((error = UFLValidateHMACWithHashedSecret(theSignatureNode, 
         hashedSecret, secretSize, theServerCert, &theStatus, validation)) 
         != OK)
         fprintf(stderr, "UFLValidateHMACWithHashedSecret error %ld.\n", 
      /* 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