JDBC Client-Side Security Features

This section discusses support in the Oracle JDBC OCI and Thin drivers for login authentication, data encryption, and data integrity--particularly with respect to features of the Oracle Advanced Security option.

Oracle Advanced Security, previously known as the "Advanced Networking Option" (ANO) or "Advanced Security Option" (ASO), includes features to support data encryption, data integrity, third-party authentication, and authorizations. Oracle JDBC supports most of these features; however, the JDBC Thin driver must be considered separately from the JDBC OCI driver.

Note: This discussion is not relevant to the server-side internal driver, given that all communication through that driver is completely internal to the server.

JDBC Support for Oracle Advanced Security

Both the JDBC OCI drivers and the JDBC Thin driver support at least some of the features of Oracle Advanced Security. If you are using one of the OCI drivers, you can set relevant parameters in the same way that you would in any thick-client setting. The Thin driver supports Advanced Security features through a set of Java classes included with the JDBC classes ZIP file, and supports security parameter settings through Java properties objects.

Included in your Oracle JDBC classes111.zip or classes12.zip file are a JAR file containing classes that incorporate features of Oracle Advance Security, and a JAR file containing classes whose function is to interface between the JDBC classes and the Advanced Security classes for use with the JDBC Thin driver.

OCI Driver Support for Oracle Advanced Security

If you are using one of the JDBC OCI drivers, which presumes you are running from a thick-client machine with an Oracle client installation, then support for Oracle Advanced Security and incorporated third-party features is, for the most part, no different from any Oracle thick-client situation. Your use of Advanced Security features is determined by related settings in the SQLNET.ORA file on the client machine, as discussed in the Oracle Advanced Security Administrator's Guide. Refer to that manual for information.

Important: The one key exception to the preceding, with respect to Java, is that SSL--Sun Microsystem's standard Secure Socket Layer protocol--is supported by the Oracle JDBC OCI drivers only if you use native threads in your application. This requires special attention, because green threads are generally the default.

Thin Driver Support for Oracle Advanced Security

Because the Thin driver was designed to be downloadable with applets, one obviously cannot assume that there is an Oracle client installation and a SQLNET.ORA file where the Thin driver is used. This necessitated the design of a new, 100% Java approach to Oracle Advanced Security support.

Java classes that implement Oracle Advanced Security are included in your JDBC classes12.zip or classes111.zip file. Security parameters for encryption and integrity, normally set in SQLNET.ORA, are set in a Java properties file instead.

For information about parameter settings, see "Thin Driver Support for Encryption and Integrity".

JDBC Support for Login Authentication

Basic login authentication through JDBC consists of user names and passwords, as with any other means of logging in to an Oracle server. Specify the user name and password through a Java properties object or directly through the getConnection() method call, as discussed in "Open a Connection to a Database".

This applies regardless of which client-side Oracle JDBC driver you are using, but is irrelevant if you are using the server-side internal driver, which uses a special direct connection and does not require a user name or password.

The Oracle JDBC Thin driver implements Oracle O3LOGON challenge-response protocol to authenticate the user.

Note: As of release 8.1.6 of Oracle8i, third-party authentication features supported by Oracle Advanced Security--such as those provided by RADIUS, Kerberos, or SecurID--are not supported by the Oracle JDBC Thin driver. For the Oracle JDBC OCI driver, support is the same as in any thick-client situation--refer to the Oracle Advanced Security Administrator's Guide.

JDBC Support for Data Encryption and Integrity

You can use Oracle Advanced Security data encryption and integrity features in your Java database applications, depending on related settings in the server.

When using an OCI driver in a thick-client setting, set parameters as you would in any Oracle client situation. When using the Thin driver, set parameters through a Java properties file.

Encryption is enabled or disabled based on a combination of the client-side encryption-level setting and the server-side encryption-level setting.

Similarly, integrity is enabled or disabled based on a combination of the client-side integrity-level setting and the server-side integrity-level setting.

Encryption and integrity support the same setting levels--REJECTED, ACCEPTED, REQUESTED, and REQUIRED. Table 18-3 shows how these possible settings on the client-side and server-side combine to either enable or disable the feature.

Table 18-3 Client/Server Negotiations for Encryption or Integrity

	Client Rejected	Client Accepted (default)	Client Requested	Client Required
Server Rejected	OFF	OFF	OFF	connection fails
Server Accepted (default)	OFF	OFF	ON	ON
Server Requested	OFF	ON	ON	ON
Server Required	connection fails	ON	ON	ON

This table shows, for example, that if encryption is requested by the client, but rejected by the server, it is disabled. The same is true for integrity. As another example, if encryption is accepted by the client and requested by the server, it is enabled. And, again, the same is true for integrity.

The general settings are further discussed in the Oracle Advanced Security Administrator's Guide. How to set them for a JDBC application is described in the following subsections.

Note: The term "checksum" still appears in integrity parameter names, as you will see in the following subsections, but is no longer used otherwise. For all intents and purposes, "checksum" and "integrity" are synonymous.

OCI Driver Support for Encryption and Integrity

If you are using one of the Oracle JDBC OCI drivers, which presumes a thick-client setting with an Oracle client installation, you can enable or disable data encryption or integrity and set related parameters as you would in any Oracle client situation, through settings in the SQLNET.ORA file on the client machine.

