Forms Server 4 API

Description

This method 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 method. For Signature Pad signatures, you may use this method 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 method 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 method to validate the signature.

Method

public short validateHMACWithSecret(

String theSecret,

Certificate theServerCert,

IntHolder theStatus,

) throws UWIException;

Parameters

Table 1. Method parameters

Expression

Type

Description

theSecret

String

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. For example, if the secrets were "blue" and "red", you would pass "bluered" to the method.

If there is no shared secret pass an empty string.

theServerCert

Certificate

The server certificate.

If you pass null, the method will verify the HMAC signature but will not sign it.If you pass in a certificate and if the HMAC signature is valid, the method 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.

theStatus

IntHolder

This 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

A constant if the verification is successful, or throws a generic exception (UWIException) if an error occurs. The following table lists the possible return values:Table 2. return codes

Code

Numeric Value

Status

FormNodeP.UFL_DS_OK

0

The signature is verified.

FormNodeP.UFL_DS_ALGORITHM UNAVAILABLE

13590

The appropriate verification engine for the signature is not available.

FormNodeP.UFL_DS_F2MATCHSIGNER

13529

The certificate does not match the signer's name.

FormNodeP.UFL_DS_FAILED AUTHENTICATION

1272

The signature is invalid or the secret used is incorrect.

FormNodeP.UFL_DS_HASHCOMPFAILED

13527

The document has been tampered with.

FormNodeP.UFL_DS_NOSIGNATURE

13526

There is no signature.

FormNodeP.UFL_DS_NOTAUTHENTICATED

1240

The signer cannot be authenticated.

FormNodeP.UFL_DS_UNEXPECTED

13589

An unexpected error occurred.

FormNodeP.UFL_DS_UNVERIFIABLE

859

The signature cannot be verified.

Example

The following example uses getSignature to get the signature object, and uses getDataByPath to get the signer's identity from the signature object. It then calls validateHMACWithSecret to validate the signature.

public short checkSignature(FormNodeP theSignatureNode, Certificate theServerCert)

{

Signature theSignatureObject;

String theSecret;

String signerCommonName;

BooleanHolder encodedData;

IntHolder theStatus;

short validation;

theSignatureObject = theSignatureNode.getSignature();

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