HOWTO: Make Your Java Code Trusted in Internet Explorer

ID: Q193877

The information in this article applies to:

Microsoft Visual J++, versions 1.0, 1.1, 6.0
Microsoft SDK for Java, versions 2.0, 2.01, 2.02, 3.0, 3.1
Microsoft Virtual Machine on Macintosh
Microsoft Win32 Virtual Machine

SUMMARY

You should consider several factors when you want to make your Java code run as fully trusted, partially trusted, or untrusted in Microsoft Internet Explorer. This article explains many of the considerations, and it points to some resources that can help ensure your Java code has the correct level of trust when it executes in the browser.

MORE INFORMATION

Class Loader

It is important to understand the significance of the class loader in Java. The class loader controls much of the security and access granted to a class. The following article in the Microsoft Knowledge Base explains when the Microsoft virtual machine (Microsoft VM) uses different loaders:

Q177168 INFO: How Does the Virtual Machine Search for Java Classes?

With this information, you can make a more informed decision about which method of gaining additional permissions is most suitable for your project.

What It Means to Be Trusted

The term trusted means that the code is no longer confined to the Java sandbox. The sandbox restricts untrusted code from successfully performing the trusted operations, such as:

Calling native code

Using COM

Using J/Direct

Connecting to remote computers

Printing

Using JDBC

Creating top-level windows that do not have the applet warning

For your classes to run with permissions above the sandbox level, the classes must be delivered to the client computer inside a signed cabinet (CAB) file. When you sign the CAB file, you also must specify the permissions that the contained classes require. There are three predefined levels of permissions (LOW, MEDIUM, and HIGH) in Microsoft Internet Explorer 4.x:

HIGH permissions are equivalent to the Java sandbox. The only advantage of signing in this scenario is that you can ensure a user of your code that a third party has not altered the code.

MEDIUM permissions are the same as HIGH, but allow for access to a scratch area on the local computer. For more information, please see the following article in the Microsoft Knowledge Base:
Q172200 HOWTO: Using Scratch Space From Your Java Applet

LOW permissions essentially grant access to all of the operations listed previously. See the "Java Permissions .INI Values Reference" topic in the following documentation in the SDK for Java for further details on attaining a finer granularity of permissions than one of the three predefined levels listed here:
http://www.microsoft.com/java/sdk/32/default.htm
Click Index and then click J. Scroll to find "Java Permissions .INI Values Reference."

Asserting Permission

The following Knowledge Base article provides enough information to understand when, why, and how you should assert permission in your Java code:

Q175622 PRB: SecurityExceptionEx Exception Running a Java Applet

Creating the Cabinet (CAB) File

Now that you understand the concept of loaders, trust, and permissions, the next step is knowing how to create the cabinet (CAB) file. At this stage, you need to decide whether you wish to install your code on the user's computer, or simply package your code in a CAB file for faster download on every visit to your page.

If you do not want to install your code onto the local computer, you can simply create a CAB file using the Cabarc.exe utility and reference the CAB from a parameter passed to your applet from HTML. This is shown in Sample 1 later in this article.

NOTE: This method does not require that you sign the CAB file if you do not need your code to run as trusted. You can still gain the benefits of having a single compressed file download instead of individual class files.

If you wish to install your code on the local computer, there are two approaches. One way is to create a Distribution Unit (DU) using the Dubuild.exe utility in the SDK for Java. This utility creates a CAB file and includes an automatically generated .osd file. See Sample 2 later in this article.

The other method to install code on the local computer is to use an .inf file. This method is somewhat more manual and more error-prone, but has the distinct advantage of being the only method that works on Internet Explorer 3.x and later. See Sample 3 later in this article.

Each of these methods has the advantage of downloading your code on the first visit to the page and not requiring another download on subsequent visits unless a newer version becomes available. They do however require some permanent space on the user's local drive.

Using a Digital Signature on Your CAB File

You need to sign your CAB whenever your code needs to do something outside of the Java sandbox or whenever you want to install code to the local computer from a Web page. You sign a CAB using the Signcode.exe utility in the SDK for Java. The samples later in this article show a few common signing scenarios. You can find additional information in the find "Signing Cabinet Files with Java Permissions" topic of the SDK for Java documentation and samples at the following location:

http://www.microsoft.com/java/sdk/32/default.htm

