Certifying PDF Documents

You can secure a PDF document by certifying it with a particular type of signature called a certified signature. A certified signature is distinguished from a digital signature in these ways:

  • It must be the first signature applied to the PDF document; that is, at the time the certified signature is applied, any other signature fields in the document must be unsigned. Only one certified signature is permitted in a PDF document. If you want to sign and certify a PDF document, you must certify it before signing it. After you certify a PDF document, you can digitally sign additional signature fields.

  • The author or originator of the document can specify that the document can be modified in certain ways without invalidating the certified signature. For example, the document may permit filling in forms or commenting. If the author specifies that a certain modification is not permitted, Acrobat restricts users from modifying the document in that way. If such modifications are made, such as by using another application, the certified signature is invalid and Acrobat issues a warning when a user opens the document. (With non-certified signatures, modifications are not prevented, and normal editing operations do not invalidate the original signature.)

  • At the time of signing, the document is scanned for specific types of content that could make the contents of a document ambiguous or misleading. For example, an annotation could obscure some text on a page that is important for understanding what is being certified. An explanation (legal attestation) can be provided about such content.

You can programmatically certify PDF documents by using the Signature service Java API or the Signature web service API. When certifying a PDF document, you must reference a security credential that exists in the Credential service. For information about the security credential, see the Installing and Deploying LiveCycle guide for your application server.

Note: When certifying and signing the same PDF document, if the certify signature is not trusted, a yellow triangle appears next to the first sign signature when you open the PDF document in Acrobat or Adobe Reader. The certifying signature must be trusted to avoid this situation.
Note: When using an nCipher nShield HSM credential to sign or certify a PDF document, the new credential cannot be used until the J2EE application server on which LiveCycle is deployed is restarted. However, you can set a configuration value, resulting in the sign or certify operation working without restarting the J2EE application server.

You can add the following configuration value in the cknfastrc file, which is located at /opt/nfast/cknfastrc (or c:\nfast\cknfastrc):

            CKNFAST_ASSUME_SINGLE_PROCESS=0

After you add this configuration value to the cknfastrc file, the new credential can be used without restarting the J2EE application server.

Note: For more information about the Signature service and certifying a document, seeServices Reference for LiveCycle.

Summary of steps

To certify a PDF document, perform the following tasks:

  1. Include project files.

  2. Create a Signature client.

  3. Get the PDF document to certify.

  4. Certify the PDF document.

  5. Save the certified 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-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 operation, you must create a Signature client.

Get the PDF document to certify

To certify a PDF document, you must obtain a PDF document that contains a signature field. If a PDF document does not contain a signature field, it cannot be certified. A signature field can be added by using Designer or programmatically. For information about programmatically adding a signature field, see Adding Signature Fields.

Certify the PDF document

To successfully certify a PDF document, you require the following input values that are used by the Signature service to certify a PDF document:

  • PDF document: A PDF document that contains a signature field, which is a form field that contains a graphic representation of the certified signature. A PDF document must contain a signature field before it can be certified. A signature field can be added by using Designer or programmatically. (See Adding Signature Fields.)

  • Signature field name: The fully-qualified name of the signature field that is certified. The following value is an example: form1[0].#subform[1].SignatureField3[3]. When using an XFA form field, the partial name of the signature field can also be used: SignatureField3[3]. If a null value is passed for the field name, an invisible signature field is dynamically created and certified.

  • Security credential: A credential that is used to certify the PDF document. This security credential contains a password and an alias, which must match an alias that appears in the credential that is located within the Credential service. The alias is a reference to an actual credential that may be in a PKCS#12 file (with a .pfx extension) or a hardware security module (HSM).

  • Hash algorithm: A hash algorithm to use to digest the PDF document.

  • Reason for signing: A value that is displayed in Acrobat or Adobe Reader so that other users know the reason why the PDF document was certified.

  • Location of the signer: The location of the signer specified by the credential.

  • Contact information: Contact information, such as address and telephone number, of the signer.

  • Permission information: Permissions that control the actions that an end user can perform on a document without causing the certified signature to be invalid. For example, you can set the permission so that any change to the PDF document causes the certified signature to be invalid.

  • Legal explanation: When a document is certified, it is automatically scanned for specific types of content that could make the contents of a document ambiguous or misleading. For example, an annotation could obscure some text on a page that is important for understanding what is being certified. The scanning process generates warnings about these types of content. This value provides an additional explanation of the content that may have generated warnings.

  • Appearance options: Options that control the appearance of the certified signature. For example, the certified signature can display date information.

  • Revocation checking: This value specifies whether revocation checking is done for the signer's certificate. The default setting of false means that revocation checking is not done.

  • OCSP settings: Settings for Online Certificate Status Protocol (OCSP) support, which provides information about the status of the credential that is used to certify the PDF document. You can, for example, specify the URL of the server that provides information about the credential that you are using to sign on to the PDF document.

  • CRL settings: Settings for certificate revocation list (CRL) preferences if revocation checking is done. For example, you can specify to always check whether a credential was revoked.

  • Time stamping: Settings that define time stamping information that is applied to the certified signature. A time stamp indicates that specific data was established before a certain time. This knowledge helps build a trusting relationship between the signer and verifier.

