14
Oracle HTTPS for Client Connections

This chapter describes the Oracle9iAS Containers for J2EE (OC4J) implementation of HTTPS that provides SSL functionality to client HTTP connections. The following topics are included:

• Prerequisites

• About Oracle HTTPS

• Overview of Oracle HTTPS Features

• Specifying Default System Properties

• Oracle HTTPS APIs

• Oracle HTTPS Example

Prerequisites

Please perform the following tasks before you attempt to use Oracle HTTPS:

• Install JDK version 1.2 or later.

• Ensure that the CLASSPATH environment variable includes the following jar files:
  • javax-ssl-1_1.jar

  • jssl-1_1.jar

• Add the Java SSL shared library to the shared library path:
  • For UNIX: libnjss18.so must be included in the library path specified by the LD_LIBRARY_PATH environment variable.

  • For Windows NT: njss18.dll must be included in the path specified by the PATH environment variable.

    See Also: Platform-specific documentation.

• Set the following Java security property so Oracle HTTPS can use Oracle Java SSL sockets:

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

  See Also: Sun Microsystems, Inc., JSSE (Java Secure Socket Extension) documentation for more information about setting system properties at: http://www.java.sun.com

Audience

To effectively use Oracle HTTPS, application developers should understand the basics of Java sockets programming and JSSE (Java Secure Socket Extension). They should also be familiar with the Sun Microsystems, Inc., java.net package, which supports network programming and the open source HTTPClient package that Oracle HTTPS is based on.

In addition, it is important for developers who use Oracle HTTPS to understand the fundamental concepts of public key infrastructure digital certificates and keys.

About Oracle HTTPS

HTTPS is vital to securing client-server interactions. For many server applications HTTPS is handled by the Web server. However, any application that acts as a client, such as servlets that initiate connections to other Web servers, needs its own HTTPS implementation to make requests and to receive information securely from the server. Java application developers who are familiar with either the HTTP package, HTTPClient, or who are familiar with the Sun Microsystems, Inc., java.net package can easily use Oracle HTTPS to secure client interactions with a server.

Oracle HTTPS extends the HTTPConnection class of the open source HTTPClient package, which provides a complete HTTP client library. To support client HTTPS connections, several methods have been added to the HTTPConnection class that use the Oracle Java SSL class, OracleSSLCredential.

The following sections describe these components in further detail:

• HTTPConnection Class

• OracleSSLCredential Class

  See Also: "Oracle HTTPS APIs" for a description of the methods that have been added to the HTTPConnection class.

HTTPConnection Class

The HTTPConnection class is used to create new connections that use HTTP and related protocols such as HTTPS. To provide support for PKI (Public Key Infrastructure) digital certificates and wallets, the methods described in "Oracle HTTPS APIs" have been added to this class.

http://www.innovation.ch/java/HTTPClient

OracleSSLCredential Class

Security credentials are used to authenticate the server and the client to each other. Oracle HTTPS uses the Oracle Java SSL package, OracleSSLCredential, to load user certificates, trusted certificates (trust points), and private keys from base64 or der encoded certificates.

The API for Oracle Java SSL requires that security credentials be passed to the HTTP connection before the connection is established. The OracleSSLCredential class is used to store these security credentials. Typically, a wallet generated by Oracle Wallet Manager is used to populate the OracleSSLCredential object. Alternatively, individual certificates can be added by using an OracleSSLCredential class API. After the credentials are complete, they are passed to the connection with the setCredentials method.

Overview of Oracle HTTPS Features

Oracle HTTPS, based on the open source HTTP package, HTTPClient 3.2, supports HTTP 1.0 and HTTP 1.1 connections between a client and a server. To provide SSL functionality, new methods have been added to the HTTPConnection class of this package. These methods are used in conjunction with Oracle Java SSL to support cipher suite selection, security credential management with Oracle Wallet Manager, security-aware applications, and other features that are described in the following sections.

In addition to the functionality included in the HTTPClient package, Oracle HTTPS supports the following:

• Multiple cryptographic algorithms

• Certificate and key management with Oracle Wallet Manager

• Limited support for the java.net.URL framework

