Each time a user previews an attachment, Convergence attempts to open it in the browser. If Convergence is not able to open the attachment by default, it sends the attachment to Outside In Transformation Server. The transformation server transforms the attachment into HTML, which Convergence can render in the browser.

The transformation server can handle a large number of simultaneous requests by placing attachment requests in a queue.

The Outside In proxy creates a temporary directory for each user requesting to view attachments. For each transformation, the Outside In proxy creates a temporary subdirectory under the user directory. The Outside In proxy passes the input directory containing the transformed attachment and the output directory of the transformed attachment to the Transformation Server. The Outside In proxy deletes the subdirectory after a configurable time-out period has passed.

The Convergence server manages file management to the transformation server. Convergence uses a session cookie and a server-generated URL token for each attachment request. For security, Convergence masks the URL token.

Figure 5-1 shows the attachment preview workflow.

Figure 5-1 Convergence Attachment Request Workflow

Description of "Figure 5-1 Convergence Attachment Request Workflow"

The following list explains the attachment preview workflow from Figure 5-1.

1. The Convergence client sends the request to the Convergence server.

   If the request is for an attachment type that can be rendered natively in the browser, the request is sent to the WMAP proxy.

   If the request is for an attachment type that cannot be rendered natively in the browser, the request is first passed to the Outside In proxy, and then to the WAMP proxy.

2. The request is sent to the Messaging server. The Messaging server sends the attachment back to the Convergence server.

3. For attachment types that cannot be rendered natively in the browser, the Outside In proxy sends the response from the Messaging server to the disk storage.

4. For attachment types that cannot be rendered natively in the browser, the Outside In proxy communicates where it saved the attachment to the Outside In Transformation server, and also informs the transformation server where to save the attachment after it has been converted.

5. For attachment types that cannot be rendered natively in the browser, the transformation server converts the attachment into a format that can be natively rendered in the browser and saves it to the directory provided by the Outside In proxy.

6. For attachment types that cannot be rendered natively in the browser, the transformation server informs the Outside In proxy that it has completed transforming the file.

7. If the original request was for an attachment type that could be rendered native in the browser, the Convergence server sends the attachment to the browser.

   If the original request was for an attachment type that could not be rendered native in the browser, the Outside In proxy provides the browser with a redirection URL to the transformed attachment on the disk storage.

8. If the original request was for an attachment type that could not be rendered native in the browser, the Convergence client accesses the transformed attachment using the URL provided by the Outside In proxy and renders it in the browser.

Convergence and Outside In Transformation Server have to be configured so that they can both read and write attachments in the storage disk. Convergence must have full permissions to the storage disk to read, write, and delete files.

The Convergence Server and the Outside In Transformation Server can run on the same machine or on different machines. Configure the transformation server as a network file system (NFS).

• If the transformation server is running on Solaris:

  • Share the /export/tsdir/ directory.

    chmod 700 /export/tsdir
    

  • Edit /etc/dfs/dfstab and add the following line:

    share -F nfs -d [-o root=host_name] "tsdir" /export/tsdir
    

    Include the -o parameter when the Convergence server and the transformation server are running as local root, where host_name is the host name of the Convergence server. Omit the -o parameter when the Convergence server and the transformation server are running as the same user.

  • Create a soft link or mount to the NFS directory. For example:

    -s //net/host_name/export/tsdir /export/tsdir
    

• If the transformation server is running on Linux:

  • Share the /export/tsdir/ directory:

    chmod 700 /export/tsdir
    

  • If the Convergence server and the transformation server are running as the same user, edit /etc/exports and add the following line:

    /export/tsdir
    

    If the Convergence server and the transformation server are running as local root, edit /etc/exports and add the following line:

    /export/tsdir host_name(rw,no_root_squash)
    

  • Create a soft link or mount to the NFS directory. For example:

    -s //net/host_name/export/tsdir /export/tsdir
    

The Outside In proxy generates a unique URL for each attachment and provides it to the Convergence client.

The following example shows the sample configuration settings for Outside In proxy in the Convergence configuration.xml file:

<OINService>
     <ServiceName v="SUN_OIN_SERVICE"/>
     <BackendServiceDetails>
          <Enable v="true"/>
          <HostName v="oin server name"/>
          <PortNumber v="60611"/>
     </BackendServiceDetails>
     <TsdirPath v="/export/tsdir"/>
     <AutoPruneInterval v="5"/>
</OINService>

You can use the iwcadmin command to configure the parameters for the Outside In proxy.

The Outside In proxy manages the life cycle of attachments, including temporary directories, file creation, deletion, and purging, and the number of directories and disk space per user.

By default, the Outside In proxy automatically deletes an attachment from the storage disk after five minutes.

Use the iwcadmin command to configure the duration after which attachments are deleted from the storage disk. For example, to configure the proxy to delete attachments from the disk after three minutes:

iwcadmin -o oin.autopruneinterval -v 3

Oracle Outside In Transformation Server supports many typical font sets and some extended font sets. However, depending on the locales being used in your deployment, you may need to install and configure additional font sets to support the rendering of attachments.

By default, when the transformation server cannot render characters because the font is missing, it replaces the character with an asterisk. For example, if a user is using Convergence with the Japanese locale, but the transformation server does not have access to Japanese font sets, the transformation server will render attachments with asterisks.

Install all required fonts on the host machine where the transformation is installed and export the GDFONTPATH environment variable.

