Have you ever needed to verify the status of a digital signature (“DigSig”) field in a form? A typical scenario would be that a form is to be signed prior to being submitted and you don’t want the submit button to be available until the user has successfully signed the form. Unfortunately, the “lock fields after signing” feature, available as of Designer/Acrobat 8, won’t be enough in this case because it’ll only lock the fields after a signature has been applied; it won’t also make the submit button visible/enabled.
There’s a feature in Acrobat’s scripting object model that lets you determine the status of a DigSig field (i.e. whether it’s signed or not): It’s the AcroForm Field object’s signatureValidate() method which returns a status code indicating the state of the signature field. In particular, the method returns 0 if the DigSig field is empty (hasn’t been signed) and 4 if the DigSig applied is valid and the identify of the signer was verified.
Note: This method cannot validate the status of an XML Data Signature which is different from a traditional DigSig.
Accessing the AcroForm Field Object
To access the AcroForm Field object that represents the XFA DigSig field in your form, you have to use the AcroForm Doc object’s getField() method and give it the name of the field you’re looking for.
To access the Doc object, you simply need to access the event.target property in any XFA event. This property is the Doc object. From there, you call getField() and you give it the name of the DigSig field as it’s defined in the AcroForm DOM. That’s the tricky part: Your field’s full name is its SOM expression (shown here for a DigSig field in a page subform named “PageSubform1”):
xfa.form.form1.PageSubform1.SignatureField1
however its AcroForm Field Name looks like this:
form1[0].PageSubform1[0].SignatureField1[0]
Fortunately, I’ve already written some JavaScript that generates the above syntax: Copy and paste the script from my AcroForm Field Name Generator into your event and all you have to do in your script is call GetFQSOMExp(DigSigField) where “DigSigField” is the XFA DigSig field whose AcroForm Field name you can to get.
From there, you simply make a call to the signatureValidate() method:
var status = event.target.getField(GetFQSOMExp(DigSigField).signatureValidate();
switch (status)
{
case 0:
case 1:
// not signed...
break;
case 2:
// invalid signature...
break;
case 3:
// valid but identity of signer cannot be verified...
break;
case 4:
// valid signature...
break;
default:
// error -- unexpected status code
break;
}
PreSign and PostSign Events
A key component to making this work is the ability to verify the status of the signature after the user has interacted with the DigSig field. You may think of using either the Click or MouseUp events on the DigSig field however there’s a bug in Acrobat/Reader 9 (and older) that prevents the Click and MouseUp events from coming through if the user successfully applies a signature (if they cancel-out of the digital signature dialog that appears when they click in the DigSig field, the events fire but not if they apply a signature).
Fortunately, XFA 2.8 includes new PreSign and PostSign events which occur just before and immediately after clicking on the DigSig field and they behave correctly. The only drawback here is that they are only available for scripting in Designer 8.2 and only work in Acrobat/Reader 9 or greater.
Note that if you wanted to check for signature status on start-up, the DocReady event is the correct place to do it. Initialize, FormReady and LayoutReady events are too soon in the initialization sequence for signature status to be available.
Sample Form
Getting back to our use case where we want to show the submit button only once the user has signed the form, you would simply script the DigSig field’s PreSign event to show the button and then the PostSign event to check the status of the signature. If it’s not valid (the user didn’t apply a signature or there’s something wrong with the signature that was applied), you would then hide the submit button again.
The reason why you would show the submit button in PreSign and hide it again in PostSign is because showing the button in PostSign after applying a good signature would invalidate the signature’s status (the status would become “unknown”) because the form would be modified after signing. By showing the button after signing when it was hidden prior to it, the form would no longer be the state in which it was when it was signed (which is one reason for DigSigs in the first place — to ensure that the document is in the same state as which it was when the user signed it, otherwise the document may have been maliciously modified between the time when the user signed it and the time at which you received it).
Download sample [pdf]
(Note that you’ll need a digital ID to run the sample; if you don’t, you can easily create one in the digital signature dialog that appears when you click on the DigSig field.)
Sample Minimum Requirements: Designer 8.2, Acrobat 9.0
Posted by Stefan Cameron on November 5th, 2008
Filed under
Acrobat,
Bugs,
Scripting,
Tutorials,
XFA
