1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!-- $Id$ -->
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
<document>
<header>
<title>Apache™ FOP: PDF encryption.</title>
<version>$Revision$</version>
<authors>
<person name="J.Pietschmann" email="pietsch@apache.org"/>
<person name="Jeremias Märki" email="jeremias@apache.org"/>
</authors>
</header>
<body>
<section>
<title>Overview</title>
<p>
Apache™ FOP supports encryption of PDF output, thanks to Patrick
C. Lankswert. This feature is commonly used to prevent
unauthorized viewing, printing, editing, copying text from the
document and doing annotations. It is also possible to ask the
user for a password in order to view the contents. Note that
there already exist third party applications which can decrypt
an encrypted PDF without effort and allow the aforementioned
operations, therefore the degree of protection is limited.
</p>
<p>
For further information about features and restrictions regarding PDF
encryption, look at the documentation coming with Adobe Acrobat or the
technical documentation on the Adobe web site.
</p>
</section>
<section>
<title>Usage (command line)</title>
<p>
Encryption is enabled by supplying any of the encryption related
options.
</p>
<p>
An owner password is set with the <code>-o</code> option. This
password is actually used as encryption key. Many tools for
PDF processing ask for this password to disregard any
restriction imposed on the PDF document.
</p>
<p>
If no owner password has been supplied but FOP was asked to apply some
restrictions, a random password is used. In this case it is obviously
impossiible to disregard restrictions in PDF processing tools.
</p>
<p>
A user password, supplied with the <code>-u</code> option, will
cause the PDF display software to ask the reader for this password in
order to view the contents of the document. If no user password was
supplied, viewing the content is not restricted.
</p>
<p>
Further restrictions can be imposed by using the following command-line options:
<table>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
<tr>
<td><code>-noprint</code></td>
<td>disable printing</td>
</tr>
<tr>
<td><code>-nocopy</code></td>
<td>disable copy/paste of content</td>
</tr>
<tr>
<td><code>-noedit</code></td>
<td>disable editing in Adobe Acrobat</td>
</tr>
<tr>
<td><code>-noannotations</code></td>
<td>disable editing of annotations</td>
</tr>
<tr>
<td><code>-nofillinforms</code></td>
<td>disable filling in forms</td>
</tr>
<tr>
<td><code>-noaccesscontent</code></td>
<td>disable text and graphics extraction for accessibility purposes</td>
</tr>
<tr>
<td><code>-noassembledoc</code></td>
<td>disable assembling documents</td>
</tr>
<tr>
<td><code>-noprinthq</code></td>
<td>disable high quality printing</td>
</tr>
</table>
</p>
</section>
<section>
<title>Usage (embedded)</title>
<p>
When FOP is embedded in another Java application you need to set an
options map on the renderer. These are the supported options:
</p>
<table>
<tr>
<th>Option</th>
<th>Description</th>
<th>Values</th>
<th>Default</th>
</tr>
<tr>
<td>encryption-length</td>
<td>The encryption length in bit</td>
<td>Any multiple of 8 between 40 and 128</td>
<td>40</td>
</tr>
<tr>
<td>ownerPassword</td>
<td>The owner password</td>
<td>String</td>
<td/>
</tr>
<tr>
<td>userPassword</td>
<td>The user password</td>
<td>String</td>
<td/>
</tr>
<tr>
<td>allowPrint</td>
<td>Allows/disallows printing of the PDF</td>
<td>"TRUE" or "FALSE"</td>
<td>"TRUE"</td>
</tr>
<tr>
<td>allowCopyContent</td>
<td>Allows/disallows copy/paste of content</td>
<td>"TRUE" or "FALSE"</td>
<td>"TRUE"</td>
</tr>
<tr>
<td>allowEditContent</td>
<td>Allows/disallows editing in Adobe Acrobat</td>
<td>"TRUE" or "FALSE"</td>
<td>"TRUE"</td>
</tr>
<tr>
<td>allowEditAnnotations</td>
<td>Allows/disallows editing of annotations</td>
<td>"TRUE" or "FALSE"</td>
<td>"TRUE"</td>
</tr>
<tr>
<td>allowFillInForms</td>
<td>Allows/disallows filling in forms</td>
<td>"TRUE" or "FALSE"</td>
<td>"TRUE"</td>
</tr>
<tr>
<td>allowAccessContent</td>
<td>Allows/disallows text and graphics extraction for accessibility purposes</td>
<td>"TRUE" or "FALSE"</td>
<td>"TRUE"</td>
</tr>
<tr>
<td>allowAssembleDocument</td>
<td>Allows/disallows assembling document</td>
<td>"TRUE" or "FALSE"</td>
<td>"TRUE"</td>
</tr>
<tr>
<td>allowPrintHq</td>
<td>Allows/disallows high quality printing</td>
<td>"TRUE" or "FALSE"</td>
<td>"TRUE"</td>
</tr>
</table>
<note>
Encryption is enabled as soon as one of these options is set.
</note>
<p>
An example to enable PDF encryption in Java code:
</p>
<source><![CDATA[
import org.apache.fop.pdf.PDFEncryptionParams;
[..]
FOUserAgent userAgent = fopFactory.newFOUserAgent();
useragent.getRendererOptions().put("encryption-params", new PDFEncryptionParams(
null, "password", false, false, true, true));
Fop fop = fopFactory.newFop(MimeConstants.MIME_PDF, userAgent);
[..]]]></source>
<p>
The parameters for the constructor of PDFEncryptionParams are:
</p>
<ol>
<li>userPassword: String, may be null</li>
<li>ownerPassword: String, may be null</li>
<li>allowPrint: true if printing is allowed</li>
<li>allowCopyContent: true if copying content is allowed</li>
<li>allowEditContent: true if editing content is allowed</li>
<li>allowEditAnnotations: true if editing annotations is allowed</li>
<li>allowFillInForms: true if filling in forms is allowed.</li>
<li>allowAccessContent: true if extracting text and graphics is allowed</li>
<li>allowAssembleDocument: true if assembling document is allowed</li>
<li>allowPrintHq: true if printing to high quality is allowed</li>
</ol>
<p>
Alternatively, you can set each value separately in the Map provided by
FOUserAgent.getRendererOptions() by using the following keys:
</p>
<ol>
<li>user-password: String</li>
<li>owner-password: String</li>
<li>noprint: Boolean or "true"/"false"</li>
<li>nocopy: Boolean or "true"/"false"</li>
<li>noedit: Boolean or "true"/"false"</li>
<li>noannotations: Boolean or "true"/"false"</li>
<li>nofillinforms: Boolean or "true"/"false"</li>
<li>noaccesscontent: Boolean or "true"/"false"</li>
<li>noassembledoc: Boolean or "true"/"false"</li>
<li>noprinthq: Boolean or "true"/"false"</li>
</ol>
</section>
<section>
<title>Environment</title>
<p>
In order to use PDF encryption, FOP has to be compiled with
cryptography support. Currently, only <a
href="http://java.sun.com/j2se/1.4/docs/guide/security/jce/JCERefGuide.html">JCE</a>
is supported. JCE is part of JDK 1.4. For earlier JDKs, it can
be installed separately. The build process automatically
detects JCE presence and installs PDF encryption support if
possible, otherwise a stub is compiled in.
</p>
<p>
Cryptography support must also be present at run time. In particular, a
provider for the RC4 cipher is needed. Unfortunately, the sample JCE
provider in Sun's JDK 1.4 does <strong>not</strong> provide RC4. If you
get a message saying
</p>
<source>"Cannot find any provider supporting RC4"</source>
<p>
then you don't have the needed infrastructure.
</p>
<p>
There are several commercial and a few Open Source packages which
provide RC4. A pure Java implementation is produced by <a
href="http://www.bouncycastle.org/">The Legion of the Bouncy
Castle</a>. <a
href="http://www.mozilla.org/projects/security/pki/jss/">Mozilla
JSS</a> is an interface to a native implementation.
</p>
</section>
<section id="install_crypto">
<title>Installing a crypto provider</title>
<p>
The pure Java implementation from <a
href="http://www.bouncycastle.org/">Bouncy Castle</a> is easy to
install.
</p>
<ol>
<li>
Download the binary distribution for your JDK version.
</li>
<li>
Unpack the distribution. Add the jar file to your classpath. A
convenient way to use the jar on Linux is to simply drop it into the
FOP lib directory, it will be automatically picked up by
<code>fop.sh</code>.
</li>
<li>
Open the <code>java.security</code> file and add<br/>
<code>security.provider.6=org.bouncycastle.jce.provider.BouncyCastleProvider</code>,<br/>
preferably at the end of the block defining the other crypto
providers. For JDK 1.4 this is detailed on <a href="http://java.sun.com/j2se/1.4/docs/guide/security/jce/JCERefGuide.html#InstallProvider">Sun's web site</a>.
</li>
</ol>
<p>
If you have any experience with Mozilla JSS or any other
cryptography provider, please post it to the fop-user list.
</p>
</section>
</body>
</document>
|
