Digitally Signing Interactive Forms

You can sign an interactive form that the Forms service creates. For example, consider the following workflow:

  • You merge an XFA-based PDF form created by using Designer and form data located in an XML document using the Forms service. The Forms server renders an interactive form.

  • You sign the interactive form using the Signature service API.

The result is a digitally signed interactive PDF form. When signing a PDF form that is based on an XFA form, ensure that you save the PDF file as an Adobe Static PDF form. If you attempt to sign a PDF form that is saved as an Adobe Dynamic PDF form, an exception occurs. Because you are signing the form that is returned from the Forms service, ensure that the form contains a signature field.

Note: Before you can digitally sign an interactive form, you must ensure that you add the certificate to LiveCycle. A certificate is added using Administration Console or programmatically using the Trust Manager API. (See Importing Credentials by using the Trust Manager API.)

When using the Forms Service API, set the GenerateServerAppearance run-time option to true. This run-time option ensures that the appearance of the form that is generated on the server remains valid when opened in Acrobat or Adobe Reader. It is recommended that you set this run-time option when generating an interactive form to sign by using the Forms API.

Note: Before reading Digitally Signing Interactive Forms, it is recommended that you are familiar with signing PDF documents. (See Digitally Signing PDF Documents.)

Summary of steps

To digitally sign an interactive form the Forms service returns, perform the following tasks:

  1. Include project files.

  2. Create a Forms and Signatures client.

  3. Obtain the interactive form using the Forms service.

  4. Sign the interactive form.

  5. Save the signed PDF document as a PDF file.

Include project files

Include necessary files into your development project. If you are creating a client application using Java, include the necessary JAR files. If you are using web services, ensure that you include the proxy files.

The following JAR files must be added to your project’s classpath:

  • adobe-livecycle-client.jar

  • adobe-usermanager-client.jar

  • adobe-signatures-client.jar

  • adobe-forms-client.jar

  • adobe-utilities.jar (required if LiveCycle is deployed on JBoss)

  • jbossall-client.jar (required if LiveCycle is deployed on JBoss)

For information about the location of these JAR files, see Including LiveCycle Java library files.

Create a Forms and Signatures client

Because this workflow invokes both the Forms and Signature services, create both a Forms service client and Signature service client.

Obtain the interactive form using the Forms service

You can use the Forms service to obtain the interactive PDF form to sign. As of LiveCycle, you can pass a com.adobe.idp.Document object to the Forms service that contains the form to render. The name of this method is renderPDFForm2. This method returns a com.adobe.idp.Document object that contains the form to sign. You can pass this com.adobe.idp.Document instance to the Signature service.

Likewise, if you are using web services, you can pass the BLOB instance that the Forms service returns to the Signature service.

Note: The quick start associated with Digitally Signing Interactive Forms section invokes the renderPDFForm2 method.

Sign the interactive form

When signing a PDF document, you can set run-time options that the Signature service uses. You can set the following options:

  • Appearance options

  • Revocation checking

  • Time stamping values

You set appearance options by using a PDFSignatureAppearanceOptionSpec object. For example, you can display the date within a signature by invoking the PDFSignatureAppearanceOptionSpec object’s setShowDate method and passing true.

Save the signed PDF document

After the Signature service digitally signs the PDF document, you can save it as a PDF file. The PDF file can be opened in Acrobat or Adobe Reader.

Digitally sign an interactive form using the Java API

