Script Encoding with the Microsoft Script Engine Version 5.0
Andrew Clinick

Tired of exposing your Web scripting code to prying eyes? With version 5.0 of the Microsoft Script Engine and Internet Explorer 5.0, you can now encode your VBScript and JScript work so curious users can't grab it. Scripting has become a very popular component for people developing for the Internet or intranet. This popularity has been accelerated not only by its dynamic development environment and the ubiquity of script support in browsers and servers, but also the ability to see what programming tricks others have employed simply by loading a page into Notepad. While this is a great asset for the beginning script programmer, people who are developing increasingly complex, script-based applications want to be able to protect their hard work. Version 5.0 of the Microsoft® Windows Script engines introduces a new feature, Script Encoding, that takes the first step toward protecting script from prying eyes.

    The goal of Script Encoding is four-pronged: to provide an encoding mechanism that can be implemented without significantly affecting performance, exported without regulatory headaches, embedded within HTML and any application that uses scripting, and implemented cross-platform.

    Now let's see how these requirements affected the design of the Microsoft script engines. The first and perhaps most important consideration is that the script is encoded, not encrypted. Encoding means that the script is passed through a text-encoding cipher, which replaces the original text. Therefore, the encoded script could be decoded by any program that can decipher the text cipher, without the need for an encryption key. Encoding was introduced not to provide a watertight protection mechanism for scripts (Microsoft is working on that for the future), but to provide a format that would require a prospective pirate to go through a specific decoding process to get your script code. If you have a copyright statement in your code (more on that later), it'll be far easier to show that your work was illegally copied.


How Does Encoding Work?

      All Microsoft (and many third-party) applications that use VBScript or JScript® employ the ActiveX® scripting interfaces (see Figure 1). These interfaces allow applications to integrate compatible script engines with a minimum of effort. This flexible mechanism for integrating script engines is also used without modification by Microsoft® Internet Explorer and Microsoft Internet Information Services.



      Figure 1: Script Encoding Architecture 


      Version 5.0 introduces a feature that lets script engines read encoded script, so any application that uses VBScript and JScript can use the encoding feature. The encoding features of the script engines are enabled when you set the language name to VBScript.Encode or JScript.Encode. The .Encode suffix on the language name means that the same script engine is used, but its ability to interpret encoded scripts is turned on and its debugging features are turned off. This is meant to ensure that people don't load up the script debugger and take a look at your code.

    Setting an engine to deal with encoded script is only one side of the equation. How do you encode your script? There are two mechanisms to do this: a command-line script encoder and a COM-based object model that lets you build encoding into your application. Since most of your script will probably be included in HTML and Active Server Pages (ASP), I'll cover how to encode these using the command-line script encoder, and then provide an overview of how to use the COM object.


Command-line Script Encoder

      The command-line script encoder (screnc.exe) provides a simple mechanism for encoding HTML, ASP, SCT, VBScript, and JScript files. The Microsoft Script group developed it as an easy-to-use command-line tool that can be easily built into your existing deployment batch files. To use the encoder, you just need to give it two arguments: the original file to be encoded and the new file name for the encoded version. For example, if you wanted to encode a file named default.htm you would run the following:


screnc default.htm defaultenc.htm


Figure 2 contains a list of the script encoder syntax elements used for a sample file.

Encoding Your HTML Page

      Encoding an HTML page is pretty simple. Just use the script encoder and it will automatically parse the HTML page for any script elements, encode the script, and change the language to include the .Encode directive.

    Before you encode HTML pages, there a number of issues to consider. First, is this page going on the Internet? If so, think twice about using encoding unless you are certain that your content will only run in Internet Explorer 5.0. If other browsers or other versions might be used, it doesn't mean you can't use encoding—but you should only encode the script that you intend to be used by Internet Explorer 5.0. Other browsers will ignore the code since they won't recognize the language type of VBScript.Encode or JScript.Encode, and will skip right over the <SCRIPT> element. You can use this to your advantage since you can ensure that any content for Internet Explorer 5.0 isn't run by other browsers. This is done by encoding the content to keep it away from user agent interrogation on your Web page.

    Second, can you guarantee Internet Explorer 5.0 as a client? Every installation of Internet Explorer 5.0 will have the new script engines that are required to decode encoded script, but versions 3.0 and 4.0 won't. That's not to say that Internet Explorer 3.0 or 4.0 won't be able to use encoded script. You can manually install the version 5.0 script engines for these earlier versions of Internet Explorer. Pages with encoded script will then work, since it's the engines, not the browsers, that provide the decoding ability.

    Third, what's the default language? If you don't include a language attribute in the HTML <SCRIPT> element, Internet Explorer will use the default script language for the page. The default language is JScript, but this changes to VBScript if the first script block on the page is written in VBScript. The script encoder does its best to work out the default language, but you can still run into problems. The best way around this is to always identify the language for the script block you are using. Even if you're not encoding your page, this is good programming practice. Alternatively, you can use the /l argument on the script encoder to set the default language.


