Web Translation. Web Developer Guide v8.6.0 - v10.5.0

Web Translation Web Developer Guide v8.6.0 - v10.5.0 2009 SonicWALL, Inc. All rights reserved. SonicWALL is a registered trademark of SonicWALL, Inc. Other product names mentioned herein may be trademarks and/or registered trademarks of their respective companies. Last modified 12/7/09 10:51 232-001798-00 Rev A

SonicWALL Aventail E-Class SRA SSL VPN Web Translation Developer Guide i Table of Contents Overview.................................................................................1 Introduction...........................................................................1 Translation Using Host Name and Path Portion Together.............................................2 Translation Using Only the Host Name Portion....................................................2 Benefits...........................................................................3 Notes and Caveats....................................................................3 How Web Translation Works...................................................................3 Content-Type of Web Pages................................................................3 Character Encoding......................................................................4 Cookie Translation.......................................................................4 URLs................................................................................4 HTML Translation........................................................................4 CSS Translation.........................................................................5 HTC Translations........................................................................5 JavaScript Translation....................................................................5 Translation Rules.....................................................................5 Adding Custom Rules for JavaScript Translation...............................................7 VBScript Translation......................................................................9 Java Applet, ActiveX and Flash Translation......................................................9 XML Translation.........................................................................9 Web Aliases........................................................................... 10 Referrer Lookup........................................................................ 10

ii Table of Contents

SonicWALL Aventail E-Class SRA SSL VPN Web Translation Developer Guide 1 Overview Introduction A truly clientless VPN appliance requires a robust Web-content translation engine: all network references within the Web content must be changed to point to the VPN appliance instead of internal hosts. With full-client VPNs or VPN appliances that use Web-deployed ActiveX or Java clients, this host mapping can be done on the client. But for VPN access for the broadest possible browser base, Web content translation is indispensable. This document is intended for Web application developers who want to make their software easier to translate for the SonicWALL Aventail translation engine. It provides a set of guidelines to achieve this goal and gives a brief overview of certain aspects of the translation engine. The instructions are valid for SonicWALL Aventail appliances running v8.6.0 through 10.5.0. To illustrate why a translation engine is necessary for Web content, imagine an HTML page with the following anchor tag that links to an internal resource: <a href="http://owa.in.sonicwall.com">outlook Web Access</a> Within the corporate network, the link works perfectly. When the user clicks the link in a Web browser, the browser asks the internal DNS server what the IP address of owa.in.sonicwall.com is and retrieves the desired page. Outside of the corporate network, however, the link does not work. The browser asks the DNS server of the local ISP what the IP address for owa.in.sonicwall.com is and is told that address doesn t exist. Even if the link were to a routable IP address within the corporate network, the corporate firewall would probably prevent the browser from accessing the desired resource. Web content translation is the process of changing (translating) the link above into something that is addressable in the public domain and also contain the intelligence to reach the desired backend resource. There are different ways to do the translation. 1. A dedicated DNS-resolvable host name is mapped to the desired resource. The translated URL may look something like this: <a href="https://exchange.sonicwall.com">outlook Web Access</a> The internal host name (owa.in.sonicwall.com) is mapped to the DNS-resolvable host name of the VPN appliance (exchange.sonicwall.com). But the appliance does not hold the desired resource: the end resource must be encoded in some way within the URL. In this example, the host name (exchange.sonicwall.com) itself is mapped to the desired resource. 2. A port number is mapped to the desired resource. The translated URL may look something like this: <a href="https://ex7000.sonicwall.com:7456/">outlook Web Access</a> The internal host name (owa.in.sonicwall.com) is mapped to the DNS-resolvable host name of the VPN appliance (ex7000.sonicwall.com). ). But the appliance doesn t hold the desired resource: the end resource must be encoded in some way within the URL. In this example, it is mapped with the port Number (7456) in the host name portion of the URL. 3. The path portion contains the information of the desired resource.