Digitally sign an interactive form by using the Forms and Signature API (Java):

  1. Include project files

    Include client JAR files, such as adobe-signatures-client.jar and adobe-forms-client.jar, in your Java project’s classpath.

  2. Create a Forms and Signatures client

    • Create a ServiceClientFactory object that contains connection properties.

    • Create a SignatureServiceClient object by using its constructor and passing the ServiceClientFactory object.

    • Create a FormsServiceClient object by using its constructor and passing the ServiceClientFactory object.

  3. Obtain the interactive form using the Forms service

    • Create a java.io.FileInputStream object that represents the PDF document to pass to the Forms service by using its constructor. Pass a string value that specifies the location of the PDF document.

    • Create a com.adobe.idp.Document object by using its constructor and passing the java.io.FileInputStream object.

    • Create a java.io.FileInputStream object that represents the XML document that contains form data to pass to the Forms service by using its constructor. Pass a string value that specifies the location of the XML file.

    • Create a com.adobe.idp.Document object by using its constructor and passing the java.io.FileInputStream object.

    • Create a PDFFormRenderSpec object that is used to set run-time options. Invoke the PDFFormRenderSpec object’s setGenerateServerAppearance method and pass true.

    • Invoke the FormsServiceClient object’s renderPDFForm2 method and pass the following values:

      • A com.adobe.idp.Document object that contains the PDF form to render.

      • A com.adobe.idp.Document object that contains data to merge with the form.

      • A PDFFormRenderSpec object that stores run-time options.

      • A URLSpec object that contains URI values that are required by the Forms service. You can specify null for this parameter value.

      • A java.util.HashMap object that stores file attachments. This is an optional parameter and you can specify null if you do not want to attach files to the form.

      The renderPDFForm2 method returns a FormsResult object that contains a form data stream

    • Retrieve the PDF form by invoking the FormsResult object’s getOutputContent method. This method returns a com.adobe.idp.Document object that represents the interactive form.

  4. Sign the interactive form

    Sign the PDF document by invoking the SignatureServiceClient object’s sign method and passing the following values:

    • A com.adobe.idp.Document object that represents the PDF document to sign. Ensure that this object is the com.adobe.idp.Document object obtained from the Forms service.

    • A string value that represents the name of the signature field that is signed.

    • A Credential object that represents the credential that is used to digitally sign the PDF document. Create a Credential object by invoking the Credential object’s static getInstance method. Pass a string value that specifies the alias value that corresponds to the security credential.

    • A HashAlgorithm object that specifies a static data member that represents the hash algorithm to use to digest the PDF document. For example, you can specify HashAlgorithm.SHA1 to use the SHA1 algorithm.

    • A string value that represents the reason why the PDF document was digitally signed.

    • A string value that represents the signer’s contact information.

    • A PDFSignatureAppearanceOptions object that controls the appearance of the digital signature. For example, you can use this object to add a custom logo to a digital signature.

    • A java.lang.Boolean object that specifies whether to perform revocation checking on the signer's certificate.

    • An OCSPPreferences object that stores preferences for Online Certificate Status Protocol (OCSP) support. If revocation checking is not done, this parameter is not used and you can specify null.

    • A CRLPreferences object that stores certificate revocation list (CRL) preferences. If revocation checking is not done, this parameter is not used and you can specify null.

    • A TSPPreferences object that stores preferences for time stamp provider (TSP) support. This parameter is optional and can be null.

    The sign method returns a com.adobe.idp.Document object that represents the signed PDF document.

  5. Save the signed PDF document

    • Create a java.io.File object and ensure that the filename extension is .pdf.

    • Invoke the com.adobe.idp.Document object’s copyToFile method and pass java.io.File to copy the contents of the Document object to the file. Ensure that you use the com.adobe.idp.Document object that the sign method returned.

Digitally sign an interactive form using the web service API