See the Oracle Outside In Technology documentation for more information.

The Outside In Transformation Server blacklist enumerates the types of files that are prevented from being sent to the transformation server, such as ZIP files or EXE files.

You can customize the blacklist to add or remove file types. See the discussion about customizing the attachment blacklist in for more information.

You enable and disable HTML filtering using the iwcadmin command. By default, HTML filtering is enabled.

To enable or disable HTML filtering, enter:

iwcadmin -o mail.htmlsanitizer.enable -v {true|false}

when the mail.htmlsanitizer.enable parameter is set to false, HTML content is not displayed in the email message. Only the text or plain content is displayed in the Convergence email message. To display the HTML content, set the role.http.convergencefilterenabled parameter to true in the Messaging Server. See the discussion about HTML Filtering in your Messaging Server documentation.

The default Convergence whitelist includes all known safe HTML elements, attributes, and protocols. The default Convergence blacklist includes all known potentially harmful HTML elements, attributes, and protocols. The default Convergence CSS whitelist includes all known safe CSS properties.

Blacklist takes precedence over whitelist; that is, if an element is present in both whitelist and blacklist, the element will be considered as blacklisted and the element will not be allowed in the email content.

You use the iwcadmin command to create an additional whitelist, blacklist, CSS whitelist with additional elements, attributes, protocols, or CSS properties.

It is not possible to modify the default whitelist, blacklist, or CSS whitelist. The contents of the default lists are deliberately excluded from this documentation, as such information could be used to target whitelisted values.

To configure the additional blacklist:

iwcadmin -o mail.htmlsanitizer.additionalblacklist -v "filtering_value"

To configure the additional whitelist:

iwcadmin -o mail.htmlsanitizer.additionalwhitelist -v "filtering_value"

To configure the additional CSS properties for whitelist:

iwcadmin -o mail.htmlsanitizer.additionalCSSwhitelist -v "filtering_value"

Where filtering_value is a comma-separated list of HTML elements, attributes, protocols, or CSS properties.

The following example shows a sample configuration using the additional blacklist:

• Do not allow attribute1 and attribute2 on all elements

• iwcadmin -o mail.htmlsanitizer.additionalblacklist -v "attribute1, attribute2"
  

• Do not allow attribute1 on element1 only.

  iwcadmin -o mail.htmlsanitizer.additionalblacklist -v "attribute1@element1"
  

• Do not allow element1 and element2.

  iwcadmin -o mail.htmlsanitizer.additionalblacklist -v "@element1,@element2"
  

• Do not allow element1. Do not allow attribute1 on any element. Do not allow attribute2 on element2.

  iwcadmin -o mail.htmlsanitizer.additionalblacklist -v "@element1,attribute1, attribute2@element2"
  

• Do not allow attribute1, attribute2 and attribute3 on element1.

  iwcadmin -o mail.htmlsanitizer.additionalblacklist -v "attribute1@element1,attribute2@element1, attribute3@element1"
  

• Do not allow protocol1. Colon(:) at end indicates it is a protocol.

  iwcadmin -o mail.htmlsanitizer.additionalblacklist -v "protocol1:"
  

For example:

iwcadmin -o mail.htmlsanitizer.additionalblacklist  -v "@source,srcdoc@iframe,ftp:"

With this settings, HTML element source, srcdoc attribute of HTML element iframe, and ftp protocol will not be allowed in the mail content.

The following example shows a sample configuration using the additional whitelist:

• Allow attribute1 and attribute2 on all elements

• iwcadmin -o mail.htmlsanitizer.additionalwhitelist -v "attribute1, attribute2"
  

• Allow attribute1 on element1 only.

  iwcadmin -o mail.htmlsanitizer.additionalwhitelist -v "attribute1@element1"
  

• Allow element1 and element2.

  iwcadmin -o mail.htmlsanitizer.additionalwhitelist -v "@element1,@element2"
  

• Allow element1. Allow attribute1 on any element. Allow attribute2 on element2.

  iwcadmin -o mail.htmlsanitizer.additionalwhitelist -v "@element1,attribute1, attribute2@element2"
  

• Allow attribute1, attribute2 and attribute3 on element1.

  iwcadmin -o mail.htmlsanitizer.additionalwhitelist -v "attribute1@element1,attribute2@element1, attribute3@element1"
  

• Allow protocol1. Colon(:) at end indicates it is a protocol.

  iwcadmin -o mail.htmlsanitizer.additionalwhitelist -v "protocol1:"
  

For example:

iwcadmin -o mail.htmlsanitizer.additionalwhitelist  -v "testattr2@div, abc:"

With this settings, testattr2 (custom attribute) of HTML element div, and protocol abc (custom protocol) will be allowed in the mail content.

The following example shows a sample configuration while configuring the additional CSS properties for whitelist:

iwcadmin -o mail.htmlsanitizer.additionalCSSwhitelist -v "item_1,item_2"

where item is a CSS property like visibility and z-index.

Convergence allows the URLs in inline styles in email messages. This can be set by using the mail.htmlsanitizer.allowurlsinstyle parameter. Enabling this option is vulnerable to XSS. This option should be enabled only when the URL referenced in the email message is from trusted source and is secure.

In this example, the image.png displays in the email message when mail.htmlsanitizer.allowurlsinstyle is set to true:

<span style="background-image: url(http://example.com/image.png)"></span>