Edit online

How to Secure the Publishing Process

In case you are building a publishing service based on the Oxygen Publishing Engine, there are several questions you should take into account:

Is the set of input documents coming from a trusted source?
Is the publishing template customization under your organization control or is it uploaded by another party?

If the data or customization is not fully controlled, you must take some steps to make the publishing process as secure as possible.

The Oxygen Publishing Engine is a Java process that invokes an ANT script that processes the input documents in stages, up to the final output. When using a CSS-based PDF transformation, besides the normal processing, a new Java process is forked (the Chemistry process that transforms the merged DITA map into a PDF file).

Java has a built-in security mechanism that lets you control the set of accessible resources. It has command-line options that allow the caller to indicate a security policy file.

Because there are two processes, two policy files are needed for securing the publishing process (the ope.policy file and the chemistry.policy file):

The ope.policy File

It is located here: ${OPE-INSTALL_DIR}/config/ope.policy. This can be used as a starting point (a template) for securing just the primary OPE process. You can add more permissions for other resources.

Note: When changing this file, it is better to save it in another location and change it there. This ensures that you will not lose changes when upgrading the Oxygen Publishing Engine.

....
grant {

	/////////////////////////////////////////////////////////////////
	// Permissions for the Publishing Engine input and output.
	
	// The installation directory of the OPE
	permission java.io.FilePermission "${ope.install.dir}", "read";
	permission java.io.FilePermission "${ope.install.dir}/-", "read";
	
	// The output directory where the files will be stored.
	// This property should be set to the main "out" folder, 
	// not the transtype subfolder like: "out/pdf-css-html5".
	permission java.io.FilePermission "${ope.output.dir}", "read, write";
	permission java.io.FilePermission "${ope.output.dir}/-", "read, write, delete";
	
....

In the snippet above, the variables are system properties that must be specified when starting the primary DITA transformation process.

To start the OPE process with the security constraints, you have to use the ANT_OPTS environment variable to set the Java system properties that activate the security mechanism (the java.security.manager and java.security.policy) that points to either the file specified in the config folder or to the one you changed. The OPE_INSTALL_DIR should be the directory where the OPE is installed in file syntax form (not a URL).

SET OPE_INSTALL_DIR="C:\ope"
ANT_OPTS=-Djava.security.policy="file:/%OPE_INSTALL_DIR%/config/ope.policy" \
         -Djava.security.manager

You need to set values to the variables used in the policy file. This can be done using the same ANT_OPTS environment variable:

SET ANT_OPTS=%ANT_OPTS% \
-Dope.install.dir="%OPE_INSTALL_DIR%" \
-Dope.input.dir="test\map" \
-Dope.output.dir="test\map\out" \
-Dope.temp.dir="test\map\temp" \
-Dope.publishing.template.dir="test\templates\template" \
-Djava.io.tmpdir="test\map\temp\pdf-css-html5" \
-Dcss.processor.path.chemistry="%OPE_INSTALL_DIR%\plugins\com.oxygenxml.pdf.css\lib\oxygen-pdf-chemistry\chemistry.bat"

Note: If you plan to create your own policy file, you can specify the paths directly without needing to pass them as system properties. Take care to quote the paths and escape the backslash file separators on Windows. The "*" operator means all files from the folder, while the "-" operator means all files from a folder and its subfolders. For example:

permission java.io.FilePermission "C:\\folder\\with\\images\\-", "read";

Of course, you also have the option of using more variables. Make sure you set them in the ANT_OPTS environment variable.

Note: You can control the set of system properties the XSLT processor can read by using the ope.allowed.sys.props.for.saxon parameter. It accepts a semi-colon (;) separated list of property names. The built-in default is:

-Dope.allowed.sys.props.for.saxon="file.separator;path.separator;line.separator;OT_VERSION;webhelp.*;user.dir"

Tip: It is good practice to specify another temporary directory that will be used by the Java process (the java.io.tmpdir parameter) to avoid leaving the process to read and write in the system-wide temporary folder.

The chemistry.policy File

It is located here: ${OPE_INSTALL_DIR}/plugins/com.oxygenxml.pdf.css/lib/oxygen-pdf-chemistry/config/chemistry.policy. This also can be used as it is, or as a template, for securing the Chemistry process that is forked by the OPE.

This time, the security policy file can be specified using the chemistry.security.policy system property argument. In addition, you need to specify a folder where Chemistry will create its temporary files and font cache using the chemistry.security.workspace property:

dita.bat -Dchemistry.security.policy="%OPE_INSTALL_DIR%\plugins\com.oxygenxml.pdf.css\lib\oxygen-pdf-chemistry\config\chemistry.policy \
-Dchemistry.security.workspace="C:\some\dir\for\chemistry\fonts\cache\and\temp\files"

Note: If you plan to change the chemistry policy file, it is better to save it in another location and change it there. This ensures that you will not lose changes when upgrading the Oxygen Publishing Engine.