2 SonicWALL Aventail E-Class SRA SSL VPN Web Translation Developer Guide The translated URL may look something like this: <a href="https://ex7000.sonicwall.com/go/owa.in.sonicwall.com">outlook Web Access</a> The host name is changed from the internal host name (owa.in.sonicwall.com) to the DNSresolvable host name of the VPN appliance (ex7000.sonicwall.com/go/owa.in.sonicwall.com). But the appliance doesn t hold the desired resource: the end resource must be encoded in some way within the URL. In this example, it is encoded within the path portion of the URL. If the only kind of Web translation necessary were a translation of HTML links, as in this example, things would be easy. This unfortunately is not so. There are numerous ways to reference network resources in HTML alone. JavaScript, for example, is difficult to handle because it provides a means of executing code on the browser and it allows the user to feed in additional input that is unknown at the time the server-side translation is done. The user can be prompted for a URL using JavaScript and the browser can then be instructed to go to that URL. The scenarios (1) and (2) above are those of translating only the host name portion of the URL. Case (3) is that of translating both the host name and the path portion of the URL. There are options in the AMC to select the type of transaction for each resource. For better compatibility, SonicWALL strongly recommends using options (1) or (2) in most production environments. Option (3) should be used for well-known Web applications like Outlook Web Access and Sharepoint. More details about the two methods of Translating Web URLs are provided in the following sections. Translation Using Host Name and Path Portion Together The host name is DNS-resolvable to the VPN appliance. The information for the desired backend resource is contained in the path portion of the URL. Translation Using Only the Host Name Portion The host name is DNS-resolvable to the VPN appliance and also contains the desired backend resource information. There are two ways to contain the resource information. 1. Host name mapped Host name mapping means that the backend resource or server is mapped to an external host name. The resource is accessed with the host name rather than with the IP address. The host name is resolvable to an IP address in the public domain. Apache listens on port 443 at this IP address. All HTTPS traffic is terminated at this socket. A new HTTP request is made to retrieve the mapped backend resource. The HTTP reply is parsed to translate absolute URLs. Each host name mapped site must have a valid certificate. The wildcard certificates can be leveraged for multiple host mapped sites. See example #1 in the Introduction section. 2. Port mapped Port mapping involves mapping the backend resource or server to a port number at the EX- Series appliance. The Server listens on this port and all HTTPS traffic received on it is terminated at the appliance. A new HTTP request is made to retrieve the mapped backend resource. The HTTP reply is parsed to translate absolute URLs. With Port Mapped access, any firewalls in the network need to be configured to keep the specific ports open. See example #2 in the Introduction section. These translations work best for applications using relative URLs. But the translation engine does process data for absolute URL translation. The example in the above segment explains that of an absolute URL translation. For relative URLs it works automatically as the base URL is similar in the two cases of direct access or indirect access through the VPN appliance.

SonicWALL Aventail E-Class SRA SSL VPN Web Translation Developer Guide 3 Benefits Light weight as compared to other translation Less maintenance is required Works better with most of the well written applications The resources can be accessed directly as a bookmark, or through a link in WorkPlace Modern applications which contain AJAX or Flash will work better with this mode of translation Notes and Caveats How Web Translation Works Logging out of applications like OWA, DWA and Sharepoint from an Internet Explorer browser may log you out of WorkPlace For port mapping, the firewall needs to be configured to grant access to the specific ports Each resource should be configured using only one of the access methods; do not mix translated, port mapped and host name mapped modes Host name mapped resources should be configured/accessed using host name only, that is. not via IP address The Web translation engine is part of the SonicWALL Aventail SSL VPN appliance, which sits at the network perimeter. The appliance isolates and protects private Web-based resources from unauthorized external access. A user first logs in to the appliance and is presented with the WorkPlace portal, where he or she follows links that point to resources on the internal network, or enters a URL. All URLs point to the SonicWALL Aventail appliance. The Web translation engine translates an incoming URL using an alias contained in the URL. Aliases are used to obscure the URLs that point to resources on your internal ( downstream ) servers. Because all requests are directed to the appliance, the user sees only the incoming URL that contains the alias. The translation engine matches the alias to a list it stores in memory and translates the URL. Once it s determined that the URL submitted by the user is valid and points to a resource on the network, the appliance checks its access control and authentication rules to make sure the user is authorized to access the requested resource. Content-Type of Web Pages Although the SonicWALL Aventail translation engine uses heuristics to guess the type of content in an HTTP response from the backend Web server, it is best to avoid relying on this and to instead specify the type explicitly. The single most important thing you can do to ensure proper translation is to make sure that all pages are served up with the correct Content-Type header. The Content-Type must be set as follows: Content HTML JavaScript XML Content-Type header text/html application/x-javascript text/html

