F
Oracle Implementation of Java SSL

This appendix describes the Oracle implementation of Java Secure Socket Extension (JSSE), in the following sections:

• Prerequisites
• Oracle Java SSL Features
• Oracle Java SSL Examples
• Troubleshooting Oracle Java SSL
• Oracle Java SSL API

  Note: This appendix assumes that you are familiar with the basic principles of Java socket programming and the SSL protocol.

  See Also: Java documentation from Sun Microsystems, Inc., for further information about Java SSL packages located at: http://java.sun.com/products/jsse

Prerequisites

To use the Oracle Java SSL implementation, perform the following tasks:

• Install JDK version 1.1 or later
• Ensure that the CLASSPATH environment variable includes the following jar files:
  • For JDK1.1: javax-ssl-1_1.jar, jssl-1_1.jar
  • For JDK1.2 or later: javax-ssl-1_2.jar, jssl-1_2.jar
• Add the Oracle Java SSL shared library to the shared library path for your platform:
  • For UNIX: libnjssl9.so must be included in the library path specified by the LD_LIBRARY_PATH environment variable.
  • For Windows: njssl9.dll must be included in the path specified by the PATH environment variable.
• If JSSE version 1.0.2 is in your CLASSPATH, then use jssl-1_1.jar and set the ssl.SocketFactory.provider and the ssl.ServerSocketFactory Java security properties as follows:

  ssl.SocketFactory.provider=oracle.security.ssl.OracleSSLSocketFactoryImpl
  ssl.ServerSocketFactory.provider=oracle.security.ssl.OracleSSLServerSocketFactoryImpl
  
  

• If jsse.jar or jcert.jar are installed in the Java extensions folder, then jssl-1_1.jar must also be installed in the extensions folder.

  See Also: Your operating system-specific documentation

Oracle Java SSL Features

Oracle Java SSL is a commercial-grade implementation of Java Secure Socket Extension (JSSE). In order to create a secure, fast implementation of SSL, Oracle Java SSL uses native code to improve the performance.

In addition to the functionality included in the JSSE specifications, Oracle Java SSL supports the following:

• Multiple cryptographic algorithms
• Certificate and key management by using Oracle Wallet Manager
• SSL session capabilities, including authentication, that can be used by applications built on top of Oracle Java SSL

Oracle Java SSL features are described in further detail in the following sections:

• SSL Cipher Suites Supported by Oracle Java SSL
• Certificate and Key Management with Oracle Wallet Manager
• Security-Aware Applications Support

SSL Cipher Suites Supported by Oracle Java SSL

Before data can flow through an SSL connection, both sides of the connection must negotiate common algorithms to be used for data transmission. A set of such algorithms combined to provide a mix of security features is called a cipher suite. Selecting a particular cipher suite lets the participants in an SSL connection establish the appropriate level for their communications.

Oracle Java SSL supports cipher suites with the following options:

• Key exchange of 512, 768, or 1024 bit asymmetric keys that uses the following algorithms:
  • RSA
  • Diffie-Hellman
• NULL encryption, or symmetric key encryption with 40 and 128 bit symmetric keys that uses the following algorithms:
  • RC4 stream cipher
  • DES, DES40, and 3DES-EDE, in Cipher Block Chaining (CBC) mode

    Note: With NULL encryption, SSL is only used for authentication and data integrity purposes.

• Message Authentication Code that uses MD5 or SHA1 data integrity

Certificate and Key Management with Oracle Wallet Manager

You can use Oracle Wallet Manager to generate a public/private key pair and a certificate request. A signed certificate request and the appropriate trusted certificates must be added to produce a complete Oracle wallet.

You can export a complete wallet with a certificate in Ready status, in a BASE64-formatted file, by choosing Operation > ExportWallet from the Oracle Wallet Manager menu. This file can be used to add SSL credentials in a Java SSL-based program.

If you are not using Oracle Wallet Manager, then you can manually add individual components to a file:

