Skip to content
≡

Administrator

Developer

Tools

External Tools

2. Installing and Starting SSL in Altibase#

This chapter provides instructions for installing SSL and the necessary software.

Software Requirements#

This section describes the requirements for using SSL communication on the server and client.

Server#

  • OpenSSL toolkit 3.0.8
  • Altibase version 7.3.0.0.0 or later

To use SSL/TLS in Altibase, the OpenSSL toolkit is required. This toolkit was developed by the OpenSSL Project and can be downloaded from http://www.openssl.org/source. Altibase 7.3 no longer supports OpenSSL 1.0.x, but supports OpenSSL 3.0.8.

Client#

ODBC, CLI, ADO.NET#

The OpenSSL toolkit has to be installed in order to use SSL communication with ODBC, CLI or ADO.NET.

JDBC#

To conveniently implement the client Java application through SSL, it is recommended to use Java 1.8.0_351 or later. This version is preferred for the following reasons:

  • In Java 1.8.0_351 or later, TLS 1.3 cipher algorithms can be used without any specific setting.

  • Since Java 1.8.0_261 it supports TLS 1.3. However, the following setting is required to use TLS 1.3.

    $ java -Djdk.tls.client.protocols="TLSv1.3"


Configuring the Environment for SSL Usage#

This section discusses how to configure the environment for Altibase SSL.

Configure SSL on the Server#

  • Step 1: Confirm the Installation of OpenSSL and its library
  • Step 2: Set Server Properties to Connect over SSL
  • Step 3: Specify SSL Client Authentication
  • Step 4: Set Server Certificate, Private Key, and Certificate Authority
  • Step 5: Start the Server

Step 1: Confirm the Installation of OpenSSL and its Library#

It is recommended to install the OpenSSL toolkit before installing SSL-enabled Altibase. If an Altibase function is used and the OpenSSL is not installed, Altibase reports that it is unable to find the OpenSSL library.

Check if OpenSSL is installed on the server and verify that the version is as shown below.

$ openssl version
OpenSSL 3.0.8 7 Feb 2023 (Library: OpenSSL 3.0.8 7 Feb 2023)

Step 2: Set Server Properties to Connect over SSL#

To connect over SSL within Altibase, you need to set the following properties located in the $ALTIBASE_HOME/conf/altibase.properties file. For more detailed information, please refer to the General Reference.

  • SSL_ENABLE
    Switches the SSL feature on or off within Altibase. To enable, set the value to 1.
  • SSL_PORT_NO
    Specifies the listening port number for SSL connections. The value must be unique.
  • SSL_MAX_LISTEN
    Sets the listen queue maximum size for concurrent SSL connections. You should note that more listeners require more memory.

  • SSL_CIPHER_LIST
    The candidate cipher algorithm list available for the server and client to use and negotiate with. Depending on your security policy, you can specify one or more cipher names and separate them by colons. The user can check the list at OpenSSL or execute the following command in the shell environment.

    $ openssl ciphers

  • SSL_CIPHERS_SUITES
    This property defines the list of TLS 1.3 ciphers. If left unset, all cipher lists allowed by OpenSSL are used.

  • SSL_LOAD_CONFIG
    Set this property to load the OpenSSL configuration file(openssl.cnf). The default value is 0, which disables this feature. To use the OpenSSL FIPS module, set the value of this property to 1.

    • 0: Do not load OpenSSL configuration file
    • 1: Load OpenSSL configuration file

Step 3: Specify SSL Client Authentication#

  • SSL_CLIENT_AUTHENTICATION
    Sets the SSL authentication mode to server-only authentication or mutual authentication. If the user sets the value to 1 for mutual authentication, the server will request a certificate from the client during the SSL handshake.

Step 4: Set Server Certificate, Private Key, and Certificate Authority#

  • SSL_CERT

  • SSL_KEY

  • SSL_CA

  • SSL_CAPATH

SSL_CERT#

Sets the server certificate path.

For example, if the name of a server certificate is server-cert.pem and it is located in the $ALTIBASE_HOME/cert directory, the value for this property is ?/cert/server-cert.pem.

SSL_KEY#

Sets the server private (secret) key path.

For example, if the name of a server's secret key is server-key.pem and it is located in the $ALTIBASE_HOME/cert directory, the value for this property is ?/cert/server- key.pem.

SSL_CA, SSL_CAPATH#

The SSL_CA or SSL_CAPATH property must be set in order to receive ownership of the CA certificate issued by an accredited authority. The CA certificate file is located in a user-specified path or a directory in X.509 format.

If you don't have an accredited certificate, you can use SSL by creating a private certificate.

