| title | Understanding encryption support | Microsoft Docs |
|---|---|
| ms.custom | |
| ms.date | 09/12/2019 |
| ms.prod | sql |
| ms.prod_service | connectivity |
| ms.reviewer | vanto |
| ms.technology | connectivity |
| ms.topic | conceptual |
| ms.assetid | 073f3b9e-8edd-4815-88ea-de0655d0325e |
| author | David-Engel |
| ms.author | v-daenge |
[!INCLUDEDriver_JDBC_Download]
When connecting to [!INCLUDEssNoVersion], if the application requests encryption and the instance of [!INCLUDEssNoVersion] is configured to support TLS encryption, the [!INCLUDEjdbcNoVersion] initiates the TLS handshake. The handshake allows the server and client to negotiate the encryption and cryptographic algorithms to be used to protect data. After the TLS handshake is complete, the client and server can send the encrypted data securely. During the TLS handshake, the server sends its public key certificate to the client. The issuer of a public key certificate is known as a Certificate Authority (CA). The client is responsible for validating that the certificate authority is one that the client trusts.
If the application does not request encryption, the [!INCLUDEjdbcNoVersion] will not force [!INCLUDEssNoVersion] to support TLS encryption. If the [!INCLUDEssNoVersion] instance is not configured to force the TLS encryption, a connection is established without encryption. If the [!INCLUDEssNoVersion] instance is configured to force the TLS encryption, the driver will automatically enable TLS encryption when running on properly configured Java Virtual Machine (JVM), or else the connection is terminated and the driver will raise an error.
Note
Make sure the value passed to serverName exactly matches the Common Name (CN) or DNS name in the Subject Alternate Name (SAN) in the server certificate for a TLS connection to succeed.
For more information about how to configure TLS for [!INCLUDEssNoVersion], see Enable Encrypted Connections to the Database Engine.
In order to allow applications to use TLS encryption, the [!INCLUDEjdbcNoVersion] has introduced the following connection properties starting with the version 1.2 release: encrypt, trustServerCertificate, trustStore, trustStorePassword, and hostNameInCertificate. For more information, see Setting the Connection Properties.
The following table summarizes how the [!INCLUDEjdbcNoVersion] version behaves for possible TLS connection scenarios. Each scenario uses a different set of TLS connection properties. The table includes:
-
blank: "The property does not exist in the connection string"
-
value: "The property exists in the connection string and its value is valid"
-
any: "It does not matter whether the property exists in the connection string or its value is valid"
Note
The same behavior applies for [!INCLUDEssNoVersion] user authentication and Windows integrated authentication.
| encrypt | trustServerCertificate | hostNameInCertificate | trustStore | trustStorePassword | Behavior |
|---|---|---|---|---|---|
| false or blank | any | any | any | any | The [!INCLUDEjdbcNoVersion] will not force [!INCLUDEssNoVersion] to support TLS encryption. If the server has a self-signed certificate, the driver initiates the TLS certificate exchange. The TLS certificate will not be validated and only the credentials (in the login packet) are encrypted. If the server requires the client to support TLS encryption, the driver will initiate the TLS certificate exchange. The TLS certificate will not be validated, but the entire communication will be encrypted. |
| true | true | any | any | any | The [!INCLUDEjdbcNoVersion] requests to use TLS encryption with the [!INCLUDEssNoVersion]. If the server requires the client to support TLS encryption or if the server supports encryption, the driver will initiate the TLS certificate exchange. Note that if the trustServerCertificate property is set to "true", the driver will not validate the TLS certificate. If the server is not configured to support encryption, the driver will raise an error and terminate the connection. |
| true | false or blank | blank | blank | blank | The [!INCLUDEjdbcNoVersion] requests to use TLS encryption with the [!INCLUDEssNoVersion]. If the server requires the client to support TLS encryption or if the server supports encryption, the driver will initiate the TLS certificate exchange. The driver will use the serverName property specified on the connection URL to validate the server TLS certificate and rely on the trust manager factory's look-up rules to determine which certificate store to use. If the server is not configured to support encryption, the driver will raise an error and terminate the connection. |
| true | false or blank | value | blank | blank | The [!INCLUDEjdbcNoVersion] requests to use TLS encryption with the [!INCLUDEssNoVersion]. If the server requires the client to support TLS encryption or if the server supports encryption, the driver will initiate the TLS certificate exchange. The driver will validate the TLS certificate's subject value by using the value specified for the hostNameInCertificate property. If the server is not configured to support encryption, the driver will raise an error and terminate the connection. |
| true | false or blank | blank | value | value | The [!INCLUDEjdbcNoVersion] requests to use TLS encryption with the [!INCLUDEssNoVersion]. If the server requires the client to support TLS encryption or if the server supports encryption, the driver will initiate the TLS certificate exchange. The driver will use the trustStore property value to find the certificate trustStore file and trustStorePassword property value to check the integrity of the trustStore file. If the server is not configured to support encryption, the driver will raise an error and terminate the connection. |
| true | false or blank | blank | blank | value | The [!INCLUDEjdbcNoVersion] requests to use TLS encryption with the [!INCLUDEssNoVersion]. If the server requires the client to support TLS encryption or if the server supports encryption, the driver will initiate the TLS certificate exchange. The driver will use the trustStorePassword property value to check the integrity of the default trustStore file. If the server is not configured to support encryption, the driver will raise an error and terminate the connection. |
| true | false or blank | blank | value | blank | The [!INCLUDEjdbcNoVersion] requests to use TLS encryption with the [!INCLUDEssNoVersion]. If the server requires the client to support TLS encryption or if the server supports encryption, the driver will initiate the TLS certificate exchange. The driver will use the trustStore property value to look up the location of the trustStore file. If the server is not configured to support encryption, the driver will raise an error and terminate the connection. |
| true | false or blank | value | blank | value | The [!INCLUDEjdbcNoVersion] requests to use TLS encryption with the [!INCLUDEssNoVersion]. If the server requires the client to support TLS encryption or if the server supports encryption, the driver will initiate the TLS certificate exchange. The driver will use the trustStorePassword property value to check the integrity of the default trustStore file. In addition, the driver will use the hostNameInCertificate property value to validate the TLS certificate. If the server is not configured to support encryption, the driver will raise an error and terminate the connection. |
| true | false or blank | value | value | blank | The [!INCLUDEjdbcNoVersion] requests to use TLS encryption with the [!INCLUDEssNoVersion]. If the server requires the client to support TLS encryption or if the server supports encryption, the driver will initiate the TLS certificate exchange. The driver will use the trustStore property value to look up the location of the trustStore file. In addition, the driver will use the hostNameInCertificate property value to validate the TLS certificate. If the server is not configured to support encryption, the driver will raise an error and terminate the connection. |
| true | false or blank | value | value | value | The [!INCLUDEjdbcNoVersion] requests to use TLS encryption with the [!INCLUDEssNoVersion]. If the server requires the client to support TLS encryption or if the server supports encryption, the driver will initiate the TLS certificate exchange. The driver will use the trustStore property value to find the certificate trustStore file and trustStorePassword property value to check the integrity of the trustStore file. In addition, the driver will use the hostNameInCertificate property value to validate the TLS certificate. If the server is not configured to support encryption, the driver will raise an error and terminate the connection. |
If the encrypt property is set to true, the [!INCLUDEjdbcNoVersion] uses the JVM's default JSSE security provider to negotiate TLS encryption with [!INCLUDEssNoVersion]. The default security provider may not support all of the features required to negotiate TLS encryption successfully. For example, the default security provider may not support the size of the RSA public key used in the [!INCLUDEssNoVersion] TLS certificate. In this case, the default security provider might raise an error that will cause the JDBC driver to terminate the connection. In order to resolve this issue, do one of the following:
-
Configure the [!INCLUDEssNoVersion] with a server certificate that has a smaller RSA public key
-
Configure the JVM to use a different JSSE security provider in the "<java-home>/lib/security/java.security" security properties file
-
Use a different JVM
During the TLS handshake, the server sends its public key certificate to the client. The JDBC driver or client has to validate that the server certificate is issued by a certificate authority that the client trusts. The driver requires that the server certificate must meet the following conditions:
-
The certificate was issued by a trusted certificate authority.
-
The certificate must be issued for server authentication.
-
The certificate is not expired.
-
The Common Name (CN) in the Subject or a DNS name in the Subject Alternate Name (SAN) of the certificate exactly matches the serverName value specified in the connection string or, if specified, the hostNameInCertificate property value.
-
A DNS name can include wild card characters. But the [!INCLUDEjdbcNoVersion] does not support wild card matching. That is, abc.com will not match *.com but *.com will match *.com.