Save the certified PDF document as a PDF file

After the Signature service certifies the PDF document, you can save it as a PDF file so that users can open it in Acrobat or Adobe Reader.

See also

Certify PDF documents using the Java API

Certify PDF documents using the web service API

Including LiveCycle Java library files

Setting connection properties

Adding Signature Fields

Certify PDF documents using the Java API

Certify a PDF document by using the Signature API (Java):

  1. Include project files

    Include client JAR files, such as 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 to certify

    • Create a java.io.FileInputStream object that represents the PDF document to certify 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. Certify the PDF document

    Certify the PDF document by invoking the SignatureServiceClient object’s certify method and passing the following values:

    • The com.adobe.idp.Document object that represents the PDF document to certify.

    • A string value that represents the name of the signature field that will contain the signature.

    • A Credential object that represents the credential that is used to certify the PDF document. Create a Credential object by invoking the Credential object’s static getInstance method and passing 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 used 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 certified.

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

    • A MDPPermissions object that specifies actions that can be performed on the PDF document that invalidates the signature.

    • A PDFSignatureAppearanceOptions object that controls the appearance of the certified signature. If desired, modify the appearance of the signature by invoking a method, such as setShowDate.

    • A string value that provides an explanation of what actions invalidate the signature.

    • A java.lang.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.

    • A java.lang.Boolean object that specifies whether the signature field being certified is locked. If the field is locked, the signature field is marked as read only, its properties cannot be modified, and it cannot be cleared by anyone who does not have the required permissions. 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. For example, after you create a TSPPreferences object, you can set the URL of the TSP server by invoking the TSPPreferences object’s setTspServerURL method. This parameter is optional and can be null. For more information, see Services Reference for LiveCycle.

    The certify method returns a com.adobe.idp.Document object that represents the certified PDF document.

  5. Save the certified PDF document as a PDF file

    • Create a java.io.File object and ensure that the file 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.

See also

Certifying PDF Documents

Quick Start (EJB mode): Certifying a PDF document using the Java API

Quick Start (SOAP mode): Certifying a PDF document using the Java API

Including LiveCycle Java library files

Setting connection properties

Certify PDF documents using the web service API

Certify a PDF document 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.

    Note: 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 to certify

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

    • 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 certify 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 data member the contents of the byte array.

  4. Certify the PDF document

    Certify the PDF document by invoking the SignatureServiceClient object’s certify method and passing the following values:

    • The BLOB object that represents the PDF document to certify.

    • A string value that represents the name of the signature field that will contain the signature.

    • A Credential object that represents the credential that is used to certify 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 used 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 certified.

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

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

    • An MDPPermissions object’s static data member that specifies actions that can be performed on the PDF document that invalidate the signature.

    • A Boolean value that specifies whether to use the MDPPermissions object that was passed as the previous parameter value.

    • A string value that explains what actions invalidate the signature.

    • A PDFSignatureAppearanceOptions object that controls the appearance of the certified signature. Create a PDFSignatureAppearanceOptions object by using its constructor. You can modify the appearance of the signature by setting one of its data members.

    • 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.

    • A System.Boolean object that specifies whether the signature field being certified is locked. If the field is locked, the signature field is marked as read only, its properties cannot be modified, and it cannot be cleared by anyone who does not have the required permissions. The default is false.

    • A System.Boolean object that specifies whether the signature field is locked. That is, if you pass true to the previous parameter, then pass true to this parameter.

    • An OCSPPreferences object that stores preferences for Online Certificate Status Protocol (OCSP) support, which provides information about the status of the credential that is used to certify the PDF document. 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. For example, after you create a TSPPreferences object, you can set the URL of the TSP by setting the TSPPreferences object’s tspServerURL data member. This parameter is optional and can be null.

    The certify method returns a BLOB object that represents the certified PDF document.

  5. Save the certified 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 certified 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 certify method. Populate the byte array by getting the value of the BLOB object’s binaryData 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.

See also

Certifying PDF Documents

Quick Start (MTOM): Certifying a PDF document using the web service API

Quick Start (SwaRef): Certifying a PDF document using the web service API

Invoking LiveCycle using MTOM

Invoking LiveCycle using SwaRef

// Ethnio survey code removed