11 SSL Support

The Secure Sockets Layer (SSL) protocol and the Transport Layer Security (TLS) protocol help protect the privacy and integrity of data that is transported over a network, such as the Internet. This chapter provides an overview of the SSL protocol and discusses its support in the JDBC Thin driver.

This chapter consists of the following sections:

Overview of SSL
Java Version of SSL
SSL in JDBC

Overview of SSL

SSL is a widely used protocol that provides secure communication over a network. It uses several different cryptographic processes to ensure that the data sent over the network is secure. It provides a secure enhancement to the standard TCP/IP protocol, which is used for Internet communication. SSL uses public key cryptography to provide authentication. SSL also uses secret key cryptography and digital signatures to ensure privacy and integrity of data.

Data communication between a client and a server over an SSL enabled network begins with an exchange of information called SSL handshake. The SSL session first decides on a cipher suite, which is a set of cryptographic algorithms and key sizes, that will be used by the client and the server. Optionally, the client then authenticates the server to ensure that the server represents the entity with which the client wants to interact. The server too can authenticate the client before exchanging data. After authenticating, the client and server exchange data. The data is encrypted using the already agreed upon cryptographic hash function.

Java Version of SSL

The Java Secure Socket Extension (JSSE) enables secure Internet communication by providing a framework and an implementation for a Java version of the SSL and TLS protocols. It provides support for data encryption, server authentication, optional client authentication, and message integrity. JSSE abstracts the complex security algorithms and handshaking mechanisms and simplifies application development by providing a building block for application developers, which they can directly integrate into their applications. JSSE is integrated into Java Development Kit (JDK) 1.4 and supports SSL version 2.0 and 3.0.

The JSSE standard application programming interface (API) is available in the javax.net, javax.net.ssl, and javax.security.cert packages. These packages provide classes for creating sockets, server sockets, SSL sockets, and SSL server sockets. These classes also enable you to configure the sockets. The packages also provide a class for secure HTTP connections, a public key certificate API compatible with JDK1.1-based platforms, and interfaces for key and trust managers.

SSL in JDBC

Oracle Database 10g release 2 (10.2) implements JSSE to provide secure communication between client and server. The JDBC Thin driver makes use of the JSSE APIs, abstracting the complexity of creating SSL enabled connections. The application developers are not exposed to the overhead involved in using the JSSE APIs.

Note:

SSL support is only available with JDK 1.4 and later.

Oracle Database 10g provides the following sets of properties that can be used to create SSL enabled connection between client and server:

Non-JSSE Related Properties
JSSE Related Properties
Enabling SSL

Note:

A client can choose to establish either an SSL connection or a non-SSL connection.

Non-JSSE Related Properties

Oracle Database 10g defines certain properties, which are non-JSSE specific, to configure an SSL connection. These properties are available with both the JDBC OCI and Thin drivers. The following properties are defined:

oracle.net.ssl_version

This property is used to set the SSL version to be used by the JDBC driver. It takes a String value. The value specified should be supported by both the SSL implementation and the server. The default value of the property is ANY. In the case of the default value, first TLS 1.0 is tried followed by SSL 3.0 and then SSL 2.0.
oracle.net.wallet_location

This property is used to specify the location of the wallet. The wallet contains the certificates and keys used by SSL. This property takes a String value that identifies a valid location of the wallet. It does not have any default value.
Note:
If this property is set, then it overrides the value of the javax.net.ssl.keyStore JSSE property and the following values will be used for other JSSE properties:
```
javax.net.ssl.keyStorePassword = null
javax.net.ssl.keyStoreType = SSO
```
The value of javax.net.ssl.trustStore will be same as that of javax.net.ssl.keyStore.

Only METHOD=file is supported in Oracle Database 10g release 2 (10.2).
oracle.net.ssl_cipher_suites

This property is used to specify a cipher suite that will be used by the SSL connection. It takes a String value that specifies the algorithms and the key sizes for data integrity and encryption, which are separated by commas. The cipher suite specified should be supported by both the SSL implementation and the server. This property does not have any default value.
oracle.net.ssl_server_dn_match