Click Index and then click S. Scroll to find "Signing Cabinet Files with Java Permissions."

Following are a few key points to keep in mind:

Fine-grained Java permissions were added in the Microsoft VM and signing tools in the SDK for Java 2.0 and later.

Using fine-grained permissions can help limit your exposure as a developer of a Java package by reducing the access allowed to the bare minimum required by your project.

Fine-grained permissions are requested by using an .ini file at the time of signing. See the SDK for Java documentation titled "Java Permissions .ini Values Reference" for additional information.

Finally, you can use a test certificate for development purposes (as seen in the samples later in this article), but a real certificate will be desired before deploying your application. A real certificate can be obtained by a Certificate Authority. VeriSign is now issuing full-assurance certificates for use with Authenticode. You can contact VeriSign at the following location:

http://digitalid.verisign.com/

For more information regarding Microsoft's code-signing technology, please see the following Web site:

http://www.microsoft.com/security/tech/authcode/authcode-f.htm

Tags to Reference Your Signed CAB File

There are several options to reference your signed CAB file in HTML. Following is a list and brief comparison of the different methods:

cabbase parameters to an APPLET tag

cabinets parameters to an APPLET tag. For additional information, click the article number below to view the article in the Microsoft Knowledge Base:
Q177159 INFO: Support for Multiple CABs or JARs in the Same APPLET Tag

useslibrary, useslibrarycodebase, and useslibraryversion parameters to an APPLET tag

cabbase parameters to an OBJECT tag

cabinets parameters to an OBJECT tag

useslibrary, useslibrarycodebase, and useslibraryversion parameters to an OBJECT tag

Trusted Code in Internet Explorer for Macintosh

Authenticode is not supported in Internet Explorer for Macintosh. To enable downloaded code access outside the Java sandbox, the user must add the server to the list of Trusted Sites and then set the site permissions to those that the code requires.

SAMPLES

You can use the following Java class with the following three short samples. Cut and paste this text into a file named Simple.java.

NOTE: Ensure you have a version of jvc.exe in your path from the SDK for Java 2.0 (build 4337) or later. This class will simple assert permission and display a Win32 MessageBox when run:


