Creating Policies

You can programmatically create policies using the Rights Management Java API or web service API. A policy is a collection of information that includes document security settings, authorized users, and usage rights. You can create and save any number of policies, using security settings appropriate for different situations and users.

Policies enable you to perform these tasks:

  • Specify the individuals who can open the document. Recipients can either belong to or be external to your organization.

  • Specify how recipients can use the document. You can restrict access to different Acrobat and Adobe Reader features. These features include the ability to print and copy text, add signatures, and add comments to a document.

  • Change the access and security settings at any time, even after you distribute the policy-protected document.

  • Monitor the use of the document after you distribute it. You can see how the document is being used and who is using it. For example, you can find out when someone has opened the document.

Creating a policy using web services

When creating a policy using the web service API, reference an existing Portable Document Rights Language (PDRL) XML file that describes the policy. Policy permissions and the principal are defined in the PDRL document. The following XML document is an example of a PDRL document.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<Policy PolicyInstanceVersion="1" PolicyID="5DA3F847-DE76-F9CC-63EA-49A8D59154DE" PolicyCreationTime="2004-08-30T00:02:28.294+00:00" PolicyType="1" PolicySchemaVersion="1.0" PolicyName="SDK Test Policy -4344050357301573237" PolicyDescription="An SDK Test policy" xmlns="http://www.adobe.com/schema/1.0/pdrl"> 
      <PolicyEntry> 
         <ns1:Permission PermissionName="com.adobe.aps.onlineOpen" Access="ALLOW" xmlns:ns1="http://www.adobe.com/schema/1.0/pdrl" xmlns="http://www.adobe.com/schema/1.0/pdrl-ex" /> 
 
         <ns2:Permission PermissionName="com.adobe.aps.offlineOpen" Access="ALLOW" xmlns:ns2="http://www.adobe.com/schema/1.0/pdrl" xmlns="http://www.adobe.com/schema/1.0/pdrl-ex" /> 
 
         <ns3:Permission PermissionName="com.adobe.aps.pdf.editNotes" Access="ALLOW" xmlns:ns3="http://www.adobe.com/schema/1.0/pdrl" xmlns="http://www.adobe.com/schema/1.0/pdrl-ex" /> 
 
         <ns4:Permission PermissionName="com.adobe.aps.pdf.fillAndSign" Access="ALLOW" xmlns:ns4="http://www.adobe.com/schema/1.0/pdrl" xmlns="http://www.adobe.com/schema/1.0/pdrl-ex" /> 
 
         <Principal PrincipalNameType="SYSTEM"> 
            <PrincipalDomain>EDC_SPECIAL</PrincipalDomain> 
 
            <PrincipalName>all_internal_users</PrincipalName> 
         </Principal> 
      </PolicyEntry> 
 
      <PolicyEntry> 
         <ns5:Permission PermissionName="com.adobe.aps.onlineOpen" Access="ALLOW" xmlns:ns5="http://www.adobe.com/schema/1.0/pdrl" xmlns="http://www.adobe.com/schema/1.0/pdrl-ex" /> 
 
         <ns6:Permission PermissionName="com.adobe.aps.offlineOpen" Access="ALLOW" xmlns:ns6="http://www.adobe.com/schema/1.0/pdrl" xmlns="http://www.adobe.com/schema/1.0/pdrl-ex" /> 
 
         <ns7:Permission PermissionName="com.adobe.aps.pdf.copy" Access="ALLOW" xmlns:ns7="http://www.adobe.com/schema/1.0/pdrl" xmlns="http://www.adobe.com/schema/1.0/pdrl-ex" /> 
 
         <ns8:Permission PermissionName="com.adobe.aps.pdf.printLow" Access="ALLOW" xmlns="http://www.adobe.com/schema/1.0/pdrl-ex" xmlns:ns8="http://www.adobe.com/schema/1.0/pdrl" /> 
 
         <ns9:Permission PermissionName="com.adobe.aps.policySwitch" Access="ALLOW" xmlns:ns9="http://www.adobe.com/schema/1.0/pdrl" xmlns="http://www.adobe.com/schema/1.0/pdrl-ex" /> 
 
         <ns10:Permission PermissionName="com.adobe.aps.revoke" Access="ALLOW" xmlns="http://www.adobe.com/schema/1.0/pdrl-ex" xmlns:ns10="http://www.adobe.com/schema/1.0/pdrl" /> 
 
         <ns11:Permission PermissionName="com.adobe.aps.pdf.edit" Access="ALLOW" xmlns:ns11="http://www.adobe.com/schema/1.0/pdrl" xmlns="http://www.adobe.com/schema/1.0/pdrl-ex" /> 
 
         <ns12:Permission PermissionName="com.adobe.aps.pdf.editNotes" Access="ALLOW" xmlns:ns12="http://www.adobe.com/schema/1.0/pdrl" xmlns="http://www.adobe.com/schema/1.0/pdrl-ex" /> 
 
         <ns13:Permission PermissionName="com.adobe.aps.pdf.fillAndSign" Access="ALLOW" xmlns:ns13="http://www.adobe.com/schema/1.0/pdrl" xmlns="http://www.adobe.com/schema/1.0/pdrl-ex" /> 
 
         <ns14:Permission PermissionName="com.adobe.aps.pdf.printHigh" Access="ALLOW" xmlns:ns14="http://www.adobe.com/schema/1.0/pdrl" xmlns="http://www.adobe.com/schema/1.0/pdrl-ex" /> 
 
         <Principal PrincipalNameType="SYSTEM"> 
            <PrincipalDomain>EDC_SPECIAL</PrincipalDomain> 
 
            <PrincipalName>publisher</PrincipalName> 
         </Principal> 
      </PolicyEntry> 
 
      <OfflineLeasePeriod> 
         <Duration>P31D</Duration> 
      </OfflineLeasePeriod> 
 
      <AuditSettings isTracked="true" /> 
 
      <PolicyValidityPeriod isAbsoluteTime="false"> 
         <ValidityPeriodRelative> 
            <NotBeforeRelative>PT0S</NotBeforeRelative> 
 
            <NotAfterRelative>P20D</NotAfterRelative> 
         </ValidityPeriodRelative> 
      </PolicyValidityPeriod> 
