Configuring a client for SSL connections

Configure an ESQL/C, ODBC, DB-Access, dbexport, dbimport, dbschema, or dbload database client by adding connection information to the sqlhosts file, setting SSL configuration parameters, and configuring the keystore and the digital certificates it stores.

Before you begin

The client and the server must be enabled with a mutual TLS version. Set the TLS version on the server with the TLS_VERSION configuration parameter.

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.

Procedure

  1. Update connection information in the sqlhosts file by using the onsocssl protocol for SSL SQLI client connections.

    The following table shows an example of an sqlhosts file configured for these client connections.

    Table 1. Example of sqlhosts file configured for SSL SQLI client connections
    Server Name Protocol Host Name Service Name
    sf_on onsoctcp sanfrancisco sf_serv
    oak_on onsocssl oakland oak_serv
  2. Using a text editor, create a conssl.cfg file in the $INFORMIXDIR/etc directory. The file must contain the following information:
    • SSL_KEYSTORE_FILE that specifies the fully qualified file name of the keystore that stores the root CA certificates of all of the servers to which the client connects
    • SSL_KEYSTORE_STH that specifies the fully qualified file name of the keystore password stash file. With versions 14.10.xC4W1 and newer, this parameter is optional and needed only if the stash file is at a different location or has a different file name than the keystore file itself.
    The format of the conssl.cfg file is: 
    Parameter    Value   # Comment
    For example, the conssl.cfg file might contain this information:
    SSL_KEYSTORE_FILE  /work/keystores/ssl_client.p12  # Keystore file
  3. Create the keystore.

    The client keystore must contain all the certificates that are needed to authenticate the server during the SSL handshake. Generally, these certificates are CA certificates. You get such CA certificates from the CA that signed the server’s certificate. However, if the server’s certificate is self-signed, then the client keystore must contain a copy of this self-signed certificate in its keystore. In this case you must extract that certificate from the server keystore and add it to the client keystore.

    Note: Follow your company policies to obtain the server certificates.

    Client versions 4.50.xC3 and older use GSKit as encryption module. Therefore, with these versions it is possible to use the GSKit proprietary CMS keystore format. However, we recommend to use the standard PKCS#12 format with file name extension “.p12" for client keystores. A separately from a server installed stand-alone client of version 14.10.xC4W1 or newer uses OpenSSL as encryption module. For these installations the keystore must be in the standard PKCS#12 format.

    When you create the keystore, be sure that:
    • The name and location of the keystore and optional stash file are as specified in the conssl.cfg file as explained in step 2 above.
    • Permissions on the keystore and its stash file are set to 666, even though the permissions are not enforced.
    Use the external utilities from GSKit or OpenSSL to create the client keystore. Following are the steps to create the keystore:

    3.1 Using OpenSSL:

    For more information on the OpenSSL utility commands, see the OpenSSL documentation at http://www.openssl.org.

    • If the certificate created for the server is self-signed,
      1. Log on to the database server machine and extract the certificate from the server keystore: 
        
      -openssl pkcs12 -in  $INFORMIXSERVER.p12 \
      -passin pass:SERVERPASSWD \
      -out SSL_KEYSTORE_LABEL.cert.pem -nokeys
        Note: If the format of the server’s keystore is CMS (filename extension “.kdb"), then you need to use a GSKit utility like gsk8capicmd to extract the certificate from this keystore. (The CMS keystore format is a GSKit proprietary format.) See below for a gsk8capicmd example to extract the server’s certificate from the keystore.
        Tip: If you don’t know the password of the server’s keystore but the password is stashed, you can use the GSKit gsk8capicmd utility to extract the certificate without specifying the keystore password. See below for a gsk8capicmd example.
      2. Transfer the output file SSL_KEYSTORE_LABEL.cert.pem from the server machine to the client machine.
      3. Create the client keystore using the exported certificate in the PEM file as input:
        
       openssl pkcs12 -export -out client.p12 -passout pass:CLIENTPASSWD \
      -in SSL_KEYSTORE_LABEL.cert.pem -caname LABEL -nokeys
        Note: You must specify the option "-caname ..." in order to give a label (“friendly name") as identifier to the certificate in the client keystore.
      4. Use the utility onkstash to create the stash file with the keystore password:
        onkstash client.p12 CLIENTPASSWD
    • If your client connects to several different database servers or your database server has a CA-signed certificate:
      1. Collect all the certificates needed for the authentication of each database server into a single PEM file:
        • For a database server that uses a single self-signed certificate, use a command as described above to extract that certificate from the server’s keystore
        • For a database server that uses a certificate signed by a CA, get all needed CA certificates from the CA
        • In case there are duplicates in the collected certificates, eliminate all duplicates. Duplicate certificates may be collected e.g. when the same CA signed the certificates of several different database servers
        • Concatenate all unique certificates into a single PEM file
      2. On the client machine, create the client keystore using the single PEM file with the unique certificates as input:
        openssl pkcs12 -export -out client.p12 -passout pass:CLIENTPASSWD \
 -in SINGLE_PEM_FILE -nokeys -caname LABEL1 -caname LABEL2..
        Note: You must specify the option “-caname ..." multiple times with an individual label name as unique identifier for each certificate in the input PEM file.
      3. Use the utility onkstash to create the stash file with the keystore password:
        onkstash client.p12 CLIENTPASSWD
    3.2 Using GSKit:
    Use the GSKCapiCmd command-line interface to set up a keystore and its password stash file and digital certificate.
    Note:
    • If the password of the keystore is stashed, you may replace the option “-pw <passwd>" with the option "-stashed".
    • Replace file extension “.p12" with “.kdb" for versions 14.10.XC3 and older OR if the format of the server’s keystore is CMS instead of PKSC#12.
    For example:

    • Run the following command on the client machine to create an empty PKCS#12 keystore and stash the password:

      GSK_COMMAND -keydb -create -db client.p12 -pw CLIENTPASSWD -stash
      For database clients of versions 14.10.XC3 and older, instead use the following command to create an empty CMS format keystore and stash the password:
      GSK_COMMAND -keydb -create -db client.kdb -pw CLIENTPASSWD -stash
    • Get the certificate(s) needed to authenticate the server:
      • If the server's certificate is self-signed:
        1. Log on to the remote server and extract the certificate from the server keystore: 
          GSK_COMMAND -cert -extract -db $INFORMIXSERVER.p12 -pw SERVERPASSWD -label
  SSL_KEYSTORE_LABEL -target SSL_KEYSTORE_LABEL.cert.pem -format ascii

          where, SSL_KEYSTORE_LABEL stands for the label name of the server’s certificate in the server’s keystore, This is the value that is also specified for the server’s configuration parameter SSL_KEYSTORE_LABEL.

        2. Use FTP to move the extracted certificate to your client.
      • If the server’s certificate is signed by a CA:
        • Get all the needed CA certificates from the CA
    • Add each certificate to the client keystore by running a command : 
      GSK_COMMAND -cert -add -db client.p12 -stashed -label 
  LABEL1 -file SSL_KEYSTORE_LABEL.cert.pem -format ascii
      Note: You must specify a unique label name as identifier for each certificate that you add to the client keystore.
    • If your client connects to several different database servers:
      • Repeat the above steps for each database server
    Note: For the migration of pre-existing client keystores used with GSKit, see Using SSL/TLS database connections in the Migration Guide.