How to make your Java code trusted in Internet Explorer (193877)

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: 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.
• LOW permissions essentially grant access to all of the operations listed previously.

Asserting permission

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

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: In the SDK, 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: For more information about how to create, how to view, and how to manage certificates, visit the following Microsoft Developer Network (MSDN) Web site:

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.
• 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.

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:

1. Copy the master.inf from the <sdk-dir>\bin\packsign directory.
2. Rename the new copy of master.inf to simple.inf.
3. Open the simple.inf file in a text editor.
4. 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:
   1. Run guidgen.exe (from the <sdk-dir>\bin directory).
   2. Select option #4 "Registry Format".
   3. Push the "New GUID" button.
   4. Push the "Copy" button.
   5. 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%\<filename>"
   						

   To:

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

5. Save the changes you have made to the simple.inf file.
6. Run the go3.bat file created previously.

Note 1 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".

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

1. 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".
2. 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.

Note 3 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.

Note 4 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:

1. Go to the Security tab in the Internet Properties dialog box.
2. Select the Local Intranet Zone.
3. Select the Custom option, and click Settings.
4. Locate the Java Permissions item in the list, and choose Custom.
5. Select Custom, and then click Java Custom Settings.
6. Go to the Edit Permissions tab.
7. Under Run Unsigned Content, click Enable.