Configure TLS protocol

Problem

You want to configure your .NET application environment to handle external HTTP requests via a specific version of TLS (for example, TLS 1.1 or 1.2).

If your environment is not configured properly for allowing SSL/TLS communication, it may not allow the New Relic .NET agent to communicate with New Relic. There are many possible error messages that can be caused by this problem, including:

NewRelic ERROR: Unable to connect to the New Relic service at collector.newrelic.com:443 : System.Net.WebException: 
The request was aborted: Could not create SSL/TLS secure channel.
NewRelic ERROR: Unable to connect to the New Relic service at collector.newrelic.com:443 : System.Net.WebException: 
The underlying connection was closed: An unexpected error occurred on a send. ---> System.IO.IOException: 
Received an unexpected EOF or 0 bytes from the transport stream.
NewRelic ERROR: Unable to connect to the New Relic service at collector.newrelic.com:443 : System.Net.WebException: 
The underlying connection was closed: An unexpected error occurred on a receive. ---> System.ComponentModel.Win32Exception: 
The client and server cannot communicate, because they do not possess a common algorithm.

Solution

You can configure your .NET environment's security protocols, including setting a default TLS version.

If you set a TLS version as default, it will be used by both the application and the New Relic agent. It's not possible for it to use a different TLS version for each.

Enable a specific TLS version protocol with these steps:

Step 1. Enable TLS protocols in Windows registry.

Follow these steps carefully. Serious problems may occur if you modify the registry incorrectly. Before you modify it, it's recommended you back up the registry.

Older versions of Windows Server (2008/2012) may not have TLS 1.1/1.2 support enabled by default.

Here's an example of how to update Windows registry to TLS 1.2:

  1. Copy and paste the following into a file:

    Windows Registry Editor Version 5.00
    
    [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2]
    
    [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client]
    "DisabledByDefault"=dword:00000000
    "Enabled"=dword:00000001
    
  2. Save the file with a .reg extension.
  3. Run the script.
Step 2. Turn on .NET default protocols

.NET Frameworks 4.5 or lower use protocols SSL v3 and TLS 1.0 by default.

After you've enabled TLS 1.1 or 1.2 via the server, you still need to change the default protocols used by .NET.

Choose one of the following options:

Enable strong crypto property in Windows registry

Follow these steps carefully. Serious problems may occur if you modify the registry incorrectly. Before you modify it, it's recommended you back up the registry.

If you want to make sure strong cryptography is enabled and that the SSL protocol is TLS 1.0, TLS 1.1 or TLS 1.2, follow these steps:

  1. Copy and paste the following into a file:

    Windows Registry Editor Version 5.00
    
    [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\.NETFramework\v4.0.30319] 
    "SchUseStrongCrypto"=dword:00000001
    
    [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319]
    "SchUseStrongCrypto"=dword:00000001
    
  2. Save the file with a .reg extension.
  3. Run the script.
Include protocol in your app code

You can change .NET's default security protocols by modifying your application's source code. The following command enables TLS 1.2, 1.1, and 1.0 as default protocols for your application. It's a global setting and should be set early in your application's start-up. You can modify it to enable the specific protocols you want.

System.Net.ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12 | SecurityProtocolType.Tls11 | SecurityProtocolType.Tls;

Cause

If you require a specific version of TLS for external HTTP requests, then you must make sure your application and server are configured correctly. Not having proper configuration can lead to the New Relic .NET agent not being able to connect to New Relic.

New Relic's .NET agent communicates with New Relic servers using standard classes available with .NET for making external HTTP requests. Because the New Relic agent code runs alongside your application code, the security protocols used for communicating with New Relic servers depend on your application's environment and configuration.

For more information on correctly configuring your system or application's TLS settings depending on your version of the .NET Framework, review Microsoft's documentation on (TLS) best practices.

For more help

Recommendations for learning more: