Azure SQL Database TLS Handshake Error after v12 Upgrade

You may encounter a TLS Handshake error after an Azure SQL Database instance is upgraded to v12. This error occurs when the certificate presented by the server doesn't match the hostname specified in the client's connection string.

Error Details

The error message typically indicates that the certificate is valid for a hostname other than the one used in the client connection. For example:

TLS Handshake failed: x509: certificate is valid for
tr12.northcentralus1-a.worker.database.windows.net,
*.tr12.northcentralus1-a.worker.database.windows.net, not [server-name].database.windows.net

Solution

To resolve this issue, update the client connection string to include the following parameters:

• TrustServerCertificate=True: This parameter tells the client to trust the server's certificate, even if it doesn't match the hostname.
• hostNameInCertificate=*.database.windows.net: This parameter specifies the hostname that should be present in the server's certificate.

Updated Connection String

The updated connection string should look something like this:

Server=[server-name].database.windows.net;Port=1433;Database=[dbname];User
ID=[user];Password=[pass];Trusted_Connection=False;Encrypt=True;Connection
Timeout=30;TrustServerCertificate=True;hostNameInCertificate=*.database.windows.net;

Explanation

In previous versions of Azure SQL Database, the server's certificate always matched the hostname specified in the client connection string. However, in v12, this is no longer guaranteed. By setting TrustServerCertificate to True and specifying the correct hostname in hostNameInCertificate, you can instruct the client to accept the certificate and establish the connection properly.

Note:

Although the Azure portal suggests setting TrustServerCertificate to False, this may lead to TLS Handshake errors in some cases. If you encounter these errors, setting TrustServerCertificate to True and adding hostNameInCertificate to the connection string should resolve the issue.