Step 5: Start the Server#

Start SSL-enabled Altibase. Please refer to the sample files provided in the Appendix.

If SSL_ENABLE is set to 1, the SSL listen port is displayed as follows. This means that both the environment variables ALTIBASE_PORT_NO and ALTIBASE_SSL_PORT_NO need to be defined. 

$ server start
-----------------------------------------------------------------
     Altibase Client Query utility.
     Release Version 7.3.0.0.1
     Copyright 2000, Altibase Corporation or its subsidiaries.
     All Rights Reserved.
-----------------------------------------------------------------
ISQL_CONNECTION = UNIX, SERVER = localhost
[ERR-910FB : Connected to idle instance]
Connecting to the DB server.... Connected.
...
TRANSITION TO PHASE : SERVICE
  [CM] Listener started : TCP on port 20300 [IPV4]
  [CM] Listener started : SSL on port 20443 [IPV4]
  ...
--- STARTUP Process SUCCESS ---
Command executed successfully.

Configure SSL for JDBC#

  • Step 1: Import Certificates

  • Step 2: Set up Authentication in a Java Environment

  • Step 3: Set JDBC Properties for SSL

  • Step 4: Set Altibase Environment Variables

Step 1: Import Certificates#

The first step is to import certificates into the truststore for the server's CA certificate or into the keystore for its own CA certificate and secret key. Java Secure Socket Extension (JSSE) uses the truststore and keystore for authentication.

The next step to take depends on whether the CA certificate type is public or private and the job thereafter depends on whether the chosen authentication mode is server-only authentication or mutual authentication.

  1. Private certificates with server-only authentication mode:
    Import the server's CA certificate into the truststore.

  2. Private certificates with mutual authentication mode:
    Import the server's CA certificate into the truststore. Import the PKCS #12 formatted file, containing its own CA certificate and secret key, into the keystore.

  3. Public certificates with server-only authentication mode:
    No action is necessary.

  4. Public certificates with mutual authentication mode:
    Import the PKCS #12 formatted file, containing its own CA certificate and secret key, into the keystore.

When using private certificates (1 or 2 above), import the server's CA certificate into the truststore.

$ keytool -import -alias alias_name -file server_certificate_file.pem -keystore truststore -storepass password

For 2 or 4, prior to importing its certificate and secret key, ensure that the PKCS #12 formatted file, containing its own certificate and secret key, is ready.

If the PKCS #12 file is not ready, execute OpenSSL with the pkcs12 option to generate the PKCS #12 file which contains the client's certificate and secret key as follows.

$ openssl pkcs12 -export -in client_certificate.pem -inkey client_secretkey_file.pem > pkcs_file.p12

Import the prepared PKCS #12 file into the keystore with the following options.1

$ keytool -importkeystore -srckeystore pkcs_file.p12 -destkeystore keystore.jks -srcstoretype pkcs12

Step 2: Set up Authentication in a Java Environment#

JRE must access the truststore and keystore for authentication over SSL. The user can select from any of the following three configurations.

  • Configure a Java Application's Command-line Option

  • Use the System.setProperty Method in a Java Application

  • Configure the JDBC Property in a Java Application

Configure a Java Application's Command-line Option#
-Djavax.net.ssl.keyStore=path_to_keystore
-Djavax.net.ssl.keyStorePassword=password
-Djavax.net.ssl.trustStore=path_to_truststore
-Djavax.net.ssl.trustStorePassword=password
Use the System.setProperty Method in a Java Application#
System.setProperty("javax.net.ssl.keyStore", "path_to_keystore");
System.setProperty("javax.net.ssl.keyStorePassword", "password");
System.setProperty("javax.net.ssl.trustStore", "path_to_truststore");
System.setProperty("javax.net.ssl.trustStorePassword", "password");
Configure the JDBC Property in a Java Application#
Properties sProp = new Properties();
sProps.put("keystore_url", "path_to_keystore");
sProps.put("keystore_password", "password");
sProps.put("truststore_url", "path_to_truststore");
sProps.put("truststore_password", "password");

Step 3: Set JDBC Properties for SSL#

Altibase provides JDBC for SSL connection to use SSL within the database. JDBC properties are categorized into the following two groups:

  • JDBC Properties for SSL Connections

  • JDBC Properties for Authentication

