Setting up OTW Encryption

Go Up to Encrypting Network Communication

InterBase OTW encryption consists of two parts: one resides on the server side and the other resides on the client side and works to secure the server. The sections below explain how to set up OTW on both the server and client sides. Sample OTW configurations follow the instructions.

Note:
For information on specifying JDBC properties for OTW, see SSL File Properties. Also in the Developer's Guide, table 4.10 defines the new extended properties.

Before setting up OTW encryption on the server or client side, you must first obtain the necessary security certificates, provided by your Certificate Authority (CA) vendor. InterBase uses these certificates to verify identity information.

Generating Security Certificates

OTW requires the generation and use of the following certificates:

• A public key certificate for the server. For example, ibserverCAfile.pem
• The server’s private key and server certificate. For example, ibserver.pem

You can use any SSL tool to generate these certificates, or contact your IT department or CA vendor. To learn how to create SSL certificates using OpenSSL, see the following website:

• http://www.openssl.org/docs/apps/openssl.html

Setting up the Client Side

The client application indicates to the InterBase client library that it needs to perform OTW encryption via the connection string. The connection string takes the OTW parameters before the database path/name, as specified in the syntax below.

Note:
The existing OTW properties have been changed to the new JDBC OTW properties.

Important:
It is strongly recommended that the old native OTW properties no longer be used. However, the new native client and server supports both the old and new names.

It is likely that this will be the last release of InterBase Client which supports the old parameters. It is important that you start using the new parameters:

Old OTW Client Properties:	New OTW Properties Starting with InterBase XE:
OTWENABLE	ssl=true
PASSPHRASE	clientPassPhrase
PASSPHRASEFILE	clientPassPhraseFile
CERTFILE	clientCertFile
CAFILE	serverPublicFile
CAPATH	serverPublicPath

Syntax: To enable OTW on the client side, use the following syntax for your database connection string:

<secure server host name>[/secure server port name | secure server port number]?ssl=true[?serverPublicFile=complete location of the CA file | ?serverPublicPath=name
 of directory containing the CA certificates |?clientCertFile=name of the client certificate file][?clientPassPhraseFile=pass phrase filename |?clientPassPhrase=pass phrase]??:<database path>;/<database name>

The starting '?ssl=true' and the ending '??' are mandatory, and work as demarcations for the OTW encryption parameters. Table 5.3 lists the descriptions of the options used in the syntax sample.

Client-side OTW Options

Options	Description
secure server host name	The hostname, Fully Qualified Domain name, or IP address of the machine that is hosting the secure InterBase server. If the machine has multiple network interface cards, define the hostname/IP of the interface that is used by the InterBase server.
secure server port name	If you have a local service name associated with the socket port of the remote server, mention that name here; this is typically defined in the /etc/services file on Unix or on the <windows system directory>/drivers/etc/services file on Windows. The client library will automatically translate this to the socket port number at connection time.
secure server port number	The socket port number where the remote server is listening for secure connection requests. You provide this OR the port name above; not both.
ssl	This must be set for any of the other OTW parameters to be accepted and for the connection to be secure. Note: This option replaces the “OTWENABLE” option. It is strongly recommended that the OTWENABLE option no longer be used.
serverPublicFile	Location of the certificate file. By default, InterBase searches for ibserverCAfile.pem in the user’s home directory. Both the serverPublicFile and serverPublicPath (defined below) must follow the PEM format as per standard SSL requirements. The client will not be expected to create this file. This file will be created by the database administrator of the server you are connecting to. If you are the person generating this file, please ensure that the public certificate file has been created binding the certificate to the DNS of the server. This DNS must match the <secure host name> used by the client. Note: This option replaces the “CAFILE” option. It is strongly recommended that the CAFILE option no longer be used.
serverPublicPath	If you use and mention the serverPublicPath, then each file in the directory must contain only a single CA certificate and the files must be named by the hash of the subject name and extension of “.0”. There are no default for this option. It is recommended that you use the serverPublicFile as opposed to serverPublicPath; if you specify both, serverPublicFile will be used. The organization hosting the server will provide the CA file. This file is used to verify that the connection is being made to a legitimate and verified server. Care must be taken to ensure that you are referencing the CA you want to use. Please see About the “c_rehash” command for more information. Note: This option replaces the “CAPATH” option. It is strongly recommended that the CAPATH option no longer be used.

In addition, if you need to enable server verification of the client, you can use the parameters described in the table below. An example follows the table:

Parameter name	Description
clientCertFile	Location and name of the client certification file. This certificate will be presented to the server during the SSL connection phase. The clientCertFile must be in the PEM format and must contain both the client certificate and the private key. Note: This option replaces the “CERTFILE” option. It is strongly recommended that the CERTFILE option no longer be used.
clientPassPhraseFile	Name and location of the text file containing the client private key passphrase. You can use either the clientPassPhrase File parameter, or the clientPassPhrase parameter. Note: This option replaces the “PASSPHRASEFILE” option. It is strongly recommended that the PASSPHRASEFILE option no longer be used.
clientPassPhrase	Specify a private key PassPhrase. You can use either the clientPassPhrase parameter or the clientPassPhraseFile parameter. Note: This option replaces the “PASSPHRASEFILE” option. It is strongly recommended that the PASSPHRASEFILE option no longer be used.

Following is a sample of how to use these parameters in an isql command:

isql> connect ‘localhost/gds_ssl?ssl=true?clientPassPhrase=clientkey?
clientCertFile=c:\ib_builds\InterBase\secureserver\client\client.pem?
serverPublicFile=c:\ib_builds\InterBase\secureserver\client\ serverCAfile.pem??:c:/foo.ib’

About the “c_rehash” command

Use this command if you want to use the serverPublicPath parameter instead of the serverPublicFile on the client or the IBSSL_SERVER_CAPATH instead of the IBSSL_SERVER_CAFILE parameter on the server. For more information on how to set up this directory please go to the OpenSSL website and look for the c_rehash command.

“c_rehash” is a command provided by OpenSSL. This script automatically creates symbolic links to a directory of certificates. For example, suppose that you have a directory called some/where/certs, which contains several CA certificates, and that you want to prepare this directory for use as a serverPublicPath directory. In this case, you can use the following commands:

cd /some/where/certs
c_rehash .

Advance To:

• Setting up the Server Side