diff options
| author | Joerg Pietschmann <pietsch@apache.org> | 2003-03-05 23:15:25 +0000 |
|---|---|---|
| committer | Joerg Pietschmann <pietsch@apache.org> | 2003-03-05 23:15:25 +0000 |
| commit | 2c04cbf5b37b9158a6e923a7cef43e6dab1804a2 (patch) | |
| tree | 3bf02444cd01b6326a45cd9657a0e78b49f2f0a6 /src | |
| parent | 5c3513970f55b9d2cce51b109648f37ec63cb542 (diff) | |
| download | xmlgraphics-fop-2c04cbf5b37b9158a6e923a7cef43e6dab1804a2.tar.gz xmlgraphics-fop-2c04cbf5b37b9158a6e923a7cef43e6dab1804a2.zip | |
Added documentation for PDF encryption to xdocs.
git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@196022 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'src')
| -rw-r--r-- | src/documentation/content/xdocs/book.xml | 1 | ||||
| -rwxr-xr-x | src/documentation/content/xdocs/pdfencryption.xml | 108 | ||||
| -rw-r--r-- | src/documentation/content/xdocs/running.xml | 130 |
3 files changed, 177 insertions, 62 deletions
diff --git a/src/documentation/content/xdocs/book.xml b/src/documentation/content/xdocs/book.xml index 9c635c565..2edad2e51 100644 --- a/src/documentation/content/xdocs/book.xml +++ b/src/documentation/content/xdocs/book.xml @@ -38,6 +38,7 @@ <menu-item label="SVG" href="svg.html"/> <menu-item label="Extensions" href="extensions.html"/> <menu-item label="Fonts" href="fonts.html"/> + <menu-item label="PDF encryption" href="pdfencryption.html"/> <menu-item label="Configuration" href="configuration.html"/> </menu> diff --git a/src/documentation/content/xdocs/pdfencryption.xml b/src/documentation/content/xdocs/pdfencryption.xml new file mode 100755 index 000000000..23a38a4f5 --- /dev/null +++ b/src/documentation/content/xdocs/pdfencryption.xml @@ -0,0 +1,108 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.1//EN" + "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> + +<document> + <header> + <title>PDF encryption.</title> + </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 + printing, editing and copying text from the document or to forbid + 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 regarrding PDFF + encryption, look at the documentation coming with Adobe Acrobat or the + technial documentation on the Adobe web site. + </p> + </section> + <section> + <title>Usage</title> + <p> + Encryption is enabled by supplying an owner password with the + <code>-o</code> option. The owner password can be used to disregard + any restriction imposed on the PDF document. If no owner password has + been supplied but FOP was asked to apply some restrictions, a random + password is used. + </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, copy text, editing in Adobe Acrobat and making + annotations, respectively. + </p> + </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, however, the build process currently recognizes + JCE from JDK 1.4. + </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> + you don't have the needed support. + </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> + <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 alos 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> + </section> + </body> +</document> diff --git a/src/documentation/content/xdocs/running.xml b/src/documentation/content/xdocs/running.xml index 685b7da0e..5e420bf98 100644 --- a/src/documentation/content/xdocs/running.xml +++ b/src/documentation/content/xdocs/running.xml @@ -3,77 +3,83 @@ "http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/schema/dtd/document-v11.dtd"> <document> -<header> - <title>Running FOP</title> -</header> + <header> + <title>Running FOP</title> + </header> -<body> - <section> - <title>Installation</title> + <body> <section> - <title>Overview</title> - <p>The following software must be installed:</p> - <ul> - <li>Java 1.2.x or later.</li> - <li>FOP. The <jump href="http://xml.apache.org/fop/download.html">FOP distribution</jump> includes all libraries that you will need to run a basic FOP installation. These can be found in the xml-fop/lib directory. These libraries include the following:</li> + <title>Installation</title> + <section> + <title>Overview</title> + <p>The following software must be installed:</p> <ul> - <li>Apache <jump href="http://xml.apache.org/xerces-j/index.html">Xerces-J</jump> for XML parsing. You can use other XML parsers which support SAX and DOM.</li> - <li>Apache Xalan, an XSLT processor.</li> - <li>Apache <jump href="http://xml.apache.org/batik/">Batik</jump>, an SVG library.</li> + <li>Java 1.2.x or later.</li> + <li>FOP. The <jump href="http://xml.apache.org/fop/download.html">FOP distribution</jump> includes all libraries that you will need to run a basic FOP installation. These can be found in the xml-fop/lib directory. These libraries include the following:</li> + <ul> + <li>Apache <jump href="http://xml.apache.org/xerces-j/index.html">Xerces-J</jump> for XML parsing. You can use other XML parsers which support SAX and DOM.</li> + <li>Apache Xalan, an XSLT processor.</li> + <li>Apache <jump href="http://xml.apache.org/batik/">Batik</jump>, an SVG library.</li> + </ul> + <li>Optional Libraries</li> </ul> - <li>Optional Libraries</li> - </ul> - </section> - <section> - <title>Instructions</title> - <p>Basic FOP installation consists of first unzipping the <code>.gz</code> file that is the distribution medium, then unarchiving the resulting <code>.tar</code> file in a directory/folder that is convenient on your system. Please consult your operating system documentation or Zip application software documentation for instructions specific to your site.</p> + </section> + <section> + <title>Instructions</title> + <p>Basic FOP installation consists of first unzipping the <code>.gz</code> file that is the distribution medium, then unarchiving the resulting <code>.tar</code> file in a directory/folder that is convenient on your system. Please consult your operating system documentation or Zip application software documentation for instructions specific to your site.</p> + </section> + <section> + <title>Problems</title> + <p>Some Mac OSX users have experienced filename truncation problems using Stuffit to unzip and unarchive their distribution media. This is a legacy of older Mac operating systems, which had a 31-character pathname limit. Several Mac OSX users have recommended that Mac OSX users use the shell command <code>tar -xzf</code> instead.</p> + </section> </section> <section> - <title>Problems</title> - <p>Some Mac OSX users have experienced filename truncation problems using Stuffit to unzip and unarchive their distribution media. This is a legacy of older Mac operating systems, which had a 31-character pathname limit. Several Mac OSX users have recommended that Mac OSX users use the shell command <code>tar -xzf</code> instead.</p> - </section> - </section> - - <section> - <title>Starting FOP as a standalone application</title> - <p>Review the batch file fop.bat or the shell script fop.sh to see how FOP is invoked.</p> - <p>The standard scripts for starting FOP require that the environment variable JAVA_HOME be set to a path pointing to the appropriate Java installation on your system. Macintosh OSX includes a Java environment as part of its distribution. We are told by Mac OSX users that the path to use in this case is <code>/Library/Java/Home</code>. <strong>Caveat: </strong>We suspect that, as Apple releases new Java environments and as FOP upgrades the minimum Java requirements, the two will inevitably not match on some systems. Please see <jump href="http://developer.apple.com/java/faq">Java on Mac OSX FAQ</jump> for information as it becomes available.</p> - <p><code>fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-pcl|-ps|-txt|-svg|-at|-print] <outfile></code></p> - <p>[OPTIONS]</p> - <source> - -d debug mode<br/> - -x dump configuration settings<br/> - -q quiet mode<br/> - -c cfg.xml use additional configuration file cfg.xml<br/> - -l lang the language to use for user information<br/></source> - <p>[INPUT]</p> - <source> - infile xsl:fo input file (the same as the next)<br/> - -fo infile xsl:fo input file<br/> - -xml infile xml input file, must be used together with -xsl<br/> - -xsl stylesheet xslt stylesheet<br/></source> + <title>Starting FOP as a standalone application</title> + <p>Review the batch file fop.bat or the shell script fop.sh to see how FOP is invoked.</p> + <p>The standard scripts for starting FOP require that the environment variable JAVA_HOME be set to a path pointing to the appropriate Java installation on your system. Macintosh OSX includes a Java environment as part of its distribution. We are told by Mac OSX users that the path to use in this case is <code>/Library/Java/Home</code>. <strong>Caveat: </strong>We suspect that, as Apple releases new Java environments and as FOP upgrades the minimum Java requirements, the two will inevitably not match on some systems. Please see <jump href="http://developer.apple.com/java/faq">Java on Mac OSX FAQ</jump> for information as it becomes available.</p> + <p><code>fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-pcl|-ps|-txt|-svg|-at|-print] <outfile></code></p> + <p>[OPTIONS]</p> + <source> + -d debug mode + -x dump configuration settings + -q quiet mode + -c cfg.xml use additional configuration file cfg.xml + -l lang the language to use for user information + -s (-at output) omit tree below block areas + -txt.encoding (-txt output encoding use the encoding for the output file. + The encoding must be a valid java encoding. + -o [password] pdf file will be encrypted with option owner password + -u [password] pdf file will be encrypted with option user password + -noprint pdf file will be encrypted without printing permission + -nocopy pdf file will be encrypted without copy content permission + -noedit pdf file will be encrypted without edit content permission + -noannotations pdf file will be encrypted without edit annotation permission</source> + <p>[INPUT]</p> + <source> infile XSLFO input file (the same as the next) + -fo infile xsl:fo input file + -xml infile xml input file, must be used together with -xsl + -xsl stylesheet xslt stylesheet</source> - <p>[OUTPUT]</p> - <source> - outfile input will be rendered as pdf file into outfile<br/> - -pdf outfile input will be rendered as pdf file (outfile req'd)<br/> - -awt input will be displayed on screen<br/> - -mif outfile input will be rendered as mif file (outfile req'd)<br/> - -pcl outfile input will be rendered as pcl file (outfile req'd)<br/> - -ps outfile input will be rendered as PostScript file (outfile req'd)<br/> - -txt outfile input will be rendered as text file (outfile req'd)<br/> + <p>[OUTPUT]</p> + <source> outfile input will be rendered as pdf file into outfile + -pdf outfile input will be rendered as pdf file (outfile req'd) + -awt input will be displayed on screen + -mif outfile input will be rendered as mif file (outfile req'd) + -pcl outfile input will be rendered as pcl file (outfile req'd) + -ps outfile input will be rendered as PostScript file (outfile req'd) + -txt outfile input will be rendered as text file (outfile req'd) -svg outfile input will be rendered as an svg slides file (outfile req'd) -at outfile representation of area tree as XML (outfile req'd) - -print input file will be rendered and sent to the printer<br/> see options with "-print help"<br/></source> - - <p>[Examples]</p> - <source> - fop foo.fo foo.pdf<br/> - fop -fo foo.fo -pdf foo.pdf (does the same as the previous line)<br/> - fop -xsl foo.xsl -xml foo.xml -pdf foo.pdf<br/> - fop foo.fo -mif foo.mif<br/> - fop foo.fo -print or Fop -print foo.fo<br/> - fop foo.fo -awt<br/></source> + -print input file will be rendered and sent to the printer + see print specific options with "-print help"</source> + <p>[Examples]</p> + <source> fop foo.fo foo.pdf + fop -fo foo.fo -pdf foo.pdf (does the same as the previous line) + fop -xsl foo.xsl -xml foo.xml -pdf foo.pdf + fop foo.fo -mif foo.mif + fop foo.fo -print or Fop -print foo.fo + fop foo.fo -awt</source> + <p>PDF encryption is only available if FOP was compiled with encryption support <strong>and</strong> if compatible encryption support is availabe at run time. Currently, only the JCE is supported. Check the <link href="pdfencryption.html">Details</link>.</p> </section> <section> |