Configuring a server instance for secure sockets layer connections

Configure the HCL OneDB™ instance for Secure Sockets Layer (SSL) connections by adding connection information to the sqlhosts file, setting SSL configuration parameters, and configuring the keystore and the digital certificates it stores.

About this task

Note: Transport Layer Security (TLS) is the successor to SSL. In this documentation, the same information applies to TLS as to SSL.

To configure the HCL OneDB instance for SSL connections:

Procedure

Update connection information in the sqlhosts file (UNIX™) or the SQLHOSTS registry (Windows™) to include information about SSL connections. Use the:

onsocssl protocol for ESQL/C, ODBC, DB-Access, dbexport utility, dbimport utility, dbschema utility, or dbload utility connections
drsocssl protocol for DRDA® connections

The following table shows an example of an sqlhosts file configured for both SSL and non-SSL connections.

Table 1. Example of sqlhosts file configured for SSL connections
Server Name	Protocol	Host Name	Server Name
server1_on	onsoctcp	sanfrancisco	s1_on
sever1_on_ssl	onsocssl	sanfrancisco	s1_on_ssl
server1_dr_ssl	drsocssl	sanfrancisco	s1_dr_ssl

For more information about the sqlhosts file or SQLHOSTS registry, see the HCL OneDB Administrator's Guide.

Update configuration parameters in the onconfig file, as follows:
1. Specify the friendly name of the server digital certificate in the SSL_KEYSTORE_LABEL configuration parameter.
  The friendly name can contain up to 512 bytes.
  For example, specify:
```
SSL_KEYSTORE_LABEL server1_ssl
```
2. Configure poll threads for SSL connections by using the NETTYPE configuration parameter.
  If you do not configure poll threads, HCL OneDB starts one poll thread.
  
  For the protocol, specify socssl.
  For example, specify:
```
NETTYPE socssl,3,50,NET
```
3. Configure Encrypt Virtual Processors (VPs) for SSL encryption and decryption operations, by using the VPCLASS parameter.
  
  If Encrypt VPs are not configured, HCL OneDB starts one Encrypt VP the first time an SSL operation occurs.
  
  You can also use the onmode -p command to add or drop Encrypt VPs when the database server is in online mode.
  
  Tip: For large systems, configure multiple Encrypt VPs.
4. If you want to control the version of the TLS protocol to be used, set the configuration parameter TLS_VERSION accordingly.
  For example, specify:
```
TLS_VERSION 1.1,1.2
```
  to allow the use of TLS protocol versions 1.1 and 1.2, but disallow the use of TLS protocol version 1.0.
Set up a digital certificate, the keystore and its password stash file by using the OpenSSL utility openssl.
When you create the keystore, be sure to:
- Name the keystore as servername.p12, where servername is value of the DBSERVERNAME configuration parameter.
- Create the password stash file using the utility onkstash.
- Create the keystore and its stash file in the ONEDB_HOME/ssl directory.
- Set the permissions on the ONEDB_HOME/ssl/server-name.p12 and $ONEDB_HOME/ssl/server-name.stl files to 600, with onedb set as both the owner and the group, even though HCL OneDB does not enforce these permissions.
For example, specify:
```
openssl genrsa -out server1.key.pem
openssl req -new -x509 -key server1.key.pem \
 -subj ‘/CN=OneDB Server 1’ -days 365 -out server1.cert.pem 
cat server1.key.pem server1.cert.pem > server1.all.pem
openssl pkcs12 -export -in server1.all.pem -name server1_ssl \ 
 -passout pass:server1passwd -out server1_on.p12
onkstash server1_on.p12 server1passwd 
```
Note:
- The above commands create a simple keystore that contains just a single self-signed certificate. As such, the certificate is the server’s own certificate and at the same time is to be used by the client in lieu of a real CA certificate when authenticating the server. In such a scenario there is no certificate from a CA involved.
- The PEM files contain the generated private key in unencrypted form. Therefore you may want to remove the PEM files after you have successfully created the keystore and its password stash file. Or at least move them to a safe place.
For information about the keystore, the password stash file, and digital certifications, see Secure sockets layer protocol.

What to do next

If any of the HCL OneDB utilities (such as DB-Access) must connect to the server by SSL, you must also configure a client keystore for the utility in the server environment, following the steps in Configuring a client for SSL connections.