4 SonicWALL Aventail E-Class SRA SSL VPN Web Translation Developer Guide Character Encoding Cookie Translation URLs As an internationalized network device, the SonicWALL Aventail appliance uses UTF-8 exclusively for its internal work. ISO-8859-x encoding is not supported. Use UTF-8 exclusively for all your Web content, and do not use the Microsoft code-pages. This particularly important when POSTing form data. The path portion of a Set-Cookie header is translated, and the domain portion is discarded. For example, suppose the back-end Web server sends the following header: Set-Cookie: x=y; path=/; domain=.in.sonicwall.com If the alias associated with the Web resource is morty, then this header is translated as follows: Set-Cookie: x=y; path=/morty/ This forces the Web browser to send the cookie only to the alias (and therefore the Web server) that set the cookie. Follow these recommendations when handling browser cookies: Avoid sophisticated client-side cookie manipulations using JavaScript. Avoid using URLs in cookies. Although an attempt is made to translate those URLs, there is some risk of letting them through. The translation engine can handle URLs in any form: Type of URL Fully-qualified Example http://www.acme.com/dir1/dir2/file.html Absolute path /dir1/dir2/file.html Relative path (recommended)../dir2/file.html HTML Translation Using relative paths in your Web application is recommended. This also has the advantage of making your Web application more portable if you move it to another Web server and directory. HTML translation is handled very reliably by the SonicWALL Aventail appliance. Follow these recommendations when coding your HTML: Make sure your HTML content is formatted according to standards, especially the quotes around attributes in tags. Ideally, use XHTML formatting. HTML attributes containing a value (for example, src="path") may not be translated if they contain any of the following errors: Spaces before or after the equal sign: src ="path" or src= "path" Leading or trailing spaces within the value: src=" path" or src="path " Missing an opening or closing quotation mark: src="path or src=path" Avoid base tags in your HTML code. For example: <base href="http://myapp.internal.acme.com/dir/" /> The meta tag is commonly used to redirect users to another page. For example: <meta http-equiv="refresh" content="5;url=redirecturl.html" />

SonicWALL Aventail E-Class SRA SSL VPN Web Translation Developer Guide 5 CSS Translation HTC Translations JavaScript Translation The meta tag s content attribute must be formatted carefully; don t include line breaks or spaces. CSS content is handled by the translation engine without difficulty. No translation is done for HTC (HTML components). Avoid using the standard attributes (such as action and innerhtml) of HTML as a property of various HTML components. JavaScript translation is complex and there are certain coding practices that you can use to make sure your code translates correctly. Translation Rules The SonicWALL Aventail JavaScript translation engine is based on a parse tree that can handle complex syntax. It is also a rule-based translator that makes use of the appliance s client-side JavaScript library. The rules are stored in the following file: /usr/local/extranet/etc/jstrans.cfg The translation rules are divided into the following four categories: Type ASSIGNMENT CALL SUBSTITUTION SUBARGS Description Assignment statement translation Function call translation Substitution of one language token with another Special kind of substitution within a function call Here are the JavaScript rules as of January 2009. # Type Left Hand Side (LHS) Encapsulate RHS with ASSIGNMENT location aventail.translate_url ASSIGNMENT.location aventail.translate_url ASSIGNMENT.href aventail.translate_url ASSIGNMENT.src aventail.translate_url ASSIGNMENT.action aventail.translate_url ASSIGNMENT document.domain aventail.setdomain ASSIGNMENT document.cookie aventail.setcookie ASSIGNMENT.innerHTML aventail.posttext ASSIGNMENT.url aventail.translate_url # Function Call Translation # Type Function Name Param Encapsulate param with

