Talking to Proxy Servers from Director

December 4, 2002
by Gabrielle Dara Krim

[Editor's Note: The author is the Product Manager for INM's SecureNet Xtra. -DP]

Every Client Counts

With security threats becoming a universal fear, in the IT sector, as well as nationally, many corporations are now using proxy servers to monitor and restrict Internet traffic to and from their internal networks.

Why proxy servers concern you

Basic Definitions

A proxy server intercepts requests between a client (e.g., your desktop) and a web server for one or more of the following reasons:

to mask the identity of the client computer; only the proxy server's IP address is seen from outside.
to serve web pages from its cache and thus alleviate network traffic when the same URLs are requested repeatedly
to control access to the web

A proxy server does not take the place of a firewall, which mainly blocks potentially harmful network queries. A proxy server can be implemented in addition to, or without a firewall.

Please see the following definitions:

A proxy server can prevent unauthorized individuals from accessing external Internet resources by requiring a user name and password, which must be authenticated before processing the request.

This restriction is inconvenient for many e-learning and e-marketing applications, which rely on the Internet to deliver timely, up-to-date content. These days even CD-ROM and Intranet applications, running on a client's local machine, need to access the Internet for live content updates, or to communicate with remote servers that collect data from individual users. As a developer, you want to take advantage of the Internet's capabilities, but you do not want to exclude the potential consumers, clients, and e-learners, who are now sitting behind proxy servers.

The proxy challenge

NetLingo, Director's Xtra for network communications, allows for basic proxy server communication, but does not allow access through proxy servers that require username and password authentication. Internet applications developed in Director, such as electronic catalogs, e-learning systems, and online stores, could not deliver their content to users behind proxy servers requiring this kind of authentication.

The only options for developers were to either:

Use a non-multimedia, plain-HTML tool that would be both secure and ensure access from behind proxies, thus drastically reducing interactivity, multimedia features and user experience in general
Get the user's IT department to override security policies in the proxy server for a specific application. Most IT departments would be reluctant to do this; it requires going through approvals at many different levels of the organization.
Exclude those clients who use proxy servers with authentication, and deal with after-delivery crisis and disgruntled clients.

SecureNet Xtra

Integration New Media solved this problem by building an Xtra for Director that can "talk" directly to the proxy server. SecureNet Xtra enables Director applications to establish HTTP and HTTPS network communications through virtually any proxy server, with or without authentication. It works from projectors, Shockwave and even in Director's authoring environment.

SecureNet Xtra uses the client machine's Internet communications libraries: On Windows, it piggy-backs on IE's wininet.DLL; on Mac it uses the URLAccess Manager. It supports the most commonly used proxy server authentication schemes:

Basic (clear text) : Uses a base64-encoded string that contains the user name and password.
Digest challenge-response : A challenge-response scheme that challenges using a nonce (a server-specified data string) value. Was introduced in Microsoft® Internet Explorer 5.
NT LAN Manager (NTLM) : A challenge-response scheme that bases the challenge on the user name.
Microsoft Network (MSN) : The Microsoft Network's challenge-response authentication scheme.
Distributed Password Authentication (DPA) : Similar to MSN authentication and will also be used by the Microsoft Network.
Remote Passphrase Authentication (RPA) : CompuServe's authentication scheme.

For a detailed description of SecureNet Xtra's features, visit the product web site.

How to use SecureNet Xtra

INM designed SecureNet so that users of Director's existing NetLingo Xtra would easily be able to adapt their projects to use the new Xtra. It contains methods that are nearly identical in name; the only difference being that SecureNet Xtra's methods start with the prefix "snx". SecureNet Xtra also comes with its own set of behaviors that allow even novice users to easily create network applications in Director.

Our previous article on SecureNet -- "Bringing Security to Director" -- contains a comparison chart of SecureNet Xtra vs. NetLingo.

Example - HTTP GET through a proxy server

Using a sample project called Proxy-Connect, we will illustrate how to implement network communications across a proxy server. First, we will demonstrate how to use the SecureNet Xtra behaviors; then we will implement the same example with Lingo. The Behavior version of this sample is also available as a complete tutorial from INM's web site.

In this example we make a secure HTTP GET request to a URL on Integration New Media's secure server. We will implement the system default proxy server settings and allow for communication across a proxy server with, or without user authentication.

The destination URL is specified in the text field labeled URL on the Stage. The fields labeled Username and Password allow the end-user to enter authentication information if it is required by their proxy server. If no authentication is required, that information is ignored. When the user clicks Go, the request is sent to the destination URL. Any result text returned from the GET operation is displayed in the text box labeled Results.

Using SecureNet Xtra Behaviors

Only one SecureNet Xtra behavior is needed: snbGetNetText. Drag the snbGetNetText behavior over the button labeled Go in Director. This dialog box opens.

From this box, you can define most of the parameters by simply selecting from drop-down menus. The URL you are querying is stored within the cast member 11, "fldURL". The result returned is stored in member 12, "txtResults".