package simple;
import com.ms.security.*;
public class Simple extends java.applet.Applet
{
  public void init()
  {
    try {
      if (Class.forName("com.ms.security.PolicyEngine") != null)
        PolicyEngine.assertPermission(PermissionID.SYSTEM);
    } catch (Throwable cnfe) {  }
    try {
          MessageBox(0, "MessageBox successfully called.", "Java", 0);
      } catch (UnsatisfiedLinkError ule) {
          System.err.println("Caught exception: " + ule);
          System.err.println("Probably wrong version of Java
                             compiler.");
      }
  }

  /** @dll.import("USER32") */ 
  static native int MessageBox(int    hwndOwner,
                               String text,
                               String title,
                               int    style);
}

NOTE: The linefeed is inserted in the command lines for Signcode.exe below. These command lines are too long to fit in one line in the Microsoft Knowledge Base, but should be edited in your batch files to be a single line.

Sample 1 - Simple1

This sample shows a signed CAB file that does not install onto the local computer.

You can use the commands below to compile Simple.java, create a CAB file that contains Simple.class, enable the test root on the local computer, create a test certificate, sign the CAB file with LOW Java permissions using the test certificate, and launch the Simple1.html page in the browser. Cut and paste these commands into a batch file named go1.bat and save it to the same directory as the Simple.java file created above:


jvc /d . Simple.java
cabarc -p n mycab1.cab simple/Simple.class
del simple\Simple.class
setreg 1 true
makecert -sk MyKeyName -n "CN=My Publisher Name" MyTestCert.cer
cert2spc MyTestCert.cer MyTestCert.spc
signcode -j javasign.dll -jp LOW -spc MyTestCert.spc -k MyKeyName
  mycab1.cab
start Simple1.html

Before you execute go1.bat, cut and paste the HTML below into a file named Simple1.html and place it in the same directory as the files named Simple.java and go1.bat created previously:


<HTML>
 <APPLET CODE="simple.Simple" WIDTH=100 HEIGHT=100>
 <PARAM NAME="cabbase" VALUE="mycab1.cab">
 </APPLET>
</HTML>

NOTE: A "cabinets" parameter works interchangeably with a "cabbase" parameter on computers running Internet Explorer 4.0 and later. The "cabinets" parameter has the added functionality of allowing for multiple CAB files to be referenced from the same APPLET tag. For more information, please the following article in the Microsoft Knowledge Base:

Q177159 INFO: Support for Multiple CABs or JARs in the Same APPLET Tag

Sample 2 - Simple2

This sample shows a signed CAB file that installs into the Java Package Manager (JPM) on the local computer.

You can use the commands below to compile Simple.java, create a CAB file that contains Simple.class and a dubuild-generated .osd file, enable the test root on the local computer, create a test certificate, sign the CAB file with LOW Java permissions using the test certificate, and launch the Simple2.html page in the browser. Cut and paste these commands into a batch file named go2.bat and save it to the same directory as the Simple.java file created previously:


jvc /d . Simple.java
dubuild mycab2.cab . /D "JPM Simple2" /I *.class /V 1,1,23,0
del simple\Simple.class
setreg 1 true
makecert -sk MyKeyName -n "CN=My Publisher Name" MyTestCert.cer
cert2spc MyTestCert.cer MyTestCert.spc
signcode -j javasign.dll -jp LOW -spc MyTestCert.spc -k MyKeyName
  mycab2.cab
start Simple2.html

Before you execute go2.bat, cut and paste the HTML below into a file named Simple2.html and place it in the same directory as the files named Simple.java and go2.bat created previously:


<HTML>
 <APPLET code="simple.Simple" WIDTH=100 HEIGHT=100>
 <PARAM NAME=useslibrary VALUE="JPM Simple2">
 <PARAM NAME=useslibrarycodebase VALUE="mycab2.cab">
 <PARAM NAME=useslibraryversion VALUE="1,1,23,0">
 </APPLET>
</HTML>

Once a package is installed on the local computer using JPM, it will be present in the "<windir>\Downloaded Program Files" folder. Use this folder to view and remove packages that are installed using Internet Explorer.

Sample 3 - Simple3

This sample shows a signed CAB file that installs the Simple.class file in the <windir>\java\lib\simple directory on the local computer. You can use the commands below to compile Simple.java, create a CAB file that contains Simple.class and an .inf file that you create, enable the test root on the local computer, create a test certificate, sign the CAB file with LOW Java permissions using the test certificate, and launch the Simple3.html page in the browser. Cut and paste these commands into a batch file named go3.bat and save it to the same directory as the Simple.java file created previously:


jvc /d . Simple.java
cabarc -p n mycab3.inner.cab simple/Simple.class
del simple\Simple.class
cabarc n mycab3.cab mycab3.inner.cab simple.inf
setreg 1 true
makecert -sk MyKeyName -n "CN=My Publisher Name" MyTestCert.cer
cert2spc MyTestCert.cer MyTestCert.spc
signcode -j javasign.dll -jp LOWX -spc MyTestCert.spc -k MyKeyName
  mycab3.cab
start Simple3.html

Before you execute go3.bat, you need to cut and paste the following HTML into a file named Simple3.html and place it in the same directory as the files named Simple.java and go3.bat created previously:


<HTML>
 <OBJECT    CLASSID="clsid:99999999-9999-9999-9999-999999999999"
 CODEBASE="mycab3.cab#Version=1,1,23,0">
 </OBJECT>

