PrizmDoc Viewer v13.14 - Updated
Developer Guide / Viewer / Configure the Viewer / Configuration Options / Enable Content Encryption
In This Topic
    Enable Content Encryption
    In This Topic

    Introduction

    This topic contains an overview and steps to help you enable content encryption:

    The goal of content encryption is to provide an obscured transfer of data from the PrizmDoc Server to the Viewer website, preventing unauthorized agents from discerning the content being transmitted. Additional security can be enabled by configuring the Viewer and server to communicate over the Secured Socket Layer (SSL), https protocol, rather than standard non-secure http protocol. In cases where this is not viable or enough protection, the content encryption adds a strong measure of privacy to the document content. When content encryption is enabled, the web data images and document text strings sent to the Viewer will be encrypted and then decrypted by the Viewer.

    Overview of Enabling Content Encryption

    Content encryption must be enabled in the Viewer and in the PrizmDoc Server; it is disabled by default. Enabling content encryption in the Viewer is straightforward and performed by an option passed to the Viewer constructor or jQuery plugin. This process is documented below.

    The file paths for the Central Configuration file are:

    • Linux: /usr/share/prizm/prizm-services-config.yml
    • Windows: C:\Prizm\prizm-services-config.yml

    NOTE: The default installation directory is: C:\Prizm.

    There are two options for enabling content encryption on the server:

    1. Enable content encryption via the central configuration file (prizm-services-config.yml - located in the top-level of the installation directory): this enables content encryption for all viewing sessions.
    2. Toggle (enable or disable) content encryption via viewing session property: this enables or disables content encryption per viewing session, overriding the option set in the central configuration file.

    These two options are documented below.

    NOTE: For security reasons, toggling content encryption per viewing session is not permitted in the out-of-box product configuration. It must be explicitly allowed via the ServiceHost pcc.config file.

    Finally, it’s important to note it must be enabled or disabled on both the Viewer and server, or unexpected behavior will occur. If encryption is enabled on the server but not for the Viewer, then the content will not be rendered correctly. If encryption is enabled for the Viewer but not on the server, then the content will not be encrypted during transit, however, it will be rendered correctly in the Viewer.

    In summary:

    • Content encryption is disabled out of the box.
    • It must be enabled in the Viewer and PrizmDoc Server.
    • It can be enabled or disabled on the server via the central configuration file.
    • If permitted, enabling or disabling content encryption can be overridden when creating a viewing session.

    Enabling Content Encryption in PrizmDoc Server via the Central Configuration File

    To enable content encryption follow the steps below:

    1. Open the central configuration file, prizm-services-config.yml in your favorite editor. The prizm-services-config.yml file is located in the top-level of the installation directory.
    2. Find the viewing.contentEncryption.enabled section and change the value to true.

      Encrypted Transmission Example

      # Controls whether or not content is encrypted by the back end before being
      # transmitted to a client viewer. The client viewer will decrypt the content in
      # the browser. This is useful for DRM, making it more difficult to copy
      # protected content that has been delivered to the browser.
      #
      viewing.contentEncryption.enabled: true
      
      
    3. Save the changes to the file.

    4. Restart the PrizmDoc Server for the changes to take effect.
    5. Continue by enabling the encryption option for the Viewer as described in the section below.

    Enabling Content Encryption in PrizmDoc Server via the ViewingSession Property

    1. Open the central configuration file, prizm-services-config.yml in your favorite editor. The prizm-services-config.yml file is located in the top-level of the installation directory.
    2. Find the viewing.sessionConstraints.pageContentEncryption.allowedValues section and change the value to ["default", "enabled", "disabled"].

      Encrypted Transmission Example

      # Defines the list of allowed values for the pageContentEncryption viewing
      # session creation option.
      #
      # Must be an array with either ONE or ALL of the following strings:
      #
      # "default" -  Allow REST API callers to create a new viewing session without
      #              explicitly stating whether or not page content encryption (DRM)
      #              should be applied. The value configured in this file at
      #              viewing.contentEncryption.enabled will be used to determine
      #              whether or not page encryption is applied.
      #
      # "enabled" -  Allows REST API callers to explicitly enable page content
      #              encryption (DRM) when creating a new viewing session, overriding
      #              whatever value is configured in this file by
      #              viewing.contentEncryption.enabled.
      #
      # "disabled" - Allows REST API callers to explicitly disable page content
      #              encryption (DRM) when creating a new viewing session, overriding
      #              whatever value is configured in this file by
      #              viewing.contentEncryption.enabled.
      #
      viewing.sessionConstraints.pageContentEncryption.allowedValues: ["default","enabled","disabled"]
      
      
    3. Save the changes to the file.

    4. Restart the PrizmDoc Server for the changes to take effect.
    5. Update your web-tier code to set the value of the pageContentEncryption Viewing Session property to "enabled" when creating the viewing session. The example below is for a .NET web tier:

      Example

      viewingSessionProperties.pageContentEncryption = "enabled";
      ....
      // Serialize document properties as JSON which will go into the body of the request string requestBody = serializer.Serialize(viewingSessionProperties);
      requestStream.Write(requestBody);
      
      
    6. Continue by enabling the encryption option for the Viewer as described in the section below.

    Enabling Content Encryption in the Viewer

    To enable encryption in the Viewer, provide the encryption option in the viewer options parameter as follows so that the Viewer can handle encrypted data:

    Example

    <script type="text/javascript">
      $(function() {
        $('#viewerContainer').pccViewer({
          documentID:       'XYZ...',
          imageHandlerUrl:  '/pas-proxy',
          viewerAssetsPath: 'viewer-assets',
          resourcePath:     'viewer-assets/img',
          language: viewerCustomizations.languages['en-US'],
          template: viewerCustomizations.template,
          icons:    viewerCustomizations.icons,
          annotationsMode: "LayeredAnnotations",
          encryption: true
        });
      });
    </script>
    
    

    Enabling the encryption will not work without setting the configuration parameter as described above. Also, if the PrizmDoc Server configuration setting is either not set or the PrizmDoc Server is not restarted, the data will arrive unencrypted.

    How to Start & Stop the PrizmDoc Server

    Refer to these topics for additional information: