Understanding SSL Support
When connecting to SQL Server, if the application requests encryption and the instance of SQL Server is configured to support SSL encryption, the Microsoft SQL Server JDBC Driver initiates the SSL handshake. The handshake allows the server and client to negotiate the encryption and cryptographic algorithms to be used to protect data. After the SSL handshake is complete, the client and server can send the encrypted data securely. During SSL 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 Microsoft SQL Server JDBC Driver will not force SQL Server to support SSL encryption. If the SQL Server instance is not configured to force the SSL encryption, a connection is established without encryption. If the SQL Server instance is configured to force the SSL encryption, the driver will automatically enable SSL encryption when running on properly configured Java Virtual Machine (JVM), or else the connection is terminated and the driver will raise an error.
Note
For more information about how to configure SSL for SQL Server, see the Encrypting Connections to SQL Server topic in SQL Server Books Online.
In order to allow applications to use SSL encryption, the Microsoft SQL Server JDBC Driver 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 Microsoft SQL Server JDBC Driver version behaves for possible SSL connection scenarios. Each scenario uses a different set of SSL 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 SQL Server user authentication and Windows integrated authentication.
| encrypt | trustServerCertificate | hostNameInCertificate | trustStore | trustStorePassword | Behavior |
|---|---|---|---|---|---|
false or blank |
any |
any |
any |
any |
The Microsoft SQL Server JDBC Driver will not force SQL Server to support SSL encryption. If the server has a self-signed certificate, the driver initiates the SSL certificate exchange. The SSL certificate will not be validated and only the credentials (in the login packet) are encrypted. If the server requires the client to support SSL encryption, the driver will initiate the SSL certificate exchange. The SSL certificate will not be validated, but the entire communication will be encrypted. |
true |
true |
any |
any |
any |
The Microsoft SQL Server JDBC Driver requests to use SSL encryption with the SQL Server. If the server requires the client to support SSL encryption or if the server supports encryption, the driver will initiate the SSL certificate exchange. Note that if the trustServerCertificate property is set to "true", the driver will not validate the SSL 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 Microsoft SQL Server JDBC Driver requests to use SSL encryption with the SQL Server. If the server requires the client to support SSL encryption or if the server supports encryption, the driver will initiate the SSL certificate exchange. The driver will use the serverName property specified on the connection URL to validate the server SSL 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 Microsoft SQL Server JDBC Driver requests to use SSL encryption with the SQL Server. If the server requires the client to support SSL encryption or if the server supports encryption, the driver will initiate the SSL certificate exchange. The driver will validate the SSL 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 Microsoft SQL Server JDBC Driver requests to use SSL encryption with the SQL Server. If the server requires the client to support SSL encryption or if the server supports encryption, the driver will initiate the SSL 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 Microsoft SQL Server JDBC Driver requests to use SSL encryption with the SQL Server. If the server requires the client to support SSL encryption or if the server supports encryption, the driver will initiate the SSL 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 Microsoft SQL Server JDBC Driver requests to use SSL encryption with the SQL Server. If the server requires the client to support SSL encryption or if the server supports encryption, the driver will initiate the SSL 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 Microsoft SQL Server JDBC Driver requests to use SSL encryption with the SQL Server. If the server requires the client to support SSL encryption or if the server supports encryption, the driver will initiate the SSL 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 SSL 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 Microsoft SQL Server JDBC Driver requests to use SSL encryption with the SQL Server. If the server requires the client to support SSL encryption or if the server supports encryption, the driver will initiate the SSL 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 SSL 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 Microsoft SQL Server JDBC Driver requests to use SSL encryption with the SQL Server. If the server requires the client to support SSL encryption or if the server supports encryption, the driver will initiate the SSL 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 SSL 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 Microsoft SQL Server JDBC Driver uses the JVM's default JSSE security provider to negotiate SSL encryption with SQL Server. The default security provider may not support all of the features required to negotiate SSL encryption successfully. For example, the default security provider may not support the size of the RSA public key used in the SQL Server SSL 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 SQL Server 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
Validating Server SSL Certificate
During SSL 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 subject property of the certificate indicates that the common name (CN) begins with the server name specified in the connection string or, if specified, the hostNameInCertificate property value. If the server name is an IP address, the driver validates that the CN value begins with the IP address.