Chapter 5 Using SSL in Java Clients

Using Java Secure Socket Extension classes

The Java Secure Socket Extension (JSSE) is a set of Java packages that implements SSL and Transport Layer Security, which enables data encryption, server authentication, message integrity, and client authentication. JSSE is a client-side feature, which can be used with EAServer when it has been configured for SSL communication. For more information on SSL, see Chapter 12, "Managing Keys and Certificates".

Setting up your JSSE environment

Download and install the JSSE according to the documentation on the Java Web page . The basic steps are:
- Copy the JSSE JAR files to the JDK/jre/lib/ext directory.
- Edit the JDK/jre/lib/security/java.security file, and add this line:
```
security.provider.2=com.sun.net.ssl.internal.ssl.Provider
```
From the Sun documentation, note the following:
- JSSE 1.0.2 requires JDK 1.2.2 or higher.
- JRE 1.3.1_02 includes the Java plug-in HTML Converter 1.3.1_02, which works best with JDK 1.3.
- JDK/JRE 1.3 or higher is recommended to run HTML applets.
- The Java plug-in HTML Converter is recommended for HTML applet clients.
Download and install the Java Plug-in HTML Converter, either version 1.3.1 or 1.4.

If you install version 1.3.1:
1. Download and install JSSE 1.0.2 in the JDK 1.3.1 JDK/jre/lib/ext subdirectory.
2. Set up JDK/jre/lib/security/java.security according to the JSSE 1.0.2 directions.
The JSSE Samples Web page includes samples that create clients using JSSE. Verify that the samples compile and run with your JDK. You must be able to use the Java samples to request the Web page http://www.verisign.com.
Start EAServer and connect using Security Manager.
In the User Certificates folder, highlight the Sample 1 Test ID certificate, and select File | Certificate Info. Confirm that the Sample1 Test ID certificate is valid; that is, that the current date falls between the certificate's Not Valid Before and Not Valid After dates.
From the User Certificates folder, export Sample1 Test ID as a Binary Encoded X509 Certificate (*.crt). For example, save to a file named eas.crt.
Using the Java keytool, import the eas.crt file; for example:
```
keytool -import -file eas.crt -keystore /JDK/jre/lib/security/ 
[cacerts | jssecacerts] -trustcacerts
```
To simplify things, use the default certificate store cacerts; the password is "changeit".
To run a JSSE client application; for example, ClientApp :
1. Create a ClientApp.bat file with these lines:
```
set classpath=%JAGUAR%\java\lib\easclient.jar; \
    %JAGUAR%\java\lib\easj2ee.jar;%classpath%
java -Djava.protocol.handler.pkgs=
   com.sun.net.ssl.internal.www.protocol ClientApp
```
2. Run ClientApp.bat.
If you do not have a Web proxy, remove the Web proxy settings from your client, and enter the server information; for example:
```
iiops://localhost:9001, or
iiops://<host_name>:9001
```
The following steps apply only to HTML applets.
Remove these client ORB properties from your HTML applet client, if appropriate:
- com.sybase.CORBA.WebProxyHost=localhost
- com.sybase.CORBA.WebProxyPort=80
- com.sybase.CORBA.LogFile=.\iiop.log
To access your Web page from a Web browser, enter:
```
http://<host_name>:8080/jssehtml/yourAppClient.html
```
Where yourAppClient.html is your HTML applet client.
In the applet, enter iiops://<host_name>:9001 as the connection parameter, and click Connect.

Sybase recommends using a Web browser that supports the Java Plug-in 1.3.1 or higher and the Java Plug-in Converter 1.3.1 or higher

Configuring ORB settings

Direct IIOP connections using JSSE are not supported.

Tunnelling IIOP through HTTPS (JSSE socket) using HTTP GET requests

IIOP is contained within the HTTP packets.

Set the client URL to iiops://<host_name>:9001.
Set these client ORB properties:
Property Vale

org.omg.CORBA.ORBClass com.sybase.CORBA.ORB

