| Documentation Contents

# Application Development Considerations

This chapter includes the following topics:

- Introduction
- Retrieving Resources from JAR files
- Accessing the Client Using JNLP API
- Security and Code Signing
- Signing JAR Files With a Test Certificate
- How to Encode JNLP Files
- Dynamic Download of HTTPS Certificates

### Introduction

Developing applications for deployment with Java Web Start is generally the same as developing stand-alone applications for the Java(TM) Platform Standard Edition. For instance, the entry point for the application is the standard `public static void main(String[] argv)`.

However, in order to support Web deployment—automatic download and launching of an application—and to ensure that an application can run in a secure sandbox, there are some additional considerations:

- An application must be delivered as a set of JAR files.
- All application resources, such as files and images must be stored in JAR files; and they must be referenced using the `getResource` mechanism in the Java(TM) Platform Standard Edition (see below).
- If an application is written to run in a secure sandbox, it must follow these restrictions:
  - No access to local disk.
  - All JAR files must be downloaded from the same host.
  - Network connections are enabled only to the host from which the JAR files are downloaded.
  - No security manager can be installed.
  - No native libraries may be used.
  - Limited access to system properties. The application has read/write access to all system properties defined in the JNLP File, as well as read-only access to the same set of properties that an Applet has access to.
  Some of these restrictions can be overcome by the use of JNLP API to access the file system and other system resources.
- An application is allowed to use the `System.exit` call.
- An application that needs unrestricted access to the system will need to be delivered in a set of signed JAR files. All entries in each JAR file must be signed.

### Retrieving Resources from JAR files

Java Web Start only transfers JAR files from the Web server to the client machine. It determines where to store the JAR files on the local machine. Thus, an application cannot use disk-relative references to resources such as images and configuration files.

All application resources must be retrieved from the JAR files specified in the `resources` section of the JNLP file, or retrieved explicitly using an HTTP request to the Web server. Storing resources in JAR files is recommended, since they will be cached on the local machine by Java Web Start.

The following code example shows how to retrieve images from a JAR file:

`// Get current classloader`
`ClassLoader cl = this.getClass().getClassLoader();`
`// Create icons`
`Icon saveIcon = new ImageIcon(cl.getResource("images/save.gif"));`
`Icon cutIcon = new ImageIcon(cl.getResource("images/cut.gif"));`
`...`

The example assumes that the following entries exist in one of the JAR files for the application:

> `images/save.gif`
> `images/cut.gif`

### Accessing the Client Using JNLP API

JNLP API can be used to access the client's file system and other resources. See the following topics for more information about using JNLPI API to access the client:

- JNLP API Examples
- Accessing Client the Using JNLP API (Topic in the Deployment Trail of the Java Tutorials. Although the sample shown is an applet, the information applies to Java Web Start applications also.)

### Security and Code Signing

Java Web Start addresses the security issues:

- Protecting users against malicious code (intentional & unintentional) that may affect local files;
- Protecting enterprises against code that may attempt to access or destroy data on networks.

Applications launched with Java Web Start are, by default, run in a restricted environment where they have limited access to local computing resources, such as storage devices and the local network. In this sandbox environment, Java Web Start can guarantee that a downloaded and potentially untrusted application cannot compromise the security of the local files or the network.

An additional security feature supported by Java Web Start is digital code signing. If an application being invoked is delivered in one or more signed JAR files, Java Web Start will verify that the contents of the JAR file have not been modified since they were signed. If verification of a digital signature fails, Java Web Start will not run the application, since it may have been compromised by a third-party.

The support for code signing is important for both users and for application service providers. This service makes it possible for users to verify that an application comes from a trusted source. Because the application service provider signs the code, both can be ensured that no other party can impersonate the application on the Web. A signed application that is trusted by the user can also request additional system privileges, such as access to a local disk.

Java Web Start presents a dialog displaying the application's origin, based on the signer's certificate, before the application is launched. This allows the user to make an informed decision about whether or not to grant additional privileges to the downloaded code.

By including the following settings in the JNLP file, an application can request full access to a client system if all its JAR files are signed :

