Setting up the Client Side

From InterBase
Jump to: navigation, search

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’