The lower half of the dialog box contains the proxy server settings. To ensure that the user's default proxy server settings are used, keep the Use default proxy settings box checked. With this setting neither you, nor your user needs to know the proxy server's IP address or port number.

To ensure that the user can enter his proxy server user name or password if needed, assign the User name stored in parameter to the Director cast member named "fldUserName" and the password parameter to the member named "fldPassword". These are the fields labeled similarly, below the URL field on the stage.

With SecureNet Xtra behaviors, the communication is synchronous -- that is, Director waits until the network operation has completed before processing any other commands.

The user fills in his proxy server username and password and clicks Go. The result text from the URL queried is displayed in the Results text box. If there is no proxy server, or the proxy server does not require user authentication, the user name and password are ignored.

Using SecureNet Xtra Lingo Methods

Now let's look at how to implement the same kind of example using the Lingo methods. For this example, you would place the SecureNet Xtra code in the mouseUp handler for the button Go.

Synchronous example:

on mouseUp
   -- initialize the proxy server settings to be used
   snxProxyServer (#Default, member ("fldUsername").text, member ("fldPassword").text)
   -- initiate the GET request
   NetID = snxGetNetText (member ("URL").text)
  if NOT snsDisplayError (NetID,1) then
     -- wait for operation to complete
     repeat while NOT (snxNetDone (NetID))
     end repeat
     -- retrieve the result text
     member ("txtResult").text = snxNetTextResult (NetID)
  end if
end

The above example uses a synchronous mode of communication; during the repeat loop, the user cannot interact with Director. This is usually desirable for network operations that are reasonably quick. If, however, you want the user to be able to send multiple network communications without waiting for a response between each, or you want to display an animation while the user waits, you may use the asynchronous mode.

Asynchronous example:

global gNetID
on mouseUp
  -- initialize the proxy server settings
   snxProxyServer(#Default, member ("fldUsername").text, member ("fldPassword").text)
  -- initiate the GET request
   gNetID = snxGetNetText (member ("URL").text)
   -- if an error occurred, display the error directly in an
   -- alert box and don't continue
   if (snsDisplayError (gNetID, 1)) then
     -- error - do something else
   end if
   -- the command was initiated successfully
end mouseUp

-- now check for completion
on exitFrame
   if (gNetID > 0) then -- make sure gNetID is valid
     -- get the status of the operation
     lStatus = snxGetStreamStatus (gNetID)
    total = lStatus[#BytesTotal]
     if (total <> 0) then
       pct = (lStatus[#BytesSoFar]/total) * 100
     else
       pct = 0
     end if
     -- display a progress indicator while the user waits
     ...

     -- check for completion
     if (snxNetDone (gNetID)) then
       if (snsDisplayError (gNetID, 1)) then
         -- don't continue if errors occurred
         exit
       end if
       -- display the response from the server script
       member ("Result").text = snxNetTextResult(gNetID)
       -- go to a specific frame

     else -- request is not yet completed, keep waiting
       go to the frame
     end if
  end if
end exitFrame

When using the asynchronous mode, you must use a global variable, gNetID, instead of NetID.

NOTE: Rather than have the username and password fields appear immediately, your application could try to call:

snxProxyServer (#Default)
errcode = snxGetNetText (URL)

without any username and password first. If an error code of -401 is returned, then your application can assume that the user's proxy server requires authentication and only then display the fields for the user to enter those parameters.

Conclusion

Director/Shockwave projects that use NetLingo for network communications automatically exclude most end-users who sit behind proxy servers. INM's SecureNet Xtra enables you to deliver projects that work from behind most proxy servers, thus allowing you to reach a wider audience and buying you peace of mind. Using SecureNet Xtra is similar to, and even simpler than, NetLingo and thus integrates smoothly in your production cycle.

System requirements

As of the writing of this article, SecureNet Xtra version 1.1 is available for Director and Authorware, on Windows. The Mac version is currently available as a Beta, to be released shortly.

Macromedia Director version 7.x, 8.x.
Windows: Windows 95/98/NT4/Me/2000/XP.
Microsoft Internet Explorer 4.x and later (or at least the corresponding wininet.dll library).
Mac OS 9.x (with URL Access Manager version 2.4.1 or later)

Product Info

The introductory, limited-time price for a SecureNet Xtra license is $149.
The Shockwave download weighs only 55K.
Installation is automatic, Verisign-approved, and safe for end-users.

Visit the product web site for more information.

All colorized Lingo code samples have been processed by Dave Mennenoh's brilliant HTMLingo Xtra, available from his site at http://www.crackconspiracy.com/~davem/

Gabrielle Krim has a B.A. in Computer Science from Cornell University and a M.A. in Educational Technology from Concordia University. She has over 10 years experience in the industry, as a software developer and multimedia author for database and e-learning projects. She has been working for INM as Instructional Designer and Project Manager since March 2002.