6 SonicWALL Aventail E-Class SRA SSL VPN Web Translation Developer Guide CALL.addBehavior 1 aventail.translate_url CALL.showModalDialog 1 aventail.translate_url CALL.showModelessDialog 1 aventail.translate_url CALL.insertAdjacentHTML 2 aventail.posttext CALL.location.replace 1 aventail.translate_url CALL location.replace 1 aventail.translate_url CALL location.assign 1 aventail.translate_url CALL location.href 1 aventail.translate_url CALL eval 1 aventail.post # Subsitution of one token with another # lvalue/rvalue: 0: substitute always # 1: substitute only if token is an rvalue (read from) # 2: substitute only if token is an lvalue (written to) # 3: substitute only if token is a function name # Type Token lval/rval Replacement SUBSTITUTION location.pathname 0 aventail.location.pathname SUBSTITUTION.location.pathname 0.aventail.location.pathname SUBSTITUTION document.domain 1 document.aventail.getdomain() SUBSTITUTION document.domain 2 aventail.junk SUBSTITUTION location.host 0 aventail.location.host SUBSTITUTION.location.host 0.aventail.location.host SUBSTITUTION location.hostname 0 aventail.location.hostname SUBSTITUTION.location.hostname 0.aventail.location.hostname SUBSTITUTION location.port 0 aventail.location.port SUBSTITUTION.location.port 0.aventail.location.port SUBSTITUTION location.protocol 0 aventail.location.protocol SUBSTITUTION.location.protocol 0.aventail.location.protocol SUBSTITUTION location.href 1 aventail.location.href SUBSTITUTION.location.href 1.aventail.location.href SUBSTITUTION location.search 1 aventail.location.search SUBSTITUTION.location.search 1.aventail.location.search SUBSTITUTION location 1 aventail.location SUBSTITUTION.scripts 1.aventail.getScripts() # Subsitution of one token with another, with a twist: # Take the "stem" of the call and make it the first argument in the new function. # For example: # If we have the token "foo.bar" and the replacement "aventail.ourfoo": # We will replace the construction "anobject.foo.bar(arg1, arg2)" with: # aventail.ourfoo(anobject, arg1, arg2) # This allows us to verify the type of the anobject object prior to operating on it # lvalue/rvalue: 0: substitute always # 1: substitute only if token is an rvalue (read from) # 2: substitute only if token is an lvalue (written to) # 3: substitute only if token is a function name # 4: special case, turn a flat lvalue into a function call # The "3" case above is used in cases such as "foo.location" to allow us to ensure # that "foo" is an object such as a document, window, or frame, and not some # user-defined object that just happens to have a "location" member.

SonicWALL Aventail E-Class SRA SSL VPN Web Translation Developer Guide 7 # Type Token lval/rval Replacement SUBARGS document.close 0 aventail.docclose SUBARGS document.write 0 aventail.docwrite SUBARGS document.writeln 0 aventail.docwrite SUBARGS.open 0 aventail.objopen SUBARGS.Open 0 aventail.objopen SUBARGS.location 4 aventail.objlocation SUBARGS.opener 4 aventail.findopener SUBARGS.execCommand 3 aventail.execcommand # SharePoint 2003 extensions... Because these URLs end up getting # passed directly to an ActiveX control that fires up MSWord directly # we need to include our state token in the URLs. # These calls are documented at: # http://msdn.microsoft.com/library/default.asp?url=/library/enus/spptsdk/html/tscliopendocuments_sv01032771.asp CALL.ViewDocument 1 aventail.translatewithstatetoken CALL.ViewDocument2 2 aventail.translatewithstatetoken CALL.EditDocument 1 aventail.translatewithstatetoken CALL.EditDocument2 2 aventail.translatewithstatetoken CALL.CreateNewDocument 1 aventail.translatewithstatetoken CALL.CreateNewDocument 2 aventail.translatewithstatetoken CALL.CreateNewDocument2 2 aventail.translatewithstatetoken CALL.CreateNewDocument2 3 aventail.translatewithstatetoken CALL ExportList 1 aventail.translatewithstatetoken CALL RDSDataSpace.CreateObject 2 aventail.translate_url Adding Custom Rules for JavaScript Translation Although most rules for standard JavaScript translation are present in jstrans.cfg, additional rules may be required. To create new rules you must first understand how each ASSIGNMENT, CALL, SUBSTITUTION, and SUBARGS is translated. ASSIGNMENT This is used to translate the assignments. Sample rule ASSIGNMENT location aventail.translate_url Result Replaces assignments such as location=str with location= aventail.translate_url(str) CALL This is used to translate the parameters (which have urls) of function calls. Sample rule CALL eval 1 aventail.post Result

8 SonicWALL Aventail E-Class SRA SSL VPN Web Translation Developer Guide Sample rule Replaces calls such as eval(str) with eval(aventail.post(str)) In this case the eval parameter must be translated before the function is called. SUBSITUTION This is used to replace certain tokens with something else. Sample rule SUBSTITUTION location.host 0 aventail.location.host Result In this rule, 0 is the lval/rval value, which tells the Web access service (extraweb) when to do substitution. If substitution is to be done only when a token is read from RHS then the value is 1. If substitution is to be done only when a token is written to, then this value is 2. To substitute in all instances, 0 is used. The sample rule above replaces all instances of location.host with aventail.location.host. SUBARGS This is used if the object on which the function is called requires translation. Sample rule SUBARGS.Open 0 aventail.objopen Result Replaces all calls such as window.open(param) with avential.objopen(window, param). This helps in translating the param correctly depending on the window object, and then does additional processing before opening a new window.