com.sybase.CORBA.https true

com.sybase.CORBA.useJSSE true

com.sybase.CORBA.forceSSL true

Tunnelling IIOP through HTTPS (JSSE socket) using HTTP POST requests

IIOP is contained within the HTTP packets.

Set the client URL to iiops://<host_name>:9001
Set these client ORB properties:
Property Vale

org.omg.CORBA.ORBClass com.sybase.CORBA.ORB

com.sybase.CORBA.https true

com.sybase.CORBA.useJSSE true

com.sybase.CORBA.forceSSL true

com.sybase.CORBA.HttpUsePost true

Tunnelling IIOP through an HTTPS connect (JSSE socket) using HTTP GET requests

IIOP is contained within the HTTP packets.

Set the client URL to iiops://<host_name>:9001.

Set these client ORB properties:

Property	Vale
org.omg.CORBA.ORBClass	com.sybase.CORBA.ORB
com.sybase.CORBA.https	true
com.sybase.CORBA.WebProxyHost	<web_proxy_host_name>
com.sybase.CORBA.WebProxyPort	<web_proxy_port>
com.sybase.CORBA.useJSSE	true
com.sybase.CORBA.forceSSL	true

Tunnelling IIOP through an HTTPS connect (JSSE socket) using HTTP POST requests

IIOP is contained within the HTTP packets.

Set the client URL to iiops://<host_name>:9001.

Set these client ORB properties:

Property	Vale
org.omg.CORBA.ORBClass	com.sybase.CORBA.ORB
com.sybase.CORBA.https	true
com.sybase.CORBA.HttpUsePost	true
com.sybase.CORBA.WebProxyHost	<web_proxy_host_name>
com.sybase.CORBA.WebProxyPort	<web_proxy_port>
com.sybase.CORBA.useJSSE	true
com.sybase.CORBA.forceSSL	true

The first time you connect may take a while because JSSE goes through an SSL authentication process.

Using an unsigned JAR

When using an unsigned JAR, your code runs with the default Security Manager plug-in, which is fairly restrictive. To improve performance, you can edit Java's default security policy file using the instructions in Sun's security documentation. To enable EAServer's ORB to work in an unsigned environment:

You must grant the ORB permission to read the proxy host settings, using one of these methods:

permission java.util.PropertyPermission "*", "read"

permission java.util.PropertyPermission "javaplugin.proxy.config.*", "read"

The ORB may require socket connect permissions to connect to a proxy server.
If you are using the sample test certificate generated by EAServer, the EAServer certificate authority must be installed. You can do this in either the cacerts or the jssecacerts keystore using this syntax:
```
keytool -import -file <file_name> -keystore [cacerts | jssecacerts]
```
The password for the cacerts keystore is "changeit".

With a signed applet, you do not need to set permissions at the plug-in level. A signed JAR file describes the type of permissions it requires.

Sample security file

You can find a sample JDK 1.3 security file in jdk13/jre/lib/security/java.security.

Possible solutions for JSEE issues

Cannot load applet

If you cannot load an HTML applet from your Web browser:

In the Tools | Internet Options dialog box:
- On the Connections tab, select Settings, then deselect Use a Proxy Server. Or, if you use a proxy server, verify the information is valid.
- On the Advanced tab, under Browsing, select Browse in a New Process.
In the Control Panel, double-click Java Plug-in 1.3.1_02. In the Java Plug-in Control Panel:
- On the Basic tab, select Enable Java plug-in and Show Java Console.
- On the Proxies tab, either select Use Browser Settings, or verify the Proxy Settings.
- Verify settings on the other tabs.
Shut down all Web browser sessions.
Close all Java console sessions; for example, from the Java Plug-in.
Restart your Web browser.
Delete all your temporary and cache files.
Reload the HTML applet page.

Debugging

If necessary, use the Java Plug-in console for debugging; set to debug level 5. If you reset the debug level, refresh the HTML applet.