Unlocking Encrypted PDF Documents

Summary of steps
Unlock an encrypted PDF document using the Java API
Unlock an encrypted PDF document using the web service API

A password-encrypted or certificate-encrypted PDF document must be unlocked before another LiveCycle operation can be performed on it. If you attempt to perform an operation on an encrypted PDF document, you will generate an exception. After you unlock an encrypted PDF document, you can perform one or more operations on it. These operations can belong to other services, such as the Reader Extensions Service.

Note: For more information about the Encryption service, see Services Reference for LiveCycle.

Summary of steps

To unlock an encrypted PDF document, perform the following steps:

Include project files.
Create an encryption service client.
Get the encrypted PDF document.
Unlock the document.
Perform a LiveCycle operation.

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, make sure 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 service client

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

You must obtain an encrypted PDF document in order to unlock it. If you attempt to unlock a PDF document that is not encrypted, an exception is thrown.

Unlock the document

To unlock a password-encrypted PDF document, you require both an encrypted PDF document and a password value that is used to open a password-encrypted PDF document. This value is specified when encrypting the PDF document with a password. (See Encrypting PDF Documents with a Password.)

To unlock a certificate-encrypted PDF document, you require both an encrypted PDF document and the alias value of the public key that corresponds to the private key that was used to encrypt the PDF document.

Perform a LiveCycle operation

After an encrypted PDF document is unlocked, you can perform another service operation on it, such as applying usage rights to it. This operation belongs to the Reader Extensions service.

Unlock an encrypted PDF document using the Java API

Unlock an encrypted PDF document by using the Encryption API (Java):

Include project files.

Include client JAR files, such as adobe-encryption-client.jar, in your Java project’s class path.
Create an encryption service client.
- Create a ServiceClientFactory object that contains connection properties.
- Create an EncryptionServiceClient object by using its constructor and passing the ServiceClientFactory object.
Get the encrypted PDF document.
- Create a java.io.FileInputStream object that represents the encrypted PDF document by using its constructor and passing a string value that specifies the location of the encrypted PDF document.
- Create a com.adobe.idp.Document object by using its constructor and passing the java.io.FileInputStream object.
Unlock the document.

Unlock an encrypted PDF document by invoking the EncryptionServiceClient object’s unlockPDFUsingPassword or unlockPDFUsingCredential method.

To unlock a PDF document that is encrypted with a password, invoke the unlockPDFUsingPassword method and pass the following values:
- A com.adobe.idp.Document object that contains the password-encrypted PDF document.
- A string value that specifies the password value that is used to open a password-encrypted PDF document. This value is specified when encrypting the PDF document with a password.
To unlock a PDF document that is encrypted with a certificate, invoke the unlockPDFUsingCredential method and pass the following values:
- A com.adobe.idp.Document object that contains the certificate-encrypted PDF document.
- A string value that specifies the alias name of the public key that corresponds to the private key used to encrypt the PDF document.
The unlockPDFUsingPassword and unlockPDFUsingCredential methods both return a com.adobe.idp.Document object that you pass to another LiveCycle Java method to perform an operation.
Perform a LiveCycle operation.

Perform a LiveCycle operation on the unlocked PDF document to meet your business requirements. For example, assuming that you want to apply usage rights to an unlocked PDF document, pass the com.adobe.idp.Document object that was returned by either the unlockPDFUsingPassword or unlockPDFUsingCredential methods to the ReaderExtensionsServiceClient object’s applyUsageRights method.

Unlock an encrypted PDF document using the web service API

Unlock an encrypted PDF document by using the Encryption API (web service):

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.
Create an encryption service client.
- 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.
Get an encrypted PDF document.
- Create a BLOB object by using its constructor.
- Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the encrypted 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 the contents of the byte array to the BLOB object’s MTOM data member.
Unlock the document.

Unlock an encrypted PDF document by invoking the EncryptionServiceClient object’s unlockPDFUsingPassword or unlockPDFUsingCredential method.

To unlock a PDF document that is encrypted with a password, invoke the unlockPDFUsingPassword method and pass the following values:
- A BLOB object that contains the password-encrypted PDF document.
- A string value that specifies the password value that is used to open a password-encrypted PDF document. This value is specified when encrypting the PDF document with a password.
To unlock a PDF document that is encrypted with a certificate, invoke the unlockPDFUsingCredential method and pass the following values:
- A BLOB object that contains the certificate-encrypted PDF document.
- A string value that specifies the alias name of the public key that corresponds to the private key used to encrypt the PDf document.
The unlockPDFUsingPassword and unlockPDFUsingCredential methods both return a com.adobe.idp.Document object that you pass to another LiveCycle method to perform an operation.
Perform a LiveCycle operation.

Perform a LiveCycle operation on the unlocked PDF document to meet your business requirements. For example, assuming that you want to apply usage rights to the unlocked PDF document, pass the BLOB object that was returned by either the unlockPDFUsingPassword or unlockPDFUsingCredential methods to the ReaderExtensionsServiceClient object’s applyUsageRights method.