Modifying Signature Fields

You can modify signature fields that are located in a PDF document by using the Java API and web service API. Modifying a signature field involves manipulating its signature field lock dictionary values or seed value dictionary values.

A field lock dictionary specifies a list of fields that are locked when the signature field is signed. A locked field prevents users from making changes to the field. A seed value dictionary contains constraining information that is used at the time the signature is applied. For example, you can change permissions that control the actions that can occur without invalidating a signature.

By modifying an existing signature field, you can make changes to the PDF document to reflect changing business requirements. For example, a new business requirement may require locking all document fields after the document is signed.

This section explains how to modify a signature field by amending both field lock dictionary and seed value dictionary values. Changes made to the signature field lock dictionary result in all fields in the PDF document being locked when a signature field is signed. Changes made to the seed value dictionary prohibit specific types of changes to the document.

Remarque : For more information about the Signature service and modifying signature fields, see Services Reference for LiveCycle.

Summary of steps

To modify signature fields located in a PDF document, perform the following tasks:

  1. Include project files.

  2. Create a Signature client.

  3. Get the PDF document that contains the signature field to modify.

  4. Set dictionary values.

  5. Modify the signature field.

  6. Save the PDF document as a PDF file.

Include project files

Include necessary files in your development project. If you are creating a client application by 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-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 Signature client

Before you can programmatically perform a Signature service operation, you must create a Signature service client.

Get the PDF document that contains the signature field to modify

Retrieve a PDF document that contains the signature field to modify.

Set dictionary values

To modify a signature field, assign values to its field lock dictionary or seed value dictionary. Specifying signature field lock dictionary values involves specifying PDF document fields that are locked when the signature field is signed. (This section discusses how to lock all fields.)

The following seed value dictionary values can be set:

  • Revision checking: Specifies whether revocation checking is performed when a signature is applied to the signature field.

  • Certificate options: Assigns values to the certificate seed value dictionary. Before specifying certificate options, it is recommended that you become familiar with a certificate seed value dictionary. (See PDF Reference.)

  • Digest options: Assigns digest algorithms that are used for signing. Valid values are SHA1, SHA256, SHA384, SHA512, and RIPEMD160.

  • Filter: Specifies the filter that is used with the signature field. For example, you can use the Adobe.PPKLite filter. (See PDF Reference.)

  • Flag options: Specifies the flag values that are associated with this signature field. A value of 1 means that a signer must use only the specified values for the entry. A value of 0 means that other values are permitted. Here are the Bit positions:

    • 1(Filter): The signature handler to be used to sign the signature field

    • 2 (SubFilter): An array of names that indicate acceptable encodings to use when signing

    • 3 (V): The minimum required version number of the signature handler to be used to sign the signature field

    • 4 (Reasons): An array of strings that specify possible reasons for signing a document

    • 5 (PDFLegalWarnings): An array of strings that specify possible legal attestations

  • Legal attestations: When a document is certified, it is automatically scanned for specific types of content that can make the visible contents of a document ambiguous or misleading. For example, an annotation can obscure text that is important for understanding what is being certified. The scanning process generates warnings that indicate the presence of this type of content. It also provides an additional explanation of the content that may have generated warnings.

  • Permissions: Specifies permissions that can be used on a PDF document without invalidating the signature.

  • Reasons: Specifies reasons why this document must be signed.

  • Time stamp: Specifies time-stamping options. You can, for example, set the URL of the time-stamping server that is used.

  • Version: Specifies the minimum version number of the signature handler to be used to sign the signature field.

Modify the signature field

After you create a Signature service client, retrieve the PDF document that contains the signature field to modify, and set dictionary values, you can instruct the Signature service to modify the signature field. The Signature service then returns a PDF document that contains the modified signature field. The original PDF document is not affected.

Save the PDF document as a PDF file

Save the PDF document that contains the modified signature field as a PDF file so that users can open it in Acrobat or Adobe Reader.

Modify signature fields using the Java API

