Temp_SpaceResolution/src/documentation/content/xdocs/pdfencryption.xml - xmlgraphics-fop - Git at Google

 <?xml version="1.0" standalone="no"?>
 <!--
   Copyright 1999-2004 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 V1.1//EN"
     "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/core/context/resources/schema/dtd/document-v12.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[
 Driver driver = new Driver();
 driver.setRenderer(Driver.RENDER_PDF);
 Map rendererOptions = new java.util.HashMap();
 rendererOptions.put("ownerPassword", "mypassword");
 rendererOptions.put("allowCopyContent", "FALSE");
 rendererOptions.put("allowEditContent", "FALSE");
 rendererOptions.put("allowPrint", "FALSE");
 driver.getRenderer().setOptions(rendererOptions);
 driver.setOutputStream(...]]></source>
     </section>
     <section>
       <title>Environment</title>
       <p>
         In order to use PDF encryption, FOP has to be compiled with
         cryptography support. Currently, only <link
         href="http://java.sun.com/j2se/1.4/docs/guide/security/jce/JCERefGuide.html">JCE</link>
         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 <link
         href="http://www.bouncycastle.org/">The Legion of the Bouncy
         Castle</link>. <link
         href="http://www.mozilla.org/projects/security/pki/jss/">Mozilla
         JSS</link> 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 <link
         href="http://www.bouncycastle.org/">Bouncy Castle</link> 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 <link href="http://java.sun.com/j2se/1.4/docs/guide/security/jce/JCERefGuide.html#InstallProvider">Sun's web site</link>.
         </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>
	<?xml version="1.0" standalone="no"?>
	<!--
	Copyright 1999-2004 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 V1.1//EN"
	"http://cvs.apache.org/viewcvs.cgi/checkout/xml-forrest/src/core/context/resources/schema/dtd/document-v12.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[
	Driver driver = new Driver();
	driver.setRenderer(Driver.RENDER_PDF);
	Map rendererOptions = new java.util.HashMap();
	rendererOptions.put("ownerPassword", "mypassword");
	rendererOptions.put("allowCopyContent", "FALSE");
	rendererOptions.put("allowEditContent", "FALSE");
	rendererOptions.put("allowPrint", "FALSE");
	driver.getRenderer().setOptions(rendererOptions);
	driver.setOutputStream(...]]></source>
	</section>
	<section>
	<title>Environment</title>
	<p>
	In order to use PDF encryption, FOP has to be compiled with
	cryptography support. Currently, only <link
	href="http://java.sun.com/j2se/1.4/docs/guide/security/jce/JCERefGuide.html">JCE</link>
	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 <link
	href="http://www.bouncycastle.org/">The Legion of the Bouncy
	Castle</link>. <link
	href="http://www.mozilla.org/projects/security/pki/jss/">Mozilla
	JSS</link> 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 <link
	href="http://www.bouncycastle.org/">Bouncy Castle</link> 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 <link href="http://java.sun.com/j2se/1.4/docs/guide/security/jce/JCERefGuide.html#InstallProvider">Sun's web site</link>.
	</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>