diff options
Diffstat (limited to 'src/documentation/content/xdocs/1.1rc1/pdfencryption.xml')
| -rw-r--r-- | src/documentation/content/xdocs/1.1rc1/pdfencryption.xml | 301 |
1 files changed, 301 insertions, 0 deletions
diff --git a/src/documentation/content/xdocs/1.1rc1/pdfencryption.xml b/src/documentation/content/xdocs/1.1rc1/pdfencryption.xml new file mode 100644 index 000000000..2d8fdfb10 --- /dev/null +++ b/src/documentation/content/xdocs/1.1rc1/pdfencryption.xml @@ -0,0 +1,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>
\ No newline at end of file |