This property is used to force the distinguished name (dn) of the server to match with its service name. It takes a String value. The permitted values are TRUE, FALSE, YES, NO, ON, and OFF. The values TRUE, YES, and ON force the dn of the server to match with its service name. The default value is FALSE.

Note:

The property values are not case-sensitive. The properties are set as key/value pairs using a java.util.Properties object.

Example

A sample code illustrating the use of the non-JSSE properties is as follows:

//import packages
import java.sql.*;
import oracle.jdbc.*;
import oracle.jdbc.pool.OracleDataSource;

//specify the properties object
java.util.Properties info = new java.util.Properties();
...
// Set the SSL version
info.put ("oracle.net.ssl_version","3.0");

// Set the wallet location
info.put ("oracle.net.wallet_location", "(SOURCE=(METHOD=file)(METHOD_DATA=(DIRECTORY=directory)))");

// Set the cipher suite
info.put("oracle.net.ssl_cipher_suites","SSL_DH_DSS_WITH_DES_CBC_SHA");

// Force dn to match service name
info.put("oracle.net.ssl_serevr_dn_match","TRUE");
...

//specify the datasource object 
OracleDataSource ods = new OracleDataSource();
ods.setURL("jdbc:oracle:thin:@//myhost:1521/orcl");
ods.setUser("scott");
ods.setPassword("tiger");
ods.setConnectionProperties(info);
...

JSSE Related Properties

Oracle Database 10g supports certain properties that are defined by the JSSE framework for configuring SSL. These properties are available only with the JDBC Thin driver. Any of these properties can be set on a per-connection basis. When a value is set for any of these properties, the corresponding system or security property is overridden. The following properties are defined:

javax.net.ssl.keyStore

This property is used to specify the location of the key store. A key store is a database of key material that are used for various purposes, including authentication and data integrity. This property takes a String value. Any valid key store location can be assigned to this property. The default value is NULL.
javax.net.ssl.keyStoreType

This property denotes the type of the key store. It takes a String value. Any valid key store type supported by SSL can be assigned to this property. The default value is KeyStore.getDefaultValue().
javax.net.ssl.keyStorePassword

This property specifies the password of the key store. This password value is used to check the integrity of the data in the key store before accessing it. This property takes a String value. It does not have a default value.
javax.net.ssl.trustStore

This property is used to specify the location of the trust store. A trust store is a key store that is used when making decisions about which clients and servers can be trusted. The property takes a String value that specifies a valid trust store location. The default value is jssecacerts, if available, or cacerts.
javax.net.ssl.trustStoreType

This property denotes the type of the trust store. It takes a String value. Any valid trust store type supported by SSL can be assigned to this property. The default value is TrustStore.getDefaultValue().
javax.net.ssl.trustStorePassword

This property is used to set the password for the trust store. The trust store password is used to check the integrity of the data in the trust store before accessing it. The property takes a String value. It does not have any default value.

Example

A sample code illustrating the use of the JSSE properties is as follows:

//import packages
import java.sql.*;
import oracle.jdbc.*;
import oracle.jdbc.pool.OracleDataSource;

//specify the properties object
java.util.Properties info = new java.util.Properties();
...
// Set the key store, type, and password
info.put ("javax.net.ssl.keyStore","file_location");
info.put ("javax.net.ssl.keyStoreType","JKS");
info.put ("javax.net.ssl.keyStorePassword","password");

// Set the trust store, type, and password
info.put("javax.net.ssl.trustStore","location");
info.put("javax.net.ssl.trustStoreType","JKS");
info.put("javax.net.ssl.trustStorePassword","password");
...

//specify the datasource object 
OracleDataSource ods = new OracleDataSource();
ods.setURL("jdbc:oracle:thin:@//myhost:1521/orcl");
ods.setUser("scott");
ods.setPassword("tiger");
ods.setConnectionProperties(info);
...

Enabling SSL

An Oracle JDBC user has to specify tcps and a DN. The following is an example:

(DESCRIPTION=
  (ADDRESS_LIST=
    (ADDRESS= (PROTOCOL = tcps) (HOST = finance_server) (PORT = 1521)))
(CONNECT_DATA=
  (SERVICE_NAME= Finance.us.acme.com))
(SECURITY=
  (SSL_SERVER_CERT_DN="cn=finance,cn=OracleContext,c=us,o=acme"))