Encrypting PDF Documents with Certificates

Certificate-based encryption lets you encrypt a document for specific recipients by means of public key technology. Various recipients can be given different permissions for the document. Many aspects of encryption are made possible by public key technology. An algorithm is used to generate two large numbers, known as keys, that have the following properties:

  • One key is used to encrypt a set of data. Subsequently, only the other key can be used to decrypt the data.

  • It is impossible to distinguish one key from the other.

One of the keys acts as a user’s private key. It is important that only the user has access to this key. The other key is the user’s public key, which can be shared with others.

A public key certificate contains a user’s public key and identifying information. The X.509 format is used for storing certificates. Certificates are typically issued and digitally signed by a certificate authority (CA), which is a recognized entity that provides a measure of confidence in the validity of the certificate. Certificates have an expiration date, after which they are no longer valid. In addition, certificate revocation lists (CRLs) provide information about certificates that were revoked prior to their expiration date. CRLs are published periodically by certificate authorities. The revocation status of a certificate can also be retrieved through Online Certificate Status Protocol (OCSP) over the network.

Note: If you upload an encrypted PDF document to the LiveCycle repository, it cannot decrypt the PDF document and extract the XDP content. It is recommended that you do not encrypt a document prior to uploading it to the LiveCycle repository. (See Writing Resources.)
Note: Before you can encrypt a PDF document with a certificate, 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.)
Note: For more information about the Encryption service, see Services Reference for LiveCycle.

Summary of steps

To encrypt a PDF document with a certificate, perform the following steps:

  1. Include project files.

  2. Create an Encryption Client API object.

  3. Get a PDF document to encrypt.

  4. Reference the certificate.

  5. Set encryption run-time options.

  6. Create a certificate-encrypted PDF document.

  7. Save the encrypted PDF document as a PDF file.

Include project files

Include the 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 class path:

  • adobe-livecycle-client.jar

  • adobe-usermanager-client.jar

  • adobe-encryption-client.jar

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

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

Create an Encryption Client API object

To programmatically perform an Encryption service operation, you must create an Encryption service client. If you are using the Java Encryption Service API, create an EncrytionServiceClient object. If you are using the web service Encryption Service API, create an EncryptionServiceService object.

Get a PDF document to encrypt

You must obtain an unencrypted PDF document to encrypt. If you attempt to secure a PDF document that is already encrypted, an exception is thrown.

Reference the certificate

To encrypt a PDF document with a certificate, reference a certificate that is used to encrypt a PDF document. The certificate is a .cer file, a .crt file, or a .pem file. A PKCS#12 file is used to store private keys with corresponding certificates.

When encrypting a PDF document with a certificate, specify permissions that are associated with the secured document. By specifying permissions, you can control the actions that a user who opens a certificate-encrypted PDF document can perform.

Set encryption run-time options

Specify the PDF document resources to encrypt. You can encrypt the entire PDF document, everything except the document’s metadata, or only the document’s attachments.

Create a certificate-encrypted PDF document

After you retrieve an unsecured PDF document, reference the certificate, and set run-time options, you can create a certificate-encrypted PDF document. After the PDF document is encrypted, you need the corresponding public key to decrypt it.

Save the encrypted PDF document as a PDF file

You can save the encrypted PDF document as a PDF file.

Encrypt a PDF document with a certificate using the Java API

