|
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 servicesWhen 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>
Summary of stepsTo create a policy, perform the following steps:
Include project files.
Create a Rights Management Client API object.
Set the policy’s attributes.
Create a policy entry.
Register the policy.
Include project filesInclude 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 objectBefore you can programmatically
perform a Rights Management service operation, create a Rights Management
service client object.
Set the policy’s attributesTo
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.
Note: For
information about other attributes that you can set, see the Policy interface
description in the LiveCycle API Reference.
Create a policy entryA 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 policyA 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 APICreate a policy by using the Rights Management API (Java):
Include project files.
Include client JAR files,
such as adobe-rightsmanagement-client.jar, in your Java project’s
class path.
Create a Rights Management Client API object.
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.
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.
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:
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.
Note: 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):
Create a policy using the web service APICreate
a policy by using the Rights Management 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/RightsManagementService?WSDL&lc_version=9.0.1.
Note: Replace localhost with the IP
address of the server hosting LiveCycle.
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.
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.
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.
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.
Note: 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):
|
|
|