Digitally sign an interactive form by using the Forms and Signature API (web service):

  1. Include project files

    Create a Microsoft .NET project that uses MTOM. Because this client application invokes two LiveCycle services, create two service references. Use the following WSDL definition for the service reference associated with the Signature service: http://localhost:8080/soap/services/SignatureService?WSDL&lc_version=9.0.1.

    Use the following WSDL definition for the service reference associated with the Forms service: http://localhost:8080/soap/services/FormsService?WSDL&lc_version=9.0.1.

    Because the BLOB data type is common to both service references, fully qualify the BLOB data type when using it. In the corresponding web service quick start, all BLOB instances are fully qualified.

    Note: Replace localhost with the IP address of the server hosting LiveCycle.
  2. Create a Forms and Signatures client

    • Create a SignatureServiceClient object by using its default constructor.

    • Create a SignatureServiceClient.Endpoint.Address object by using the System.ServiceModel.EndpointAddress constructor. Pass a string value that specifies the WSDL to the LiveCycle service (for example, http://localhost:8080/soap/services/SignatureService?WSDL). You do not need to use the lc_version attribute. This attribute is used when you create a service reference.)

    • Create a System.ServiceModel.BasicHttpBinding object by getting the value of the SignatureServiceClient.Endpoint.Binding field. Cast the return value to BasicHttpBinding.

    • Set the System.ServiceModel.BasicHttpBinding object’s MessageEncoding field to WSMessageEncoding.Mtom. This value ensures that MTOM is used.

    • Enable basic HTTP authentication by performing the following tasks:

      • Assign the LiveCycle user name to the field SignatureServiceClient.ClientCredentials.UserName.UserName.

      • Assign the corresponding password value to the field SignatureServiceClient.ClientCredentials.UserName.Password.

      • Assign the constant value HttpClientCredentialType.Basic to the field BasicHttpBindingSecurity.Transport.ClientCredentialType.

    • Assign the constant value BasicHttpSecurityMode.TransportCredentialOnly to the field BasicHttpBindingSecurity.Security.Mode.

    Note: Repeat these steps for the Forms service client.
  3. Obtain the interactive form using the Forms service

    • Create a BLOB object by using its constructor. The BLOB object is used to store a PDF document that is signed.

    • Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the PDF document to sign, and the mode in which to open the file.

    • Create a byte array that stores the content of the System.IO.FileStream object. You can determine the size of the byte array by getting the System.IO.FileStream object’s Length property.

    • Populate the byte array with stream data by invoking the System.IO.FileStream object’s Read method and passing the byte array, the starting position, and the stream length to read.

    • Populate the BLOB object by assigning its MTOM property the contents of the byte array.

    • Create a BLOB object by using its constructor. The BLOB object is used to store form data.

    • Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the XML file that contains form data, and the mode in which to open the file.

    • Create a byte array that stores the content of the System.IO.FileStream object. You can determine the size of the byte array by getting the System.IO.FileStream object’s Length property.

    • Populate the byte array with stream data by invoking the System.IO.FileStream object’s Read method and passing the byte array, the starting position, and the stream length to read.

    • Populate the BLOB object by assigning its MTOM property the contents of the byte array.

    • Create a PDFFormRenderSpec object that is used to set run-time options. Assign the value true to the PDFFormRenderSpec object’s generateServerAppearance field.

    • Invoke the FormsServiceClient object’s renderPDFForm2 method and pass the following values:

      • A BLOB object that contains the PDF form to render.

      • A BLOB object that contains data to merge with the form.

      • A PDFFormRenderSpec object that stores run-time options.

      • A URLSpec object that contains URI values that are required by the Forms service. You can specify null for this parameter value.

      • A java.util.HashMap object that stores file attachments. This is an optional parameter and you can specify null if you do not want to attach files to the form.

      • A long output parameter used to store the number of pages in the form.

      • A string output parameter that is used for the locale value.

      • A FormResult value that is an output parameter that is used to store the interactive form.

    • Retieve the PDF form by invoking the FormsResult object’s outputContent field. This field stores a BLOB object that represents the interactive form.

  4. Sign the interactive form

    Sign the PDF document by invoking the SignatureServiceClient object’s sign method and passing the following values:

    • A BLOB object that represents the PDF document to sign. Use the BLOB instance returned by the Forms service.

    • A string value that represents the name of the signature field that is signed.

    • A Credential object that represents the credential that is used to digitally sign the PDF document. Create a Credential object by using its constructor and specify the alias by assigning a value to the Credential object’s alias property.

    • A HashAlgorithm object that specifies a static data member that represents the hash algorithm to use to digest the PDF document. For example, you can specify HashAlgorithm.SHA1 to use the SHA1 algorithm.

    • A Boolean value that specifies whether the hash algorithm is used.

    • A string value that represents the reason why the PDF document was digitally signed.

    • A string value that represents the signer’s location.

    • A string value that represents the signer’s contact information.

    • A PDFSignatureAppearanceOptions object that controls the appearance of the digital signature. For example, you can use this object to add a custom logo to a digital signature.

    • A System.Boolean object that specifies whether to perform revocation checking on the signer's certificate. If this revocation checking is done, it is embedded in the signature. The default is false.

    • An OCSPPreferences object that stores preferences for Online Certificate Status Protocol (OCSP) support. If revocation checking is not done, this parameter is not used and you can specify null. For information about this object, see LiveCycle API Reference.

    • A CRLPreferences object that stores certificate revocation list (CRL) preferences. If revocation checking is not done, this parameter is not used and you can specify null.

    • A TSPPreferences object that stores preferences for time stamp provider (TSP) support. This parameter is optional and can be null.

    The sign method returns a BLOB object that represents the signed PDF document.

  5. Save the signed PDF document

    • Create a System.IO.FileStream object by invoking its constructor. Pass a string value that represents the file location of the signed PDF document and the mode in which to open the file.

    • Create a byte array that stores the content of the BLOB object that was returned by the sign method. Populate the byte array by getting the value of the BLOB object’s MTOM data member.

    • Create a System.IO.BinaryWriter object by invoking its constructor and passing the System.IO.FileStream object.

    • Write the contents of the byte array to a PDF file by invoking the System.IO.BinaryWriter object’s Write method and passing the byte array.

// Ethnio survey code removed