SonicWALL Aventail E-Class SRA SSL VPN Web Translation Developer Guide 9 VBScript Translation Follow these recommendations when writing JavaScript: Do not use DOM references as variables names. For example, do not call any of your variables location. See the list of existing rules in Translation Rules on page 5 to know what to avoid. Avoid the with construct. For example: with(object) {statements} Avoid passing DOM objects as parameters to functions. For example, avoid writing functions of the following form: function test(mywin) { mywin.location = "http://owa.in.sonicwall.com" } Instead, make sure that the network-sensitive JavaScript appears verbatim and do not hide the names of the underlying DOM objects. For example: window.location = "http://owa.in.sonicwall.com"; Do not set a base tag using JavaScript; this invalidates all the translated URLs on the page. Do not use conditional compilation for Internet Explorer (for example, @if ). Do not use Microsoft Script Encoding (for example, do not set language to JScript.Encode). Avoid using eval and innerhtml; they post the content back to the server for translation, which may affect performance. To add a rule for JavaScript translation 1. Create a file named custom-jstrans.cfg in the /usr/local/extranet/etc/ directory on the appliance. 2. Add custom translation rules following the syntax used in jstrans.cfg (see Translation Rules on page 5). For example, suppose an application uses a function that loads a file from a link, such as.load. This function is not defined in JavaScript, but is a method of a standard object present in the browser context. The param of this function must be translated in order for it to work properly. Add the following line to custom-jstrans.cfg to do the required translation: CALL.load 1 aventail.translate_url 3. Restart the Web access service by running the following command on the appliance: /etc/init.d/extraweb restart Alternatively, you can restart Web proxy service in AMC: click Services in the main navigation menu, click Stop, and then click Start. VBScript translation is not supported. Java Applet, ActiveX and Flash Translation XML Translation No translation of Java applets, ActiveX or Flash objects is performed. If possible, avoid using them. If it is not possible to avoid using these objects entirely, consider constructing the network references they need from the URL of the page that they are on. Perform this construction dynamically at run time. Host name mapped or Port mapped translations can be used for Java applets, ActiveX or Flash object based applications. The XML translation is done when content is identified as XML data, which is determined using the following logic: Content header is text/xml An XML declaration tag is present inside the content header: <?xml version="1.0" encoding="utf-8"?>

10 SonicWALL Aventail E-Class SRA SSL VPN Web Translation Developer Guide Web Aliases Referrer Lookup The html tag has an attribute of xmlns Doctype/Meta tags are used to indicate the content type Since XML needs to be described to make sense of the data, you must identify the portions of the XML content that require translation. This is done in the following file: /usr/local/extranet/etc/custom-xmltrans.cfg The format of the rules to add to this file is: ELEMENT ATTR1 ATTR2... ATTRn This instructs the translation engine to look for element ELEMENT in the XML and to translate its attributes ATTR1, ATTR2..., ATTRn (these attributes are URLs). For XML the custom-xmltrans.cfg file needs to be edited only if relative URLs are used. For example: <customelement path= /foo/bar.html helpfile= /help/en/index.html > <otherelement src= http://xxx.in.aventail.com/ /> <otherelement src= http://yyy.in.aventail.com/ /> <otherelement src= http://aaa.in.aventail.com/ /> <otherelement src= http://bbb.in.aventail.com/ /> <otherelement src= http://ccc.in.aventail.com/ /> </customelement> The src attribute of otherelement does not need an entry because it always uses a fully qualified URL. Because customelement uses relative paths it requires a rule: customelement path helpfile Web aliases are declared when you configure a resource. They are used to hide the host name of the internal server. You should avoid using the same name for the alias as for the top level directory of your application. For example, if your Web appliance resides in http://myapp.in.sonicwall.com/coolapp/, do not use coolapp as the alias for the resource in AMC. When a request for an absolute or relative URL for which there is no matching alias comes in, the Web translation engine looks at the Referrer HTTP header or the referrer cookie that it sets. This header or cookie is used to correctly assemble the destination URL. This is a best effort attempt and you should not rely on this mechanism for proper translation.