In addition, Oracle HTTPS uses the HTTPClient package to support

• HTTP tunneling through proxies

• HTTP proxy authentication

The following sections describe Oracle HTTPS features in detail:

• SSL Cipher Suites Supported by Oracle HTTPS

• Certificate and Key Management with Oracle Wallet Manager

• Access Information About Established SSL Connections

• Security-Aware Applications Support

• java.net.URL Framework Support

SSL Cipher Suites Supported by Oracle HTTPS

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 HTTPS supports cipher suites with the following options:

• Key exchange of 512, 768, or 1024 bit asymmetric keys using the following algorithms:
  • RSA

  • Diffie-Hellman

• NULL encryption, or symmetric key encryption with 40 and 128 bit symmetric keys using 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 using MD5 or SHA1 data integrity.

Table 14-1 lists all of the cipher suites that are supported by Oracle HTTPS.

Table 14-1 Cipher Suites Supported by Oracle HTTPS  

Certificate and Key Management with Oracle Wallet Manager

You can use Oracle Wallet Manager to generate public/private key pairs and certificate requests. 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, using the menu option Operation ->ExportWallet. This file can be used to add SSL credentials in a Java SSL-based program.

Access Information About Established SSL Connections

Users can access information about established SSL connections using the getSSLSession method of Oracle HTTPS. After a connection is established, users can retrieve the cipher suite used for the connection, the peer certificate chain, and other information about the current connection.

Security-Aware Applications Support

Oracle HTTPS uses Oracle Java SSL to provide security-aware applications support. When security-aware applications do not set trust points, Oracle Java SSL allows them to perform their own validation letting the handshake complete successfully only if a complete certificate chain is sent by the peer. With Oracle HTTPS, the connection completes successfully when no trust points are set if the server sends the client a complete certificate chain that starts from the root CA (Certifying Authority) and ends with the server certificate. 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.

After the handshake is complete, the application must obtain the SSL session information and perform any additional validation for the connection.

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

java.net.URL Framework Support

The HTTPClient package provides basic support for the java.net.URL framework with the HTTPClient.HttpUrlConnection class. However, many of the Oracle HTTPS features are supported through system properties only. Features that are only supported through system properties are

• cipher suites selection option

• confidentiality only option

• server authentication option

• mutual authentication option

• security credential management with Oracle Wallet Manager

java.protocol.handler=HTTPClient

Specifying Default System Properties

For many users of HTTPS it is desirable to specify some default properties in a non-programmatic way. The best way to accomplish this is through Java system properties which are accessible through the java.lang.System class. These properties are the only way for users of the java.net.URL framework to set security credential information. Oracle HTTPS recognizes the following properties:

• javax.net.ssl.KeyStore

• javax.net.ssl.KeyStorePassword

• Oracle.ssl.defaultCipherSuites

The following sections describe how to set these properties.

 http://www.java.sun.com

javax.net.ssl.KeyStore

This property can be set to point to the text wallet file exported from Oracle Wallet Manager that contains the credentials that are to be used for a specific connection. For example:

javax.net.ssl.KeyStore=/etc/ORACLE/WALLETS/Default/default.txt

where default.txt is name of the text wallet file that contains the credentials.

If no other credentials have been set for the HTTPS connection, then the file set by this property is opened when a handshake first occurs. If any errors occur while reading this file, then the connection fails and an IOException is thrown.

javax.net.ssl.KeyStorePassword

This property can be set to the password that is necessary to open the wallet file. For example:

javax.net.ssl.KeyStorePassword=welcome1

where welcome1 is the password that is necessary to open the wallet file.

Potential Security Risk with Storing Passwords in System Properties

Storing the wallet file password as a Java system property can result in a security risk in some environments. To avoid this risk, use one of the following alternatives:

• If mutual authentication is not required for the application, then a text wallet that contains no private key should be used instead. To open these wallets, no password is necessary.

• If a password is necessary, then do not store it in a cleartext file. Instead, load the property dynamically before the HTTPConnection is started by using System.setProperty(). Unset the property after the handshake is completed.

Oracle.ssl.defaultCipherSuites

