aboutsummaryrefslogtreecommitdiffstats
path: root/src/documentation/content/xdocs/0.92/pdfencryption.xml
diff options
context:
space:
mode:
authorJeremias Maerki <jeremias@apache.org>2006-04-20 07:20:08 +0000
committerJeremias Maerki <jeremias@apache.org>2006-04-20 07:20:08 +0000
commite7c525e71f648127fd392b56490219b36670f70e (patch)
tree8b6a64e1d747b7203ccf426137eafac1c861288a /src/documentation/content/xdocs/0.92/pdfencryption.xml
parent274e03076bc7dd15e444f1628d96f0703b40e16f (diff)
downloadxmlgraphics-fop-e7c525e71f648127fd392b56490219b36670f70e.tar.gz
xmlgraphics-fop-e7c525e71f648127fd392b56490219b36670f70e.zip
Merged changes from 0.92 branch back into Trunk.
git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@395518 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'src/documentation/content/xdocs/0.92/pdfencryption.xml')
-rwxr-xr-xsrc/documentation/content/xdocs/0.92/pdfencryption.xml233
1 files changed, 233 insertions, 0 deletions
diff --git a/src/documentation/content/xdocs/0.92/pdfencryption.xml b/src/documentation/content/xdocs/0.92/pdfencryption.xml
new file mode 100755
index 000000000..aca98135a
--- /dev/null
+++ b/src/documentation/content/xdocs/0.92/pdfencryption.xml
@@ -0,0 +1,233 @@
+<?xml version="1.0" standalone="no"?>
+<!--
+ Copyright 1999-2006 The Apache Software Foundation
+
+ Licensed 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>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>
+ <warning>
+ PDF Encryption is available in Release 0.20.5 and later. The comments on this page do
+ not apply to releases earlier than 0.20.5.
+ </warning>
+ <p>
+ 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 <code>-noprint</code>,
+ <code>-nocopy</code>, <code>-noedit</code> and
+ <code>-noannotations</code> options, which disable printing, copying
+ text, editing in Adobe Acrobat and making annotations, respectively.
+ </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>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 of content</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>
+ </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>
+ </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>
+ </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. If you have JDK
+ 1.3 or earlier you must also download a JCE from the same page.
+ </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>. If you have JDK 1.3 or earlier don't forget to
+ install the JCE as well.
+ </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>