To summarize, the client parameters are shown in Table 18-4:

Table 18-4 OCI Driver Client Parameters for Encryption and Integrity

Parameter Description	Parameter Name	Possible Settings
Client encryption level	SQLNET.ENCRYPTION_CLIENT	REJECTED ACCEPTED REQUESTED REQUIRED
Client encryption selected list	SQLNET.ENCRYPTION_TYPES_CLIENT	RC4_40 RC4_56 DES DES40 (see note below)
Client integrity level	SQLNET.CRYPTO_CHECKSUM_CLIENT	REJECTED ACCEPTED REQUESTED REQUIRED
Client integrity selected list	SQLNET.CRYPTO_CHECKSUM_TYPES_CLIENT	MD5

Note: For the Oracle Advanced Security domestic edition only, a setting of RC4_128 is also possible.

These settings, and corresponding settings in the server, are further discussed in Appendix A of the Oracle Advanced Security Administrator's Guide.

Thin Driver Support for Encryption and Integrity

Thin driver support for data encryption and integrity parameter settings parallels the thick-client support discussed in the preceding section. Corresponding parameters exist under the oracle.net package and can be set through a Java properties object that you would then use in opening your database connection.

If you replace "SQLNET" in the parameter names in Table 18-4 with "oracle.net", you will get the parameter names supported by the Thin driver (but note that in Java, the parameter names are all-lowercase).

Table 18-5 lists the parameter information for the Thin driver. See the next section for examples of how to set these parameters in Java.

Table 18-5 Thin Driver Client Parameters for Encryption and Integrity

Parameter Name	Parameter Type	Parameter Class	Possible Settings
oracle.net.encryption_client	string	static	REJECTED ACCEPTED REQUESTED REQUIRED
oracle.net.encryption_types_client	string	static	RC4_40 RC4_56 DES40C DES56C
oracle.net.crypto_checksum_client	string	static	REJECTED ACCEPTED REQUESTED REQUIRED
oracle.net.crypto_checksum_types_client	string	static	MD5

Notes: Because Oracle Advanced Security support for the Thin driver is incorporated directly into the JDBC classes ZIP file, there is only one version, not separate domestic and export editions. Only parameter settings that would be suitable for an export edition are possible. The "C" in DES40C and DES56C refers to CBC (cipher block chaining) mode.

Setting Encryption and Integrity Parameters in Java

Use a Java properties object (java.util.Properties) to set the data encryption and integrity parameters supported by the Oracle JDBC Thin driver.

The following example instantiates a Java properties object, uses it to set each of the parameters in Table 18-5, and then uses the properties object in opening a connection to the database:

...
Properties prop = new Properties();
prop.put("oracle.net.encryption_client", "REQUIRED");
prop.put("oracle.net.encryption_types_client", "( DES40 )");
prop.put("oracle.net.crypto_checksum_client", "REQUESTED");
prop.put("oracle.net.crypto_checksum_types_client", "( MD5 )");
Connection conn = DriverManager.getConnection
   ("jdbc:oracle:thin:@localhost:1521:main", prop);
...

The parentheses around the parameter values in the encryption_types_client and crypto_checksum_types_client settings allow for lists of values. Currently, the Thin driver supports only one possible value in each case; however, in the future, when multiple values are supported, specifying a list will result in a negotiation between the server and the client that determines which value is actually used.

Complete example

Following is a complete example of a class that sets data encryption and integrity parameters before connecting to a database to perform a query.

Note that in this example, the string "REQUIRED" is retrieved dynamically through functionality of the AnoServices and Service classes. You have the option of retrieving the strings in this manner or hardcoding them as in the previous examples.

import java.sql.*;
import java.sql.*;
import java.io.*;
import java.util.*;
import oracle.net.ns.*;
import oracle.net.ano.*;

class Employee
{
  public static void main (String args [])
    throws Exception
  {

    // Register the Oracle JDBC driver
    System.out.println("Registring the driver...");
    DriverManager.registerDriver(new oracle.jdbc.driver.OracleDriver());

    Properties props = new Properties();

    try {
      FileInputStream defaultStream = new FileInputStream(args[0]);
      props.load(defaultStream);


      int level = AnoServices.REQUIRED;
      props.put("oracle.net.encryption_client", Service.getLevelString(level));
      props.put("oracle.net.encryption_types_client", "( DES40 )");
      props.put("oracle.net.crypto_checksum_client",
                 Service.getLevelString(level));
      props.put("oracle.net.crypto_checksum_types_client", "( MD5 )");
    } catch (Exception e) { e.printStackTrace(); }


    // You can put a database name after the @ sign in the connection URL.
    Connection conn = DriverManager.getConnection
               ("jdbc:oracle:thin:@dlsun608.us.oracle.com:1521:main", props);

    // Create a Statement
    Statement stmt = conn.createStatement ();

    // Select the ENAME column from the EMP table
    ResultSet rset = stmt.executeQuery ("select ENAME from EMP");

    // Iterate through the result and print the employee names
    while (rset.next ())
       System.out.println (rset.getString (1));

    conn.close();
  }

}

---