Edit online

Security Manager

By default, Oxygen XML Web Author comes with Java Security Manager configured. It is enabled by default when using the Windows Installer, Linux Installer, or All Platforms Kit. When enabled, it only allows the minimal file access permissions that are required for the application to function properly:
  • READ access to the directory where the Oxygen XML Web Author is deployed.
  • READ and WRITE access to the application's working directory.
  • READ and WRITE access to JVM's temporary directory.

Disabling Security Manager

To disable the default security mode that only allows minimal file permissions, follow this procedure (depending on your installation method):

Windows Installer
  1. Go to the installation directory of Oxygen XML Web Author.
  2. Launch Manage Web Author Service.
  3. Go to the Java tab.
  4. In the Java Options section, remove the -Djava.security.manager system property.
  5. Click Apply.
  6. Restart the application.
Linux Installer or All Platforms Kit
  1. Go to the installation directory of Oxygen XML Web Author.
  2. Edit the oXygenXmlWebAuthor.vmoptions file.
  3. Remove the -Djava.security.manager system property.
  4. Save the file.
  5. Restart the application.

Enabling Security Manager

To enable security mode, use the following procedure (depending on your installation method):

Windows Installer
  1. Go to the installation directory of Oxygen XML Web Author.
  2. Launch Manage Web Author Service.
  3. Go to the Java tab.
  4. In the Java Options section, add the -Djava.security.manager system property.
  5. Click Apply.
  6. Restart the application.
Linux Installer or All Platforms Kit
  1. Go to the installation directory of Oxygen XML Web Author.
  2. Edit the oXygenXmlWebAuthor.vmoptions file.
  3. Add the -Djava.security.manager property.
  4. Save the file.
  5. Restart the application.
WAR distribution (when deployed on an Apache Tomcat server)
  1. Edit the catalina.policy file and add the following snippet:
    grant codeBase "file:${catalina.base}/webapps/oxygenxml-web-author/-" {
      // Oxygen uses System properties for various configuration purposes.
      permission java.util.PropertyPermission "*", "read,write";
      // Oxygen custom protocols need access to network.
      permission java.net.NetPermission "*";
      permission java.net.SocketPermission "*", "accept,connect,listen,resolve";
      // The web framework used by Oxygen Webapp uses reflection and classloaders.
      permission java.lang.reflect.ReflectPermission "suppressAccessChecks";
      permission java.security.SecurityPermission "*";
      permission java.util.logging.LoggingPermission "control";
      permission java.lang.RuntimePermission "*";
    
      // Oxygen requires these permissions to connect to a URL.
      permission java.net.URLPermission "http:*", "*";
      permission java.net.URLPermission "https:*", "*";
      permission java.net.URLPermission "file:*", "*";
    
      // Oxygen should be allowed to read JVM jars
      permission java.io.FilePermission "${java.home}/-", "read";
    	
      // Oxygen uses the JVM's java.io.tempdir for various file handling tasks.
      permission java.io.FilePermission "${java.io.tmpdir}/-", "read,write,delete";
      permission java.io.FilePermission "${java.io.tmpdir}", "read,write,delete";
    
      // Folder used by Oxygen to deploy the plugins to.
      permission java.io.FilePermission "${oxygen.data.dir}/-", "read,write,delete";
      permission java.io.FilePermission "${oxygen.data.dir}", "read,write,delete";
    };
    // The jar that contains sandboxing code.
    grant codeBase 
      "jar:file:${catalina.base}/webapps/oxygenxml-web-author/WEB-INF/lib/
    oxygen-sandbox.jar!/-" {
        permission java.security.AllPermission;
    };
    // Give all permissions to plugins code unless otherwise instructed by vendor.
    grant codeBase "file:${oxygen.data.dir}/plugins/-" {
        permission java.security.AllPermission;
    };
    // Give all permissions to frameworks code unless otherwise instructed by vendor
    grant codeBase "file:${oxygen.data.dir}/frameworks/-" {
        permission java.security.AllPermission;
    };
    ...
    Note: Replace oxygenxml-web-author with the name of your deployment of Oxygen XML Web Author.
  2. Start the Apache Tomcat server using the -security flag.

Security Manager Restrictions

  • XML External Entities that reference files inside JAR archives are not allowed.

Configuring File Permissions to Custom Locations

There are cases when the Oxygen XML Web Author needs to access files system resources, but due to security reasons, you want to prevent your users from opening them directly in the Oxygen XML Web Author editing page using the file:// protocol.

You can do this by following these steps:
  1. Edit the catalina.policy file and add a line such as:
    permission java.io.FilePermission "path/to/yourSecretDir/-", "read,write,delete";
    permission java.io.FilePermission "path/to/yourSecretDir", "read,write,delete";
  2. Use the following system property when starting the Tomcat server:
    -Dfile.protocol.blacklist=/path/to/yourSecretDir
    Note: Use the value of path.separator system property to separate more directories. For example, under Linux, the value of path.separator property is a colon punctuation character :.

Security Options

Oxygen XML Web Author comes with several security options preconfigured and they may prevent loading some documents (for example, in development mode). These options are:

  • ignore.absolute.file.system.entities - If set to true (default value), system entities with an absolute URL (file://URL) are ignored.
  • ignore.extenal.entities.outside.frameworks - If set to true (default value), XML external entities are resolved only if their target is inside a framework folder in the DITA-OT folder.
  • block.cross.protocol.system.entities - If set to true (default value), XML external entities are blocked if their target URL does not have the same protocol as the URL of the file where the entity is declared.
  • block.cross.protocol.author.references - If set to true (default value), Author references (for example DITA conref) are blocked if their target URL has a different protocol than the URL of the file that contains the referencing element.
  • author.display.references.expanded - If set to false, referenced content is not expanded and displayed in the visual editor.
  • enable.file.protocol - If set to false (default value), users cannot open resources (documents, images, etc.) whose URL uses the file protocol.
Note: XML external entities that use URLs with the jar protocol are blocked unless the XML file that declares the entity is loaded from an URLs with the jar protocol.