JDBC Properties for SSL Connections#
Name Description Range Default Value
ssl_enable Specifies whether or not to connect to the database over SSL connection. An SSL connection is created if this value is true; a TCP connection is created if this value is false. true
false		 false
port Specifies the SSL port number on the target server. The priority for the SSL port number is: 1) if ssl_enable is true and a value has been specified, this value is applied first. 2) if ssl_enable is true and this value is omitted, the ALTIBASE_SSL_PORT_NO environment variable is applied. 3) if ssl_enable is true and both this value and the ALTIBASE_SSL_PORT_NO environment variable are omitted, the default value (20300) is applied. 0 ~ 65535 ssl_enable(false): 20300
ssl_enable(true): 20443
ciphersuite_list This is a list of available ciphers. Each name is separated by a colon (e.g., SSL_RSA_WITH_RC4_128_MD5:SSL _RSA_WITH_RC4_128_SHA). If JRE does not support the named algorithm, an IllegalArgumentException with the "Unsupported ciphersuite" message is thrown. String All cipher suite lists supported by JRE
ssl_protocols This is a list of protocols used for SSL communication on the server. Users can set several protocols using commas(e.g., TLSv1.2,TLSv1.3). String All SSL/TLS protocols supported by JRE
JDBC Properties for Authentication#
Name Description Range Default Value
verify_server_certificate Specifies whether or not to authenticate the target server's CA certificate. To use SSL exception authentication, set as false and the client application will not authenticate the server's CA certificate. In this case, it is unnecessary to import the server's private CA certificate for authentication. true
false		 true
keystore_url Specifies the path to the keystore (a container for its own private key and the certificates with their corresponding public keys). String
keystore_type Specifies the keystore type for keystore_url. Java Key Store (JKS) is the most common type in Java. JKS, JCEKS, PKCS12, etc JKS
keystore_password Specifies the password for keystore_url. String
truststore_url Specifies the path to the truststore (a keystore containing certificates that belong to the communication partners). String
truststore_type Specifies the truststore type at truststore_url above. Java Key Store (JKS) is the most common type in Java. JKS, JCEKS, PKCS12, etc
truststore_password Specifies the password to truststore_url above. String

Step 4: Set Altibase Environment Variables#

Altibase sets the port number for SSL communication, and this step can be omitted.

If the port property has not been set for JDBC, the value specified for ALTIBASE_SSL_PORT_NO will be used as the port number. If ALTIBASE_SSL_PORT_NO is omitted, the default value for the port property is used.

Name Description Range Default Value
ALTIBASE_SSL_PORT_NO Specifies the SSL port number on the target server. 1024 ~ 65535

Considerations When Using SSL with JDBC#

Please consider the following when using SSL for JDBC.

Importing the PKCS #12 File into the Keystore#

To use mutual authentication over SSL, you must first import the client's CA certificate and private key into the KeyStore. Users can import PKCS #12 using the -importkeystore option of keytool as shown below.

$ keytool -importkeystore -srckeystore pkcs_file.p12 -destkeystore keystore.jks
-srcstoretype pkcs12

Configure SSL for ODBC/CLI#

  • Step 1: Verify the OpenSSL Library

  • Step 2: Prepare the Client's Certificate

  • Step 3: Set ODBC/CLI Properties for SSL

  • Step 4: Set the Altibase Environment Variables (in case of using FIPS module)

  • Step 5: Write a Client Program

Step 1: Verify the OpenSSL Library#

ODBC and CLI read the OpenSSL library and call the necessary functions while connecting to the server using SSL communication. Therefore, you should verify that the OpenSSL library has been installed properly, before writing a client application. Where the library is installed can differ among operating systems.

  • Verify the library installation

    $ ls -al /usr/lib/libssl*
$ ls -al /usr/lib/libcrypto*

  • Verify the utility installation

    $ openssl version

Step 2: Prepare the Client's Certificate#

Prepare the client's certificate and secret key in a PEM format file for mutual authentication of the server and client. The location of these files should be accessible by a client using ODBC or CLI.

Step 3: Set ODBC/CLI Properties for SSL#

You need to set SSL properties appropriately, before writing a client program using SSL. The client can specify the following properties as a connection string when connecting to the server.

SSL connection properties are located in $ALTIBASE_HOME/conf/altibase.properties.

