Configuring a server instance for secure sockets layer connections

Configure the HCL Informix® 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 Informix instance for SSL connections:

Procedure

Update connection information in the sqlhosts file 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	Service Name
server1_on	onsoctcp	sanfrancisco	s1_on
server1_on_ssl	onsocssl	sanfrancisco	s1_on_ssl
server1_dr_ssl	drsocssl	sanfrancisco	s1_dr_ssl

For more information about the sqlhosts file, see the Informix Administrator's Guide.

Update configuration parameters in the onconfig file, as follows:
1. Specify the label of the SSL/TLS digital certificate issued to the server in the SSL_KEYSTORE_LABEL configuration parameter.
  The label 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, Informix starts one poll thread.
  For the protocol, specify socssl. The protocol format is iiippp, where iii=[ipc|soc|tli] and ppp=[shm|str|tcp|imc|ssl].
  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, Informix 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.2,1.3
```
  to allow the use of TLS protocol versions 1.2, 1.3 .
  Note: TLS versions 1.0 and 1.1 are disabled starting Informix Server version 14.10.xC8 .
Set up a keystore and its password stash file and digital certificate by using the iKeyman utility, GSKCmd command-line interface, or GSKCapiCmd command-line interface.
To use the iKeyman utility and GSKCmd tool, a supported Java™ runtime environment must be installed. The GSKCapiCmd tool is part of the GSKit and does not require Java.
When you create the keystore, be sure to:
- Select the option to stash the password.
- Name the keystore as servername.p12 (versions 14.10.xC4W1 and newer) or servername.kdb (versions 14.10.xC3 and older), where servername is the value of the DBSERVERNAME configuration parameter.
- Create the keystore and its stash file in the INFORMIXDIR/ssl directory.
- Set the permissions on the INFORMIXDIR/ssl/servername.p12 (or $INFORMIXDIR/ssl/servername.kdb) file and the $INFORMIXDIR/ssl/servername.sth file to 600, with informix set as both the owner and the group, even though Informix does not enforce these permissions.
For example with versions 14.10.xC4W1 and newer, use:
```
gsk8capicmd -keydb -create -db server1.p12 -pw server1_password -stash 
gsk8capicmd -cert -create -db server1.p12 -stashed -label server1_ssl -dn ‘CN=Informix Server 1’ -size 4096 { -ca true -sigalg
SHA256WithRSA ]  
```
For example with versions 14.10.xC3 and older, use:
```
gsk8capicmd -keydb -create -db server1.kdb -pw server1_password -stash 
gsk8capicmd -cert -create -db server1.kdb -stashed -label server1_ssl -dn ‘CN=Informix Server 1’ -size 4096 [ -ca true -sigalg
SHA256WithRSA ]   
```
Note:
- For 64bit products, you need to add _64 to the command name i.e. use gsk8capicmd_64.
- The above commands create a simple keystore that contains a single self-signed certificate and a key. As such, the certificate is the SSL/TLS digital certificate issued to the server and at the same time is to be used by the client in lieu of a CA certificate. In such a scenario, there is no certificate from a CA involved.
- While it is possible to continue using CMS format keystores (“.kdb" file name extension) with versions 14.10.xC4W1 and newer, we recommend the use of the PKCS#12 open standard format for keystores (file name extension “.p12").
- Versions 14.10.xC3 and older depend on the file name extension for keystores being “.kdb".
- The first command of the examples creates an empty keystore. The given option “-stash" causes the password to be stashed in the corresponding file server1.sth. With the password already stashed, subsequent commands can be given the option “stashed" instead of having to repeat the password. The second command creates a self-signed certificate and a key in the keystore.
- In the example, the option “-label server1_ssl" specifies “server1_ssl" as an identifier of the certificate created in the keystore. This is the value that must correspond to the setting of parameter SSL_KEYSTORE_LABEL in the onconfig file.
  Tip: You can find the labels of certificates in a keystore with a command like:
  gsk8capicmd -cert -list -db server1.p12 -stashed
- In the example, the option “-dn ‘CN=Informix Server 1’" specifies the distinguished name of the certificate with just the common name being “Informix Server 1".
- At least with versions 14.10.xC4W1 and newer, we recommend the use of options “-ca true" and “-sigalg SHA256WithRSA" when creating a (self-signed) certificate. These options make sure that certificates are created and signed with certain attributes that may be required by future versions of encryption libraries, especially in the case of TLS 1.3 .
  Tip: To get detailed information about a specific certificate in a keystore, use a command like the following, specifying the label of the certificate:
  gsk8capicmd -cert -details -db server1.p12 -stashed -label server1_ssl
- If you are planning to use TLS 1.3, -size argument should have the value at least 4096.
- Refer GSKCapiCmd User's Guide ftp://ftp.software.ibm.com/software/webserver/appserv/library/v80/GSK_CapiCmd_UserGuide.pdf for further details.
For information about the keystore, the password stash file, and digital certifications, see Secure sockets layer protocol.

For information about the iKeyman utility, GSKCmd command-line interface, and the GSKCapiCmd command-line interface, see IBM Global Security Kit (GSKit).

What to do next

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