 <APPLET CODE="simple.Simple" WIDTH=100 HEIGHT=100>
 </APPLET>
</HTML>

NOTE: Replace the guid above "99999999-9999-9999-9999-999999999999" with the one created for the .inf file in the following instructions.

Follow these steps to create the simple.inf file that is to be included in the outer CAB file:

Copy the master.inf from the <sdk-dir>\bin\packsign directory.

Rename the new copy of master.inf to simple.inf.

Open the simple.inf file in a text editor.

Change the following lines from:


run=extrac32.exe /e /a /y /l %49000% CabFileName.cab

To:


run=extrac32.exe /e /a /y /l %49000% mycab3.inner.cab

From:


InfFile=master.inf

To:


InfFile=simple.inf

From:


ClassId="{99999999-9999-9999-9999-999999999999}"

To:

Run guidgen.exe (from the <sdk-dir>\bin directory).

Select option #4 "Registry Format".

Push the "New GUID" button.

Push the "Copy" button.

Paste the new guid from the clipboard into the line above in the simple.inf file and into the HTML above as well.

From:


PackageName="name"

To:


PackageName="SIMPLE3"

From:


HKLM,"SOFTWARE\Classes\CLSID\%ClassId%\InstalledVersion",,,"aa,bb,cc,dd"

To:


HKLM,"SOFTWARE\Classes\CLSID\%ClassId%\InstalledVersion",,,"1,1,23,0"

From:


HKLM,"Software\Classes\CLSID\%ClassId%\InstalledVersion","Path",,  "%49000%\&lt;filename&gt;"

To:


HKLM,"Software\Classes\CLSID\%ClassId%\InstalledVersion","Path",,  "%49000%\simple\Simple.class"

Save the changes you have made to the simple.inf file.

Run the go3.bat file created previously.

NOTE1: After you run the previous samples, you should disable the test root on the local computer by running "setreg.exe 1 false". This will prevent the test root from being honored as a real certificate by Internet Explorer. The test root can always be re-enabled using "setreg.exe 1 true".

NOTE2: Please consider the following when signing your CAB file for production use verses testing:

All of the previous commands generate the certificate and immediately sign with it. Most people re-create their certificates each time they build and sign a CAB, but you don't do that if you're publishing the CAB. You buy and use a certificate, and you keep track of it carefully.

The previous commands create a test certificate, but you only need to do this if you haven't bought one. This is how you would sign if they have a .pvk file instead of keeping the key in the registry, because some people receive their keys in that form. Substitute "-v MyCertName.pvk" for "-k KeyName".

When you run the signcode.exe command, you should probably add the "-t http://timestamp.verisign.com/scripts/timstamp.dll" option to properly time stamp the signature on the CAB file. It was left out of these samples to allow the command to succeed for users that do not have a persistent connection to the internet.

NOTE3: Microsoft Visual J++ 6.0 provides for simple packaging of Java components. See the Output tab in the Project Properties dialog box and the product documentation for additional information. Distribution Units created with Visual J++ 6.0 use the JPM for package installation.

NOTE4: You can configure Internet Explorer 4.x or higher to treat unsigned code as having more than the sandbox permissions by default. You should only do this for specialized situations like the intranet or for testing purposes. If you choose to configure Internet Explorer in this manner, be advised that you will no longer have any protection against malicious Java code that runs on your computer. For example, to automatically treat all Java applets as fully trusted in the Intranet Zone, perform the following steps:

Go to the Security tab in the Internet Properties dialog box.

Select the Local Intranet Zone.

Select the Custom option, and click Settings.

Locate the Java Permissions item in the list, and choose Custom.

Select Custom, and then click Java Custom Settings.

Go to the Edit Permissions tab.

Under Run Unsigned Content, click Enable.

REFERENCES

For more in-depth information and samples related to Java security, creating cabinets, and signing, see the Microsoft SDK for Java at the following address:

http://www.microsoft.com/java/sdk/default.htm

For additional information about security and packaging issues in the Microsoft Virtual Machine, click the article numbers below to view the articles in the Microsoft Knowledge Base:

Q175622 PRB: SecurityExceptionEx Exception Running a Java Applet

Q177168 INFO: How Does the Java Virtual Machine Search for Java Classes?

Q177159 INFO: Support for Multiple CABs or JARs in the Same APPLET Tag

Q172200 HOWTO: Using Scratch Space From Your Java Applet

Q179652 HOWTO: Deploying Java in Internet Explorer 4.0 and Netscape 4.0

Q181374 INFO: Related Component Download Articles

See the following Site Builder article written by Michael Edwards for additional discussion of many Code Download issues:

http://msdn.microsoft.com/workshop/components/downcode.asp

For the latest Knowledge Base articles and other support information on Visual J++ and the SDK for Java, please see the following pages on the Microsoft Technical Support site:

http://support.microsoft.com/support/visualj/

http://support.microsoft.com/support/java/

Additional query words:


Keywords          : kbJavaVM kbJDBC kbJNative kbSDKJava200 kbSDKJava201 kbSDKJava300 kbVJ100 kbVJ110 kbVJ600 kbSDKJava310 kbSDKJava202 
Version           : MACINTOSH:; WINDOWS:1.0,1.1,2.0,2.01,2.02,3.0,3.1,6.0
Platform          : MACINTOSH WINDOWS 
Issue type        : kbhowto

Last Reviewed: August 2, 1999