• Add the certificate first, followed by the private key.
• Add the certificate authority certificate and other trusted certificates subsequently.

  See Also: "Public Class: OracleSSLCredential" for information about setting the credentials in Java SSL Chapter 17, "Using Oracle Wallet Manager"

Security-Aware Applications Support

Some security-aware applications do not set trust points. In order to let these applications perform their own validation, Oracle Java SSL lets handshakes complete if no security credentials are set and a complete certificate chain is sent by the peer. This feature is useful when there is a large number of trust points stored in a database, and the application is constrained from passing all of them to the SSL layer.

Once the handshake is complete, it is possible to obtain the peer certificate chain and extract individual peer certificates. These certificates can be used for application-specific validation, such as matching the certificate's distinguished name (DN) against a user database.

Security-unaware applications that need the trust point check must ensure that trust points are set in the application.

Oracle Java SSL Examples

The examples in this section illustrate the use of Oracle Java SSL. For purposes of the examples, we created a model server and client named SSLServerExample and SSLClientExample, respectively. Together, they demonstrate some common features of Oracle Java SSL, as well as the basics of socket communication. In addition, SSLProxyClientExample demonstrates one of the possible ways to implement firewall tunnelling connections.

The complete code for each program is presented, and some of its more important sections are discussed.

Oracle Java SSL examples are described in the following sections:

• Example: SSLServerExample Program
• Example: SSLClientExample Program
• Example: SSLProxyClientExample Program

  See Also: Later sections of this appendix for detailed information about different security options that are available with this package. "Public Class: OracleSSLServerSocketFactoryImpl" for general information about socket programming. Java documentation for the java.net package, for information about sockets and socket streams.

Example: SSLServerExample Program

SSLServerExample is a simple SSL server. It uses a wallet exported from Oracle Wallet Manager to set up its security credentials. When the server is started it waits for a client to initiate a connection. After the SSL handshake is complete, the server sends a short message to the client and closes the connection.

The program contains the following code:

import oracle.security.ssl.*;
import java.net.*;
import java.io.*;
import java.util.*;
import javax.net.*;
import javax.net.ssl.*;

public class SSLServerExample 
{


private OracleSSLServerSocketFactoryImpl _socketFactory;
private OracleSSLCredential _credential;
private SSLServerSocket _svrSoc;
private void initCredential(String wltPath, String password) 

throws java.io.IOException 

{

_credential = new OracleSSLCredential();
_credential.setWallet(wltPath, password);

}

private void initSocketFactory() 

throws javax.net.ssl.SSLException

{

_socketFactory 

= (OracleSSLServerSocketFactory)SSLServerSocketFactory.getDefault();

_socketFactory.setSSLProtocolVersion(

OracleSSLProtocolVersion.SSL_Version_3_0_With_2_0_Hello);

_socketFactory.setSSLCredentials(_credential);

}

private void initServerSocket(int port) 

throws java.io.IOException

{

_svrSoc = (SSLServerSocket)_socketFactory.createServerSocket(port);
_svrSoc.setUseClientMode(false);
_svrSoc.setNeedClientAuth(false);
_svrSoc.setEnabledCipherSuites(new String[]{"SSL_RSA_WITH_RC4_128_SHA",

"SSL_RSA_WITH_RC4_128_MD5"});

}

public SSLServerExample(String wltPath, String password, int port)

throws java.io.IOException, javax.net.ssl.SSLException

{

initCredential(wltPath, password);
initSocketFactory();
initServerSocket(port);

}

public void runServer()
{

String message = "Hello! Current Server Time is " + new Date() + "\n";
Socket csocket = null;
OutputStreamWriter out = null;
try
{

csocket = _svrSoc.accept();
out = new OutputStreamWriter(csocket.getOutputStream());
out.write(message);
System.out.println("Connection Succeeded");

}
catch(IOException e)
{

System.out.println("Connection Failed");
e.printStackTrace();

}
finally
{

try
{ 
 if(out != null)
  out.close();
 if(csocket != null)
  csocket.close();
 _svrSoc.close();
}
catch(IOException e){}

}

}

public static void main(String[] argv)
{

System.getProperties().put("SSLServerSocketFactoryImplClass",

"oracle.security.ssl.OracleSSLServerSocketFactoryImpl");

try
{

SSLServerExample myServer = new SSLServerExample("mywallet.txt",
 "welcome1", 19978);
myServer.runServer();

}
catch(IOException i)
{

System.out.println("Failied to start up server");
i.printStackTrace();

}

}

}

