TLS/SSL client authentication

If the server is configured for TLS/SSL client authentication, the server asks the client to verify its identity after the server identity has been proven. Similar to server authentication, the client sends a public certificate to the server to accept or deny. The client stores its public certificate in an encrypted file known as a keystore. Public certificates are paired with a private key in the keystore. To send the public certificate, the driver must access the private key.

Like the truststore, most keystores are password-protected. The driver must be able to locate the keystore and unlock the keystore with the appropriate password. Two connection options are available to the driver to provide this information: Keystore (KeyStore) and Keystore Password (KeyStorePassword). The value of KeyStore is a pathname that specifies the location of the keystore file. The value of Keystore Password is the password required to access the keystore.

The private keys stored in a keystore can be individually password-protected. In many cases, the same password is used for access to both the keystore and to the individual keys in the keystore. It is possible, however, that the individual keys are protected by passwords different from the keystore password. The driver needs to know the password for an individual key to be able to retrieve it from the keystore. An additional connection option, Key Password (KeyPassword), allows you to specify a password for an individual key.

To configure the driver to use data encryption via TLS/SSL client authentication:

• Set the minimum required options for all connections:
  • Set the Host Name (HostName) option to specify the name or the IP address of the server to which you want to connect.
  • Set the Port Number (PortNumber) option to specify the port number of the server listener. The default is 1433.
  • Set the Database Name (Database) option to specify the name of the database to which you want to connect.
• Set the Encryption Method (EncryptionMethod) option to one of the following to valid values:

  • If set to 1 (SSL), data is encrypted using the TLS/SSL protocols specified in the Crypto Protocol Version connection option.

  • Set to 6 (RequestSSL) to specify the login request and data are encrypted using TLS/SSL if the server is configured for TLS/SSL encryption. If the server is not configured for TLS/SSL, an unencrypted connection is established. The TLS/SSL protocol used is determined by the setting of the Crypto Protocol Version connection option.
  • Set to 7 (LoginSSL) to specify that the login request is encrypted using TLS/SSL regardless of whether the server is configured for TLS/SSL. The data is encrypted using TLS/SSL if the server is configured for TLS/SSL, and the data is unencrypted if the server is not configured for TLS/SSL. The TLS/SSL protocol used is determined by the setting of the Crypto Protocol Version connection option.
  • Set to 8 (Strict) to configure the driver to use the TDS (Tabular Data Stream) 8.0 protocol to support TLSv1.3 encryption for SQL Server connections. You must specify this value when your server is configured with Force Strict Encryption=yes.
  • Important: When using strict connection encryption:

    • The driver validates the certificates sent by the server (ValidateServerCertificate=1) for the connection, regardless of the setting of the Validate Server Certificate option.
    • You must specify a truststore containing the server certificate against which the server will be validated at connection.
• Set the Validate Server Certificate (ValidateServerCertificate) option to determine whether the driver validates the certificates sent by the server. When it is set to 1, the driver validates the certificates. When it is set to 0, the driver does not validate the certificates.
• Set the Host Name In Certificate (HostNameInCertificate) option to specify the host name that is specified in the Subject of the certificate. This option provides additional security against man-in-the-middle (MITM) attacks by ensuring that the server the driver is connecting to is the server that was requested. Consult your TLS/SSL administrator for the correct value.
• Set the Key Store (Keystore) option to specify the location of the keystore file.
• Set the Keystore Password (KeystorePassword) option to specify the password that is used to access the keystore file.
• Optionally, set the Crypto Protocol Version (CryptoProtocolVersion) to specify the cryptographic protocol versions supported by your database server that you want to allow your driver to use. For example, CryptoProtocolVersion=TLSv1.3,TLSv1.2.
  Note: TLSv1.3 is currently supported only when strict connection encryption is enabled (EncryptionMethod=8).
• Optionally, set the Enable FIPS (EnableFIPS) connection option to 1 to allow the driver to load the FIPS provider. The FIPS provider contains a set of approved cryptographic algorithms that conform to the Federal Information Processing Standards (FIPS) specified in FIPS 140-2. If you do not specify a value for Enable FIPS, the driver uses its default value (0) and loads the default provider.
  Note:

  • The FIPS provider is supported only on the following platforms: Windows 64-bit, Linux 64-bit, and AIX 64-bit.
  • For using the FIPS and default providers, the certificates must be generated using the OpenSSL 3.5-compliant cryptographic algorithms. See "Generating TLS/SSL certificates using OpenSSL 3.5-compliant algorithms" for more information.
  • Do not set the Keystore Password connection option when using the FIPS provider. The keystore password uses the PKCS12KDF algorithm, which is not an approved FIPS algorithm. Hence, it must not be specified when using the FIPS provider.

The following examples show how to configure the driver to establish a connection via user ID/password authentication and use data encryption via TLS/SSL client authentication. In these examples, since ValidateServerCertificate=1 and EnableFIPS=1, the driver validates the certificate sent by the server and the host name specified by HostNameInCertificate, and loads the FIPS provider for data encryption.

DRIVER=DataDirect 8.0 SQL Server Wire Protocol;EnableFIPS=1;
EncryptionMethod=1;HostName=YourServer;HostNameInCertificate=MySubjectAltName;
PortNumber=1433;Database=Payroll;Keystore=KeyStoreName;ValidateServerCertificate=1;

Driver=ODBCHOME/lib/ivsqlsxx.so
Description=DataDirect SQL Server Wire Protocol
...
EnableFIPS=1
...
EncryptionMethod=1
...
HostName=YourServer
...
HostNameInCertificate=MySubjectAltName
...
PortNumber=1433
...
Database=Payroll;
...
KeyStore=KeyStoreName
...
ValidateServerCertificate=1
...