PDF encryption.

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 @@ + + + + +

+ PDF encryption. +

+ +

+ Overview +

+ 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. +

+ 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. +

+ Usage +

+ Encryption is enabled by supplying an owner password with the + -o 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. +

+ A user password, supplied with the -u 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. +

+ Further restrictions can be imposed by using the + -noprint, -nocopy, + -noedit and -noannotations options, + which disable printing, copy text, editing in Adobe Acrobat and making + annotations, respectively. +

+ Environment +

+ In order to use PDF encryption, FOP has to be compiled with cryptography + support. Currently, only JCE + 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. +

+ 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 not provide RC4. If you + get a message saying +

+ "Cannot find any provider supporting RC4" +

+ you don't have the needed support. +

+ There are several commercial and a few Open Source packages which + provide RC4. A pure Java implementation is produced by The Legion of the Bouncy + Castle. Mozilla + JSS is an interface to a native implementation. +

+ Installing a crypto provider +

+ The pure Java implementation from Bouncy Castle is easy to + install. +

+ 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. +
+ 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 + fop.sh. If you have JDK 1.3 or earlier don't forget to + install the JCE as well. +
+ Open the java.security file and add
+ security.provider.6=org.bouncycastle.jce.provider.BouncyCastleProvider,
+ preferably at the end of the block defining the other crypto + providers. For JDK 1.4 this is detailed on Sun's web site. +

+ + 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"> -

- Running FOP -

+ Running FOP +

- -

- Installation +

- Overview -

The following software must be installed:

Java 1.2.x or later.
FOP. The FOP distribution 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:

Installation

+ Overview +

The following software must be installed:

Apache Xerces-J for XML parsing. You can use other XML parsers which support SAX and DOM.
Apache Xalan, an XSLT processor.
Apache Batik, an SVG library.
Java 1.2.x or later.
FOP. The FOP distribution 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:

Apache Xerces-J for XML parsing. You can use other XML parsers which support SAX and DOM.
Apache Xalan, an XSLT processor.
Apache Batik, an SVG library.

Optional Libraries

Optional Libraries

- Instructions -

Basic FOP installation consists of first unzipping the .gz file that is the distribution medium, then unarchiving the resulting .tar 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.

+ Instructions +

+ Problems +

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 tar -xzf instead.

- Problems -

- - -

- Starting FOP as a standalone application -

Review the batch file fop.bat or the shell script fop.sh to see how FOP is invoked.

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 /Library/Java/Home. Caveat: 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 Java on Mac OSX FAQ for information as it becomes available.

fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-pcl|-ps|-txt|-svg|-at|-print] <outfile>

[OPTIONS]

- - -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
-

[INPUT]

- - infile xsl:fo 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
+ Starting FOP as a standalone application +

Review the batch file fop.bat or the shell script fop.sh to see how FOP is invoked.

fop [options] [-fo|-xml] infile [-xsl file] [-awt|-pdf|-mif|-pcl|-ps|-txt|-svg|-at|-print] <outfile>

[OPTIONS]

+ + -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 +

[INPUT]

+ 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 -

[OUTPUT]

- - 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)
+

[OUTPUT]

+ 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
see options with "-print help"
- -

[Examples]

- - 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
+ -print input file will be rendered and sent to the printer + see print specific options with "-print help" +

[Examples]

+ 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 +

PDF encryption is only available if FOP was compiled with encryption support and if compatible encryption support is availabe at run time. Currently, only the JCE is supported. Check the Details.