Initializing the Credentials

SSLServerExample uses a wallet created by Oracle Wallet Manager, so the job of setting up the credential object is quite easy. To read the wallet located at (wltPath), initCredential() calls

_credential = new OracleSSLCredential();
_credential.setWallet(wltPath, password);

The private key, user certificate, certificate and trust points located in the wallet are used in the connection. An IOException is returned if an error occurs while accessing the wallet.

If you do not elect to use the wallet, then you can install the necessary security credentials manually.

Initializing the Socket Factory

To create SSL sockets, you must access the proper socket factory. For Oracle Java SSL, oracle.security.ssl.OracleSSLSocketFactoryImpl is the name of the class that implements javax.net.ServerSocketFactory. In order to make sure it is accessed correctly, set up the system properties in the main() function by using the following settings:

System.getProperties().put("SSLServerSocketFactoryImplClass","oracle.security.ss
l.OracleSSLServerSocketFactoryImpl");

Once the system properties are set, you can obtain an instance of the socket factory and customize it. In initSocketFactory(), specify the SSL protocol that the sockets created by this factory are to support, and install the security credentials to be used by all sockets created by this factory.

Initializing Server Socket

The method initServerSocket() uses the socket factory to create a new server socket that listens in server mode on the specified port:

_svrSoc = (SSLServerSocket)_socketFactory.createServerSocket(port);
_svrSoc.setUseClientMode(false);

Once the socket is created, you can change some of its attributes by modifying the following properties:

_svrSoc.setNeedClientAuth(false);
_svrSoc.setEnabledCipherSuites(new String[]{"SSL_RSA_WITH_RC4_128_SHA"
"SSL_RSA_WITH_RC4_128_MD5"});

For this example, the clients are not required to authenticate themselves to the server. However, instead of using the default enabled cipher suites, only clients that support RSA_WITH_RC4_128_SHA or SSL_RSA_WITH_RC4_128_MD5 cipher suites are allowed to connect.

Use OracleSSLServerSocketFactory.getSupportedCipherSuites() to determine which cipher suites are supported by Java SSL.

Waiting for the Connection and Sending Data

SSLServerExample waits until the client connects to the server. The method accept() blocks until a connection is established. Once the client connects, the output stream for the socket is obtained by calling getOutputStream(). This output stream is used to send information to the client. When the server has no more data to send to the client, the server closes the corresponding output stream and socket. To stop accepting connections, the server must close the corresponding server socket. The server closes the socket when it cannot accept any further connections.

Example: SSLClientExample Program

The SSLClientExample is a simple program used to connect to the SSLServerExample program by using JDK, version 1.1. The initialization of the SSLClientExample is very similar to that of the server. However, certain differences are included in this example to demonstrate some of the features of Oracle Java SSL. The explanations focus on these differences whenever appropriate. The example program contains the following code:

import oracle.security.ssl.*;
import java.net.*;
import java.io.*;
import java.util.*;
import javax.net.*;
import javax.net.ssl.*;
import javax.security.cert.*;
public class SSLClientExample 
{


protected OracleSSLSocketFactoryImpl _socketFactory;
private OracleSSLCredential _credential;
protected SSLSocket _socket;

private void initCredential(String wltPath, String password)

throws java.io.IOException

{

_credential = new OracleSSLCredential();
_credential.setWallet(wltPath, password);

}

private void initSocketFactory() 

throws javax.net.ssl.SSLException

{

_socketFactory 

= (OracleSSLSocketFactoryImpl)SSLSocketFactory.getDefault();

_socketFactory.setSSLProtocolVersion(

OracleSSLProtocolVersion.SSL_Version_3_0);

_socketFactory.setSSLCredentials(_credential);

}
private void initSocket(String host, int port) 

throws java.io.IOException

{

_socket = (SSLSocket)_socketFactory.createSocket(host, port);
_socket.setUseClientMode(true);

}
public SSLClientExample(String wltPath, String pass, String host, int port)

throws java.io.IOException, javax.net.ssl.SSLException

{

initCredential(wltPath, pass);
initSocketFactory();
initSocket(host, port);

}
public void connectSocket()
{

try
{

_socket.startHandshake();
getData();

}
catch(IOException e)
{

System.out.println("Connection Failed");
e.printStackTrace();

}
finally
{

try
{
 _socket.close();
} 
catch(IOException e){}

}

}
public void getData()
{

InputStreamReader in = null;
try
{

int ch;
SSLSession session = _socket.getSession();
System.out.println("Negotiated Cipher Suite " +
 session.getCipherSuite());
X509Certificate[] peerCerts = session.getPeerCertificateChain();
for(int i = 0; i < peerCerts.length; i++)
{
 System.out.println(peerCerts[i]);
}
System.out.println("Server Response:");
in = new InputStreamReader(_socket.getInputStream());
ch =  in.read();
while((char)ch != '\n')
{
 if(ch != -1)
 System.out.print((char)ch);
 ch=in.read();
}
System.out.println();

}
catch(IOException e)
{

System.out.println("Connection Failed");
e.printStackTrace();

}
finally
{ 

try
{ 
 if(in != null)
 in.close();
}
catch(IOException e){}

}

}
 public static void main(String[] argv)
{

System.getProperties().put("SSLSocketFactoryImplClass", 

"oracle.security.ssl.OracleSSLSocketFactoryImpl");

try
{

SSLClientExample myClient = new 
SSLClientExample("mywallet.txt","welcome1","localhost", 19978);
myClient.connectSocket();

}
catch(IOException i)
{

System.out.println("Failied to start up client");
i.printStackTrace();

}

}

}

Initializing the Credentials

The client initializes the credentials in the same way as the server. For purposes of the example, the client and the server use the same wallet. However, in production applications, the client and the server must have different security credentials. In order for an SSL connection to complete successfully it is important that the proper trusted certificates are present in the wallets.

Initializing the Socket Factory

The socket factory class used to create client sockets is similar to the one used by the server. As with the SSLServerExample program, it is necessary to set the system properties to obtain the correct socket factory before configuring it in initSocketFactory(). The correct socket factory is set in main()by using the following syntax:

System.getProperties().put("SSLSocketFactoryImplClass",
"oracle.security.ssl.OracleSSLSocketFactoryImpl");

Initializing and Connecting the Client Socket

Client sockets are created by the socket factory just as server sockets are created by the server socket factory. However, to connect the client socket to a specific server, you must supply the server's name and the port number at creation. In addition, ensure that the socket connects in client mode by specifying the following settings:

_socket = (SSLSocket)_socketFactory.createSocket(host, port);
_socket.setUseClientMode(true);

After the socket is created, it can connect to the server using:

_socket.startHandshake();

Viewing Peer Credentials

After the socket connects to the server, information about the connection can be accessed. The information is stored in the OracleSSLSession class, an instance of which can be obtained by using _socket.getSession().

In this example, the cipher suite negotiated between the client and the server as well as the security credentials of the server is printed. This information can be used by security-aware applications to determine whether it should trust the connection. For example, most browsers check to confirm that the common name in the server certificate matches the URL that was accessed, and they display a warning if it does not. However, this check is not required by the SSL protocol.

Receiving Data

Receiving and sending data through an SSL socket is no different than receiving data through any other socket. In this example, the socket's input stream is accessed and read until an end-of-line character occurs.

Example: SSLProxyClientExample Program

This example uses firewall tunneling to establish a secure connection to the server. Note that this program may not work for all firewalls. For example, some firewalls do not permit a connection to non-standard ports, such as port 19978 that is used here. In this case you have to set up a secure server on port 443 and modify the client appropriately.

import oracle.security.ssl.*;
import java.net.*;
import java.io.*;
import java.util.*;
import javax.net.*;
import javax.net.ssl.*;
import javax.security.cert.*;
public class SSLProxyClientExample extends SSLClientExample 
{


private String _proxyName;
private int _proxyPort;
 protected void initSocket(String host, int port) 

throws java.io.IOException

{

final String connString = "CONNECT" + host + ":" + port + 

" HTTP/1.0 \n" + "User-Agent: Oracle Proxy Enabled SSL Socket\n\n";

Socket normalSocket = new Socket(_proxyName, _proxyPort);
OutputStreamWriter out 

= new OutputStreamWriter(normalSocket.getOutputStream());

out.write(connString, 0, connString.length());
_socket = (SSLSocket)_socketFactory.createSocket(normalSocket);

}
public SSLProxyClientExample(String wltPath, String password,String host,
                            int port, String proxyName, int proxyPort)

throws java.io.IOException, javax.net.ssl.SSLException

{

super(wltPath, password, host, port);
_proxyName = proxyName;
_proxyPort = proxyPort;

}
public static void main(String[] argv)
{

System.getProperties().put("SSLSocketFactoryImplClass", 
"oracle.security.ssl.OracleSSLSocketFactory");
try{

SSLClientExample myClient 
 = new SSLProxyClientExample("mywallet.txt", "welcome1",
 "localhost", 19978,  "www-proxy", 80);
myClient.connectSocket();

}
catch(IOException i)
{

System.out.println("Failed to start up client");
i.printStackTrace();

}

}

}

Note: If you use JDK, version 1.2, then change import javax.security.cert.*; to import java.security.cert.*;

_socketFactory.createSocket(normalSocket)

public OracleSSLCredential()

public void addTrustedCert(java.lang.String b64TrustedCert)

public void addTrustedCert(byte[] trustedCert)

public void setPrivateKey(java.lang.String b64PvtKey,java.lang.String password)

public void setPrivateKey(byte[] pvtKey, java.lang.String password)

public void addCertChain(java.lang.String b64certChainCert)

public void addCertChain(byte[] certChainCert)

public void setWallet(java.lang.String wltPath, java.lang.String password) 
     throws java.io.IOException

public static final int SSL_Version_Undetermined

public static final int SSL_Version_3_0_With_2_0_Hello

public static final int SSL_Version_3_0_Only

public static final int SSL_Version_2_0

public static final int SSL_Version_3_0

public OracleSSLServerSocketFactoryImpl()

System.getProperties().put("SSLServerSocketFactoryImplClass",
 "oracle.security.ssl.OracleSSLServerSocketFactoryImpl");
SSLServerSocketFactory factory = OracleSSLServerSocketFactoryImpl.getDefault();

public void setSSLCredentials(OracleSSLCredentialsslCredential)throws 
   javax.net.ssl.SSLException

public void setSSLProtocolVersion(int version)throws javax.net.ssl.SSLException

public byte[][] getPeerRawCertificateChain() throws 
javax.net.ssl.SSLPeerUnverifiedException

public java.lang.String getNegotiatedProtocolVersion()

public OracleSSLSocketFactoryImpl()

System.getProperties().put("SSLSocketFactoryImplClass",
 "oracle.security.ssl.OracleSSLSocketFactoryImpl");
SSLSocketFactory factory = OracleSSLSocketFactoryImpl.getDefault();

public java.net.Socket createSocket(java.net.Socket socket) throws 
   java.io.IOException

public void setSSLCredentials(OracleSSLCredentialsslCredential) throws 
   javax.net.ssl.SSLException

public void setSSLProtocolVersion(int version) throws javax.net.ssl.SSLException

public void setTrustManagers(OracleX509TrustManagerInterface[] tm)

public OracleX509TrustManagerInterface[] getTrustManagers()

public abstract void checkClientTrusted(X509Certificate[] chain)
 throws CertificateException

public abstract void checkServerTrusted(X509Certificate[] chain) throws 
   CertificateException

public abstract X509Certificate[] getAcceptedIssuers()