Encoding ASP Files

      Encoding ASP files is a little more complex than encoding HTML, since the ASP file format provides more information about script. If you have a relatively simple ASP file with a single script element, you should be able to run it through the script encoder and have it do the right thing.

    ASP lets you embed script code using the <%…%> notation. Since this is a great way of interspersing your script with HTML, many ASP pages use this method rather than the alternate <SCRIPT runat=Server>. This presents a potential problem when encoding an ASP page, since the <%...%> notation doesn't contain any language information, and the encoding mechanism needs that information to do its job. It turns out that the vast majority of ASP developers use VBScript as their programming language of choice. VBScript is also the default language for ASP. Based on these factors, the script encoder will assume that the default language is set to VBScript.

    How do you get around this? There are two ways you can proceed: with the /l command-line argument or with the <language> directive in ASP. If you use the <language> directive, you can set the default language for the page. The encoder will read this and change the language name to the encoded version. Using the /l argument will cause the encoder to include an <language> directive with the proper language specified. For example,


screnc default.asp defaultencode.asp /l Jscript


would write 

<language Jscript.encode>


to the top of your file.

    ASP pages can have a number of different file extensions, so the script encoder knows how to handle the common ones (.asp, .asa, and .cdx) by default. If you create your own file extensions and want to use the encoder on them, you can use the file extension argument (/e) to specify the file extension you want the encoder to use on your file. If, for example, you use an .ajc extension for your ASP pages, you would encode the page using the following command:


Screnc default.ajc defaultencode.ajc /e ASP


      ASP applications typically involve a number of .asp files in a virtual root (vroot) on a Web server. To help you encode an entire project at once, the script encoder supports wildcards so you can use specifications like *.asp. To encode all ASP files in the current directory and place them in a folder named c:\encode, you would use the following syntax: 

screnc *.asp c:\encode


What about Windows Script Host?

      Windows Script Host (WSH) is rapidly gaining popularity as a way to develop batch files for Windows and login scripts. It would be great if you could encode these batch files to hide their contents from prying eyes. Since the encoding is all performed within the script engines, WSH gets encoding for free. All you need is the version 5.0 script engines to make WSH 1.0 support encoding. For more in-depth information on WSH, see http://msdn.microsoft.com/
scripting/windowshost/.

    The script encoder supports .vbs and .js files by default, and will encode them with the proper language based on the file extension. Since encoding is based on the language name, it's necessary to make some changes to machines using WSH 1.0 to make sure they load the encoded script engine when they encounter encoded script. The changes required include registering the file types .vbe (VBScript Encoded) and .jse (JScript Encoded) on your machine. Microsoft now includes a registry file (wshencode.reg) in the Windows Scripting Host download, available at http://msdn.microsoft.com/scripting/. Version 2.0 is ready for download now, so you can install it and get encoding without doing any extra work.


Using the Encoder in other Applications

      The script encoder uses the scripting runtime module (scrrun.dll) to do all the encoding. All the script encoder does is provide a command-line mechanism for calling the scripting.encoder object that's implemented in the scripting runtime. This setup provides you with an extensible mechanism for using encoding in your applications or in third-party apps. Microsoft did it this way to ensure that you could use encoding where you wanted to rather than where Microsoft thought you might want to use it.

    To illustrate the use of the scripting.encoder object, I have created a very simple Visual Basic for Applications macro for use in Microsoft FrontPage® 2000, which is in beta as I'm writing this. FrontPage 2000 has an object model that allows you to access pretty much everything within your Web site. For this demo, I'll use it to get the contents of an HTML page. To get the HTML page I get the current active document, which is represented by the ActiveDocument object. Once I have that object, I can get its HTML content from the DocumentHTML property. When I have the HTML, it's a simple matter of calling the EncodeScriptFile method on the scripting.encoder object, making it encode any script in the HTML and returning a string with the encoded script. Figure 3 shows some sample code for encoding a page.

    Since scripting.encoder is just a COM object, it can be used anywhere a COM object can be used. An interesting use for the object is within WSH to provide functionality that is missing from the script encoder. For example, the script encoder doesn't provide the ability to encode subdirectories. Using a combination of the scripting.FileSystemObject and scripting.encoder object, this can be accomplished reasonably easily.


Summary

      Script encoding is Microsoft's first step in helping script developers develop script applications that they want to protect from prying eyes. It's not unbreakable, but it provides a useful tool. Microsoft intends to build on script encoding considerably in future releases of the engines. If you want more information on encoding, or want to download the encoder, go to the Microsoft scripting Web site at http://msdn.microsoft.com/scripting/. The Script Technologies group at Microsoft is always keen to get your feedback on new features, so please try it out and send mail to msscriptmicrosoft.com, or visit the scripting newsgroup at news://msnews.microsoft.com/
microsoft.public.scripting.vbscript.