pietsch 2003/03/05 15:15:25 Modified: src/documentation/content/xdocs book.xml running.xml Added: src/documentation/content/xdocs pdfencryption.xml Log: Added documentation for PDF encryption to xdocs. Revision Changes Path 1.9 +1 -0 xml-fop/src/documentation/content/xdocs/book.xml Index: book.xml =================================================================== RCS file: /home/cvs/xml-fop/src/documentation/content/xdocs/book.xml,v retrieving revision 1.8 retrieving revision 1.9 diff -u -r1.8 -r1.9 --- book.xml 27 Jan 2003 20:59:55 -0000 1.8 +++ book.xml 5 Mar 2003 23:15:25 -0000 1.9 @@ -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> 1.5 +68 -62 xml-fop/src/documentation/content/xdocs/running.xml Index: running.xml =================================================================== RCS file: /home/cvs/xml-fop/src/documentation/content/xdocs/running.xml,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- running.xml 18 Jan 2003 18:04:58 -0000 1.4 +++ running.xml 5 Mar 2003 23:15:25 -0000 1.5 @@ -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>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>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> + <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> - <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> - - <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> 1.1 xml-fop/src/documentation/content/xdocs/pdfencryption.xml Index: pdfencryption.xml =================================================================== <?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>
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]