Stefan Cameron on Forms
Building intelligent forms using Adobe LiveCycle Designer

Digital Signature Field Status

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
Both comments and pings are currently closed.

6 Responses to “Digital Signature Field Status”

  1. Em D on December 15th, 2008

    Hi Stefan,

    Barely related, but I am not able to get any help on these, thought I shuld try here,

    1. Would it be possible to write a script on a form to read the name/email address from a smartcard using LiveCycle 8 / Acrobat Pro 8 on XP?
    Or – maybe it could read the info from Windows (as shown in MMC – Certificates snap-in)? Are you aware of any code sample available?

    2. Is the “security” object available for JavaScript in LiveCycle 8? Getting the “NotAllowedError”. Am I missing something? Have the Acrobat Pro 8, enabled usage rights – still nothing…

    Thank you a lot

  2. Stefan Cameron on December 19th, 2008

    Em D,

    Unfortunately, I’ve never seen anything to do with smartcard readers so I can’t speak to that. I’m sure there’s some way to do it with LiveCycle but when it comes to accessing that data directly from within an XFA-PDF form running in Acrobat, I wouldn’t know.

    As for the use of the Acrobat security object, it’s not available other than from the console, batch mode or at Acrobat startup which explains the security error when you try to use it in your form’s script.

  3. Kim M on August 3rd, 2009

    Stefan,

    I’m receiving a ‘invalid enumerated value’ error when I try to access your sample .pdf. I also receive this error when I put any script into the preSign or postSign events of my own forms.

    I have Designer 8.2 and Acrobat 9.0 installed.

    Any help would be appreciated.

    Thanks.

    Kim

  4. Stefan Cameron on August 23rd, 2009

    Kim M,

    It sounds like your forms might not be targeting Acrobat 9 and therefore may not have their XFA version set to 2.8 which is required for the use of the PreSign and PostSign events.

    I’m not sure about the “invalid enumerated value” error on my sample form, however. Are you certain you’re running my sample in Acrobat/Reader 9.0?

  5. Pete Clarke on September 25th, 2009

    Hi

    Is it possible to remove the submit form action from a distributed form. I would like to use the signature and button that apears as the only method of submitting.

    Regards

    Pete

  6. Stefan Cameron on October 2nd, 2009

    Pete Clarke,

    By “distributed”, do you mean in Workspace?