This property can be set to a comma-delimited list of cipher suites. For example:

Oracle.ssl.defaultCipherSuites=

SSL_RSA_WITH_DES_CBC_SHA,\
SSL_RSA_EXPORT_WITH_RC4_40_MD5,\
SSL_RSA_WITH_RC4_128_MD5

The cipher suites that you set this property to are used as the default cipher suites for new HTTPS connections.

Oracle HTTPS APIs

This section describes the public classes and interfaces used by Oracle HTTPS. Oracle HTTPS uses the Oracle Java SSL class, OracleSSLCredential, and it extends the HTTPConnection class of the open source HTTPClient package. The following sections describe these packages:

• Public Class: HTTPConnection

• Public Class: OracleSSLCredential

Public Class: HTTPConnection

Because Oracle HTTPS extends the HTTPConnection class, only the methods that are added to that package are described in the following:

public void connect()

Initiates a connection with the host, but does not perform any data transfer.

public String[] getSSLEnabledCipherSuites()

Returns a list of cipher suites enabled for this connection.

public javax.net.ssl.SSLSession getSSLSession()

Returns an SSLSession containing the information about the current connection.

public javax.net.ssl.SSLSocketFactory getSSLSocketFactory()

Returns the SSLSocketFactory used by the HTTPConnection to create SSLSockets.

public oracle.security.ssl.OracleSSLCredential getSSLCredential()

Returns the SSL credentials used by this connection.

public void setSSLCredential (oracle.security.ssl.OracleSSLCredential)

Sets the authentication context for the connection.

Parameters: credential - Authentication context contains the private key, certificate chains, and trusted certificates that are to be used in the SSL connection.

public void setSSLEnabledCipherSuites(String[] suites) throws IllegalArgumentException

Controls which particular cipher suites are enabled for use on this connection. The cipher suites must have been listed by SSLSocketFactory.getSupportedCipherSuites() as being supported. The method throws an IllegalArgumentException when one of the ciphers named by the parameter is not supported.

Parameters: suites - List of cipher suites.

Public Class: OracleSSLCredential

This public class extends java.lang.Object.

Credentials are used to authenticate the server and the client to each other. OracleSSLCredential is used to load user certificates, trusted certificates (trust points), and private keys from base64 or der encoded certificates.

Constructor

public OracleSSLCredential()

Creates an empty OracleSSLCredential. An empty credential lets the socket connect to any peer that sends a complete certificate chain during the handshake.

Methods

public void addTrustedCert(java.lang.String b64TrustedCert)

Adds a trusted certificate to the credential.

Parameters: b64TrustedCert - A Base64 encoded X509 certificate.

public void addTrustedCert(byte[] trustedCert)

Adds a trusted certificate to the credential.

Parameters: trustedCert - A der encoded X509 trusted certificate.

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

Adds a private key to the credential.

Parameters: b64PvtKey - A Base64 encoded X509 Private Key

password - The password needed to decipher the private key.

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

Adds a private key to the credential.

Parameters: b64PvtKey - A der encoded X509 Private Key

password - The password needed to decipher the private key.

public void addCertChain(java.lang.String b64certChainCert)

Adds a certificate to the certificate chain. The certificate chain is sent along with the user certificate during the SSL handshake. It is used by the peer to verify the user certificate. The first certificate added to the certificate chain must be the Root CA certificate. Each subsequent certificate added must be signed by its immediate predecessor.

Parameters: b64certChainCert - A Base64 encoded X509 certificate.

public void addCertChain(byte[] certChainCert)

Adds a certificate to the certificate chain.

Parameters: certChainCert - A der encoded X509 certificate.

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

If Oracle Wallet Manager is used to create a wallet, the wallet can be exported in text format and used by JavaSSL. The text file must contain the user certificate, followed by the private key, the certificate chain, and any other trusted certificates. The method throws a java.io.IOException if the wallet cannot be opened.

Parameters: wltPath - The pathname of the wallet

password - The password needed to decrypt the private key

Oracle HTTPS Example

