Revoking Access to Documents

You can revoke access to a policy-protected PDF document resulting in all copies of the document being inaccessible to users. When a user attempts to open a revoked PDF document, they are redirected to a specified URL where a revised document can be viewed. The URL to where the user is redirected must be programmatically specified. When you revoke access to a document, the change takes effect the next time the user synchronizes with the Rights Management service by opening the policy-protected document online.

The ability to revoke access to a document provides additional security. For example, assume a newer version of a document is available and you no longer want anyone viewing the outdated version. In this situation, access to the older document can be revoked, and nobody can view the document unless access is reinstated.

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

Summary of steps

To revoke a policy-protected document, perform the following steps:

  1. Include project files.

  2. Create a Rights Management Client API object.

  3. Retrieve a policy-protected PDF document.

  4. Revoke the policy-protected document.

Include project files

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

Create a Rights Management Client API object

Before you can programmatically perform a Rights Management service operation, you must create a Rights Management service client object.

Retrieve a policy-protected PDF document

You must retrieve a policy-protected PDF document in order to revoke it. You cannot revoke a document that has already been revoked or is not a policy-protected document.

If you know the license identifier value of the policy-protected document, then it is not necessary to retrieve the policy-protected PDF document. However, in most cases, you will need to retrieve the PDF document in order to obtain the license identifier value.

Revoke the policy-protected document

To revoke a policy-protected document, specify the license identifier of the policy-protected document. In addition, you can specify the URL of a document that the user can view when they attempt to open the revoked document. That is, assume that an outdated document is revoked. When a user attempts to open the revoked document, they will see an updated document instead of the revoked document.

Note: If you attempt to revoke a document that is already revoked, an exception is thrown.

Revoke access to documents using the Java API

Revoke access to a policy-protected PDF document by using the Rights Management API (Java):

  1. Include project files

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

  2. Create a Rights Management Client API object

    • Create a ServiceClientFactory object that contains connection properties.

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

  3. Retrieve a policy-protected PDF document

    • Create a java.io.FileInputStream object that represent the policy-protected PDF document 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. Revoke the policy-protected document

    • Create a DocumentManager object by invoking the RightsManagementClient object’s getDocumentManager method.

    • Retrieve the license identifier value of the policy-protected document by invoking the DocumentManager object’s getLicenseId method. Pass the com.adobe.idp.Document object that represents the policy-protected document. This method returns a string value that represents the license identifier value.

    • Create a LicenseManager object by invoking the RightsManagementClient object’s getLicenseManager method.

    • Revoke the policy-protected document by invoking the LicenseManager object’s revokeLicense method and passing the following values:

      • A string value that specifies the license identifier value of the policy-protected document (specify the return value of the DocumentManager object’s getLicenseId method).

      • A static data member of the License interface that specifies the reason to revoke the document. For example, you can specify License.DOCUMENT_REVISED.

      • A java.net.URL value that specifies the location to where a revised document is located. If you do not want to redirect a user to another URL, then you can pass null.

Code examples

For code examples using the Rights Management service, see the following Quick Starts in API Quick Starts (Code Examples):

  • “Quick Start (EJB mode): Revoking a document using the Java API”

  • “Quick Start (SOAP mode): Revoking a document using the Java API”

Revoke access to documents using the web service API

Revoke access to a policy-protected PDF document by using the Rights Management 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/RightsManagementService?WSDL&lc_version=9.0.1.

    Note: Replace localhost with the IP address of the server hosting LiveCycle.
  2. Create a Rights Management Client API object

    • Create a RightsManagementServiceClient object by using its default constructor.

    • Create a RightsManagementServiceClient.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/RightsManagementService?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 RightsManagementServiceClient.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 RightsManagementServiceClient.ClientCredentials.UserName.UserName.

      • Assign the corresponding password value to the field RightsManagementServiceClient.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. Retrieve a policy-protected PDF document

    • Create a BLOB object by using its constructor. The BLOB object is used to store a policy-protected PDF document that is revoked.

    • Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the policy-protected PDF document to revoke 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 field with the contents of the byte array.

  4. Revoke the policy-protected document

    • Retrieve the license identifier value of the policy-protected document by invoking the RightsManagementServiceClient object’s getLicenseID method and passing the BLOB object that represents the policy-protected document. This method returns a string value that represents the license identifier.

    • Revoke the policy-protected document by invoking the RightsManagementServiceClient object’s revokeLicense method and passing the following values:

      • A string value that specifies the license identifier value of the policy-protected document (specify the return value of the RightsManagementServiceService object’s getLicenseId method).

      • A static data member of the Reason enum that specifies the reason to revoke the document. For example, you can specify Reason.DOCUMENT_REVISED.

      • A string value that specifies the URL location to where a revised document is located. If you do not want to redirect a user to another URL, then you can pass null.

Code examples

For code examples using the Rights Management service, see the following Quick Starts in API Quick Starts (Code Examples):

  • “Quick Start (MTOM): Revoking a document using the web service API”

  • “Quick Start (SwaRef): Revoking a document using the web service API”

// Ethnio survey code removed