In the TLS connection common causes and troubleshooting guide (microsoft.com) and TLS connection common causes and troubleshooting guide (microsoft.com), the mechanism of establishing SSL/TLS and tools to troubleshoot SSL/TLS connection were introduced. In this article, I would like to introduce 3 common issues that may occur when establishing SSL/TLS connection and corresponding solutions for windows, Linux, .NET and Java.
TLS certificate is not trusted
TLS version mismatch
Before we jump into solutions, let me introduce how TLS version is determined.
As the dataflow introduced in the first session(https://techcommunity.microsoft.com/t5/azure-paas-blog/ssl-tls-connection-issue-troubleshooting-guide/ba-p/2108065), TLS connection is always started from client end, so it is client proposes a TLS version and server only finds out if server itself supports the client's TLS version. If the server supports the TLS version, then they can continue the conversation, if server does not support, the conversation is ended.
Detection
You may test with the tools introduced in this blog(TLS connection common causes and troubleshooting guide (microsoft.com)) to verify if TLS connection issue was caused by TLS version mismatch. If capturing network packet, you can also view TLS version specified in Client Hello. If connection terminated without Server Hello, it could be either TLS version mismatch or Ciphersuite mismatch.
Solution
Different types of clients have their own mechanism to determine TLS version. For example, Web browsers - IE, Edge, Chrome, Firefox have their own set of TLS versions. Applications have their own library to define TLS version. Operating system level like windows also supports to define TLS version.
- Web browser
In the latest Edge and Chrome, TLS 1.0 and TLS 1.1 are deprecated. TLS 1.2 is the default TLS version for these 2 browsers. Below are the steps of setting TLS version in Internet Explorer and Firefox and are working in Window 10.
- Internet Explorer
- Search Internet Options
- Find the setting in the Advanced tab.
- Firefox
- Open Firefox, type about:config in the address bar.
- Type tls in the search bar, find the setting of security.tls.version.min and security.tls.version.max.
The value is the range of supported tls version. 1 is for tls 1.0, 2 is for tls 1.1, 3 is for tls 1.2, 4 is for tls 1.3.
- Windows System
Different windows OS versions have different default TLS versions. The default TLS version can be override by adding/editing DWORD registry values ‘Enabled’ and ‘DisabledByDefault’. These registry values are configured separately for the protocol client and server roles under the registry subkeys named using the following format:
<SSL/TLS/DTLS> <major version number>.<minor version number><Client\Server>
For example, below is the registry paths with version-specific subkeys:
Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client
For the details, please refer to Transport Layer Security (TLS) registry settings | Microsoft Learn.
- Application that running with .NET framework
The application uses OS level configuration by default. For a quick test for http requests, you can add the below line to specify the TLS version in your application before TLS connection is established. To be on a safer end, you may define it in the beginning of the project.
ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12
Above can be used as a quick test to verify the problem, it is always recommended to follow below document for best practices.
https://docs.microsoft.com/en-us/dotnet/framework/network-programming/tls
- Java Application
For the Java application which uses Apache HttpClient to communicate with HTTP server, you may check link How to Set TLS Version in Apache HttpClient | Baeldung about how to set TLS version in code.
Cipher suite mismatch
Like TLS version mismatch, CipherSuite mismatch can also be tested with the tools that introduced in previous article.
Detection
In the network packet, the connection is terminated after Client Hello, so if you do not see a Server Hello packet, that indicates either TLS version mismatch or ciphersuite mismatch.
If server is supported public access, you can also test using SSLLab(https://www.ssllabs.com/ssltest/analyze.html) to detect all supported CipherSuite.
Solution
From the process of establishing SSL/TLS connections, the server has final decision of choosing which CipherSuite in the communication. Different Windows OS versions support different TLS CipherSuite and priority order. For the supported CipherSuite, please refer to Cipher Suites in TLS/SSL (Schannel SSP) - Win32 apps | Microsoft Learn for details.
If a service is hosted in Windows OS. the default order could be override by below group policy to affect the logic of choosing CipherSuite to communicate. The steps are working in the Windows Server 2019.
- Edit group policy -> Computer Configuration > Administrative Templates > Network > SSL Configuration Settings -> SSL Cipher Suite Order.
- Enable the configured with the priority list for all cipher suites you want.
The CipherSuites can be manipulated by command as well. Please refer to TLS Module | Microsoft Learn for details.
TLS certificate is not trusted
Detection
Access the url from web browser. It does not matter if the page can be loaded or not. Before loading anything from the remote server, web browser tries to establish TLS connection. If you see the error below returned, it means certificate is not trusted on current machine.
Solution
To resolve this issue, we need to add the CA certificate into client trusted root store.
The CA certificate can be got from web browser.
- Click warning icon -> the warning of ‘isn’t secure’ in the browser.
- Click ‘show certificate’ button.
- Export the certificate.
Import the exported crt file into client system.
- Windows
- Manage computer certificates.
- Trusted Root Certification Authorities -> Certificates -> All Tasks -> Import. Select the exported crt file with other default setting.
- Ubuntu
Below command is used to check current trust CA information in the system.
awk -v cmd='openssl x509 -noout -subject' ' /BEGIN/{close(cmd)};{print | cmd}' < /etc/ssl/certs/ca-certificates.crt
If you did not see desired CA in the result, the commands below are used to add new CA certificates.
$ sudo cp <exported crt file> /usr/local/share/ca-certificates
$ sudo update-ca-certificates
- RedHat/CentOS
Below command is used to check current trust CA information in the system.
awk -v cmd='openssl x509 -noout -subject' ' /BEGIN/{close(cmd)};{print | cmd}' < /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem
If you did not see desired CA in the result, the commands below are used to add new CA certificates.
sudo cp <exported crt file> /etc/pki/ca-trust/source/anchors/
sudo update-ca-trust
- Java
The JVM uses a trust store which contains certificates of well-known certification authorities. The trust store on the machine may not contain the new certificates that we recently started using. If this is the case, then the Java application would receive SSL failures when trying to access the storage endpoint. The errors would look like the following:
Exception in thread "main" java.lang.RuntimeException: javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
at org.example.App.main(App.java:54)
Caused by: javax.net.ssl.SSLHandshakeException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
at java.base/sun.security.ssl.Alert.createSSLException(Alert.java:130)
at java.base/sun.security.ssl.TransportContext.fatal(TransportContext.java:371)
at java.base/sun.security.ssl.TransportContext.fatal(TransportContext.java:314)
at java.base/sun.security.ssl.TransportContext.fatal(TransportContext.java:309)
Run the below command to import the crt file to JVM cert store. The command is working in the JDK 19.0.2.
keytool -importcert -alias <alias> -keystore "<JAVA_HOME>/lib/security/cacerts" -storepass changeit -file <crt_file>
Below command is used to export current certificates information in the JVM cert store.
keytool -keystore " <JAVA_HOME>\lib\security\cacerts" -list -storepass changeit > cert.txt
The certificate will be displayed in the cert.txt file if it was imported successfully.
Microsoft