The following is a simple program that uses Oracle HTTPS to connect to a Web server, send a GET request, and fetch a Web page. The complete code for this program is presented here followed by sections that explain how Oracle HTTPS is used to set up secure connections.

import HTTPClient.HTTPConnection;
import HTTPClient.HTTPResponse;
import oracle.security.ssl.OracleSSLCredential;
import java.io.IOException;

public class HTTPSConnectionExample
{

public static void main(String[] args)
{


if(args.length < 4)
{


System.out.println(
"Usage: java HTTPSConnectionTest [host] [port] " +
"[wallet] [password]");
System.exit(-1);


}

String hostname = args[0].toLowerCase();
int port = Integer.decode(args[1]).intValue();
String walletPath = args[2];
String password = args[3];

HTTPConnection httpsConnection = null; 
OracleSSLCredential credential = null;

try
{


httpsConnection = new HTTPConnection("https", hostname, port);


}
catch(IOException e)
{


System.out.println("HTTPS Protocol not supported");
System.exit(-1);


}

try
{


credential = new OracleSSLCredential();
credential.setWallet(walletPath, password);


}
catch(IOException e)
{


System.out.println("Could not open wallet");
System.exit(-1);


}
httpsConnection.setSSLCredential(credential);

try
{


httpsConnection.connect();


}
catch (IOException e)
{ 


System.out.println("Could not establish connection");
e.printStackTrace();
System.exit(-1);


}

javax.security.cert.X509Certificate[] peerCerts = null;
try
{


peerCerts =

  (httpsConnection.getSSLSession()).getPeerCertificateChain();


}
catch(javax.net.ssl.SSLPeerUnverifiedException e)
{ 


System.err.println("Unable to obtain peer credentials");
System.exit(-1);


}

String peerCertDN = 

  peerCerts[peerCerts.length -1].getSubjectDN().getName();
peerCertDN = peerCertDN.toLowerCase();
if(peerCertDN.lastIndexOf("cn="+hostname) == -1)
{


System.out.println("Certificate for " + hostname + " is issued to "

  + peerCertDN); 
System.out.println("Aborting connection");
System.exit(-1);


}

try
{


HTTPResponse rsp = httpsConnection.Get("/");
System.out.println("Server Response: ");
System.out.println(rsp); 


}
catch(Exception e)
{


System.out.println("Exception occured during Get");
e.printStackTrace();
System.exit(-1);


}


}

}

Initializing SSL Credentials

This program example uses a wallet created by Oracle Wallet Manager to set up credential information. First the credentials are created and the wallet is loaded using

credential = new OracleSSLCredential();
credential.setWallet(walletPath, password);

After the credentials are created, they are passed to HTTPSConnection using

httpsConnection.setSSLCredential(credential);

The private key, user certificate, and trust points located in the wallet can now be used for the connection.

Verifying Connection Information

Although SSL verifies that the certificate chain presented by the server is valid and contains at least one certificate trusted by the client, that does not prevent impersonation by malicious third parties. An HTTPS standard that addresses this problem requires that HTTPS servers have certificates issued to their hostname. Then it is the responsibility of the client to perform this validation after the SSL connection is established.

To perform this validation in this sample program, HTTPSConnectionExample establishes a connection to the server without transferring any data using

httpsConnection.connect();

After the connection is established, the connection information, in this case the server certificate chain, is obtained with

peerCerts = (httpsConnection.getSSLSession()).getPeerCertificateChain();

Finally the server certificate's common name is obtained with

String peerCertDN = peerCerts[peerCerts.length -1].getSubjectDN().getName();
peerCertDN = peerCertDN.toLowerCase();

If the certificate name is not the same as the host name used to connect to the server, then the connection is aborted with

if(peerCertDN.lastIndexOf("cn="+hostname) == -1)
{

System.out.println("Certificate for " + hostname + " is issued to " +


peerCertDN);


System.out.println("Aborting connection");
System.exit(-1);

}

Transferring Data

It is important to verify the connection information before data is transferred from the client or from the server. The data transfer is performed in the same way for HTTPS as it is for HTTP. In this sample program a GET request is made to the server using

HTTPResponse rsp = httpsConnection.Get("/");