Introduction

This topic covers the essential items that you should consider before deploying your application.

High Level Architecture

Typically, your end users will use a client application running in a browser, that will talk to a web application running on your web server. The web application will access PrizmDoc Application Services (PAS) and/or PrizmDoc Server REST APIs.

In each of those cases, we recommend you use a reverse proxy as an entry point for your solution, and only expose the reverse proxy to the internet.

One of the options is to use the reverse proxy as a gateway to your web application. In that case, the reverse proxy can be used as a terminator for the incoming HTTPS traffic. Communication between reverse proxy, web application, PAS, and PrizmDoc instances can then use the HTTP protocol.

If you need the web application, PAS or Server instances to communicate over an untrusted network, or if you need additional security within your local network, please see HTTPS Protocol Support for PAS, HTTPS Protocol Support for PrizmDoc Server for additional information.

PrizmDoc Server

PrizmDoc Server Addresses and Ports

Your solution may need to expose up to two ports for PrizmDoc Server:

Public port, specified by the network.publicPort Central Configuration parameter. Expose this port only in the following cases:
- Your web application and/or web client use PrizmDoc Server API. In this case, the port needs to be exposed to your web client.
- This PrizmDoc Server instance provides the native rendering of Microsoft Office documents to other PrizmDoc Server instances of your solution. In this case, the port needs to be exposed to your other PrizmDoc Server instances.
Cluster port, specified by the network.clustering.clusterPort Central Configuration parameter. Expose this port only when you are running a cluster of PrizmDoc instances, and only to your other PrizmDoc Server instances.

You can specify binding addresses for those ports using the network.binding.addresses Central Configuration parameter.

PrizmDoc Server uses a range of internal ports for communication between its microservices, specified by the network.internalStartingPort Central Configuration parameter. Take steps to ensure these ports are not accessible to end-users or the internet.

HTTPS Protocol Support

If you need the web application, PAS or Server instances to communicate over an untrusted network, or if you need additional security within your local network, you may want to set them up to support the HTTPS protocol.

Using Windows

PrizmDoc Server can be configured to accept HTTPS traffic on the Windows platform.

NOTE: This is disabled by default and only supported on the Windows platform.

In order for your PrizmDoc Server instances to accept HTTPS traffic, you need to:

Put your certificate and private key files in a location accessible by PrizmDoc.
Specify the locations of your certificate and private key files in network.certificateFile and network.certificateKeyFile Central Configuration parameters.
Set the network.publicScheme Central Configuration parameter to https.

PrizmDoc Server will accept HTTPS traffic on addresses specified in the network.binding.addresses Central Configuration parameter and the port specified by the network.publicPort Central Configuration parameter, and will not accept incoming HTTP traffic.

If instances within your PrizmDoc cluster need to communicate via HTTPS, you should:

Set the network.clustering.scheme Central Configuration parameter to https to make cluster instances route requests to other servers in the cluster via the HTTPS protocol.
Make sure the necessary certificates are available on your PrizmDoc Server instances.

Supported TLS Protocols and Cipher Suites

PrizmDoc Server supports TLS 1.2 and TLS 1.3 protocols and the following cipher suites on Windows platform:

For TLS 1.3:

TLS_CHACHA20_POLY1305_SHA256
TLS_AES_256_GCM_SHA384
TLS_AES_128_GCM_SHA256

For TLS 1.2:

TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

Using Docker

The PrizmDoc Server Container image does not accept HTTPS traffic out-of-the-box. In order for your PrizmDoc Server instances to accept HTTPS traffic, you need to set up a reverse proxy alongside every PrizmDoc Server instance, and use it as an HTTPS terminator for that instance. For example, you may set up the reverse proxy to accept incoming HTTPS traffic on port 18681 bound to an external address, and forward that traffic via HTTP to the PrizmDoc Server listening on the same port bound to an internal address.

If instances within your PrizmDoc cluster need to communicate via HTTPS, you should:

Use a reverse proxy to route requests to the PrizmDoc Server's cluster port.
Set the network.clustering.scheme Central Configuration parameter to https to make cluster instances route requests to other servers in the cluster via the HTTPS protocol.
Make sure the necessary certificates are available on your PrizmDoc Server instances.

If your PrizmDoc Server instance (cluster) running on Linux needs to communicate to a Windows MSO instance (cluster) via HTTPS, you should:

Enable HTTPS support on your MSO instance, as described in the Using Windows section above.
Set fidelity.msOfficeCluster.scheme Central Configuration parameter to https to make your PrizmDoc Server instance (cluster) running on Linux route requests to the PrizmDoc Windows MSO instance (cluster) via the HTTPS protocol.
Make sure the necessary certificates are available on your PrizmDoc Server instances.

Option to Require HTTPS for External Requests