`<security>`
`<all-permissions/>`
`</security>`

The implementation of code signing in Java Web Start is based on the security API in the core Java(TM) Platform Standard Edition. The Java 2 SE JRE 1.4.2 supports code signing with the SHA1withDSA and MD5withRSA algorithms.

Developers sign code for use with Java Web Start in the same way as for Java Applets—by using the standard `jarsigner` tool from the Java(TM) Platform Standard Edition. The `jarsigner` tool documentation provides examples of how to sign code and create test certificates, and it discusses other issues related to signing.

Java Web Start also supports use of the Netscape `signtool` used with SDK/JRE 1.4.2. See the Netscape Web site for details: http://developer.netscape.com/software/signedobj/

### Signing JAR Files With a Test Certificate

Here are the steps needed to sign a JAR file with a test certificate:

1. Make sure that you have an SDK 1.4.2 `keytool` and `jarsigner` in your path. These tools are located in the SDK bin directory.

2. Create a new key in a new `keystore` as follows:

> > `keytool -genkey -keystore myKeystore -alias myself`

> You will get prompted for a information about the new key, such as password, name, etc. This will create the `myKeystore` file on disk.

3. Then create a self-signed test certificate as follows:

> `keytool -selfcert -alias myself -keystore myKeystore`

> This will prompt for the password. Generating the certificate may take a few minutes.

4. Check to make sure that everything is okay. To list the contents of the keystore, use this command:

> `keytool -list -keystore myKeystore`

> It should list something like:

> > `Keystore type: jks
> > Keystore provider: SUN
> > Your keystore contains 1 entry:
> > myself, Tue Jan 23 19:29:32 PST 2001, keyEntry,
> > Certificate fingerprint (MD5):
> > C2:E9:BF:F9:D3:DF:4C:8F:3C:5F:22:9E:AF:0B:42:9D`

5. Finally, sign the JAR file with the test certificate as follows:

> `jarsigner -keystore myKeystore test.jar myself`

> Repeat this step with all of your JAR files.

Note that a self-signed test certificate should only be used for internal testing, since it does not guarantee the identity of the user and therefore cannot be trusted. A trust-worthy certificate can be obtained from a certificate authority, such as VeriSign or Thawte, and should be used when the application is put into production.

### How to Encode JNLP Files

Beginning with Java Web Start version 1.2, JNLP files may be encoded in any character encoding supported by the Java(TM) Platform Standard Edition. (See the Java(TM) Platform Standard Edition documentation for a list of supported encodings.)

To encode a JNLP file, specify an encoding in the XML prolog of that file. For example, the following line indicates that the JNLP file will be encoded in UTF-16.

>     <?xml version="1.0" encoding="utf-16"?>

The XML prolog itself must be UTF-8-encoded.

### Dynamic Download of HTTPS Certificates

Beginning with 1.4.2, Java Web Start dynamically imports certificates in much the same way as browsers do. In order to make this work, Java Web Start now sets its own https handler, using the `java.protocol.handler.pkgs` system properties, to initialize defaults for `SSLSocketFactory` and `HostnameVerifier`. It sets the defaults with `HttpsURLConnection.setDefaultSSLSocketFactory` and `HttpsURLConnection.setDefaultHostnameVerifier`.

If your application uses those two method, make sure they are called after the Java Web Start https handler is initialized, otherwise your custom handler will be replaced by the Java Web Start default handler. You can ensure that your own customized `SSLSocketFactory` and `HostnameVerifiter` are used by doing either of the following:

1. Installing your own https handler, which will completely replace the Java Web Start https handler (for more information, see A New Era for Java Protocol Handlers);
2. Calling `HttpsURLConnection.setDefaultSSLSocketFactory` or `HttpsURLConnection.setDefaultHostnameVerifier` only after the first https url object is created, which will execute the Java Web Start https handler initialization code first.

For information on creating a download servlet see the next chapter, JnlpDownloadServlet Guide.

Copyright © 1995-2010 Sun Microsystems, Inc. All Rights Reserved. Please send comments using this Feedback page. | Java Technology