</Policy> 
Remarque : For more information about the Rights Management service, see Services Reference for LiveCycle.

Summary of steps

To create a policy, perform the following steps:

  1. Include project files.

  2. Create a Rights Management Client API object.

  3. Set the policy’s attributes.

  4. Create a policy entry.

  5. Register the policy.

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.

The following JAR files must be added to your project’s classpath:

  • adobe-rightsmanagement-client.jar

  • namespace.jar (if LiveCycle is deployed on JBoss)

  • jaxb-api.jar (if LiveCycle is deployed on JBoss)

  • jaxb-impl.jar (if LiveCycle is deployed on JBoss)

  • jaxb-libs.jar (if LiveCycle is deployed on JBoss)

  • jaxb-xjc.jar (if LiveCycle is deployed on JBoss)

  • relaxngDatatype.jar (if LiveCycle is deployed on JBoss)

  • xsdlib.jar (if LiveCycle is deployed on JBoss)

  • adobe-livecycle-client.jar

  • adobe-usermanager-client.jar

  • adobe-utilities.jar

  • jbossall-client.jar (use a different JAR file if LiveCycle is not deployed on JBoss)

For information about the location of these JAR files, see Including LiveCycle Java library files.

Create a Rights Management Client API object

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

Set the policy’s attributes

To create a policy, set policy attributes. A mandatory attribute is the policy name. Policy names must be unique for each policy set. A policy set is simply a collection of policies. There can be two policies with the same name if the policies belong to separate policy sets. However, two policies within a single policy set cannot have the same policy name.

Another useful attribute to set is the validity period. A validity period is the time period during which a policy-protected document is accessible to authorized recipients. If you do not set this attribute, then the policy is always valid.

A validity period can be set to one of these options:

  • A set number of days that the document is accessible from the time which the document is published

  • An end date after which the document is not accessible

  • A specific date range for which the document is accessible

  • Always valid

You can specify just a start date, which results in the policy being valid after the start date. If you specify just an end date, the policy is valid until the end date. However, an exception is thrown if both a start date and an end date are not defined.

When setting attributes that belong to a policy, you can also set encryption settings. These encryption settings take affect when the policy is applied to a document. You can specify the following encryption values:

  • AES256: Represents the AES encryption algorithm with a 256-bit key.

  • AES128: Represents the AES encryption algorithm with a 128-bit key.

  • NoEncryption: Represents no encryption.

When specifying the NoEncryption option, you cannot set the PlaintextMetadata option to false. If you attempt to do so, an exception is thrown.

Remarque : For information about other attributes that you can set, see the Policy interface description in the LiveCycle API Reference.

Create a policy entry

A policy entry attaches principals, which are groups and users, and permissions to a policy. A policy must have at least one policy entry. Assume, for example, that you perform these tasks:

  • Create and register a policy entry that enables a group to only view a document while online and prohibits recipients from copying it.

  • Attach the policy entry to the policy.

  • Secure a document with the policy by using Acrobat.

These actions result in recipients only being able to view the document online and not being able to copy it. The document remains secure until security is removed from it.

Register the policy

A new policy must be registered before it can be used. After you register a policy, you can use it to protect documents.

Create a policy using the Java API

