Preparing for TLS 1.1 removal

Following industry best practices, Docusign is scheduling the removal of weak ciphers on January 12, 2021, and will stop support for TLSv1.1 on June 9, 2021. This blog post strives to point you in the right direction to ensure you support the new modern secure TLS protocols and cipher suites in integrations and connections to Docusign.

The PCI Security Standards Council has mandated that companies that wish to remain PCI Data Security Standard (PCI DSS) compliant must have transitioned to TLS 1.2 by June of 2020. TLS 1.1 and weak cipher suites are utilized by a small set of customers to support legacy integrations that utilize SOAP or REST APIs. These integrations will need to be updated to support the more secure, modern protocols and ciphers, which can be as easy as recompiling the solution with updated libraries or updating a config file.

Even though you can configure TLS 1.2 in a Web application, it is also a good idea to force the web server to use a minimum security level of TLS 1.2. Microsoft offers these resources: 

• Enable Transport Layer Security (TLS) 1.2 overview - Configuration Manager

• Download Solving the TLS 1.0 Problem from Official Microsoft Download Center

Legacy .NET applications (compiled with an old version of the .NET Framework, such as 4.0 or 4.5) are likely already experiencing connectivity issues with TLS 1.2 servers as they are becoming more and more common, especially since installing a more recent version of the .NET Framework is not sufficient: it's the version used for compiling your project that matters when it comes to selecting the supported TLS versions during the TLS handshake.

One solution is to update your project to target .NET Framework 4.7 or later.  in this case, you'll have nothing else to do, since .NET 4.7+ applications automatically default to whatever the operating system offers and considers safe (which currently includes TLS 1.2 and will later include TLS 1.3). This requires recompiling the application, however, which is not always feasible. You can also force an existing application to use the system default TLS versions without having to recompile (assuming it doesn't explicitly set the SSL/TLS versions it prefers via ServicePointManager).

Another solution is to update the configuration file associated with the application, as it's easy to do and doesn't impact anything else on the machine. For that, locate the configuration file associated with the executable of the application, which is typically named ‘theapplicationname’.exe.config. If there is no such file, create one. Once you've located or created it, update the content to enable the compatibility switch required to support TLS 1.2.

A solution could include the following early in your pipeline, such as your startup.cs or Global.asax:

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

Or ,if you want to specify it only for some requests instead of application-wide, then you can customize the HttpClientHandler of your HttpClient**:**

var handler = new HttpClientHandler { SslProtocols = SslProtocols.Tls12};
HttpClient client = new HttpClient(handler);
…

To make migration easier, Microsoft published a paper, Transport Layer Security (TLS) best practices with the .NET Framework, that lists solutions that help avoid handshake errors related to the use of legacy TLS versions. 

What ciphers are you using?

It is not always easy to determine which ciphers are being offered and accepted without physically watching or by having great telemetry. Here are a couple of methods I have used in the past.

1. Wireshark can be used to monitor and capture the cipher suite negotiation. Select the Client Hello packet in the top pane of the display to drill down to the list of cipher suites offered. 

2. In Windows Server PowerShell, use these Get-TlsCipherSuite cmdlet: 

3. Nmap can be used capture ciphers on a remote endpoint:nmap --script ssl-enum-ciphers -p 443 www.docusign.net 

4. SSL Labs can be used to list all available TLS and ciphers, as a server or a client: https://www.ssllabs.com/ssltest/analyze.html?d=account-d.docusign.com

As you embark on your journey to TLS 1.2 and greater, you will be rewarded with more efficient and secure protocols and ciphers to protect your data. 

Additional resources

• Docusign Developer Center

• @DocuSignAPI on Twitter

• Docusign for Developers on LinkedIn

• Docusign for Developers on YouTube

• Docusign Developer Newsletter