PrizmDoc can be configured to require the use of the HTTPS protocol for all of the external content it downloads, such as external images in HTML or email documents, external watermarks or URLs provided for creation of viewing sessions. See security.externalContent.requireHttps for details.

_NOTE: This option is only supported when using the LibreOffice rendering engine. If you are using the MSO rendering engine, and want to avoid making external requests over the HTTP protocol, you should block such requests outside of PrizmDoc. See Server Side Request Forgery Concerns section for details._

If a URL uses the HTTP scheme, an attempt would be made to access it via HTTPS, except for the case mentioned below:

NOTE: When using LibreOffice rendering engine, PrizmDoc blocks requests for external content in office documents and email documents that use RTF bodies, for both HTTP and HTTPS protocols.

PrizmDoc Server Administration

PrizmDoc Server includes a Health Status API to request real-time information about the state and health of the system.

The Health Status API provides information that can be helpful in diagnosing problems. However, it also contains sensitive information such as the OS version and host ID. Because of this any application accessing the Health Status API of PrizmDoc Server should not be accessible to end-users or the public internet.

Secure Viewing Sessions

The central configuration file contains properties that can help prevent users from setting inappropriate values to try and attack the PrizmDoc Server, which could render performance problems with the server. These values are properties in the ViewingSessionProperties object that a client-user passes to PrizmDoc Server to start a viewing session.

The file paths for the Central Configuration file are:

Docker: <config_folder>/prizm-services-config.yml, where <config_folder> is the folder that you mapped as /config when creating the container. See Installing / Using Docker for more details.
Windows: C:\Prizm\prizm-services-config.yml (assuming the standard install location.)

For more information on creating secure viewing sessions, refer to the following topics:

The following configuration properties put limits on viewing session properties sensitive to abusive attacks:

Central Configuration Properties Example

# Defines the min and max allowed values for the countOfInitialPages viewing
# session creation option.
#
# viewing.sessionConstraints.countOfInitialPages.min: 0
# viewing.sessionConstraints.countOfInitialPages.max: 10

# A regex which defines the pattern of an acceptable value for the
# documentExtension viewing session creation option.
#
# viewing.sessionConstraints.documentExtension.regex: ".\*"

# A regex which defines the pattern of an acceptable value for the
# externalId viewing session creation option.
#
# viewing.sessionConstraints.externalId.regex: ".\*"

# Defines the list of allowed values for the serverCaching viewing session
# creation option.
#
# Must be an array with one or more of the following strings:
#
# "none" - Allow REST API callers to create a new viewing session with caching
#          explicitly disabled.
#
# "full" - Allow REST API callers to create a new viewing session with caching
#          explicitly enabled.
#
# viewing.sessionConstraints.serverCaching.allowedValues: \["none","full"\]

# Defines the list of allowed values for the alwaysUseRaster viewing session
# creation option.
#
# Must be an array with one or more of the following values:
#
# false - Allow REST API callers to create a new viewing session which will
#         generate both raster and vector page content. Ideal for modern
#         browsers.
# true -  Allow REST API callers to create a new viewing session which will
#         only generate raster content; vector content will not be generated.
#         This is useful for some older browsers.
#
# viewing.sessionConstraints.render.alwaysUseRaster.allowedValues: \[false\]

Server Side Request Forgery Concerns

Some source files, such as HTML, email, and Microsoft Office files, may reference content that resides on a local or an external server. When rendering or converting these kinds of files, PrizmDoc Server may make network requests for such external content. Depending on what your deployment servers have network access to, this can be a security vulnerability. An attacker may leverage this to gain access to internal data and/or cause undesirable behavior. We recommend you take steps to prevent this.

There are two primary kinds of files you should be concerned with: 1) HTML files and email files that use HTML formatted bodies and 2) Microsoft Office files and email files that use RTF formatted bodies.

HTML Files and Email files with HTML bodies

HTML code can be found in both HTML and email (EML and MSG) files. When rendering or converting these files, the content may include an HTML tag (like an image or iframe) which refers to external content. The presence of something like an iframe tag could allow an attacker a way to gain access to any URL or HTTP resource in your network, potentially exposing a variety of data you never intended to.

If you do not need to render or convert HTML or email files, or if you do but you never need to include external content, we recommend you block all requests for external content by setting security.htmlRendering.blockExternalContent to true. When you do this, PrizmDoc Server will avoid making any external requests when rendering or converting HTML files and email files that contain HTML bodies.

If you need to allow the rendering of external content, we recommend you set up firewall rules which only allow accessing hosts you consider to be safe or, at the very least, prevent access to all internal hosts an attacker should not have access to (like metadata services, typically running on 169.254.169.254, or any other sensitive internal services or servers). See the Firewall Rules section below.

Microsoft Office Files and Email files with RTF bodies (LibreOffice rendering mode)

When using the LibreOffice rendering engine, PrizmDoc Server:

Disables all macros for Word, Excel, and PowerPoint formats.
Blocks requests for external content in Office documents and email documents that use RTF bodies.
Does not recalculate spreadsheet formulas when rendering Microsoft Excel documents.
Blocks SMB traffic from the LibreOffice engine.

Microsoft Office Files and Email files with RTF bodies (MSO rendering mode)

When using the MSO rendering engine, PrizmDoc Server disables all macros for Word, Excel, and PowerPoint formats.

The Microsoft Office rendering engine may make external requests for image data, text data, or reveal information about your system. If you are using the MSO rendering mode, we recommend you do the following:

To avoid revealing information about your server, set the fileTypes.excel.formulas.autocalculate.enabled Central Configuration parameter to false. This will block re-calculation of spreadsheet formulas during the rendering, including the following formulas:
- CELL("filename")
- INFO("osversion")
- INFO("system")
- INFO("release")
Formulas that use static content, such as arithmetic or string operations, don't need to be recalculated during the rendering and thus will continue to show expected results.
To avoid external requests (to either localhost or external servers) for text data from Microsoft Excel, disable the Excel WEBSERVICE function:
- Microsoft Office 2013: change the policy value for User Configuration -> Administrative Templates -> Microsoft Excel 2013 -> Excel Options -> Security -> "WEBSERVICE Function Notification Settings" to "Disabled".
- Microsoft Office 2016 / 2019: change the policy value for User Configuration -> Administrative Templates -> Microsoft Excel 2016 -> Excel Options -> Security -> "WEBSERVICE Function Notification Settings" to "Disabled".
To avoid external requests for image or text data, and to prevent the SMB traffic from Microsoft Office, see the Firewall Rules / Windows, MSO rendering mode section below.

Firewall Rules

In certain cases you will need to set up firewall rules on your system to prevent PrizmDoc from accessing external content.

Windows, MSO rendering mode

The following Microsoft Office executables are known to potentially request external content (assuming the default installation folder for Microsoft Office):

C:\Program Files\Microsoft Office\Office16\EXCEL.EXE
C:\Program Files\Microsoft Office\Office16\WINWORD.EXE
C:\Program Files\Microsoft Office\Office16\POWERPNT.EXE
C:\Program Files\Microsoft Office\Office15\WINWORD.EXE
C:\Program Files\Microsoft Office\Office15\EXCEL.EXE
C:\Program Files\Microsoft Office\Office15\POWERPNT.EXE

If you are using the MSO rendering mode, we recommend you do the following:

If you do not need to render external content and external text in Office files, set up firewall rules which prevent all of the above executables from being able to make outgoing network requests.
To prevent SMB traffic from leaving the configured Windows instance, block the following outbound ports: TCP: 137, 138, 139, 445 and UDP: 137, 138. Please refer to the Microsoft guidelines for blocking specific firewall ports to prevent SMB traffic.

When the security.htmlRendering.blockExternalContent Central Configuration parameter is set to false (default), the node.js executable may make requests for external content in HTML documents and email documents that use HTML bodies.

C:\Prizm\node.js\<node.js version>\node.exe

If you do need to allow the rendering of some external content, we still recommend you set up firewall rules which only allow these executables to access hosts you consider to be safe or, at the very least, prevent access to all internal hosts an attacker should not have access to (like metadata services, typically running on 169.254.169.254, or any other sensitive internal services or servers).

If you want PrizmDoc to only use the HTTPS protocol for external requests, and block requests that use the unencrypted HTTP protocol, configure the firewall to only allow external connections to the standard HTTPS port 443.

Please refer to the Microsoft guidelines for blocking of application outbound traffic.

Windows, LibreOffice rendering mode

C:\Prizm\node.js\<node.js version>\node.exe

Please refer to the Microsoft guidelines for blocking of application outbound traffic.

If you want PrizmDoc to only use the HTTPS protocol for external requests, and block requests that use the unencrypted HTTP protocol, use the security.externalContent.requireHttps Central Configuration parameter.

Firewall Rules (Docker)

See Packet filtering and firewalls on how to set up the filtering rules for Docker. How exactly you set this up will depend upon your environment, but we recommend putting some sort of firewall rules in place which prevent PrizmDoc Server from being able to make network requests to hosts an attacker should not have access to.

PrizmDoc Application Services

PrizmDoc Application Services Port

If your solution uses the PrizmDoc Application Services (PAS) API, you will need to expose this port for PAS:

Public port, specified by the port PAS Configuration parameter.

PAS does not use internal ports.

HTTPS Protocol Support

PAS does not accept HTTPS traffic out of the box. In order for your PAS instances to accept HTTPS traffic, you need to set up a reverse proxy in front of your PAS instance or cluster, and use it as an HTTPS terminator. For example, you may set up the reverse proxy to accept incoming HTTPS traffic on port 3000 bound to an external address, and forward that traffic via HTTP to PAS listening on the same port bound to an internal address.