123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301 |
- <?xml version="1.0" 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>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>
- 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>
|