Configuring SSL for ODBC Clients

Configuring SSL for ODBC clients requires that you set the SSLMode connection property. If you want to configure optional SSL client authentication, you must also configure the Security Parameters SSLKeyFile and SSLCertFile connection properties.

How you configure the DSN depends on your operating system:

  • Linux and UNIX — Enter the connection properties in the odbc.ini file. See Creating an ODBC DSN for Linux.

  • Microsoft Windows — Enter the connection properties in the Windows Registry. See Creating an ODBC DSN for Windows Clients.

    For Windows ODBC you can set connection string properties in the Client Settings tab on the ODBC DSN Configuration dialog. Connection string properties you can set are:

    SSL CA file - the location of the root certificate file, for example root.crt.

    SSL cert file - the location of the server certificate file, for example server.crt.

    SSL key file - the location of the server key file, for example, server.key.

Set SSLMode Connection Property

Set the SSLMode connection property to one of the following options for the DSN:

Property Description
verify_full Encrypts data and connects to a user-specified trusted server.
verify_ca Encrypts data and connects to a trusted server.
require Requires the server to use SSL. If the server cannot provide an encrypted channel, the connection fails.
prefer (Default value) Indicates your preference that the server to use SSL. The first connection to the database tries to use SSL. If that connection fails, a second connection is attempted over a clear channel.
allow Makes a connection to the server whether the server uses SSL or not. The first connection attempt to the database is made over a clear channel. If that connection fails, a second connection is attempted over SSL.
disable Never connects to the server using SSL. This setting is typically used for troubleshooting.

Using verify_ca and verify_full

You can use the SSL Mode properties verify_ca and verify_full exclusively on client authentication. These properties require:

  • The root.crt to allow the client to access the server's authentication certificate. If root.crt does not exist, and verify_can or verify_full are set, the connection fails upon SSL initialization.
  • A server.crt, which contains the authentication certificate.
  • A server.key, which contains the server's private key that prevents the server from accessing external systems.
  • A server hostname that matches the hostname specified by the client, verify_full only.
  • A certificateAll nodes in the cluster must either share the same certificate or each certificate must contain all the hostnames or IP addresses in the Subject Alernative Name (SAN).

SSL Workflow

The following diagram shows an example workflow for SSL authentication. Your actual workflow may differ depending on what SSLMode Connection Properties you use.

In this workflow:

  • If the SSLMode Connection Property is set to none or allow, the client connects without authentication.

  • If the SSLMode Connection Property is set to verify_ca or verify_full, and root.crt does not exist, the SSL authentication fails. If root.crt exists, the authentication process proceeds.

  • During SSL authentication if the SSLMode Connection Property is set to verify_full, and the server hostname is not the same as the hostname specified by the client, authentication fails.

Enable SSL Mutual Mode Authentication

You can optionally configure SSL mutual mode by setting the following database Security Parameters:

  • SSLKeyFile — Set this connection property to the file path and name of the client's private key. This key can reside anywhere on the client.
  • SSLCertFile — Set this connection property to the file path and name of the client's public certificate. This file can reside anywhere on the client.