Name Description Range Default Value
SSL_CA Specifies the file path to store CA certificates to certify the ownership of received certificates. CA certificates can exist in a user-specific file path or a X.509 structured directory.
Example: SSL_CA= /cert/ ca-cert.pem.
SSL_CAPATH Specifies CAPATH in a CA directory format.
Example: SSL_CAPATH=/etc/ssl/certs
SSL_CERT Sets the Altibase certificate path.
Example: SSL_CERT=/cert/client-cert.pem
SSL_KEY Sets the server private (secret) key path.
Example: SSL_KEY=/cert/client-key.pem
SSL_VERIFY Sets whether or not to authenticate the server certificate. An SSL handshake fails if authentication fails, and it becomes impossible to communicate over SSL.
0 : (OFF) Does not authenticate the server certificate
1: (ON) Authenticates the server certificate
Example: SSL_VERIFY=0		 0: OFF
1: ON		 0(OFF)
SSL_CIPHER A cipher algorithms available for the server and client to use and negotiate with. Depending on your security policy, you can specify one or more cipher names and separate them by colons(:). You can check the list at OpenSSL or execute command "$ openssl ciphers" in the shell environment.
Example: SSL_CIPHER=EDH-DSS-DES-CBC-SHA:DES-CBC-SHA

The following is a table comparing the server SSL properties and ODBC/CLI properties.

Name Server(altibase.properties) ODBC/CLI
SSL_ENABLE O X
The client is same meaning with SSL_ENABLE = 1 if CONNTYPE = SSL
SSL_PORT_NO O X
On the client, connect with CONNTYPE = SSL; PORT = 20443 without a separate SSL port.
SSL_MAX_LISTEN O X
SSL_CLIENT_AUTHENTICATION O X
SSL_CIPHER_LIST O X
SSL_CA O O
SSL_CAPATH O O
SSL_CERT O O
SSL_KEY O O
SSL_CIPHER X O
SSL_VERIFY X O

Step 4: Set the Altibase Environment Variables (in case of using FIPS module)#

To use FIPS module, users have to set the ALTIBASE_SSL_LOAD_CONFIG property in client environment variables to 1. Users who do not use FIPS module is able to skip this step. For more detailed information, please refer to How to Use OpenSSL FIPS Module.

Name Description Default Value
ALTIBASE_SSL_LOAD_CONFIG Specifies whether to load the OpenSSL configuration file.
0: Do not load the file
1: Load the file		 0

Step 5: Write a Client Program#

Write a program to use SSL connection in the client application. You can find a sample program that uses SSL connection in the altibase directory. Please refer to $ALTIBASE_HOME/sample/SQLCLI/SSL.

How to Use OpenSSL FIPS Module#

FIPS 140 is a program that verifies the security and reliability of encryption modules, and modules that have passed verification can be used by the U.S. federal government and related agencies. To use OpenSSL's FIPS module in Altibase, users can set it up as below.

  1. Enable the FIPS module in the OpenSSL configuration file (see http://www.openssl.org/).
  2. Set the SSL_LOAD_CONFIG property of the Altibase server to 1.
  3. Set the ODBC/CLI environment variable ALTIBASE_SSL_LOAD_CONFIG to 1.

Configure SSL for ADO.NET#

  • Step 1: Verify the OpenSSL Library
  • Step 2: Prepare the Client's Certificate
  • Step 3: Set .NET Connection Properties for SSL
  • Step 4: Write a Client Program

Step 1: Verify the OpenSSL Library#

This step is same as Step 1 of Configure SSL for ODBC/CLI.

Step 2: Prepare the Client's Certificate#

This step is same as Step 2 of Configure SSL for ODBC/CLI.

Step 3: Set .NET Connection Properties for SSL#

When connecting to the server using SSL communication, users can specify the following properties in the connection string:

Name Description Range Default Value
conn type Determine whether to connect to the server using SSL communication. If this value is set to "ssl", the connection is established using SSL communication. ssl
port Specify the value of SSL_PORT_NO, which is the port number of the target server to connect to. 0 ~ 65535
ssl ca Refer to SSL_CA from Configure SSL for ODBC/CLI > Step 3: Set ODBC/CLI Properties for SSL.
ssl capath Refer to SSL_CAPATH from Configure SSL for ODBC/CLI > Step 3: Set ODBC/CLI Properties for SSL.
ssl cert Refer to SSL_CERT from Configure SSL for ODBC/CLI > Step 3: Set ODBC/CLI Properties for SSL.
ssl key Refer to SSL_KEY from Configure SSL for ODBC/CLI > Step 3: Set ODBC/CLI Properties for SSL
ssl verify Refer to SSL_VERIFY from Configure SSL for ODBC/CLI > Step 3: Set ODBC/CLI Properties for SSL. false: OFF
true: ON		 false
ssl cipher Refer to SSL_CIPHER from Configure SSL for ODBC/CLI > Step 3: Set ODBC/CLI Properties for SSL.

Step 4: Write a Client Program#

To enable SSL communication in the client application, follow the instructions provided in the Sample Using SSL Connection in ADO.NET section in "Appendix A: SSL Sample".

  1. You can only import .pem files into keystore with the '-importkeystore' option. ↩