Modify a signature field by using the Signature API (Java):

  1. Include project files

    Include client JAR files, such as the adobe-signatures-client.jar, in your Java project’s class path.

  2. Create a Signature client

    • Create a ServiceClientFactory object that contains connection properties.

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

  3. Get the PDF document that contains the signature field to modify

    • Create a java.io.FileInputStream object that represents the PDF document that contains the signature field to modify by using its constructor and passing 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.

  4. Set dictionary values

    • Create a PDFSignatureFieldProperties object by using its constructor. A PDFSignatureFieldProperties object stores signature field lock dictionary and seed value dictionary information.

    • Create a PDFSeedValueOptionSpec object by using its constructor. This object lets you set seed value dictionary values.

    • Disallow changes to the PDF document by invoking the PDFSeedValueOptionSpec object’s setMdpValue method and passing the MDPPermissions.NoChanges enumeration value.

    • Create a FieldMDPOptionSpec object by using its constructor. This object lets you set signature field lock dictionary values.

    • Lock all fields in the PDF document by invoking the FieldMDPOptionSpec object’s setMdpValue method and passing the FieldMDPAction.ALL enumeration value.

    • Set seed value dictionary information by invoking the PDFSignatureFieldProperties object’s setSeedValue method and passing the PDFSeedValueOptionSpec object.

    • Set signature field lock dictionary information by invoking the PDFSignatureFieldProperties object’s setFieldMDP method and passing the FieldMDPOptionSpec object.

    Remarque : To see all seed value dictionary values that you can set, see the PDFSeedValueOptionSpec class reference. (See LiveCycle API Reference.)
  5. Modify the signature field

    Modify the signature field by invoking the SignatureServiceClient object’s modifySignatureField method and passing the following values:

    • The com.adobe.idp.Document object that stores the PDF document that contains the signature field to modify

    • A string value that specifies the name of the signature field

    • The PDFSignatureFieldProperties object that stores signature field lock dictionary and seed value dictionary information

    The modifySignatureField method returns a com.adobe.idp.Document object that stores a PDF document that contains the modified signature field.

  6. Save the PDF document as a PDF file

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

    • Invoke the com.adobe.idp.Document object’s copyToFile method to copy the contents of the com.adobe.idp.Document object to the file. Ensure that you use the com.adobe.idp.Document object that the modifySignatureField method returned.

Modify signature fields using the web service API

Modify a signature field by using the Signature API (web service):

  1. Include project files

    Create a Microsoft .NET project that uses MTOM. Ensure that you use the following WSDL definition: http://localhost:8080/soap/services/SignatureService?WSDL&lc_version=9.0.1.

    Remarque : Replace localhost with the IP address of the server hosting LiveCycle.
  2. Create a Signature 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.

  3. Get the PDF document that contains the signature field to modify

    • Create a BLOB object by using its constructor. The BLOB object is used to store the PDF document that contains the signature field to modify.

    • Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the PDF document 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.

  4. Set dictionary values

    • Create a PDFSignatureFieldProperties object by using its constructor. This object stores signature field lock dictionary and seed value dictionary information.

    • Create a PDFSeedValueOptionSpec object by using its constructor. This object lets you set seed value dictionary values.

    • Disallow changes to the PDF document by assigning the MDPPermissions.NoChanges enumeration value to the PDFSeedValueOptionSpec object’s mdpValue data member.

    • Create a FieldMDPOptionSpec object by using its constructor. This object lets you set signature field lock dictionary values.

    • Lock all fields in the PDF document by assigning the FieldMDPAction.ALL enumeration value to the FieldMDPOptionSpec object’s mdpValue data member.

    • Set seed value dictionary information by assigning the PDFSeedValueOptionSpec object to the PDFSignatureFieldProperties object’s seedValue data member.

    • Set signature field lock dictionary information by assigning the FieldMDPOptionSpec object to the PDFSignatureFieldProperties object’s fieldMDP data member.

    Remarque : To see all seed value dictionary values that you can set, see the PDFSeedValueOptionSpec class reference. (See LiveCycle API Reference).
  5. Modify the signature field

    Modify the signature field by invoking the SignatureServiceClient object’s modifySignatureField method and passing the following values:

    • The BLOB object that stores the PDF document that contains the signature field to modify

    • A string value that specifies the name of the signature field

    • The PDFSignatureFieldProperties object that stores signature field lock dictionary and seed value dictionary information

    The modifySignatureField method returns a BLOB object that stores a PDF document that contains the modified signature field.

  6. Save the PDF document as a PDF file

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

    • Create a byte array that stores the content of the BLOB object that the addSignatureField method returns. 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.