Create a policy 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. Set the policy’s attributes.

    • Create a Policy object by invoking the InfomodelObjectFactory object’s static createPolicy method. This method returns a Policy object.

    • Set the policy’s name attribute by invoking the Policy object’s setName method and passing a string value that specifies the policy name.

    • Set the policy’s description by invoking the Policy object’s setDescription method and passing a string value that specifies the policy’s description.

    • Set the policy set to which the new policy belongs by invoking the Policy object’s setPolicySetName method and passing a string value that specifies the policy set name. (You can specify null for this parameter value that results in the policy being added to the My Policies policy set.)

    • Create the policy’s validity period by invoking the InfomodelObjectFactory object’s static createValidityPeriod method. This method returns a ValidityPeriod object.

    • Set the number of days for which a policy-protected document is accessible by invoking the ValidityPeriod object’s setRelativeExpirationDays method and passing an integer value that specifies the number of days.

    • Set the policy’s validity period by invoking the Policy object’s setValidityPeriod method and passing the ValidityPeriod object.

  4. Create a policy entry.

    • Create a policy entry by invoking the InfomodelObjectFactory object’s static createPolicyEntry method. This method returns a PolicyEntry object.

    • Specify the policy’s permissions by invoking the InfomodelObjectFactory object’s static createPermission method. Pass a static data member that belongs to the Permission interface that represents the permission. This method returns a Permission object. For example, to add the permission that enables users to copy data from a policy-protected PDF document, pass Permission.COPY. (Repeat this step for each permission to add).

    • Add the permission to the policy entry by invoking the PolicyEntry object’s addPermission method and passing the Permission object. (Repeat this step for each Permission object that you created).

    • Create the policy principal by invoking the InfomodelObjectFactory object’s static createSpecialPrincipal method. Pass a data member that belongs to the InfomodelObjectFactory object that represents the principal. This method returns a Principal object. For example, to add the publisher of the document as the principal, pass InfomodelObjectFactory.PUBLISHER_PRINCIPAL.

    • Add the principal to the policy entry by invoking the PolicyEntry object’s setPrincipal method and passing the Principal object.

    • Add the policy entry to the policy by invoking the Policy object’s addPolicyEntry method and passing the PolicyEntry object.

  5. Register the policy.

    • Create a PolicyManager object by invoking the RightsManagementClient object’s getPolicyManager method.

    • Register the policy by invoking the PolicyManager object’s registerPolicy method and passing the following values:

      • The Policy object that represents the policy to register.

    • A string value that represents the policy set that the policy belongs to.

    If you use a LiveCycle administrator account within connection settings to create the RightsManagementClient object, then specify the policy set name when you invoke the registerPolicy method. If you pass a null value for the policy set, the policy is created in the administrators My Policies policy set.

    If you use a Rights Management user within connection settings, then you can invoke the overloaded registerPolicy method that accepts only the policy. That is, you do not need to specify the policy set name. However, the policy is added to the policy set named My Policies. If you do not want to add the new policy to this policy set, then specify a policy set name when you invoke the registerPolicy method.

    Remarque : When creating a policy, reference an existing policy set. If you specify a policy set that does not exist, then an exception is thrown.

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

  • “Quick Start (EJB mode): Creating a policy using the Java API”

  • “Quick Start (SOAP mode): Creating a policy using the Java API”

Create a policy using the web service API

Create a policy 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.

    Remarque : 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. Set the policy’s attributes.

    • Create a PolicySpec object by using its constructor.

    • Set the policy’s name by assigning a string value to the PolicySpec object’s name data member.

    • Set the policy’s description by assigning a string value to the PolicySpec object’s description data member.

    • Set the policy set to which the policy will belong by assigning a string value to the PolicySpec object’s policySetName data member. You must specify an existing policy set name. (You can specify null for this parameter value that results in the policy being added to My Policies.)

    • Set the policy’s offline lease period by assigning an integer value to the PolicySpec object’s offlineLeasePeriod data member.

    • Set the PolicySpec object’s policyXml data member with a string value that represents PDRL XML data. To perform this task, create a .NET StreamReader object by using its constructor. Pass the location of a PDRL XML file that represents the policy to the StreamReader constructor. Next, invoke the StreamReader object’s ReadLine method and assign the return value to a string variable. Iterate through the StreamReader object until the ReadLine method returns null. Assign the string variable to the PolicySpec object’s policyXml data member.

  4. Create a policy entry.

    It is not necessary to create a policy entry when creating a policy using the Rights Management web service API. The policy entry is defined in the PDRL document.

  5. Register the policy.

    Register the policy by invoking the RightsManagementServiceClient object’s registerPolicy method and passing the following values:

    • The PolicySpec object that represents the policy to register.

    • A string value that represents the policy set that the policy belongs to. You can specify a null value which results in the policy being added to the MyPolices policy set.

    If you use a LiveCycle administrator account within connection settings to create the RightsManagementClient object, specify the policy set name when you invoke the registerPolicy method.

    If you use a Rights Management user within connection settings, then you can invoke the overloaded registerPolicy method that accepts only the policy. That is, you do not need to specify the policy set name. However, the policy is added to the policy set named My Policies. If you do not want to add the new policy to this policy set, then specify a policy set name when you invoke the registerPolicy method.

    Remarque : When creating a policy and you specify a policy set, ensure that you specify an existing policy set. If you specify a policy set that does not exist, then an exception is thrown.

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

  • “Quick Start (MTOM): Creating a policy using the web service API”

  • “Quick Start (SwaRef): Creating a policy using the web service API”