Encrypt a PDF document with a certificate by using the Encryption API (Java):

  1. Include project files.

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

  2. Create an Encryption Client API object.

    • Create a ServiceClientFactory object that contains connection properties.

    • Create an EncryptionServiceClient object by using its constructor and passing the ServiceClientFactory object.

  3. Get a PDF document to encrypt.

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

    • Create a java.util.List object that stores permission information by using its constructor.

    • Specify the permission associated with the encrypted document by invoking the java.util.List object’s add method and passing a CertificateEncryptionPermissions enumeration value that represents the permissions that are granted to the user who opens the secured PDF document. For example, to specify all permissions, pass CertificateEncryptionPermissions.PKI_ALL_PERM.

    • Create a Recipient object by using its constructor.

    • Create a java.io.FileInputStream object that represents the certificate that is used to encrypt the PDF document by using its constructor and passing a string value that specifies the location of the certificate.

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

    • Invoke the Recipient object’s setX509Cert method and pass the com.adobe.idp.Document object that contains the certificate. (In addition, the Recipient object can have a Truststore certificate alias or LDAP URL as a certificate source.)

    • Create a CertificateEncryptionIdentity object that stores permission and certificate information by using its constructor.

    • Invoke the CertificateEncryptionIdentity object’s setPerms method and pass the java.util.List object that stores permission information.

    • Invoke the CertificateEncryptionIdentity object’s setRecipient method and pass the Recipient object that stores certificate information.

    • Create a java.util.List object that stores certificate information by using its constructor.

    • Invoke the java.util.List object’s add method and pass the CertificateEncryptionIdentity object. (This java.util.List object is passed as a parameter to the encryptPDFUsingCertificates method.)

  5. Set encryption run-time options.

    • Create a CertificateEncryptionOptionSpec object by invoking its constructor.

    • Specify the PDF document resources to encrypt by invoking the CertificateEncryptionOptionSpec object’s setOption method and passing a CertificateEncryptionOption enumeration value that specifies the document resources to encrypt. For example, to encrypt the entire PDF document, including its metadata and its attachments, specify CertificateEncryptionOption.ALL.

    • Specify the Acrobat compatibility option by invoking the CertificateEncryptionOptionSpec object’s setCompat method and passing a CertificateEncryptionCompatibility enumeration value that specifies the Acrobat compatibility level. For example, you can specify CertificateEncryptionCompatibility.ACRO_7.

  6. Create a certificate-encrypted PDF document.

    Encrypt the PDF document with a certificate by invoking the EncryptionServiceClient object’s encryptPDFUsingCertificates method and passing the following values:

    • The com.adobe.idp.Document object that contains the PDF document to encrypt.

    • The java.util.List object that stores certificate information.

    • The CertificateEncryptionOptionSpec object that contains encryption run-time options.

    The encryptPDFUsingCertificates method returns a com.adobe.idp.Document object that contains a certificate-encrypted PDF document.

  7. Save the encrypted 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 was returned by the encryptPDFUsingCertificates method.

Encrypt a PDF document with a certificate using the web service API

Encrypt a PDF document with a certificate by using the Encryption 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/EncryptionService?WSDL&lc_version=9.0.1.

    Note: Replace localhost with the IP address of the server hosting LiveCycle.
  2. Create an Encryption Client API object.

    • Create an EncryptionServiceClient object by using its default constructor.

    • Create an EncryptionServiceClient.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/EncryptionService?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 EncryptionServiceClient.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 EncryptionServiceClient.ClientCredentials.UserName.UserName.

      • Assign the corresponding password value to the field EncryptionServiceClient.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 a PDF document to encrypt.

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

    • 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 encrypt 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 with the contents of the byte array.

  4. Reference the certificate.

    • Create a Recipient object by using its constructor. This object will store certificate information.

    • Create a BLOB object by using its constructor. This BLOB object will store the certificate that encrypts the PDF document.

    • Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the certificate 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 the contents of the byte array to the BLOB object’s MTOM data member.

    • Assign the BLOB object that stores the certificate to the Recipient object’s x509Cert data member.

    • Create a CertificateEncryptionIdentity object that stores certificate information by using its constructor.

    • Assign the Recipient object that stores the certificate to the CertificateEncryptionIdentity object’s recipient data member.

    • Create an Object array and assign the CertificateEncryptionIdentity object to the first element of the Object array. This Object array is passed as a parameter to the encryptPDFUsingCertificates method.

  5. Set encryption run-time options.

    • Create a CertificateEncryptionOptionSpec object by using its constructor.

    • Specify the PDF document resources to encrypt by assigning a CertificateEncryptionOption enumeration value to the CertificateEncryptionOptionSpec object’s option data member. To encrypt the entire PDF document, including its metadata and its attachments, assign CertificateEncryptionOption.ALL to this data member.

    • Specify the Acrobat compatibility option by assigning a CertificateEncryptionCompatibility enumeration value to the CertificateEncryptionOptionSpec object’s compat data member. For example, assign CertificateEncryptionCompatibility.ACRO_7 to this data member.

  6. Create a certificate-encrypted PDF document.

    Encrypt the PDF document with a certificate by invoking the EncryptionServiceService object’s encryptPDFUsingCertificates method and passing the following values:

    • The BLOB object that contains the PDF document to encrypt.

    • The Object array that stores certificate information.

    • The CertificateEncryptionOptionSpec object that contains encryption run-time options.

    The encryptPDFUsingCertificates method returns a BLOB object that contains a certificate-encrypted PDF document.

  7. Save the encrypted 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 secured PDF document.

    • Create a byte array that stores the data content of the BLOB object that was returned by the encryptPDFUsingCertificates 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.

// Ethnio survey code removed