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.

1. 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 HCL Informix Administrator's Guide.

2. Update configuration parameters in the onconfig file, as follows:
   1. Specify the name of the label of the server digital certificate 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.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.
3. 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 to a file.
   • Name the keystore as servername.p12 (versions 14.10.xC4W1 and newer) or servername.p12 (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.p12) 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 -type pkcs12 -stash
   gsk8capicmd -cert -create -db server1.p12 -stashed -label server1_ssl -dn ‘CN=Informix Server 1’ -size 1024 -ca true -sigalg
   SHA256WithRSA  

   For example with versions 14.10.xC3 and older, use:

   gsk8capicmd -keydb -create -db server1.kdb -pw server1_password -type cms -stash
   gsk8capicmd -cert -create -db server1.kdb -stashed -label server1_ssl -dn ‘CN=Informix Server 1’ -size 1024 [ -ca true -sigalg
   SHA256WithRSA ]   

   Important: If the DBSA configures the database server to use a different version of GSKit, the version-specific gsk8capicmd command must be replaced with command from the different GSKit version. For example, gsk7capicmd.
   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.
   • 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”, even though GSKit does support the PKCS#12 keystore format.
   • 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 in the keystore.
   • In the example, the option “-label server1_ssl” specifies “server1_ssl” as unique 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 OpenSSL used by a database client.
     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

   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).