Troubleshooting applications that don't support TLS 1.2
Important
Cloud Services (classic) is now deprecated for new customers and will be retired on August 31st, 2024 for all customers. New deployments should use the new Azure Resource Manager based deployment model Azure Cloud Services (extended support).
This article describes how to enable the older TLS protocols (TLS 1.0 and 1.1) as well as applying legacy cipher suites to support the additional protocols on the Windows Server 2019 cloud service web and worker roles.
We understand that while we are taking steps to deprecate TLS 1.0 and TLS 1.1, our customers may need to support the older protocols and cipher suites until they can plan for their deprecation. While we don't recommend re-enabling these legacy values, we are providing guidance to help customers. We encourage customers to evaluate the risk of regression before implementing the changes outlined in this article.
Note
Guest OS Family 6 release enforces TLS 1.2 by explicitly disabling TLS 1.0 and 1.1 and defining a specific set of cipher suites.For more information on Guest OS families see Guest OS release news
Dropping support for TLS 1.0, TLS 1.1 and older cipher suites
In support of our commitment to use best-in-class encryption, Microsoft announced plans to start migration away from TLS 1.0 and 1.1 in June of 2017. Since that initial announcement, Microsoft announced our intent to disable Transport Layer Security (TLS) 1.0 and 1.1 by default in supported versions of Microsoft Edge and Internet Explorer 11 in the first half of 2020. Similar announcements from Apple, Google, and Mozilla indicate the direction in which the industry is headed.
For more information, see Preparing for TLS 1.2 in Microsoft Azure
TLS configuration
The Windows Server 2019 cloud server image is configured with TLS 1.0 and TLS 1.1 disabled at the registry level. This means applications deployed to this version of Windows AND using the Windows stack for TLS negotiation will not allow TLS 1.0 and TLS 1.1 communication.
The server also comes with a limited set of cipher suites:
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
Step 1: Create the PowerShell script to enable TLS 1.0 and TLS 1.1
Use the following code as an example to create a script that enables the older protocols and cipher suites. For the purposes of this documentation, this script will be named: TLSsettings.ps1. Store this script on your local desktop for easy access in later steps.
# You can use the -SetCipherOrder (or -sco) option to also set the TLS cipher
# suite order. Change the cipherorder variable below to the order you want to set on the
# server. Setting this requires a reboot to take effect.
Param(
[parameter(Mandatory=$false)]
[alias("sco")]
[switch]$SetCipherOrder)
Function DisableRC4 {
param ( $restart)
$subkeys = Get-Item -Path "HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL"
$ciphers = $subkeys.OpenSubKey("Ciphers", $true)
if($ciphers.SubKeyCount -eq 0) {
$k1 = $ciphers.CreateSubKey("RC4 128/128")
$k1.SetValue("Enabled", 0, [Microsoft.Win32.RegistryValueKind]::DWord)
$restart = $true
$k2 = $ciphers.CreateSubKey("RC4 64/128")
$k2.SetValue("Enabled", 0, [Microsoft.Win32.RegistryValueKind]::DWord)
$k3 = $ciphers.CreateSubKey("RC4 56/128")
$k3.SetValue("Enabled", 0, [Microsoft.Win32.RegistryValueKind]::DWord)
$k4 = $ciphers.CreateSubKey("RC4 40/128")
$k4.SetValue("Enabled", 0, [Microsoft.Win32.RegistryValueKind]::DWord)
}
$restart
}
Function Set-CryptoSetting {
param (
$keyindex,
$value,
$valuedata,
$valuetype,
$restart
)
# Check for existence of registry key, and create if it does not exist
If (!(Test-Path -Path $regkeys[$keyindex])) {
New-Item $regkeys[$keyindex] | Out-Null
}
# Get data of registry value, or null if it does not exist
$val = (Get-ItemProperty -Path $regkeys[$keyindex] -Name $value -ErrorAction SilentlyContinue).$value
If ($null -eq $val) {
# Value does not exist - create and set to desired value
New-ItemProperty -Path $regkeys[$keyindex] -Name $value -Value $valuedata -PropertyType $valuetype | Out-Null
$restart = $True
Write-Host "Configuring $regkeys[$keyindex]...."
} Else {
# Value does exist - if not equal to desired value, change it
If ($val -ne $valuedata) {
Set-ItemProperty -Path $regkeys[$keyindex] -Name $value -Value $valuedata
$restart = $True
Write-Host "Configuring $regkeys[$keyindex]..."
}
}
$restart
}
$regkeys = @(
"HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.0",
"HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.0\Client",
"HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.0\Server", #2
"HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.1",
"HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.1\Client", #4
"HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.1\Server",
"HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2", #6
"HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client",
"HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server", #8
"HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\SSL 2.0",
"HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\SSL 2.0\Client", #10
"HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\SSL 2.0\Server",
"HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\SSL 3.0", #12
"HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\SSL 3.0\Client",
"HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\SSL 3.0\Server", #14
"HKLM:\SOFTWARE\Policies\Microsoft\Cryptography\Configuration\SSL\00010002"
)
Function Set-Windows10PlusCurveOrder {
param ( $reboot)
$desiredOrder = "NistP384;NistP256".Split(";")
If ([Environment]::OSVersion.Version.Major -ge 10) {
If (!(Test-Path -Path $regkeys[15])) {
New-Item $regkeys[15] | Out-Null
$reboot = $True
}
$val = (Get-Item -Path $regkeys[15] -ErrorAction SilentlyContinue).GetValue("EccCurves", $null)
if( $null -eq $val) {
New-ItemProperty -Path $regkeys[15] -Name EccCurves -Value $desiredOrder -PropertyType MultiString | Out-Null
$reboot = $True
} else {
if ([System.String]::Join(';', $val) -ne [System.String]::Join(';', $desiredOrder)) {
Write-Host "The original curve order ", `n, $val, `n, "needs to be updated to ", $desiredOrder
Set-ItemProperty -Path $regkeys[15] -Name EccCurves -Value $desiredOrder
$reboot = $True
}
}
}
$reboot
}
If ([Environment]::OSVersion.Version.Major -lt 10) {
# This is for Windows before 10
Write-Host "Configuring Windows before 10..."
$cipherorder = "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384_P384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256_P256,"
$cipherorder += "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384_P384,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256_P256,"
$cipherorder += "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384_P256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256_P256,"
$cipherorder += "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA_P256,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA_P256,"
$cipherorder += "TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256,"
$cipherorder += "TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,"
$cipherorder += "TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA"
} Else {
# this is for windows 10 or above
Write-Host "Configuring Windows 10+..."
$cipherorder = "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,"
$cipherorder += "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,"
$cipherorder += "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,"
$cipherorder += "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,"
$cipherorder += "TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,"
$cipherorder += "TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,"
$cipherorder += "TLS_RSA_WITH_AES_256_GCM_SHA384,TLS_RSA_WITH_AES_128_GCM_SHA256,"
$cipherorder += "TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,"
$cipherorder += "TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA"
}
# If any settings are changed, this will change to $True and the server will reboot
$reboot = $False
# Check for existence of registry keys (SSL 2.0, SSL 3.0, TLS 1.0, TLS 1.1, TLS 1.2), and create if they do not exist
For ($i = 0; $i -le 14; $i = $i + 1) {
If (!(Test-Path -Path $regkeys[$i])) {
New-Item $regkeys[$i] | Out-Null
}
}
# Ensure SSL 2.0 disabled for client/server
$reboot = Set-CryptoSetting 10 DisabledByDefault 1 DWord $reboot
$reboot = Set-CryptoSetting 10 Enabled 0 DWord $reboot
$reboot = Set-CryptoSetting 11 DisabledByDefault 1 DWord $reboot
$reboot = Set-CryptoSetting 11 Enabled 0 DWord $reboot
# Ensure SSL 3.0 disabled for client/server
$reboot = Set-CryptoSetting 13 DisabledByDefault 1 DWord $reboot
$reboot = Set-CryptoSetting 13 Enabled 0 DWord $reboot
$reboot = Set-CryptoSetting 14 DisabledByDefault 1 DWord $reboot
$reboot = Set-CryptoSetting 14 Enabled 0 DWord $reboot
# Ensure TLS 1.0 enabled for client/server
$reboot = Set-CryptoSetting 1 DisabledByDefault 0 DWord $reboot
$reboot = Set-CryptoSetting 1 Enabled 1 DWord $reboot
$reboot = Set-CryptoSetting 2 DisabledByDefault 0 DWord $reboot
$reboot = Set-CryptoSetting 2 Enabled 1 DWord $reboot
# Ensure TLS 1.1 enabled for client/server
$reboot = Set-CryptoSetting 4 DisabledByDefault 0 DWord $reboot
$reboot = Set-CryptoSetting 4 Enabled 1 DWord $reboot
$reboot = Set-CryptoSetting 5 DisabledByDefault 0 DWord $reboot
$reboot = Set-CryptoSetting 5 Enabled 1 DWord $reboot
# Ensure TLS 1.2 enabled for client/server
$reboot = Set-CryptoSetting 7 DisabledByDefault 0 DWord $reboot
$reboot = Set-CryptoSetting 7 Enabled 1 DWord $reboot
$reboot = Set-CryptoSetting 8 DisabledByDefault 0 DWord $reboot
$reboot = Set-CryptoSetting 8 Enabled 1 DWord $reboot
$reboot = DisableRC4($reboot)
If ($SetCipherOrder) {
If (!(Test-Path -Path $regkeys[15])) {
New-Item $regkeys[15] | Out-Null
$reboot = $True
}
$val = (Get-Item -Path $regkeys[15] -ErrorAction SilentlyContinue).GetValue("Functions", $null)
if ($val -ne $cipherorder)
{
Write-Host "The original cipher suite order needs to be updated", `n, $val
Set-ItemProperty -Path $regkeys[15] -Name Functions -Value $cipherorder
$reboot = $True
}
}
$reboot = Set-Windows10PlusCurveOrder $reboot
If ($reboot) {
# Randomize the reboot timing since it could be run in a large cluster.
$tick = [System.Int32]([System.DateTime]::Now.Ticks % [System.Int32]::MaxValue)
$rand = [System.Random]::new($tick)
$sec = $rand.Next(30, 600)
Write-Host "Rebooting after", $sec, " second(s)..."
Write-Host "shutdown.exe /r /t $sec /c ""Crypto settings changed"" /f /d p:2:4"
shutdown.exe /r /t $sec /c "Crypto settings changed" /f /d p:2:4
} Else {
Write-Host "Nothing get updated."
}
Step 2: Create a command file
Create a CMD file named RunTLSSettings.cmd using the below. Store this script on your local desktop for easy access in later steps.
SET LOG_FILE="%TEMP%\StartupLog.txt"
SET EXECUTE_PS1=0
IF "%ComputeEmulatorRunning%" == "" (
SET EXECUTE_PS1=1
)
IF "%ComputeEmulatorRunning%" == "false" (
SET EXECUTE_PS1=1
)
IF %EXECUTE_PS1% EQU 1 (
echo "Invoking TLSsettings.ps1 on Azure service at %TIME% on %DATE%" >> %LOG_FILE% 2>&1
PowerShell -ExecutionPolicy Unrestricted %~dp0TLSsettings.ps1 -sco >> %LOG_FILE% 2>&1
) ELSE (
echo "Skipping TLSsettings.ps1 invocation on emulated environment" >> %LOG_FILE% 2>&1
)
EXIT /B %ERRORLEVEL%
Step 3: Add the startup task to the role's service definition (csdef)
Add the following snippet to your existing service definition file.
<Startup>
<Task executionContext="elevated" taskType="simple" commandLine="RunTLSSettings.cmd">
</Task>
</Startup>
Here is an example that shows both the worker role and web role.
<?xmlversion="1.0" encoding="utf-8"?>
<ServiceDefinitionname="CloudServiceName" xmlns="http://schemas.microsoft.com/ServiceHosting/2008/10/ServiceDefinition" schemaVersion="2015-04.2.6">
<WebRolename="WebRole1" vmsize="Standard_D1_v2">
<Sites>
<Sitename="Web">
<Bindings>
<Bindingname="Endpoint1" endpointName="Endpoint1"/>
</Bindings>
</Site>
</Sites>
<Startup>
<Task executionContext="elevated" taskType="simple" commandLine="RunTLSSettings.cmd">
</Task>
</Startup>
<Endpoints>
<InputEndpointname="Endpoint1" protocol="http" port="80"/>
</Endpoints>
</WebRole>
<WorkerRolename="WorkerRole1" vmsize="Standard_D1_v2">
<Startup>
<Task executionContext="elevated" taskType="simple" commandLine="RunTLSSettings.cmd">
</Task>
</Startup>
</WorkerRole>
</ServiceDefinition>
Step 4: Add the scripts to your Cloud Service
- In Visual Studio, right-click on your WebRole or WorkerRole
- Select Add
- Select Existing Item
- In the file explorer, navigate to your desktop where you stored the TLSsettings.ps1 and RunTLSSettings.cmd files
- Select the two files to add them to your Cloud Services project
Step 5: Enable Copy to Output Directory
To ensure the scripts are uploaded with every update pushed from Visual Studio, the setting Copy to Output Directory needs to be set to Copy Always
- Under your WebRole or WorkerRole, right-click on RunTLSSettings.cmd
- Select Properties
- In the properties tab, change Copy to Output Directory to Copy Always"
- Repeat the steps for TLSsettings.ps1
Step 6: Publish & Validate
Now that the above steps have been complete, publish the update to your existing Cloud Service.
You can use SSLLabs to validate the TLS status of your endpoints
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for