(.NET) Enable SSL Protocols for your Integrations – TLS 1.1 and TLS 1.2

Introduction

When developing integrations with external services (REST, SOAP), there is often the need to use specific SSL protocols, namely:

  • TLS 1.1
  • TLS 1.2.

While trying to use those API’s in OutSystems applications, such attempts to integrate may not work, and produce errors like:

  • The request was aborted: Could not create SSL/TLS secure channel.
  • Unsupported procotol. You need to enable TLS X.X to use this API

(other types of errors may occur, related to the required SSL protocols)

TLS 1.0 is no longer secure. Exploits exist to downgrade a connection based on TLS 1.0 to an older version of the protocol. There is no active exploit affecting all of TLS 1.1, but the downgrade attack works on some versions and installations and academically speaking, TLS 1.1’s hash functions are under threat.

If using an older SSL/TLS protocol revision you could have someone sitting on the line and taking in your data while absolutely nothing about the connection indicated it. A compromised secure connection is no different from an insecure connection, but may give a false sense of security.

The revision and deprecation of protocols is an expected, occasional thing, as encryption techniques improve and processing speeds increase over time. This deprecation and notice is for our customers’ security. Anyone keeping up with the latest developments will already be secure, but those who have not kept up to date could end up using an insecure method.

What is TLS?

Transport Layer Security (TLS) is a protocol that ensures privacy between communicating applications and their users on the Internet. When a server and client communicate, TLS ensures that no third-party may eavesdrop or tamper with any message. TLS is the successor to the Secure Sockets Layer (SSL).

Technical Resources:

Why do you see those errors

.NET Framework 4.5 (and older) uses, by default, two SSL Protocols: SSL v3 and TLS 1.0.

 

Solution

It is possible for you to enable the protocol you need and include it in the request. That can be achieved through two steps:

  • A. Enable the TLS protocols on the server, as “Client”;

and one of the following:

  • B1. Enable the SchUseStrongCrypto property in the Windows registry to use as the default protocols: TLS 1.0, TLS 1.1 and TLS 1.2
  • B2. Include the TLS 1.1 and/or TLS 1.2 protocols in your application code, before the request to the API.

Note that, for cloud customers, option B2 is the only one available.

A. Enable the TLS protocols on the server, as “Client”

ProtocolsTo enable the TLS protocols, you need to add new registry entries for the Schannel [1]

For that, please follow this steps:

  1. Start the registry editor by clicking on Start and Run. Type in “regedit” into the Run field (without quotations).
  2. Highlight Computer at the top of the registry tree.  Backup the registry first by clicking on File and then on Export.  Select a file location to save the registry file.

    Note: You will be editing the registry.  This could have detrimental effects on your computer if done incorrectly, so it is strongly EnableProtocoladvised to make a backup.

  3. Browse to the following registry key:
    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols
  4. Right click on the Protocols folder and select New and then Key from the drop-down menu. This will create new folder.  Rename this folder to TLS 1.1 or TLS 1.2 (depending on the protocol you want to enable)
  5. Right click on the TLS 1.1 or TLS 1.2 key and add a new key underneath it.
  6. Rename the new key as:
    • Client
  7. Right click on the Client key and select New and then DWORD (32-bit) Value from the drop-down list.
  8. Rename the DWORD to DisabledByDefault.
  9. Right-click the name DisabledByDefault and select Modify… from the drop-down menu.
  10. Ensure that the Value data field is set to 0 and the Base is Hexadecimal.  Click on OK.
  11. Create another DWORD for the Client key as you did in Step 7.
  12. Rename this second DWORD to Enabled.
  13. Right-click the name Enabled and select Modify… from the drop-down menu.
  14. Ensure that the Value data field is set to 1 and the Base is Hexadecimal. Click on OK.
  15. Reboot the server

After the reboot, the server will be able to communicate through the SSL protocol you enabled. However, you need now to add it to your applications requests.

 

B1. Enable the SchUseStrongCrypto property in the Windows registry to use as the default protocols: TLS 1.0, TLS 1.1 and TLS 1.2

If you want to make sure strong cryptography is enabled and the SSL protocols for your requests to be TLS 1.0, TLS 1.1 and TLS 1.2, please follow this steps:

  1. Start the registry editor by clicking on Start and Run. Type in “regedit” into the Run field (without quotations).
  2. Highlight Computer at the top of the registry tree.  Backup the registry first by clicking on File and then on Export.  Select a file location to save the registry file.

    Note: You will be editing the registry.  This could have detrimental effects on your computer if done incorrectly, so it is strongly advised to make a backup.

  3. Browse to the following registry key:
    HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NetFramework\v4.0.30319
  4. Right-click on the right pane and create a new DWORD (32-bit) Value with Name SchUseStrongCrypto.
  5. Ensure that the Value data field is set to 1 and the Base is Hexadecimal. Click on OK.
  6. Repeat steps 4 and 5 for the registry key: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NetFramework\v4.0.30319
  7. Reboot the server

Compatibility diagram

This diagram illustrates which technologies will require only testing, a potential reconfiguration, or major changes to your integration:tls1-2.png

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.