Signing a Cabinet File with Java Permissions Using Signcode

Overview

Signing a cabinet file with Java permissions gives developers more detailed control over the security restrictions placed on their applet when it is used over the Internet or an intranet.

While encoding permissions inside an applet is optional, it provides several additional benefits over regular signing:

Applets and controls can be granted only specific permissions they need.

If an applet is signed in the old style (without Java information), the user must choose between running it in the Java "sandbox," or allowing it to be fully trusted. For example, permission signing enables applets to request permission to store only temporary files on the client hard disk. Users of a permission signed applet can allow the it to run, without worrying that it will have full access to their system.

Fewer dialog boxes are presented to the user.

When Microsoft® Internet Explorer zones are used, applets might automatically receive some permissions when they are downloaded from a certain zone. When an applet is signed with the specific permissions it needs, the user will not even be queried if the zone automatically grants the permissions that the applet needs.

Cabinet File Permission Levels

The signcode utility enables you to sign a cabinet file at three different security levels. They are as follows:

High	The High security level ensures that all Java code contained in the cabinet file will run in the Java "sandbox." High is the most stringent level of signing, and is equivalent to the same permissions that an unsigned applet is granted. Signing a cabinet file with High ensures that it will never be able to do more than it would in the sandbox, regardless of where the code comes from and what the user allows it to do. A cabinet file signed High will always be allowed to run without any user intervention.
Medium	The Medium security level places the same restrictions on the applet as High, but with a few exceptions. Applets signed with the Medium level request user-directed file I/O as well as the ability to store 1 MB of data in the client computer's scratch space. This storage can be accessed through the com.ms.io.clientstorage API. Applets signed with Medium permissions may also call user-directed file I/O routines. These routines will present dialogs to the user and ensure that all file operations are done with user intervention. A cabinet file signed Medium will run without intervention in Low and Medium security zones. Because the requested permissions are greater than a High security zone can automatically give, a Medium signed cabinet file will prompt the user before allowing code to run in a High security zone.
Low	The Low security level means the code in the cabinet file is requesting to be fully trusted. Only a zone set at Low security can grant this much access without first asking the user. The other two zones prompt the user before running the applet.

Cabinet Files and ActiveX

Cabinet files may contain both Microsoft® ActiveX® Controls and Java code when downloaded using the uselibrary parameter. Because ActiveX controls must be fully trusted to run, they are treated differently from Java code. The previous security levels apply only to Java code, and ActiveX controls in the cabinet file will not be allowed to run.

For ActiveX controls to run when they are in a cabinet file that uses Java Permission signing, you must specify that the cabinet file contain ActiveX controls in the signature. Do so by specifying the LowX, MediumX, or HighX flags instead of Low, Medium, or High. These three flags have the same meaning as their respective flags without the X. However, if you include ActiveX controls in the cabinet file, they will be denied, allowed to run, or will query the user, based on the security settings of the zone.

Note If your cabinet file has only ActiveX controls, do not use the Java signing method. Instead, use signcode without JavaSign.dll.

A Brief Introduction to Zones

Zones are a way of reducing the complexity of system security by assigning security policies to entire groups of sites.

Microsoft® Internet Explorer 4.0 divides your Internet world into zones, so you can assign specific security settings to each zone, and then assign Web sites to a zone with a suitable security level. The name of the current zone appears on a status bar in the lower-right corner. Whenever you attempt to open or download content from the Web, Internet Explorer checks the security settings for that Web site's zone. Internet Explorer provides four zones:

Corporate Intranet	Addresses that don't require a proxy server (those listed in the Proxy Settings as not requiring a proxy server). The addresses included in this zone are defined by the system administrator in the Internet Explorer Administrator's Kit (IEAK). The default security level for the Corporate Intranet zone is Low.
Trusted Sites	Sites you trust enough to require low security before downloading or running files from the Internet. You can assign sites to this zone. By default, the security level for the Trusted Sites zone is Low.
Restricted Sites	Sites you don't trust, requiring medium or high security before downloading or running files from the Internet. You can assign sites to this zone. By default, the security level for the Restricted Sites zone is High.
Internet	By default, the Internet is anything not on your computer, the Intranet, or assigned to any other zone. The default security level for the Internet zone is Medium.

Each zone can be set to a specific security level. The security level applies to all code downloaded from sites within the zone:

High Security	Java applets will run in the sandbox without intervention from the user. Any requests beyond the sandbox will query the user. ActiveX controls will never be allowed to run.
Medium Security	A zone set for Medium Security will allow applets to have up to 1 MB of scratch space on the client computer, if it is requested in the cabinet file signature. Any requests beyond those restrictions will cause the user to be queried. Applets signed with Medium permissions may also call user-directed file I/O routines. These routines will present dialogs to the user and ensure that all file operations are done with user intervention. ActiveX controls will also prompt the user before running.
Low Security	A zone set for Low Security will allow applets to run fully trusted, if they request to do so in their signature. ActiveX controls will prompt the user before running.
Custom	The user or the administrator defines Custom Security levels. They may also allow ActiveX Controls to run without prompting, whereas the predefined zones do not have that option.

For more information on how zones are configured and used, see the online Help for Internet Explorer.

How Cabinet File Signing Works with Internet Explorer Zones

When a signed cabinet file is downloaded from a page, the signature is examined to see if it contains permission information. If so, Internet Explorer and the Microsoft VM for Java work together to determine what the applet will be allowed to do. This determination is based on the security level of the Zone the cabinet file is downloaded from, the permissions requested in the cabinet signature, and the response of the user, if needed.

If a cabinet file is signed at a certain security level, it will be allowed to run with that level of permissions without any intervention from the user, but only if the Zone is set at that same level or less secure. However, if a cabinet file is requesting permissions greater than those that can be automatically granted by a zone, the user is presented with a query. If the user agrees to let the applet run, it is run with the signed permissions. Otherwise, the applet will not be allowed to run.

The following chart details this behavior.

Cabinet files signed with this level

		High	Medium	Low
Zone	High	Runs in High	Query (Yes = Medium)	Query (Yes = Low)
Level	Medium	Runs in High	Runs in Medium	Query (Yes = Low)
	Low	Runs in High	Runs in Medium	Runs in Low

If the user is presented with a query and denies the request, the applet will not run.

Using Signcode with Java Permission Information

To add the Java permission information into the signature, use the -j JavaSign.dll option to signcode. You may also specify the -jp option for finer control over the exact permissions in the signature.

The command line for signcode with the Java permission information is as follows:

signcode [options] -j JavaSign.dll [-jp level] [more options] 

;
; ClientStoragePermission
;
[com.ms.security.permissions.ClientStoragePermission]
; Limit is in bytes
Limit=100
RoamingFiles=true
GlobalExempt=true

;
; ThreadPermission
;
[com.ms.security.permissions.ThreadPermission]
AllThreadGroups=true
AllThreads=true

Using the Chkjava Utility

To examine the permission information in a signed cabinet file, run

chkjava filename

where filename is the name of the filename to verify.

How to Sign a Cabinet File with Java Permissions

The following steps show you how to sign a cabinet file with Java permissions.

1. First, create a certificate with the MakeCert program.

   C:\..\>makecert -sk MyKeyName -n "CN=My Publisher Name" MyTestCert.cer

2. Turn your certificate into a test Software Publisher Certificate (SPC). A valid SPC is obtained from a Certification Authority.

   C:\..\>cert2spc MyTestCert.cer MyTestCert.spc

3. Sign the cabinet file with the permissions. The following command line signs MyApplet.CAB with medium permissions, using the key and certificate created previously.

   C:\..\>signcode -j javasign.dll -jp medium -spc MyTestCert.spc 
      -k MyKeyName MyApplet.cab
   

4. Verify that the appropriate permissions have been correctly encoded in the file.

   C:\..\>chkjava MyApplet.cab
   

More Information

For more information on all of the parameters for makecert, cert2spc, signcode, and chktrust, see the Microsoft SDK for Java Tools quick reference section.

For more information on how zones are configured and used, see the online help for Internet Explorer.