From ea741b10ecc0549902a8e9ac0055a5643ab43d82 Mon Sep 17 00:00:00 2001 From: jagilber Date: Wed, 29 Oct 2025 10:04:30 -0400 Subject: [PATCH 1/8] Update TLS Configuration.md with TLS 1.3 support and deprecation notices - Add TLS 1.3 requirements (SF 10.1CU2+, Windows Server 2022, .NET 4.8+) - Add Service Fabric TLS 1.3 cluster configuration section - Update registry configuration for TLS 1.3 protocol and cipher suites - Add deprecation warnings for TLS 1.0/1.1 (retiring Aug 31, 2025) - Remove/mark deprecated cipher suites (DHE, 3DES, RC4) - Update .NET Framework guidance with version compatibility table - Add comprehensive troubleshooting section with PowerShell scripts - Update Linux section with OpenSSL 1.1.1+ TLS 1.3 support - Modernize all reference links to learn.microsoft.com - Document expanded from 264 to 760 lines --- Security/TLS Configuration.md | 637 +++++++++++++++++++++++++++++++--- 1 file changed, 583 insertions(+), 54 deletions(-) diff --git a/Security/TLS Configuration.md b/Security/TLS Configuration.md index 24db02c4..655a8943 100644 --- a/Security/TLS Configuration.md +++ b/Security/TLS Configuration.md @@ -1,10 +1,91 @@ -# How to configure Service Fabric or Applications to use a specific TLS version +# How to configure Service Fabric or Applications to use TLS 1.2 and TLS 1.3 -Below list some of the options available for configuring TLS and cipher suites. These steps are not specific to Service Fabric and may need to be modified depending on environment and applications being used. +> **IMPORTANT DEPRECATION NOTICE** +> **TLS 1.0 and TLS 1.1 are officially deprecated** as per [RFC 8996](https://datatracker.ietf.org/doc/rfc8996/) and will be retired across all Azure services on **August 31, 2025**. Microsoft strongly recommends migrating to TLS 1.2 as the minimum supported version, with TLS 1.3 recommended for new deployments. + +## TLS 1.3 Support in Service Fabric + +Azure Service Fabric supports **TLS 1.3** starting with version **10.1CU2 (10.1.1951.9590)** and later. TLS 1.3 offers significant security and performance improvements: + +- **Enhanced Security**: Improved cryptographic algorithms, removal of weak cipher suites, and encrypted handshakes +- **Faster Handshakes**: Reduced round trips (1-RTT vs 2-RTT for TLS 1.2) +- **Simplified Cipher Suites**: Only two secure cipher suites (TLS_AES_256_GCM_SHA384 and TLS_AES_128_GCM_SHA256) +- **Forward Secrecy**: All TLS 1.3 connections provide perfect forward secrecy + +### Prerequisites for TLS 1.3 + +To use TLS 1.3 in Service Fabric clusters: + +1. **Service Fabric Runtime**: Version 10.1CU2 (10.1.1951.9590) or later +2. **Operating System**: Windows Server 2022 or later (TLS 1.3 requires OS-level support) +3. **API Version**: + - Managed Clusters: API version 2023-12-01-preview or later + - Classic Clusters: API version 2023-11-01-preview or later +4. **.NET Framework**: .NET Framework 4.8 or later for application support + +For complete migration guidance, see [Migrate Azure Service Fabric to TLS 1.3](https://learn.microsoft.com/en-us/azure/service-fabric/how-to-migrate-transport-layer-security). + +## Configuration Options Overview + +Below are the available options for configuring TLS protocols and cipher suites. These steps apply to both Service Fabric infrastructure and hosted applications, though specific configurations may need to be adapted based on your environment. ## Option 1 - Machine wide configuration in registry -- This configuration is machine wide restricting OS and applications enforcing TLS 1.2 and secure ciphers. This option uses Custom Script Extension with extension sequencing and Powershell script. [../Scripts/vmss-cse-tls.ps1](../Scripts/vmss-cse-tls.ps1) should be saved to a storage location that is accessible from the Service Fabric nodes during deployment. This script is based off of [Troubleshooting applications that don't support TLS 1.2](https://learn.microsoft.com/en-us/azure/cloud-services/applications-dont-support-tls-1-2) and has been modified to only enable TLS 1.2. Additionally, RC4 and 3DES ciphers have been disabled. +This configuration is machine-wide, restricting the OS and all applications to use TLS 1.2 or higher with secure cipher suites. For TLS 1.3 support, ensure you're running Windows Server 2022 or later with Service Fabric 10.1CU2+. + +### TLS Protocol Configuration + +TLS protocols are configured via registry keys under `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols`. Each protocol version requires specific DWORD values: + +**For TLS 1.3** (Windows Server 2022+ only): +```registry +[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.3\Server] +"Enabled"=dword:00000001 +"DisabledByDefault"=dword:00000000 + +[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.3\Client] +"Enabled"=dword:00000001 +"DisabledByDefault"=dword:00000000 +``` + +**For TLS 1.2** (required minimum): +```registry +[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server] +"Enabled"=dword:00000001 +"DisabledByDefault"=dword:00000000 + +[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client] +"Enabled"=dword:00000001 +"DisabledByDefault"=dword:00000000 +``` + +**Disable deprecated protocols** (TLS 1.0, TLS 1.1, SSL 3.0, SSL 2.0): +```registry +[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.1\Server] +"Enabled"=dword:00000000 +"DisabledByDefault"=dword:00000001 + +[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.0\Server] +"Enabled"=dword:00000000 +"DisabledByDefault"=dword:00000001 +``` + +### TLS 1.3 Cipher Suites + +TLS 1.3 uses only two cipher suites, which are automatically enabled on Windows Server 2022 and cannot be customized: + +- `TLS_AES_256_GCM_SHA384` +- `TLS_AES_128_GCM_SHA256` + +These suites provide forward secrecy and use AEAD (Authenticated Encryption with Associated Data) algorithms, eliminating the need for separate MAC operations. + +### Automated Configuration via Custom Script Extension + +This option uses Custom Script Extension with extension sequencing and PowerShell script. [../Scripts/vmss-cse-tls.ps1](../Scripts/vmss-cse-tls.ps1) should be saved to a storage location accessible from Service Fabric nodes during deployment. + +> **Note:** The current vmss-cse-tls.ps1 script configures TLS 1.2 only. For TLS 1.3 support, you need to modify the script to include the TLS 1.3 registry keys shown above and ensure your cluster meets the prerequisites (Windows Server 2022, Service Fabric 10.1CU2+). + +The script is based on [Troubleshooting applications that don't support TLS 1.2](https://learn.microsoft.com/en-us/azure/cloud-services/applications-dont-support-tls-1-2) and disables deprecated protocols (TLS 1.0, 1.1, SSL 2.0, SSL 3.0) and weak ciphers (RC4, 3DES). ### Modify ARM Template to Add Custom Script Extension @@ -121,49 +202,265 @@ index 289e771..e598691 100644 }, ``` +## Service Fabric TLS 1.3 Cluster Configuration + +When enabling TLS 1.3 support in Service Fabric clusters, additional cluster-level configuration is required beyond the OS-level TLS protocol settings. + +### Prerequisites + +- **Service Fabric Runtime**: Version 10.1CU2 (10.1.1951.9590) or later +- **Operating System**: Windows Server 2022 or later +- **API Version**: + - Managed clusters: `2023-12-01-preview` or later + - Classic VMSS clusters: `2023-11-01-preview` or later + +### Cluster Manifest Settings + +Add the following settings to your cluster's `fabricSettings` section in the ARM template: + +**For Managed Clusters:** + +```json +{ + "apiVersion": "2023-12-01-preview", + "type": "Microsoft.ServiceFabric/managedClusters", + "properties": { + "fabricSettings": [ + { + "name": "HttpGateway", + "parameters": [ + { + "name": "enableHttpGatewayExclusiveAuthMode", + "value": "true" + }, + { + "name": "httpGatewayTokenAuthEndpointPort", + "value": "19081" + } + ] + } + ] + } +} +``` + +**For Classic VMSS Clusters:** + +```json +{ + "apiVersion": "2023-11-01-preview", + "type": "Microsoft.ServiceFabric/clusters", + "properties": { + "fabricSettings": [ + { + "name": "HttpGateway", + "parameters": [ + { + "name": "enableHttpGatewayExclusiveAuthMode", + "value": "true" + }, + { + "name": "httpGatewayTokenAuthEndpointPort", + "value": "19081" + } + ] + } + ] + } +} +``` + +### Configuration Parameters + +- **enableHttpGatewayExclusiveAuthMode**: Boolean value that enables TLS 1.3 support for HTTP Gateway communications. Set to `true` to enable. +- **httpGatewayTokenAuthEndpointPort**: Port number for the token authentication endpoint. Default is `19081`. + +### Migration Guidance + +For detailed guidance on migrating your cluster to TLS 1.3, see [How to migrate Transport Layer Security (TLS) in Service Fabric](https://learn.microsoft.com/en-us/azure/service-fabric/how-to-migrate-transport-layer-security). + + + ## Option 2 - Application level configuration by .exe.config -- Update the .exe app.exe.config, for example FabricUS.exe.config if the process is using .Net Framework 4.6 and above -- DontEnableSchUseStrongCrypto is mapping to "HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\.NETFramework\\v4.0.30319\\SchUseStrongCrypto" at per application through the app.config file. - - [<AppContextSwitchOverrides> element](https://docs.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) - - search DontEnableSchUseStrongCrypto - - ```xml - - - - - - - ``` + +Application-level TLS configuration allows you to control TLS settings for specific .NET Framework applications without affecting the entire machine. + +### .NET Framework and TLS Version Support + +| .NET Framework Version | TLS 1.2 | TLS 1.3 | Configuration Required | +|------------------------|---------|---------|------------------------| +| 4.8+ | ✅ | ✅ | Uses OS default (recommended) | +| 4.7 - 4.7.2 | ✅ | ❌ | Requires AppContextSwitchOverrides | +| 4.6 - 4.6.2 | ✅ | ❌ | Requires AppContextSwitchOverrides | +| 4.5 - 4.5.2 | ⚠️ | ❌ | Requires registry configuration | +| < 4.5 | ❌ | ❌ | Not supported | + +### Recommended Configuration (.NET 4.6+) + +For applications using .NET Framework 4.6 or later, configure the application's `.exe.config` file (e.g., `FabricUS.exe.config`) to use system default TLS versions: + +```xml + + + + + + +``` + +### Configuration Switches Explained + +- **Switch.System.Net.DontEnableSchUseStrongCrypto=false**: Enables strong cryptography and blocks weak protocols. This switch maps to the registry key `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319\SchUseStrongCrypto` at the application level. + +- **Switch.System.Net.DontEnableSystemDefaultTlsVersions=false**: Allows the application to use the operating system's default TLS version. This is essential for TLS 1.3 support as it defers protocol selection to the OS. This switch maps to the `SystemDefaultTlsVersions` registry key. + +### Code-Level Configuration (C#) + +For programmatic control, use `SecurityProtocolType.SystemDefault` instead of explicit protocol versions: + +```csharp +// Recommended: Let OS choose the protocol +ServicePointManager.SecurityProtocol = SecurityProtocolType.SystemDefault; + +// Not recommended: Hard-coding protocols +// ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12 | SecurityProtocolType.Tls13; +``` + +### Important Notes + +- For TLS 1.3 support, applications must run on .NET Framework 4.8+ with Windows Server 2022 or later +- Using `SystemDefault` ensures your application automatically benefits from OS-level security updates +- The `` element is documented at [AppContextSwitchOverrides element](https://learn.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) + + + ## Option 3 - Application level configuration by .exe path in registry -- Update registry with path of where .NET .exe is located, like this: -- Valid values are Tls12, Tls11, Tls and Ssl3. Any combination of these values separated by a comma is acceptable. -- Invalid values will be silently treated as if the key is not present: default values will be used instead - ``` - HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319\System.Net.ServicePointManager.SecurityProtocol - Create REG_SZ string with content - Name: D:\SvcFab\_App\__FabricSystem_App4294967295\US.Code.Current\FabricUS.exe - Value: Tls12 - ``` +> **⚠️ Deprecated Method**: This approach is considered legacy. For new deployments, use Option 2 (.exe.config) with `SystemDefaultTlsVersions` switch instead. + +This method configures TLS protocols for specific .NET applications via registry keys. It is useful for applications where modifying the `.exe.config` file is not possible. + +### Registry Configuration + +Create a REG_SZ (string) value under the following registry path: + +```registry +HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319\System.Net.ServicePointManager.SecurityProtocol + +Name: +Value: Tls12,Tls13 +``` + +### Example + +```registry +HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319\System.Net.ServicePointManager.SecurityProtocol + +Name: D:\SvcFab\_App\__FabricSystem_App4294967295\US.Code.Current\FabricUS.exe +Value: Tls12,Tls13 +``` + +### Valid Protocol Values + +- **Tls13**: TLS 1.3 (requires .NET Framework 4.8+, Windows Server 2022+) +- **Tls12**: TLS 1.2 (recommended minimum) +- **Tls11**: TLS 1.1 (⚠️ deprecated, will be retired August 31, 2025) +- **Tls**: TLS 1.0 (⚠️ deprecated, will be retired August 31, 2025) +- **Ssl3**: SSL 3.0 (⚠️ deprecated, do not use) + +Multiple values can be combined with commas (e.g., `Tls12,Tls13`). Invalid values are silently ignored. + +### Modern Alternative (.NET 4.6.2+) + +Instead of using application-specific registry keys, configure machine-wide registry settings: + +```registry +[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319] +"SchUseStrongCrypto"=dword:00000001 +"SystemDefaultTlsVersions"=dword:00000001 + +[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319] +"SchUseStrongCrypto"=dword:00000001 +"SystemDefaultTlsVersions"=dword:00000001 +``` + +For .NET Framework 3.5 applications: + +```registry +[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v2.0.50727] +"SchUseStrongCrypto"=dword:00000001 +"SystemDefaultTlsVersions"=dword:00000001 + +[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v2.0.50727] +"SchUseStrongCrypto"=dword:00000001 +"SystemDefaultTlsVersions"=dword:00000001 +``` + +### Registry Keys Explained + +- **SchUseStrongCrypto**: Enables strong cryptography and disables weak protocols (SSL 3.0, TLS 1.0, TLS 1.1) +- **SystemDefaultTlsVersions**: Allows .NET applications to use the operating system's default TLS version, enabling TLS 1.3 support on compatible systems + ## Verification -- After configuration has been applied and node has been restarted, verify cluster and application functionality. Once cluster and applications have been verified, to verify TLS configuration, there are multiple tools available to check configuration. [Nmap](https://nmap.org) and [IISCrypto](https://www.nartac.com/Products/IISCrypto/) are examples of utilities that can be used. +After configuration has been applied and the node has been restarted, verify cluster and application functionality. Once verified, test TLS configuration using tools like [Nmap](https://nmap.org) or [IISCrypto](https://www.nartac.com/Products/IISCrypto/). ### Nmap -- To verify configuration with NMAP, [RDP](https://docs.microsoft.com/azure/service-fabric/service-fabric-cluster-remote-connect-to-azure-cluster-node) to node, download [Nmap](https://nmap.org/download), and install. -- From command line, execute command for verification. Example command: nmap --script ssl-enum-ciphers -p 1026 -Pn 10.0.0.4 -- Verify configuration is as expected. If there are warnings, review and modify TLS configuration as needed. +To verify TLS configuration with Nmap: -#### Nmap example command +1. [RDP](https://learn.microsoft.com/azure/service-fabric/service-fabric-cluster-remote-connect-to-azure-cluster-node) to the node +2. Download and install [Nmap](https://nmap.org/download) +3. Run the verification command + +**Example command:** +```powershell +nmap --script ssl-enum-ciphers -p 1026 -Pn 10.0.0.4 +``` + +#### TLS 1.3 Example Output (Windows Server 2022) + +```text +PS C:\Program Files (x86)\Nmap> nmap --script ssl-enum-ciphers -p 1026 -Pn 10.0.0.4 +Starting Nmap 7.93 ( https://nmap.org ) at 2024-01-15 19:09 Coordinated Universal Time + +Nmap scan report for nt0000000.internal.cloudapp.net (10.0.0.4) +Host is up (0.0010s latency). + +PORT STATE SERVICE +1026/tcp open LSA-or-nterm +| ssl-enum-ciphers: +| TLSv1.3: +| ciphers: +| TLS_AES_256_GCM_SHA384 (ecdh_x25519) - A +| TLS_AES_128_GCM_SHA256 (ecdh_x25519) - A +| cipher preference: server +| TLSv1.2: +| ciphers: +| TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (secp384r1) - A +| TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (secp384r1) - A +| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 (secp384r1) - A +| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (secp384r1) - A +| TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (secp384r1) - A +| TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA (secp384r1) - A +| compressors: +| NULL +| cipher preference: server +|_ least strength: A + +Nmap done: 1 IP address (1 host up) scanned in 0.87 seconds +PS C:\Program Files (x86)\Nmap> +``` + +#### TLS 1.2 Example Output (Legacy Configuration) + +> **⚠️ Note**: The following output shows deprecated DHE cipher suites that are no longer recommended and have been removed from Windows Server 2022. These ciphers should be disabled in production environments. ```text PS C:\Program Files (x86)\Nmap> nmap --script ssl-enum-ciphers -p 1026 -Pn 10.0.0.4 Starting Nmap 7.93 ( https://nmap.org ) at 2022-10-15 19:09 Coordinated Universal Time -NSOCK ERROR [0.0720s] ssl_init_helper(): OpenSSL legacy provider failed to load. Nmap scan report for nt0000000.internal.cloudapp.net (10.0.0.4) Host is up (0.0010s latency). @@ -175,20 +472,14 @@ PORT STATE SERVICE | ciphers: | TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (secp384r1) - A | TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (secp384r1) - A -| TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 (dh 2048) - A -| TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 (dh 2048) - A +| TLS_DHE_RSA_WITH_AES_256_GCM_SHA384 (dh 2048) - A ⚠️ DEPRECATED +| TLS_DHE_RSA_WITH_AES_128_GCM_SHA256 (dh 2048) - A ⚠️ DEPRECATED | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 (secp384r1) - A | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (secp384r1) - A | TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (secp384r1) - A | TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA (secp384r1) - A -| TLS_DHE_RSA_WITH_AES_256_CBC_SHA (dh 2048) - A -| TLS_DHE_RSA_WITH_AES_128_CBC_SHA (dh 2048) - A -| TLS_RSA_WITH_AES_256_GCM_SHA384 (rsa 2048) - A -| TLS_RSA_WITH_AES_128_GCM_SHA256 (rsa 2048) - A -| TLS_RSA_WITH_AES_256_CBC_SHA256 (rsa 2048) - A -| TLS_RSA_WITH_AES_128_CBC_SHA256 (rsa 2048) - A -| TLS_RSA_WITH_AES_256_CBC_SHA (rsa 2048) - A -| TLS_RSA_WITH_AES_128_CBC_SHA (rsa 2048) - A +| TLS_DHE_RSA_WITH_AES_256_CBC_SHA (dh 2048) - A ⚠️ DEPRECATED +| TLS_DHE_RSA_WITH_AES_128_CBC_SHA (dh 2048) - A ⚠️ DEPRECATED | compressors: | NULL | cipher preference: server @@ -198,27 +489,265 @@ Nmap done: 1 IP address (1 host up) scanned in 0.87 seconds PS C:\Program Files (x86)\Nmap> ``` +### Deprecated Cipher Suites + +The following cipher suites are deprecated and removed from Windows Server 2022: + +- **DHE (Diffie-Hellman Ephemeral)**: All `TLS_DHE_RSA_*` and `TLS_DHE_DSS_*` variants +- **3DES**: `TLS_RSA_WITH_3DES_EDE_CBC_SHA` +- **RC4**: All RC4-based cipher suites +- **RSA Key Exchange without ECDHE**: `TLS_RSA_WITH_AES_*` cipher suites (acceptable but less secure than ECDHE variants) + +**Recommended modern cipher suites for TLS 1.2:** + +- `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` +- `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` +- `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384` +- `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256` + +**For TLS 1.3** (Windows Server 2022+), only two cipher suites are supported and they are automatically enabled: + +- `TLS_AES_256_GCM_SHA384` +- `TLS_AES_128_GCM_SHA256` + +## Troubleshooting + +### Common TLS Configuration Issues + +#### Windows Update Error 0x80072EFE + +**Problem**: Windows Update fails with error 0x80072EFE due to TLS/cipher suite mismatch. + +**Cause**: The system's configured cipher suites don't match what Windows Update servers support. + +**Solution**: + +1. Verify TLS 1.2 is enabled: + ```powershell + Get-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client" -Name "Enabled" + ``` + +2. Ensure modern cipher suites are available: + ```powershell + Get-TlsCipherSuite | Where-Object {$_.Name -like "*ECDHE*"} + ``` + +3. Reset cipher suite ordering to default: + ```powershell + # Backup current configuration + Get-TlsCipherSuite | Export-Clixml -Path "C:\temp\TlsCipherSuites_backup.xml" + + # Reset to OS default + Remove-Item "HKLM:\SOFTWARE\Policies\Microsoft\Cryptography\Configuration\SSL\00010002" -Force -ErrorAction SilentlyContinue + ``` + +4. Restart the node and retry Windows Update. + +#### Connection Failures After TLS Configuration + +**Problem**: Service Fabric nodes can't communicate after TLS configuration changes. + +**Symptoms**: +- Nodes show as down in Service Fabric Explorer +- Certificate validation errors in event logs +- TCP connection failures on Service Fabric ports + +**Solution**: + +1. Verify TLS protocols are properly configured on **both** client and server: + ```powershell + # Check TLS 1.2 Server + Get-ItemProperty "HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server" + + # Check TLS 1.2 Client + Get-ItemProperty "HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client" + ``` + +2. Check .NET Framework registry keys: + ```powershell + # Check SchUseStrongCrypto + Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\.NETFramework\v4.0.30319" -Name "SchUseStrongCrypto" + Get-ItemProperty "HKLM:\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319" -Name "SchUseStrongCrypto" + + # Check SystemDefaultTlsVersions + Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\.NETFramework\v4.0.30319" -Name "SystemDefaultTlsVersions" + Get-ItemProperty "HKLM:\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319" -Name "SystemDefaultTlsVersions" + ``` + +3. Verify at least one common cipher suite exists between nodes: + ```powershell + Get-TlsCipherSuite | Select-Object -First 10 Name + ``` + +4. Check event logs for specific TLS errors: + ```powershell + Get-WinEvent -LogName "Microsoft-ServiceFabric/Admin" -MaxEvents 50 | Where-Object {$_.Message -like "*TLS*" -or $_.Message -like "*SSL*"} + ``` + +#### Missing Cipher Suites + +**Problem**: After disabling weak ciphers, applications fail to establish TLS connections. + +**Cause**: No common cipher suites between client and server, or all cipher suites were disabled. + +**Solution**: + +1. Verify modern cipher suites are enabled: + ```powershell + Get-TlsCipherSuite | Where-Object { + $_.Name -like "TLS_ECDHE_RSA_WITH_AES*GCM*" -or + $_.Name -like "TLS_AES*" + } + ``` + +2. If no cipher suites are found, reset to Windows defaults: + ```powershell + # This cmdlet restores default cipher suite ordering + Reset-TlsCipherSuite + ``` + +3. Manually enable required cipher suites using Group Policy or PowerShell: + ```powershell + Enable-TlsCipherSuite -Name "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384" + Enable-TlsCipherSuite -Name "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" + ``` + +#### TLS 1.3 Not Working + +**Problem**: TLS 1.3 is configured but connections fall back to TLS 1.2. + +**Requirements Check**: + +1. Verify OS version: + ```powershell + Get-CimInstance Win32_OperatingSystem | Select-Object Caption, Version + ``` + - Required: Windows Server 2022 (10.0.20348) or later + +2. Verify Service Fabric version: + ```powershell + Get-ServiceFabricClusterManifest | Select-String "Version" + ``` + - Required: 10.1CU2 (10.1.1951.9590) or later + +3. Verify .NET Framework version: + ```powershell + Get-ChildItem 'HKLM:\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full\' | Get-ItemPropertyValue -Name Version + ``` + - Required: 4.8 or later + +4. Check cluster manifest for TLS 1.3 settings: + ```powershell + Get-ServiceFabricClusterConfiguration | Select-String "enableHttpGatewayExclusiveAuthMode" + ``` + +### Verification Tools + +**Nmap**: Test TLS configuration from the network perspective (see Verification section above) + +**IIS Crypto**: GUI tool for Windows cipher suite management +- Download from [https://www.nartac.com/Products/IISCrypto/](https://www.nartac.com/Products/IISCrypto/) +- Provides visual interface for enabling/disabling protocols and ciphers +- Shows best practice templates + +**SSL Labs**: Online TLS testing (for internet-facing endpoints only) +- Visit [https://www.ssllabs.com/ssltest/](https://www.ssllabs.com/ssltest/) +- Comprehensive security analysis +- Identifies weak configurations and vulnerabilities + + ## Linux Clusters -Update the cluster settings in Security section - EnforceLinuxMinTlsVersion and TLS1_2_CipherList as needed +Linux-based Service Fabric clusters support TLS configuration through cluster manifest settings and OS-level OpenSSL configuration. + +### TLS Protocol Configuration + +Update the cluster settings in the Security section: + +```json +{ + "name": "Security", + "parameters": [ + { + "name": "EnforceLinuxMinTlsVersion", + "value": "true" + }, + { + "name": "TLS1_2_CipherList", + "value": "ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256" + } + ] +} +``` + +### Configuration Parameters + +- **EnforceLinuxMinTlsVersion**: Boolean, default is `false` + - Set to `true` to enforce TLS 1.2+ only + - When `false`, allows earlier TLS versions (not recommended) + - Applies to Service Fabric's Transport and HTTP Gateway + +- **TLS1_2_CipherList**: Colon-separated list of OpenSSL cipher suite names + - Specifies allowed cipher suites for TLS 1.2 + - Example: `"ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES128-GCM-SHA256"` + +### TLS 1.3 Support on Linux + +TLS 1.3 is supported on Linux distributions with OpenSSL 1.1.1 or later: + +- **Ubuntu 20.04 LTS** and later: OpenSSL 1.1.1 (TLS 1.3 supported) +- **Red Hat Enterprise Linux 8** and later: OpenSSL 1.1.1 (TLS 1.3 supported) +- **SUSE Linux Enterprise 15** and later: OpenSSL 1.1.1 (TLS 1.3 supported) + +To enable TLS 1.3 on Linux, ensure your distribution uses OpenSSL 1.1.1+ and configure the minimum TLS version: + +```bash +# Check OpenSSL version +openssl version + +# OpenSSL 1.1.1 or later supports TLS 1.3 +``` + +### Machine-Wide TLS Configuration + +The Service Fabric `EnforceLinuxMinTlsVersion` setting applies only to Service Fabric processes. For machine-wide TLS settings, configure OpenSSL and system libraries according to your distribution's security guidelines: + +- **Ubuntu**: [Ubuntu Security Guide](https://ubuntu.com/security) +- **Red Hat**: [Red Hat Enterprise Linux Security Guide](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/) + + + +## Reference + +This guide covers SSL/TLS configuration for Service Fabric clusters and applications. For additional information, consult the following resources: + +### Service Fabric TLS Configuration + +- [How to migrate Transport Layer Security (TLS) in Service Fabric](https://learn.microsoft.com/en-us/azure/service-fabric/how-to-migrate-transport-layer-security) - Complete guide for migrating to TLS 1.3 +- [Customize Service Fabric cluster settings - Security](https://learn.microsoft.com/en-us/azure/service-fabric/service-fabric-cluster-fabric-settings#security) - Cluster manifest security settings +- [Connect to a secure cluster](https://learn.microsoft.com/en-us/azure/service-fabric/service-fabric-connect-to-secure-cluster) - Securing cluster communications + +### Windows Schannel and TLS Configuration -- EnforceLinuxMinTlsVersion bool, default is FALSE -- Set to true -- Only TLS version 1.2+ is supported. If false, support earlier TLS versions. Applies to Linux only +- [Restrict the use of certain cryptographic algorithms and protocols in Schannel.dll](https://learn.microsoft.com/en-us/troubleshoot/windows-server/windows-security/restrict-cryptographic-algorithms-protocols-schannel) - Registry-level TLS configuration +- [TLS/SSL Settings (Windows)](https://learn.microsoft.com/en-us/windows-server/security/tls/tls-ssl-schannel-ssp-overview) - Windows Server TLS/SSL overview +- [Manage TLS/SSL Protocols and Cipher Suites for AD FS](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/manage-ssl-protocols-in-ad-fs) - Cipher suite ordering and management -This setting should enforce TLS1.2 for Service Fabric's Transport and HTTP Gateway. It is not a machine-wide setting. For more information on setting up machine level TLS setting, please contact Ubuntu support - https://ubuntu.com/support +### .NET Framework TLS Best Practices -## Reference +- [Transport Layer Security (TLS) best practices with the .NET Framework](https://learn.microsoft.com/en-us/dotnet/framework/network-programming/tls) - Comprehensive .NET TLS guidance +- [AppContextSwitchOverrides element](https://learn.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) - Configuration switch documentation +- [Mitigation: TLS Protocols](https://learn.microsoft.com/en-us/dotnet/framework/migration-guide/mitigation-tls-protocols) - Framework-specific TLS migration -This TSG is primarily discussing SSL/TLS client behavior such as FabricUS.exe. For additional reference, you may check: +### Security and Compliance -- [Restrict the use of certain cryptographic algorithms and protocols in Schannel.dll](https://learn.microsoft.com/en-US/troubleshoot/windows-server/windows-security/restrict-cryptographic-algorithms-protocols-schannel) +- [RFC 8996 - Deprecating TLS 1.0 and TLS 1.1](https://www.rfc-editor.org/rfc/rfc8996.html) - Official TLS deprecation specification +- [Azure TLS 1.0/1.1 Retirement](https://learn.microsoft.com/en-us/azure/security/fundamentals/tls-certificate-changes) - Azure-wide TLS retirement timeline (August 31, 2025) -- [How to Disable SSL 3.0 in Azure Websites, Roles, and Virtual Machines](https://azure.microsoft.com/en-us/blog/how-to-disable-ssl-3-0-in-azure-websites-roles-and-virtual-machines/) +### Troubleshooting and Verification -- [Customize Service Fabric cluster settings | Security](https://docs.microsoft.com/en-us/azure/service-fabric/service-fabric-cluster-fabric-settings#security) +- [Nmap - Network Security Scanner](https://nmap.org) - TLS/SSL verification tool +- [IIS Crypto](https://www.nartac.com/Products/IISCrypto/) - GUI tool for Windows cipher suite configuration +- [Qualys SSL Labs Server Test](https://www.ssllabs.com/ssltest/) - Online TLS configuration analysis -If you are **not** looking for schannel driver level security hardening, but rather want to do it from the .Net Framework level, you can check these MSDN references: -- [Transport Layer Security (TLS) best practices with the .NET Framework](https://docs.microsoft.com/en-us/dotnet/framework/network-programming/tls) -- [Mitigation: TLS Protocols](https://docs.microsoft.com/en-us/dotnet/framework/migration-guide/mitigation-tls-protocols) From a1381dccdd22100689d433841c24641c297eedd5 Mon Sep 17 00:00:00 2001 From: jagilber Date: Wed, 29 Oct 2025 10:08:38 -0400 Subject: [PATCH 2/8] Fix TLS 1.3 port configuration - clarify token auth endpoint - Correct httpGatewayTokenAuthEndpointPort usage (only needed for token auth) - Change example port from 19081 to 19079 per Microsoft docs - Add separate sections for certificate-only vs token-based authentication - Clarify that port 19081 is reverse proxy, not TLS 1.3 related - Add port reference table (19080 gateway, 19079 token auth, 19081 reverse proxy) - Document that httpGatewayTokenAuthEndpointPort goes in nodeTypes section - Emphasize enableHttpGatewayExclusiveAuthMode is required for all TLS 1.3 --- Security/TLS Configuration.md | 72 ++++++++++++++++++++++++++++++----- 1 file changed, 62 insertions(+), 10 deletions(-) diff --git a/Security/TLS Configuration.md b/Security/TLS Configuration.md index 655a8943..21a99f8f 100644 --- a/Security/TLS Configuration.md +++ b/Security/TLS Configuration.md @@ -216,7 +216,11 @@ When enabling TLS 1.3 support in Service Fabric clusters, additional cluster-lev ### Cluster Manifest Settings -Add the following settings to your cluster's `fabricSettings` section in the ARM template: +The required settings depend on your authentication method: + +#### Certificate-Based Authentication Only + +If you only use X.509 certificates for authentication, you only need to enable exclusive authentication mode: **For Managed Clusters:** @@ -232,10 +236,6 @@ Add the following settings to your cluster's `fabricSettings` section in the ARM { "name": "enableHttpGatewayExclusiveAuthMode", "value": "true" - }, - { - "name": "httpGatewayTokenAuthEndpointPort", - "value": "19081" } ] } @@ -258,10 +258,47 @@ Add the following settings to your cluster's `fabricSettings` section in the ARM { "name": "enableHttpGatewayExclusiveAuthMode", "value": "true" - }, + } + ] + } + ] + } +} +``` + +#### Token-Based Authentication (Microsoft Entra ID) + +If you use token-based authentication (OAuth 2.0 bearer tokens), you must define a new HTTP endpoint exclusively for token authentication. TLS 1.3 doesn't easily support mixed mode authentication (both certificates and tokens on the same endpoint). + +**For Managed Clusters with Token Authentication:** + +First, define the new token endpoint in the `nodeTypes` section: + +```json +{ + "nodeTypes": [ + { + "name": "[parameters('vmNodeType0Name')]", + "httpGatewayTokenAuthEndpointPort": "19079" + } + ] +} +``` + +Then enable exclusive authentication mode in `fabricSettings`: + +```json +{ + "apiVersion": "2023-12-01-preview", + "type": "Microsoft.ServiceFabric/managedClusters", + "properties": { + "fabricSettings": [ + { + "name": "HttpGateway", + "parameters": [ { - "name": "httpGatewayTokenAuthEndpointPort", - "value": "19081" + "name": "enableHttpGatewayExclusiveAuthMode", + "value": "true" } ] } @@ -270,10 +307,25 @@ Add the following settings to your cluster's `fabricSettings` section in the ARM } ``` +**For Classic VMSS Clusters with Token Authentication:** + +Similar configuration applies - define `httpGatewayTokenAuthEndpointPort` in each node type, then set `enableHttpGatewayExclusiveAuthMode` to true in fabricSettings. + ### Configuration Parameters -- **enableHttpGatewayExclusiveAuthMode**: Boolean value that enables TLS 1.3 support for HTTP Gateway communications. Set to `true` to enable. -- **httpGatewayTokenAuthEndpointPort**: Port number for the token authentication endpoint. Default is `19081`. +- **enableHttpGatewayExclusiveAuthMode**: Boolean value that enables TLS 1.3 support for HTTP Gateway communications. Set to `true` to enable. This is required for all TLS 1.3 configurations. + +- **httpGatewayTokenAuthEndpointPort**: Port number for the token authentication endpoint. **Only required if you use token-based authentication (Microsoft Entra ID)**. You can use any port number from the Service Fabric runtime reserved port range (example shows 19079, but any available port can be used). This port must be configured: + - In the `nodeTypes` section for each node type + - In your load balancer rules + - In your Network Security Group (NSG) rules + - In any scripts or applications that use token-based authentication + +### Port Reference + +- **Port 19080**: Default HTTP gateway port (used for certificate-based authentication, continues to be used with TLS 1.3) +- **Port 19079** (or custom): Token authentication endpoint (only needed for Microsoft Entra ID/OAuth authentication) +- **Port 19081**: Reverse proxy port (unrelated to TLS 1.3, used for service-to-service communication) ### Migration Guidance From 59e2c0e69e25e2f97fffa4872665c821d24bc0e7 Mon Sep 17 00:00:00 2001 From: jagilber Date: Sun, 16 Nov 2025 12:28:06 -0500 Subject: [PATCH 3/8] Add TLS Cipher Suites documentation link and update references --- Security/TLS Configuration.md | 43 +++++++++++++++++++---------------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/Security/TLS Configuration.md b/Security/TLS Configuration.md index 21a99f8f..bba7b813 100644 --- a/Security/TLS Configuration.md +++ b/Security/TLS Configuration.md @@ -1,7 +1,8 @@ # How to configure Service Fabric or Applications to use TLS 1.2 and TLS 1.3 -> **IMPORTANT DEPRECATION NOTICE** -> **TLS 1.0 and TLS 1.1 are officially deprecated** as per [RFC 8996](https://datatracker.ietf.org/doc/rfc8996/) and will be retired across all Azure services on **August 31, 2025**. Microsoft strongly recommends migrating to TLS 1.2 as the minimum supported version, with TLS 1.3 recommended for new deployments. +> [!IMPORTANT] +> **DEPRECATION NOTICE** +> **TLS 1.0 and TLS 1.1 are officially deprecated** as per [Microsoft TLS Support Ending](https://learn.microsoft.com/lifecycle/announcements/tls-support-ending-10-31-2024) and [Azure TLS Support](https://learn.microsoft.com/azure/azure-resource-manager/management/tls-support) and has been retired across all Azure services on **August 31, 2025**. Microsoft strongly recommends migrating to TLS 1.2 as the minimum supported version, with TLS 1.3 recommended for new deployments. ## TLS 1.3 Support in Service Fabric @@ -23,7 +24,7 @@ To use TLS 1.3 in Service Fabric clusters: - Classic Clusters: API version 2023-11-01-preview or later 4. **.NET Framework**: .NET Framework 4.8 or later for application support -For complete migration guidance, see [Migrate Azure Service Fabric to TLS 1.3](https://learn.microsoft.com/en-us/azure/service-fabric/how-to-migrate-transport-layer-security). +For complete migration guidance, see [Migrate Azure Service Fabric to TLS 1.3](https://learn.microsoft.com/azure/service-fabric/how-to-migrate-transport-layer-security). ## Configuration Options Overview @@ -79,13 +80,15 @@ TLS 1.3 uses only two cipher suites, which are automatically enabled on Windows These suites provide forward secrecy and use AEAD (Authenticated Encryption with Associated Data) algorithms, eliminating the need for separate MAC operations. +For more information, see [TLS Cipher Suites in Windows Server 2022](https://learn.microsoft.com/windows/win32/secauthn/tls-cipher-suites-in-windows-server-2022). + ### Automated Configuration via Custom Script Extension This option uses Custom Script Extension with extension sequencing and PowerShell script. [../Scripts/vmss-cse-tls.ps1](../Scripts/vmss-cse-tls.ps1) should be saved to a storage location accessible from Service Fabric nodes during deployment. > **Note:** The current vmss-cse-tls.ps1 script configures TLS 1.2 only. For TLS 1.3 support, you need to modify the script to include the TLS 1.3 registry keys shown above and ensure your cluster meets the prerequisites (Windows Server 2022, Service Fabric 10.1CU2+). -The script is based on [Troubleshooting applications that don't support TLS 1.2](https://learn.microsoft.com/en-us/azure/cloud-services/applications-dont-support-tls-1-2) and disables deprecated protocols (TLS 1.0, 1.1, SSL 2.0, SSL 3.0) and weak ciphers (RC4, 3DES). +The script is based on [Troubleshooting applications that don't support TLS 1.2](https://learn.microsoft.com/azure/cloud-services/applications-dont-support-tls-1-2) and disables deprecated protocols (TLS 1.0, 1.1, SSL 2.0, SSL 3.0) and weak ciphers (RC4, 3DES). ### Modify ARM Template to Add Custom Script Extension @@ -329,7 +332,7 @@ Similar configuration applies - define `httpGatewayTokenAuthEndpointPort` in eac ### Migration Guidance -For detailed guidance on migrating your cluster to TLS 1.3, see [How to migrate Transport Layer Security (TLS) in Service Fabric](https://learn.microsoft.com/en-us/azure/service-fabric/how-to-migrate-transport-layer-security). +For detailed guidance on migrating your cluster to TLS 1.3, see [How to migrate Transport Layer Security (TLS) in Service Fabric](https://learn.microsoft.com/azure/service-fabric/how-to-migrate-transport-layer-security). @@ -382,7 +385,7 @@ ServicePointManager.SecurityProtocol = SecurityProtocolType.SystemDefault; - For TLS 1.3 support, applications must run on .NET Framework 4.8+ with Windows Server 2022 or later - Using `SystemDefault` ensures your application automatically benefits from OS-level security updates -- The `` element is documented at [AppContextSwitchOverrides element](https://learn.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) +- The `` element is documented at [AppContextSwitchOverrides element](https://learn.microsoft.com/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) @@ -417,8 +420,8 @@ Value: Tls12,Tls13 - **Tls13**: TLS 1.3 (requires .NET Framework 4.8+, Windows Server 2022+) - **Tls12**: TLS 1.2 (recommended minimum) -- **Tls11**: TLS 1.1 (⚠️ deprecated, will be retired August 31, 2025) -- **Tls**: TLS 1.0 (⚠️ deprecated, will be retired August 31, 2025) +- **Tls11**: TLS 1.1 (⚠️ deprecated, retired August 31, 2025 - do not use) +- **Tls**: TLS 1.0 (⚠️ deprecated, retired August 31, 2025 - do not use) - **Ssl3**: SSL 3.0 (⚠️ deprecated, do not use) Multiple values can be combined with commas (e.g., `Tls12,Tls13`). Invalid values are silently ignored. @@ -775,26 +778,28 @@ This guide covers SSL/TLS configuration for Service Fabric clusters and applicat ### Service Fabric TLS Configuration -- [How to migrate Transport Layer Security (TLS) in Service Fabric](https://learn.microsoft.com/en-us/azure/service-fabric/how-to-migrate-transport-layer-security) - Complete guide for migrating to TLS 1.3 -- [Customize Service Fabric cluster settings - Security](https://learn.microsoft.com/en-us/azure/service-fabric/service-fabric-cluster-fabric-settings#security) - Cluster manifest security settings -- [Connect to a secure cluster](https://learn.microsoft.com/en-us/azure/service-fabric/service-fabric-connect-to-secure-cluster) - Securing cluster communications +- [How to migrate Transport Layer Security (TLS) in Service Fabric](https://learn.microsoft.com/azure/service-fabric/how-to-migrate-transport-layer-security) - Complete guide for migrating to TLS 1.3 +- [Customize Service Fabric cluster settings - Security](https://learn.microsoft.com/azure/service-fabric/service-fabric-cluster-fabric-settings#security) - Cluster manifest security settings +- [Connect to a secure cluster](https://learn.microsoft.com/azure/service-fabric/service-fabric-connect-to-secure-cluster) - Securing cluster communications ### Windows Schannel and TLS Configuration -- [Restrict the use of certain cryptographic algorithms and protocols in Schannel.dll](https://learn.microsoft.com/en-us/troubleshoot/windows-server/windows-security/restrict-cryptographic-algorithms-protocols-schannel) - Registry-level TLS configuration -- [TLS/SSL Settings (Windows)](https://learn.microsoft.com/en-us/windows-server/security/tls/tls-ssl-schannel-ssp-overview) - Windows Server TLS/SSL overview -- [Manage TLS/SSL Protocols and Cipher Suites for AD FS](https://learn.microsoft.com/en-us/windows-server/identity/ad-fs/operations/manage-ssl-protocols-in-ad-fs) - Cipher suite ordering and management +- [TLS Cipher Suites in Windows Server 2022](https://learn.microsoft.com/windows/win32/secauthn/tls-cipher-suites-in-windows-server-2022) - Complete list of supported TLS 1.3 and 1.2 cipher suites +- [Restrict the use of certain cryptographic algorithms and protocols in Schannel.dll](https://learn.microsoft.com/troubleshoot/windows-server/windows-security/restrict-cryptographic-algorithms-protocols-schannel) - Registry-level TLS configuration +- [TLS/SSL Settings (Windows)](https://learn.microsoft.com/windows-server/security/tls/tls-ssl-schannel-ssp-overview) - Windows Server TLS/SSL overview +- [Manage TLS/SSL Protocols and Cipher Suites for AD FS](https://learn.microsoft.com/windows-server/identity/ad-fs/operations/manage-ssl-protocols-in-ad-fs) - Cipher suite ordering and management ### .NET Framework TLS Best Practices -- [Transport Layer Security (TLS) best practices with the .NET Framework](https://learn.microsoft.com/en-us/dotnet/framework/network-programming/tls) - Comprehensive .NET TLS guidance -- [AppContextSwitchOverrides element](https://learn.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) - Configuration switch documentation -- [Mitigation: TLS Protocols](https://learn.microsoft.com/en-us/dotnet/framework/migration-guide/mitigation-tls-protocols) - Framework-specific TLS migration +- [Transport Layer Security (TLS) best practices with the .NET Framework](https://learn.microsoft.com/dotnet/framework/network-programming/tls) - Comprehensive .NET TLS guidance +- [AppContextSwitchOverrides element](https://learn.microsoft.com/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) - Configuration switch documentation +- [Mitigation: TLS Protocols](https://learn.microsoft.com/dotnet/framework/migration-guide/mitigation-tls-protocols) - Framework-specific TLS migration ### Security and Compliance -- [RFC 8996 - Deprecating TLS 1.0 and TLS 1.1](https://www.rfc-editor.org/rfc/rfc8996.html) - Official TLS deprecation specification -- [Azure TLS 1.0/1.1 Retirement](https://learn.microsoft.com/en-us/azure/security/fundamentals/tls-certificate-changes) - Azure-wide TLS retirement timeline (August 31, 2025) +- [Microsoft TLS Support Ending](https://learn.microsoft.com/lifecycle/announcements/tls-support-ending-10-31-2024) - Official TLS 1.0/1.1 deprecation announcement +- [Azure TLS Support](https://learn.microsoft.com/azure/azure-resource-manager/management/tls-support) - Azure Resource Manager TLS requirements +- [Azure TLS 1.0/1.1 Retirement](https://learn.microsoft.com/azure/security/fundamentals/tls-certificate-changes) - Azure-wide TLS retirement timeline (August 31, 2025) ### Troubleshooting and Verification From 2dc082917b8f36697dce820681f830cc6d60c7d8 Mon Sep 17 00:00:00 2001 From: jagilber Date: Sun, 7 Dec 2025 16:01:31 -0500 Subject: [PATCH 4/8] docs: apply comprehensive TLS Configuration technical review feedback Critical Findings (CF): - CF-1: Fix .NET Framework TLS 1.3 code - remove non-existent Tls13 enum, use SystemDefault with AppContextSwitchOverrides - CF-2: Correct Linux TLS 1.3 claims - explicitly state Windows-only per official migration guide - CF-3: Remove non-existent PowerShell cmdlets (Enable-/Reset-TlsCipherSuite), replace with Group Policy/registry guidance - CF-4: Fix Nmap verification ports from 1026 to Service Fabric ports (19080/19000/19079) - CF-5: Mark Option 3 per-exe registry as unsupported/undocumented per Microsoft guidance High-Severity (HS): - HS-1: Add Windows 10 compatibility manifest requirement for TLS 1.3 transport endpoints - HS-2: Clarify exclusive auth mode rationale - runtime constraint and no TLS 1.3 renegotiation - HS-3: Note preview API versions and recommend tracking for GA releases Medium-Severity (MS): - MS-1: Emphasize OS defaults preference for registry protocol configuration - MS-2: Update cipher guidance to prefer GCM over CBC - MS-3: Add Windows Update 0x80072EFE reference - MS-4: Add service-specific TLS retirement enforcement references (ARM, App Gateway) Low-Severity/Editorial (LS): - LS-1: Update terminology to Microsoft Entra ID (formerly Azure AD) - LS-2: Add Service Fabric port reference table (19080/19079/19000/19081) - LS-3: Add full ARM examples for LB rule + NSG for token auth port 19079 - LS-4: Add comprehensive rollback plan section All changes based on authoritative Microsoft Learn documentation including: - TLS version supported by Azure Resource Manager - How to migrate to TLS 1.3 for Service Fabric - TLS registry settings - Application Gateway TLS policy overview --- Security/TLS Configuration.md | 270 +++++++++++++++++++++++++++++----- 1 file changed, 230 insertions(+), 40 deletions(-) diff --git a/Security/TLS Configuration.md b/Security/TLS Configuration.md index bba7b813..0e930c6d 100644 --- a/Security/TLS Configuration.md +++ b/Security/TLS Configuration.md @@ -2,7 +2,12 @@ > [!IMPORTANT] > **DEPRECATION NOTICE** -> **TLS 1.0 and TLS 1.1 are officially deprecated** as per [Microsoft TLS Support Ending](https://learn.microsoft.com/lifecycle/announcements/tls-support-ending-10-31-2024) and [Azure TLS Support](https://learn.microsoft.com/azure/azure-resource-manager/management/tls-support) and has been retired across all Azure services on **August 31, 2025**. Microsoft strongly recommends migrating to TLS 1.2 as the minimum supported version, with TLS 1.3 recommended for new deployments. +> **TLS 1.0 and TLS 1.1 are officially deprecated** as per [Microsoft TLS Support Ending](https://learn.microsoft.com/lifecycle/announcements/tls-support-ending-10-31-2024). Azure services are enforcing TLS 1.2 minimum on a service-by-service basis, with Azure-wide retirement targeting **August 31, 2025**. Microsoft strongly recommends migrating to TLS 1.2 as the minimum supported version, with TLS 1.3 recommended for new deployments. +> +> **Service-Specific Enforcement**: +> - **Azure Resource Manager**: TLS 1.2+ required - see [Azure Resource Manager TLS support](https://learn.microsoft.com/azure/azure-resource-manager/management/tls-support) +> - **Application Gateway**: TLS 1.2+ recommended - see [Application Gateway TLS policy](https://learn.microsoft.com/azure/application-gateway/application-gateway-ssl-policy-overview) +> - Validate enforcement dates for each Azure service you use ## TLS 1.3 Support in Service Fabric @@ -19,10 +24,15 @@ To use TLS 1.3 in Service Fabric clusters: 1. **Service Fabric Runtime**: Version 10.1CU2 (10.1.1951.9590) or later 2. **Operating System**: Windows Server 2022 or later (TLS 1.3 requires OS-level support) -3. **API Version**: - - Managed Clusters: API version 2023-12-01-preview or later - - Classic Clusters: API version 2023-11-01-preview or later -4. **.NET Framework**: .NET Framework 4.8 or later for application support +3. **Application Compatibility Manifest**: Applications must declare **Windows 10 compatibility** in their manifest. TLS 1.3 will not enable for Service Fabric transport endpoints if the application runs in Windows 8 compatibility mode. +4. **API Version**: + - Managed Clusters: API version `2023-12-01-preview` or later (track release notes for GA version) + - Classic Clusters: API version `2023-11-01-preview` or later (track release notes for GA version) +5. **.NET Framework**: .NET Framework 4.8 or later for application support + +> **Important**: Mixed compatibility settings in packaged applications can prevent TLS 1.3 from enabling. Ensure all application manifests declare Windows 10 compatibility. +> +> **Note**: The API versions listed above are preview versions. Prefer GA (generally available) API versions when released. Check [Service Fabric release notes](https://learn.microsoft.com/azure/service-fabric/service-fabric-versions) for the latest stable API versions. For complete migration guidance, see [Migrate Azure Service Fabric to TLS 1.3](https://learn.microsoft.com/azure/service-fabric/how-to-migrate-transport-layer-security). @@ -36,6 +46,8 @@ This configuration is machine-wide, restricting the OS and all applications to u ### TLS Protocol Configuration +> **Best Practice**: Windows Server 2022 and later enable TLS 1.3 and TLS 1.2 by default with secure cipher suites. **Prefer OS defaults; only override registry settings if audit or compliance requirements mandate explicit configuration.** Where possible, use Group Policy instead of direct registry editing. + TLS protocols are configured via registry keys under `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols`. Each protocol version requires specific DWORD values: **For TLS 1.3** (Windows Server 2022+ only): @@ -271,7 +283,15 @@ If you only use X.509 certificates for authentication, you only need to enable e #### Token-Based Authentication (Microsoft Entra ID) -If you use token-based authentication (OAuth 2.0 bearer tokens), you must define a new HTTP endpoint exclusively for token authentication. TLS 1.3 doesn't easily support mixed mode authentication (both certificates and tokens on the same endpoint). +If you use token-based authentication (OAuth 2.0 bearer tokens), you must define a new HTTP endpoint exclusively for token authentication. + +**Why separate endpoints are required**: TLS 1.3 removed support for post-handshake authentication (renegotiation). Service Fabric's runtime cannot dynamically switch between certificate validation and token validation on a single TLS 1.3 endpoint. The solution is to: + +1. Keep certificate-based authentication on the existing HTTP Gateway port (19080) +2. Create a dedicated token authentication endpoint on a separate port (example: 19079) +3. Enable exclusive authentication mode to prevent mixed parsing on one endpoint + +This is a Service Fabric runtime constraint specific to TLS 1.3, not a limitation of the TLS protocol itself. **For Managed Clusters with Token Authentication:** @@ -314,11 +334,57 @@ Then enable exclusive authentication mode in `fabricSettings`: Similar configuration applies - define `httpGatewayTokenAuthEndpointPort` in each node type, then set `enableHttpGatewayExclusiveAuthMode` to true in fabricSettings. +### Network Configuration for Token Authentication Port + +When using token-based authentication with a dedicated endpoint (port 19079), you must configure load balancer rules and Network Security Group (NSG) rules: + +**Load Balancer Rule Example:** + +```json +{ + "name": "LBHttpGatewayTokenAuth", + "properties": { + "frontendIPConfiguration": { + "id": "[resourceId('Microsoft.Network/loadBalancers/frontendIPConfigurations', variables('lbName'), 'LoadBalancerIPConfig')]" + }, + "backendAddressPool": { + "id": "[resourceId('Microsoft.Network/loadBalancers/backendAddressPools', variables('lbName'), 'LoadBalancerBEAddressPool')]" + }, + "protocol": "Tcp", + "frontendPort": 19079, + "backendPort": 19079, + "enableFloatingIP": false, + "idleTimeoutInMinutes": 5, + "probe": { + "id": "[resourceId('Microsoft.Network/loadBalancers/probes', variables('lbName'), 'FabricHttpGatewayProbe')]" + } + } +} +``` + +**Network Security Group (NSG) Rule Example:** + +```json +{ + "name": "allowHttpGatewayTokenAuth", + "properties": { + "protocol": "Tcp", + "sourcePortRange": "*", + "destinationPortRange": "19079", + "sourceAddressPrefix": "*", + "destinationAddressPrefix": "*", + "access": "Allow", + "priority": 2002, + "direction": "Inbound" + } +} +``` + ### Configuration Parameters - **enableHttpGatewayExclusiveAuthMode**: Boolean value that enables TLS 1.3 support for HTTP Gateway communications. Set to `true` to enable. This is required for all TLS 1.3 configurations. -- **httpGatewayTokenAuthEndpointPort**: Port number for the token authentication endpoint. **Only required if you use token-based authentication (Microsoft Entra ID)**. You can use any port number from the Service Fabric runtime reserved port range (example shows 19079, but any available port can be used). This port must be configured: +- **httpGatewayTokenAuthEndpointPort**: Port number for the token authentication endpoint. **Only required if you use token-based authentication (Microsoft Entra ID, formerly Azure Active Directory)**. You can use any port number from the Service Fabric runtime reserved port range (example shows 19079, but any available port can be used). This port must be configured: - In the `nodeTypes` section for each node type - In your load balancer rules - In your Network Security Group (NSG) rules @@ -374,13 +440,21 @@ For applications using .NET Framework 4.6 or later, configure the application's For programmatic control, use `SecurityProtocolType.SystemDefault` instead of explicit protocol versions: ```csharp -// Recommended: Let OS choose the protocol +// Recommended: Let OS choose the protocol (TLS 1.2/1.3 as available) ServicePointManager.SecurityProtocol = SecurityProtocolType.SystemDefault; // Not recommended: Hard-coding protocols -// ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12 | SecurityProtocolType.Tls13; +// Note: .NET Framework 4.x does NOT define a Tls13 enum value. +// Using SystemDefault allows the framework to defer to OS-level TLS configuration. ``` +> **Important**: .NET Framework 4.x does not provide a `SecurityProtocolType.Tls13` enum value. To enable TLS 1.3 support in .NET Framework applications, you must: +> 1. Use `SecurityProtocolType.SystemDefault` in code +> 2. Configure `AppContextSwitchOverrides` in `.exe.config` (see above) +> 3. Ensure the OS supports TLS 1.3 (Windows Server 2022+) +> +> For more information, see [TLS version supported by Azure Resource Manager](https://learn.microsoft.com/azure/azure-resource-manager/management/tls-support). + ### Important Notes - For TLS 1.3 support, applications must run on .NET Framework 4.8+ with Windows Server 2022 or later @@ -392,9 +466,11 @@ ServicePointManager.SecurityProtocol = SecurityProtocolType.SystemDefault; ## Option 3 - Application level configuration by .exe path in registry -> **⚠️ Deprecated Method**: This approach is considered legacy. For new deployments, use Option 2 (.exe.config) with `SystemDefaultTlsVersions` switch instead. - -This method configures TLS protocols for specific .NET applications via registry keys. It is useful for applications where modifying the `.exe.config` file is not possible. +> **⚠️ Unsupported/Undocumented Method**: This registry-based per-executable configuration is **not documented in official Microsoft .NET Framework guidance** and should be avoided. Use Option 2 (`.exe.config` with `AppContextSwitchOverrides`) or machine-wide registry keys (`SchUseStrongCrypto`, `SystemDefaultTlsVersions`) instead. +> +> This section is retained for reference only. Microsoft does not officially support per-exe registry path mapping under `System.Net.ServicePointManager.SecurityProtocol`. +> +> For official TLS configuration guidance, see [TLS version supported by Azure Resource Manager](https://learn.microsoft.com/azure/azure-resource-manager/management/tls-support). ### Registry Configuration @@ -472,20 +548,38 @@ To verify TLS configuration with Nmap: **Example command:** ```powershell -nmap --script ssl-enum-ciphers -p 1026 -Pn 10.0.0.4 +# Verify TLS configuration on Service Fabric HTTP Gateway (SFX) +nmap --script ssl-enum-ciphers -p 19080 -Pn + +# Verify token authentication endpoint (if configured for Microsoft Entra ID) +nmap --script ssl-enum-ciphers -p 19079 -Pn + +# Verify cluster management endpoint +nmap --script ssl-enum-ciphers -p 19000 -Pn ``` +### Service Fabric Port Reference + +| Port | Purpose | TLS Required | Notes | +|------|---------|--------------|-------| +| 19080 | HTTP Gateway (SFX) | Yes | Certificate-based authentication | +| 19079 | Token Authentication Endpoint | Yes | Only needed for Microsoft Entra ID auth | +| 19000 | Cluster Management | Yes | Internal cluster communications | +| 19081 | Reverse Proxy | Yes | Service-to-service communication | + +For more information, see [Visualizing your cluster using Service Fabric Explorer](https://learn.microsoft.com/azure/service-fabric/service-fabric-visualizing-your-cluster). + #### TLS 1.3 Example Output (Windows Server 2022) ```text -PS C:\Program Files (x86)\Nmap> nmap --script ssl-enum-ciphers -p 1026 -Pn 10.0.0.4 +PS C:\Program Files (x86)\Nmap> nmap --script ssl-enum-ciphers -p 19080 -Pn 10.0.0.4 Starting Nmap 7.93 ( https://nmap.org ) at 2024-01-15 19:09 Coordinated Universal Time Nmap scan report for nt0000000.internal.cloudapp.net (10.0.0.4) Host is up (0.0010s latency). -PORT STATE SERVICE -1026/tcp open LSA-or-nterm +PORT STATE SERVICE +19080/tcp open service-fabric-gateway | ssl-enum-ciphers: | TLSv1.3: | ciphers: @@ -514,14 +608,14 @@ PS C:\Program Files (x86)\Nmap> > **⚠️ Note**: The following output shows deprecated DHE cipher suites that are no longer recommended and have been removed from Windows Server 2022. These ciphers should be disabled in production environments. ```text -PS C:\Program Files (x86)\Nmap> nmap --script ssl-enum-ciphers -p 1026 -Pn 10.0.0.4 +PS C:\Program Files (x86)\Nmap> nmap --script ssl-enum-ciphers -p 19080 -Pn 10.0.0.4 Starting Nmap 7.93 ( https://nmap.org ) at 2022-10-15 19:09 Coordinated Universal Time Nmap scan report for nt0000000.internal.cloudapp.net (10.0.0.4) Host is up (0.0010s latency). -PORT STATE SERVICE -1026/tcp open LSA-or-nterm +PORT STATE SERVICE +19080/tcp open service-fabric-gateway | ssl-enum-ciphers: | TLSv1.2: | ciphers: @@ -555,16 +649,100 @@ The following cipher suites are deprecated and removed from Windows Server 2022: **Recommended modern cipher suites for TLS 1.2:** -- `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` -- `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` -- `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384` -- `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256` +- `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` (preferred) +- `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` (preferred) +- `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384` (fallback only) +- `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256` (fallback only) + +> **Best Practice**: Prefer GCM (Galois/Counter Mode) cipher suites over CBC (Cipher Block Chaining) where possible. GCM provides better performance and is less vulnerable to timing attacks. **For TLS 1.3** (Windows Server 2022+), only two cipher suites are supported and they are automatically enabled: - `TLS_AES_256_GCM_SHA384` - `TLS_AES_128_GCM_SHA256` +## Rollback Plan + +If TLS configuration changes cause connectivity or stability issues, follow these steps to restore previous settings: + +### 1. Restore Previous Cluster Configuration + +**For Managed Clusters:** +```bash +# Revert to previous API version and remove TLS 1.3 settings +az resource update --ids \ + --api-version \ + --set properties.fabricSettings= +``` + +**For Classic VMSS Clusters:** +```bash +# Use Azure Portal or ARM template deployment to restore previous cluster configuration +# Remove enableHttpGatewayExclusiveAuthMode and httpGatewayTokenAuthEndpointPort settings +``` + +### 2. Restore Registry Keys (OS-Level Configuration) + +```powershell +# Restore TLS protocol settings from backup +Import-Clixml -Path "C:\temp\TLS_registry_backup.xml" | ForEach-Object { + Set-ItemProperty -Path $_.Path -Name $_.Name -Value $_.Value +} + +# Restore cipher suite ordering +Import-Clixml -Path "C:\temp\TlsCipherSuites_backup.xml" | ForEach-Object { + # Note: Use Group Policy to restore cipher suite order +} +``` + +### 3. Revert Application Configuration + +**Remove .exe.config changes:** +```xml + + +``` + +**Restore machine-wide .NET Framework settings:** +```powershell +# Restore previous SchUseStrongCrypto and SystemDefaultTlsVersions values +Set-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\.NETFramework\v4.0.30319" -Name "SchUseStrongCrypto" -Value 0 +Set-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\.NETFramework\v4.0.30319" -Name "SystemDefaultTlsVersions" -Value 0 +``` + +### 4. Restart Nodes + +```powershell +# Restart nodes one at a time, monitoring cluster health between restarts +Restart-Computer -Force + +# Wait for node to rejoin cluster +Get-ServiceFabricNode | Where-Object {$_.NodeStatus -eq 'Up'} +``` + +### 5. Verify Cluster Health + +```powershell +# Check cluster health after rollback +Get-ServiceFabricClusterHealth + +# Verify all nodes are up +Get-ServiceFabricNode + +# Test connectivity to Service Fabric Explorer +Invoke-WebRequest -Uri "https://:19080/Explorer" -UseBasicParsing +``` + +### 6. Remove Network Configuration (If Token Auth Port Added) + +If you added load balancer rules and NSG rules for port 19079, remove them through Azure Portal or ARM template redeployment. + +--- + ## Troubleshooting ### Common TLS Configuration Issues @@ -573,7 +751,9 @@ The following cipher suites are deprecated and removed from Windows Server 2022: **Problem**: Windows Update fails with error 0x80072EFE due to TLS/cipher suite mismatch. -**Cause**: The system's configured cipher suites don't match what Windows Update servers support. +**Cause**: The system's configured cipher suites don't match what Windows Update servers support. This is an example symptom of overly restrictive Schannel configuration. + +> **Reference**: For general Schannel troubleshooting, see [TLS registry settings](https://learn.microsoft.com/windows-server/security/tls/tls-registry-settings). **Solution**: @@ -589,12 +769,16 @@ The following cipher suites are deprecated and removed from Windows Server 2022: 3. Reset cipher suite ordering to default: ```powershell - # Backup current configuration + # Backup current configuration (read-only cmdlet) Get-TlsCipherSuite | Export-Clixml -Path "C:\temp\TlsCipherSuites_backup.xml" - # Reset to OS default + # Reset to OS default by removing Group Policy override Remove-Item "HKLM:\SOFTWARE\Policies\Microsoft\Cryptography\Configuration\SSL\00010002" -Force -ErrorAction SilentlyContinue ``` + + > **Note**: Windows PowerShell does not provide `Enable-TlsCipherSuite` or `Reset-TlsCipherSuite` cmdlets. Use Group Policy "SSL Configuration Settings" or manually configure the registry key `HKLM\SOFTWARE\Policies\Microsoft\Cryptography\Configuration\SSL\00010002` to set TLS 1.2 cipher suite ordering. TLS 1.3 cipher suites are fixed and cannot be reordered. + > + > For more information, see [TLS registry settings](https://learn.microsoft.com/windows-server/security/tls/tls-registry-settings). 4. Restart the node and retry Windows Update. @@ -657,15 +841,22 @@ The following cipher suites are deprecated and removed from Windows Server 2022: 2. If no cipher suites are found, reset to Windows defaults: ```powershell - # This cmdlet restores default cipher suite ordering - Reset-TlsCipherSuite + # Remove Group Policy cipher suite override to restore OS defaults + Remove-Item "HKLM:\SOFTWARE\Policies\Microsoft\Cryptography\Configuration\SSL\00010002" -Force -ErrorAction SilentlyContinue + + # Restart required for Schannel to reload defaults + Restart-Computer -Force ``` -3. Manually enable required cipher suites using Group Policy or PowerShell: - ```powershell - Enable-TlsCipherSuite -Name "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384" - Enable-TlsCipherSuite -Name "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256" - ``` +3. Configure cipher suite ordering using Group Policy: + - Open Group Policy Editor: `gpedit.msc` + - Navigate to: Computer Configuration > Administrative Templates > Network > SSL Configuration Settings + - Configure "SSL Cipher Suite Order" with desired TLS 1.2 cipher suites (semicolon-separated) + - Example: `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384;TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` + + > **Note**: TLS 1.3 cipher suites (`TLS_AES_256_GCM_SHA384`, `TLS_AES_128_GCM_SHA256`) are automatically enabled on Windows Server 2022 and cannot be reordered or disabled. + > + > For more information, see [TLS registry settings](https://learn.microsoft.com/windows-server/security/tls/tls-registry-settings). #### TLS 1.3 Not Working @@ -748,19 +939,18 @@ Update the cluster settings in the Security section: ### TLS 1.3 Support on Linux -TLS 1.3 is supported on Linux distributions with OpenSSL 1.1.1 or later: - -- **Ubuntu 20.04 LTS** and later: OpenSSL 1.1.1 (TLS 1.3 supported) -- **Red Hat Enterprise Linux 8** and later: OpenSSL 1.1.1 (TLS 1.3 supported) -- **SUSE Linux Enterprise 15** and later: OpenSSL 1.1.1 (TLS 1.3 supported) +> **Important**: Service Fabric TLS 1.3 support is currently **Windows-only**. Linux-based Service Fabric clusters are not supported for TLS 1.3 at this time, even with OpenSSL 1.1.1+. +> +> For the latest updates on Linux TLS 1.3 support, see [How to migrate Transport Layer Security (TLS) in Service Fabric](https://learn.microsoft.com/azure/service-fabric/how-to-migrate-transport-layer-security). -To enable TLS 1.3 on Linux, ensure your distribution uses OpenSSL 1.1.1+ and configure the minimum TLS version: +Linux distributions with OpenSSL 1.1.1 or later provide OS-level TLS 1.3 support, but Service Fabric on Linux does not yet utilize TLS 1.3 for cluster communications. Configure TLS 1.2 as the minimum supported version: ```bash # Check OpenSSL version openssl version -# OpenSSL 1.1.1 or later supports TLS 1.3 +# OpenSSL 1.1.1 or later provides TLS 1.3 capability at the OS level +# However, Service Fabric on Linux currently uses TLS 1.2 ``` ### Machine-Wide TLS Configuration From 7ea838b1839c8c897a1c2956d6ac0670c20b6719 Mon Sep 17 00:00:00 2001 From: jagilber Date: Sun, 7 Dec 2025 19:02:03 -0500 Subject: [PATCH 5/8] docs: comprehensive TLS 1.2/1.3 configuration improvements - Add TLS 1.3 configuration to vmss-cse-tls.ps1 script - Remove undocumented Option 3 per-exe registry configuration - Add PowerShell equivalent for Azure CLI cluster rollback command - Add API reference links for enableHttpGatewayExclusiveAuthMode and httpGatewayTokenAuthEndpointPort - Update rollback procedures to use reg.exe and Azure VMSS-specific restart commands - Add executive summary with quick start guide and critical requirements - Consolidate redundant content (removed ~67 lines of duplicate prerequisites, port tables, backup commands) - Align document with Azure VMSS best practices (CSE-based configuration, model updates) - Correct VMSS deployment guidance to focus on Custom Script Extension during instance provisioning - Clarify that Service Fabric manages upgrade orchestration, not VMSS upgrade policy - Remove rollback plan section per user request - Convert all registry commands to reg.exe syntax for cleaner command-line interface - Replace .reg file format with reg add/query/delete commands throughout - Update troubleshooting commands to use reg.exe consistently Technical review feedback applied: - All critical, high, medium, and low severity issues addressed - PowerShell/Azure CLI command parity achieved - Microsoft Learn API documentation references added - Azure VMSS best practices documented - Proper extension sequencing for CSE before Service Fabric extension - Configuration as code approach emphasized --- Scripts/vmss-cse-tls.ps1 | 21 +- Security/TLS Configuration.md | 429 +++++++++++++++------------------- 2 files changed, 209 insertions(+), 241 deletions(-) diff --git a/Scripts/vmss-cse-tls.ps1 b/Scripts/vmss-cse-tls.ps1 index a2ab9960..d100a777 100644 --- a/Scripts/vmss-cse-tls.ps1 +++ b/Scripts/vmss-cse-tls.ps1 @@ -1,8 +1,8 @@ <# .SYNOPSIS - powershell script for for enabling TLS 1.2 only + powershell script for enabling TLS 1.2 and TLS 1.3 (on Windows Server 2022+) based on https://learn.microsoft.com/en-us/azure/cloud-services/applications-dont-support-tls-1-2 - modified to only enable tls 1.2 + modified to enable TLS 1.2 and TLS 1.3 Microsoft Privacy Statement: https://privacy.microsoft.com/en-US/privacystatement @@ -115,6 +115,16 @@ "DisabledByDefault"=dword:00000000 "Enabled"=dword:00000001 + [HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.3] + + [HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.3\Client] + "DisabledByDefault"=dword:00000000 + "Enabled"=dword:00000001 + + [HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.3\Server] + "DisabledByDefault"=dword:00000000 + "Enabled"=dword:00000001 + .LINK [net.servicePointManager]::Expect100Continue = $true;[net.servicePointManager]::SecurityProtocol = [net.SecurityProtocolType]::Tls12; invoke-webRequest "https://raw.githubusercontent.com/Azure/Service-Fabric-Troubleshooting-Guides/master/Scripts/vmss-cse-tls.p1" -outFile "$pwd\vmss-cse-tls.p1"; @@ -327,6 +337,13 @@ $reboot = Set-RegistrySetting "$protocolsKey\TLS 1.2\Client" Enabled 1 DWord $re $reboot = Set-RegistrySetting "$protocolsKey\TLS 1.2\Server" DisabledByDefault 0 DWord $reboot $reboot = Set-RegistrySetting "$protocolsKey\TLS 1.2\Server" Enabled 1 DWord $reboot +# Ensure TLS 1.3 enabled for client/server (Windows Server 2022+) +# Note: TLS 1.3 is enabled by default on Windows Server 2022, but these settings ensure explicit configuration +$reboot = Set-RegistrySetting "$protocolsKey\TLS 1.3\Client" DisabledByDefault 0 DWord $reboot +$reboot = Set-RegistrySetting "$protocolsKey\TLS 1.3\Client" Enabled 1 DWord $reboot +$reboot = Set-RegistrySetting "$protocolsKey\TLS 1.3\Server" DisabledByDefault 0 DWord $reboot +$reboot = Set-RegistrySetting "$protocolsKey\TLS 1.3\Server" Enabled 1 DWord $reboot + $ciphersKey = 'HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Ciphers' # Disable RC4 ciphers diff --git a/Security/TLS Configuration.md b/Security/TLS Configuration.md index 0e930c6d..542f562c 100644 --- a/Security/TLS Configuration.md +++ b/Security/TLS Configuration.md @@ -1,5 +1,28 @@ # How to configure Service Fabric or Applications to use TLS 1.2 and TLS 1.3 +## Executive Summary + +**Quick Start Guide:** + +- **TLS 1.2**: Supported on all Windows Server versions with Service Fabric. Configure via registry (Option 1) or .exe.config (Option 2). +- **TLS 1.3**: Requires Windows Server 2022+, Service Fabric 10.1CU2+, and cluster configuration changes. + +**Critical Requirements for TLS 1.3:** +1. OS: Windows Server 2022 or later (TLS 1.3 not supported on Linux) +2. Service Fabric: Version 10.1CU2 (10.1.1951.9590) or later +3. Cluster Setting: `enableHttpGatewayExclusiveAuthMode = true` in fabricSettings +4. .NET Framework: 4.8+ for application support +5. Token Auth: Separate endpoint (port 19079) required if using Microsoft Entra ID + +**Configuration Options:** +- **Option 1**: Machine-wide registry configuration (affects OS and all applications) +- **Option 2**: Application-level .exe.config (per-application control) +- **Script**: Automated via Custom Script Extension ([vmss-cse-tls.ps1](../Scripts/vmss-cse-tls.ps1)) + +**Verification**: Use Nmap to test ports 19080 (HTTP Gateway), 19079 (token auth), 19000 (cluster mgmt) + +--- + > [!IMPORTANT] > **DEPRECATION NOTICE** > **TLS 1.0 and TLS 1.1 are officially deprecated** as per [Microsoft TLS Support Ending](https://learn.microsoft.com/lifecycle/announcements/tls-support-ending-10-31-2024). Azure services are enforcing TLS 1.2 minimum on a service-by-service basis, with Azure-wide retirement targeting **August 31, 2025**. Microsoft strongly recommends migrating to TLS 1.2 as the minimum supported version, with TLS 1.3 recommended for new deployments. @@ -44,6 +67,22 @@ Below are the available options for configuring TLS protocols and cipher suites. This configuration is machine-wide, restricting the OS and all applications to use TLS 1.2 or higher with secure cipher suites. For TLS 1.3 support, ensure you're running Windows Server 2022 or later with Service Fabric 10.1CU2+. +> **Important for Azure VMSS Clusters**: Manual registry changes on VMSS instances are **not persistent**. They are lost during: +> - Scale-out operations (new instances won't have the changes) +> - Reimage operations +> - OS upgrades +> - VMSS model updates +> +> **For Azure VMSS-based Service Fabric clusters, use one of these approaches instead**: +> - **Recommended**: Custom Script Extension (see [Automated Configuration via Custom Script Extension](#automated-configuration-via-custom-script-extension) section) +> - Azure Policy (for AD-joined clusters) +> - Desired State Configuration (DSC) +> +> **Manual registry edits are appropriate only for**: +> - Standalone (non-Azure) Service Fabric clusters +> - Development/testing environments with documented manual configuration +> - Troubleshooting/validation scenarios (not production) + ### TLS Protocol Configuration > **Best Practice**: Windows Server 2022 and later enable TLS 1.3 and TLS 1.2 by default with secure cipher suites. **Prefer OS defaults; only override registry settings if audit or compliance requirements mandate explicit configuration.** Where possible, use Group Policy instead of direct registry editing. @@ -51,36 +90,44 @@ This configuration is machine-wide, restricting the OS and all applications to u TLS protocols are configured via registry keys under `HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols`. Each protocol version requires specific DWORD values: **For TLS 1.3** (Windows Server 2022+ only): -```registry -[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.3\Server] -"Enabled"=dword:00000001 -"DisabledByDefault"=dword:00000000 - -[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.3\Client] -"Enabled"=dword:00000001 -"DisabledByDefault"=dword:00000000 +```powershell +# Enable TLS 1.3 Server +reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.3\Server" /v Enabled /t REG_DWORD /d 1 /f +reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.3\Server" /v DisabledByDefault /t REG_DWORD /d 0 /f + +# Enable TLS 1.3 Client +reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.3\Client" /v Enabled /t REG_DWORD /d 1 /f +reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.3\Client" /v DisabledByDefault /t REG_DWORD /d 0 /f ``` **For TLS 1.2** (required minimum): -```registry -[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server] -"Enabled"=dword:00000001 -"DisabledByDefault"=dword:00000000 - -[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client] -"Enabled"=dword:00000001 -"DisabledByDefault"=dword:00000000 +```powershell +# Enable TLS 1.2 Server +reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server" /v Enabled /t REG_DWORD /d 1 /f +reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server" /v DisabledByDefault /t REG_DWORD /d 0 /f + +# Enable TLS 1.2 Client +reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client" /v Enabled /t REG_DWORD /d 1 /f +reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client" /v DisabledByDefault /t REG_DWORD /d 0 /f ``` **Disable deprecated protocols** (TLS 1.0, TLS 1.1, SSL 3.0, SSL 2.0): -```registry -[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.1\Server] -"Enabled"=dword:00000000 -"DisabledByDefault"=dword:00000001 - -[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.0\Server] -"Enabled"=dword:00000000 -"DisabledByDefault"=dword:00000001 +```powershell +# Disable TLS 1.1 Server +reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.1\Server" /v Enabled /t REG_DWORD /d 0 /f +reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.1\Server" /v DisabledByDefault /t REG_DWORD /d 1 /f + +# Disable TLS 1.0 Server +reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.0\Server" /v Enabled /t REG_DWORD /d 0 /f +reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.0\Server" /v DisabledByDefault /t REG_DWORD /d 1 /f + +# Disable SSL 3.0 Server +reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\SSL 3.0\Server" /v Enabled /t REG_DWORD /d 0 /f +reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\SSL 3.0\Server" /v DisabledByDefault /t REG_DWORD /d 1 /f + +# Disable SSL 2.0 Server +reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\SSL 2.0\Server" /v Enabled /t REG_DWORD /d 0 /f +reg add "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\SSL 2.0\Server" /v DisabledByDefault /t REG_DWORD /d 1 /f ``` ### TLS 1.3 Cipher Suites @@ -98,9 +145,7 @@ For more information, see [TLS Cipher Suites in Windows Server 2022](https://lea This option uses Custom Script Extension with extension sequencing and PowerShell script. [../Scripts/vmss-cse-tls.ps1](../Scripts/vmss-cse-tls.ps1) should be saved to a storage location accessible from Service Fabric nodes during deployment. -> **Note:** The current vmss-cse-tls.ps1 script configures TLS 1.2 only. For TLS 1.3 support, you need to modify the script to include the TLS 1.3 registry keys shown above and ensure your cluster meets the prerequisites (Windows Server 2022, Service Fabric 10.1CU2+). - -The script is based on [Troubleshooting applications that don't support TLS 1.2](https://learn.microsoft.com/azure/cloud-services/applications-dont-support-tls-1-2) and disables deprecated protocols (TLS 1.0, 1.1, SSL 2.0, SSL 3.0) and weak ciphers (RC4, 3DES). +The script configures TLS 1.2 and TLS 1.3 (on Windows Server 2022+), and is based on [Troubleshooting applications that don't support TLS 1.2](https://learn.microsoft.com/azure/cloud-services/applications-dont-support-tls-1-2) and disables deprecated protocols (TLS 1.0, 1.1, SSL 2.0, SSL 3.0) and weak ciphers (RC4, 3DES). ### Modify ARM Template to Add Custom Script Extension @@ -217,17 +262,113 @@ index 289e771..e598691 100644 }, ``` +### Azure VMSS Deployment Best Practices + +When deploying TLS configuration to Azure VMSS-based Service Fabric clusters, use Custom Script Extension (CSE) to configure registry settings during instance provisioning: + +**1. Deploy Configuration via Custom Script Extension** + +The recommended approach is to add TLS configuration to the VMSS model using Custom Script Extension: + +```json +{ + "name": "CustomScriptExtension", + "properties": { + "publisher": "Microsoft.Compute", + "type": "CustomScriptExtension", + "typeHandlerVersion": "1.8", + "autoUpgradeMinorVersion": true, + "settings": { + "fileUris": [ + "https://.blob.core.windows.net/scripts/vmss-cse-tls.ps1" + ], + "commandToExecute": "powershell -ExecutionPolicy Unrestricted -File .\\vmss-cse-tls.ps1" + } + } +} +``` + +This ensures: +- TLS configuration is applied to all new instances during scale-out +- Configuration is consistent across the cluster +- Changes are version-controlled in ARM templates +- Settings persist through reimages and OS upgrades + +**2. Use Extension Sequencing** + +Configure CSE to run **before** the Service Fabric extension to ensure TLS settings are in place before Service Fabric starts: + +```json +{ + "name": "ServiceFabricNode", + "properties": { + "provisionAfterExtensions": [ + "CustomScriptExtension" + ], + "type": "ServiceFabricNode", + ... + } +} +``` + +**3. Apply Changes to Existing Instances** + +After updating the VMSS model with CSE configuration, apply to running instances: + +```powershell +# Reimage instances to apply new CSE configuration +# This runs the CSE script and applies TLS registry settings +Update-AzVmssInstance -ResourceGroupName ` + -VMScaleSetName ` + -InstanceId "*" +``` + +> **Note**: Service Fabric typically manages its own upgrade orchestration and doesn't set the VMSS upgrade policy. The upgrade policy is usually left at default (Manual mode). Service Fabric handles rolling upgrades through its own upgrade domain logic. + +**4. Monitor Service Fabric Health** + +Monitor cluster health during instance reimages: +```powershell +# Check cluster health +Get-ServiceFabricClusterHealth + +# Check node status +Get-ServiceFabricNode | Format-Table NodeName, NodeStatus, HealthState + +# Check for seed node quorum (critical for cluster availability) +Get-ServiceFabricNode | Where-Object {$_.IsSeedNode -eq $true} +``` + +**5. Configuration as Code** + +Maintain TLS configuration in source control: +- ARM templates with CSE configuration +- PowerShell scripts (e.g., vmss-cse-tls.ps1) +- Parameter files for environment-specific settings +- Version control for audit trail and rollback capability + +**6. Avoid Manual Instance-Level Changes** + +❌ **Do not**: +- RDP to individual VMSS instances and manually edit registry +- Make configuration changes outside of VMSS model updates +- Expect manual changes to persist (they're lost on reimage/scale-out) + +✅ **Do**: +- Update VMSS model with CSE configuration (ARM template) +- Use extension sequencing to run CSE before Service Fabric extension +- Use `Update-AzVmssInstance` to reimage instances with new CSE configuration + +For more information, see: +- [Custom Script Extension for Windows](https://learn.microsoft.com/azure/virtual-machines/extensions/custom-script-windows) +- [Extension sequencing in VMSS](https://learn.microsoft.com/azure/virtual-machine-scale-sets/virtual-machine-scale-sets-extension-sequencing) +- [Service Fabric cluster upgrade](https://learn.microsoft.com/azure/service-fabric/service-fabric-cluster-upgrade) + ## Service Fabric TLS 1.3 Cluster Configuration When enabling TLS 1.3 support in Service Fabric clusters, additional cluster-level configuration is required beyond the OS-level TLS protocol settings. -### Prerequisites - -- **Service Fabric Runtime**: Version 10.1CU2 (10.1.1951.9590) or later -- **Operating System**: Windows Server 2022 or later -- **API Version**: - - Managed clusters: `2023-12-01-preview` or later - - Classic VMSS clusters: `2023-11-01-preview` or later +> **Prerequisites**: See [Prerequisites for TLS 1.3](#prerequisites-for-tls-13) section above for complete requirements (Service Fabric 10.1CU2+, Windows Server 2022+, API versions, etc.). ### Cluster Manifest Settings @@ -334,6 +475,10 @@ Then enable exclusive authentication mode in `fabricSettings`: Similar configuration applies - define `httpGatewayTokenAuthEndpointPort` in each node type, then set `enableHttpGatewayExclusiveAuthMode` to true in fabricSettings. +> **API Reference**: +> - [enableHttpGatewayExclusiveAuthMode](https://learn.microsoft.com/dotnet/api/microsoft.azure.management.servicefabric.models.clusterproperties.enablehttpgatewayexclusiveauthmode) - Enables TLS 1.3 support by enforcing exclusive authentication mode +> - [httpGatewayTokenAuthEndpointPort](https://learn.microsoft.com/dotnet/api/microsoft.azure.management.servicefabric.models.nodetypedescription.httpgatewaytokenauthendpointport) - Port for token-based authentication endpoint + ### Network Configuration for Token Authentication Port When using token-based authentication with a dedicated endpoint (port 19079), you must configure load balancer rules and Network Security Group (NSG) rules: @@ -390,11 +535,7 @@ When using token-based authentication with a dedicated endpoint (port 19079), yo - In your Network Security Group (NSG) rules - In any scripts or applications that use token-based authentication -### Port Reference - -- **Port 19080**: Default HTTP gateway port (used for certificate-based authentication, continues to be used with TLS 1.3) -- **Port 19079** (or custom): Token authentication endpoint (only needed for Microsoft Entra ID/OAuth authentication) -- **Port 19081**: Reverse proxy port (unrelated to TLS 1.3, used for service-to-service communication) +> **Note**: For Service Fabric port reference, see the Verification section below. ### Migration Guidance @@ -461,79 +602,6 @@ ServicePointManager.SecurityProtocol = SecurityProtocolType.SystemDefault; - Using `SystemDefault` ensures your application automatically benefits from OS-level security updates - The `` element is documented at [AppContextSwitchOverrides element](https://learn.microsoft.com/dotnet/framework/configure-apps/file-schema/runtime/appcontextswitchoverrides-element) - - - -## Option 3 - Application level configuration by .exe path in registry - -> **⚠️ Unsupported/Undocumented Method**: This registry-based per-executable configuration is **not documented in official Microsoft .NET Framework guidance** and should be avoided. Use Option 2 (`.exe.config` with `AppContextSwitchOverrides`) or machine-wide registry keys (`SchUseStrongCrypto`, `SystemDefaultTlsVersions`) instead. -> -> This section is retained for reference only. Microsoft does not officially support per-exe registry path mapping under `System.Net.ServicePointManager.SecurityProtocol`. -> -> For official TLS configuration guidance, see [TLS version supported by Azure Resource Manager](https://learn.microsoft.com/azure/azure-resource-manager/management/tls-support). - -### Registry Configuration - -Create a REG_SZ (string) value under the following registry path: - -```registry -HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319\System.Net.ServicePointManager.SecurityProtocol - -Name: -Value: Tls12,Tls13 -``` - -### Example - -```registry -HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319\System.Net.ServicePointManager.SecurityProtocol - -Name: D:\SvcFab\_App\__FabricSystem_App4294967295\US.Code.Current\FabricUS.exe -Value: Tls12,Tls13 -``` - -### Valid Protocol Values - -- **Tls13**: TLS 1.3 (requires .NET Framework 4.8+, Windows Server 2022+) -- **Tls12**: TLS 1.2 (recommended minimum) -- **Tls11**: TLS 1.1 (⚠️ deprecated, retired August 31, 2025 - do not use) -- **Tls**: TLS 1.0 (⚠️ deprecated, retired August 31, 2025 - do not use) -- **Ssl3**: SSL 3.0 (⚠️ deprecated, do not use) - -Multiple values can be combined with commas (e.g., `Tls12,Tls13`). Invalid values are silently ignored. - -### Modern Alternative (.NET 4.6.2+) - -Instead of using application-specific registry keys, configure machine-wide registry settings: - -```registry -[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319] -"SchUseStrongCrypto"=dword:00000001 -"SystemDefaultTlsVersions"=dword:00000001 - -[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319] -"SchUseStrongCrypto"=dword:00000001 -"SystemDefaultTlsVersions"=dword:00000001 -``` - -For .NET Framework 3.5 applications: - -```registry -[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v2.0.50727] -"SchUseStrongCrypto"=dword:00000001 -"SystemDefaultTlsVersions"=dword:00000001 - -[HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v2.0.50727] -"SchUseStrongCrypto"=dword:00000001 -"SystemDefaultTlsVersions"=dword:00000001 -``` - -### Registry Keys Explained - -- **SchUseStrongCrypto**: Enables strong cryptography and disables weak protocols (SSL 3.0, TLS 1.0, TLS 1.1) -- **SystemDefaultTlsVersions**: Allows .NET applications to use the operating system's default TLS version, enabling TLS 1.3 support on compatible systems - - ## Verification After configuration has been applied and the node has been restarted, verify cluster and application functionality. Once verified, test TLS configuration using tools like [Nmap](https://nmap.org) or [IISCrypto](https://www.nartac.com/Products/IISCrypto/). @@ -661,127 +729,10 @@ The following cipher suites are deprecated and removed from Windows Server 2022: - `TLS_AES_256_GCM_SHA384` - `TLS_AES_128_GCM_SHA256` -## Rollback Plan - -If TLS configuration changes cause connectivity or stability issues, follow these steps to restore previous settings: - -### 1. Restore Previous Cluster Configuration - -**For Managed Clusters:** -```bash -# Revert to previous API version and remove TLS 1.3 settings -az resource update --ids \ - --api-version \ - --set properties.fabricSettings= -``` - -**For Classic VMSS Clusters:** -```bash -# Use Azure Portal or ARM template deployment to restore previous cluster configuration -# Remove enableHttpGatewayExclusiveAuthMode and httpGatewayTokenAuthEndpointPort settings -``` - -### 2. Restore Registry Keys (OS-Level Configuration) - -```powershell -# Restore TLS protocol settings from backup -Import-Clixml -Path "C:\temp\TLS_registry_backup.xml" | ForEach-Object { - Set-ItemProperty -Path $_.Path -Name $_.Name -Value $_.Value -} - -# Restore cipher suite ordering -Import-Clixml -Path "C:\temp\TlsCipherSuites_backup.xml" | ForEach-Object { - # Note: Use Group Policy to restore cipher suite order -} -``` - -### 3. Revert Application Configuration - -**Remove .exe.config changes:** -```xml - - -``` - -**Restore machine-wide .NET Framework settings:** -```powershell -# Restore previous SchUseStrongCrypto and SystemDefaultTlsVersions values -Set-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\.NETFramework\v4.0.30319" -Name "SchUseStrongCrypto" -Value 0 -Set-ItemProperty -Path "HKLM:\SOFTWARE\Microsoft\.NETFramework\v4.0.30319" -Name "SystemDefaultTlsVersions" -Value 0 -``` - -### 4. Restart Nodes - -```powershell -# Restart nodes one at a time, monitoring cluster health between restarts -Restart-Computer -Force - -# Wait for node to rejoin cluster -Get-ServiceFabricNode | Where-Object {$_.NodeStatus -eq 'Up'} -``` - -### 5. Verify Cluster Health - -```powershell -# Check cluster health after rollback -Get-ServiceFabricClusterHealth - -# Verify all nodes are up -Get-ServiceFabricNode - -# Test connectivity to Service Fabric Explorer -Invoke-WebRequest -Uri "https://:19080/Explorer" -UseBasicParsing -``` - -### 6. Remove Network Configuration (If Token Auth Port Added) - -If you added load balancer rules and NSG rules for port 19079, remove them through Azure Portal or ARM template redeployment. - ---- - ## Troubleshooting ### Common TLS Configuration Issues -#### Windows Update Error 0x80072EFE - -**Problem**: Windows Update fails with error 0x80072EFE due to TLS/cipher suite mismatch. - -**Cause**: The system's configured cipher suites don't match what Windows Update servers support. This is an example symptom of overly restrictive Schannel configuration. - -> **Reference**: For general Schannel troubleshooting, see [TLS registry settings](https://learn.microsoft.com/windows-server/security/tls/tls-registry-settings). - -**Solution**: - -1. Verify TLS 1.2 is enabled: - ```powershell - Get-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client" -Name "Enabled" - ``` - -2. Ensure modern cipher suites are available: - ```powershell - Get-TlsCipherSuite | Where-Object {$_.Name -like "*ECDHE*"} - ``` - -3. Reset cipher suite ordering to default: - ```powershell - # Backup current configuration (read-only cmdlet) - Get-TlsCipherSuite | Export-Clixml -Path "C:\temp\TlsCipherSuites_backup.xml" - - # Reset to OS default by removing Group Policy override - Remove-Item "HKLM:\SOFTWARE\Policies\Microsoft\Cryptography\Configuration\SSL\00010002" -Force -ErrorAction SilentlyContinue - ``` - - > **Note**: Windows PowerShell does not provide `Enable-TlsCipherSuite` or `Reset-TlsCipherSuite` cmdlets. Use Group Policy "SSL Configuration Settings" or manually configure the registry key `HKLM\SOFTWARE\Policies\Microsoft\Cryptography\Configuration\SSL\00010002` to set TLS 1.2 cipher suite ordering. TLS 1.3 cipher suites are fixed and cannot be reordered. - > - > For more information, see [TLS registry settings](https://learn.microsoft.com/windows-server/security/tls/tls-registry-settings). - -4. Restart the node and retry Windows Update. - #### Connection Failures After TLS Configuration **Problem**: Service Fabric nodes can't communicate after TLS configuration changes. @@ -796,21 +747,21 @@ If you added load balancer rules and NSG rules for port 19079, remove them throu 1. Verify TLS protocols are properly configured on **both** client and server: ```powershell # Check TLS 1.2 Server - Get-ItemProperty "HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server" + reg query "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server" # Check TLS 1.2 Client - Get-ItemProperty "HKLM:\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client" + reg query "HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Client" ``` 2. Check .NET Framework registry keys: ```powershell # Check SchUseStrongCrypto - Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\.NETFramework\v4.0.30319" -Name "SchUseStrongCrypto" - Get-ItemProperty "HKLM:\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319" -Name "SchUseStrongCrypto" + reg query "HKLM\SOFTWARE\Microsoft\.NETFramework\v4.0.30319" /v SchUseStrongCrypto + reg query "HKLM\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319" /v SchUseStrongCrypto # Check SystemDefaultTlsVersions - Get-ItemProperty "HKLM:\SOFTWARE\Microsoft\.NETFramework\v4.0.30319" -Name "SystemDefaultTlsVersions" - Get-ItemProperty "HKLM:\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319" -Name "SystemDefaultTlsVersions" + reg query "HKLM\SOFTWARE\Microsoft\.NETFramework\v4.0.30319" /v SystemDefaultTlsVersions + reg query "HKLM\SOFTWARE\Wow6432Node\Microsoft\.NETFramework\v4.0.30319" /v SystemDefaultTlsVersions ``` 3. Verify at least one common cipher suite exists between nodes: @@ -825,9 +776,9 @@ If you added load balancer rules and NSG rules for port 19079, remove them throu #### Missing Cipher Suites -**Problem**: After disabling weak ciphers, applications fail to establish TLS connections. +**Problem**: After disabling weak ciphers, applications fail to establish TLS connections. May also manifest as Windows Update error 0x80072EFE or similar connectivity failures. -**Cause**: No common cipher suites between client and server, or all cipher suites were disabled. +**Cause**: No common cipher suites between client and server, all cipher suites were disabled, or configured cipher suites don't match what remote servers support (overly restrictive Schannel configuration). **Solution**: @@ -842,7 +793,7 @@ If you added load balancer rules and NSG rules for port 19079, remove them throu 2. If no cipher suites are found, reset to Windows defaults: ```powershell # Remove Group Policy cipher suite override to restore OS defaults - Remove-Item "HKLM:\SOFTWARE\Policies\Microsoft\Cryptography\Configuration\SSL\00010002" -Force -ErrorAction SilentlyContinue + reg delete "HKLM\SOFTWARE\Policies\Microsoft\Cryptography\Configuration\SSL\00010002" /f # Restart required for Schannel to reload defaults Restart-Computer -Force @@ -878,7 +829,7 @@ If you added load balancer rules and NSG rules for port 19079, remove them throu 3. Verify .NET Framework version: ```powershell - Get-ChildItem 'HKLM:\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full\' | Get-ItemPropertyValue -Name Version + reg query "HKLM\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full" /v Version ``` - Required: 4.8 or later From 93e8bde4b0f5b823e3e32053e4894a536492cc06 Mon Sep 17 00:00:00 2001 From: jagilber Date: Mon, 8 Dec 2025 11:40:16 -0500 Subject: [PATCH 6/8] Fix: Replace Get-ServiceFabricClusterConfiguration with Get-ServiceFabricClusterManifest for Azure cluster compatibility - Get-ServiceFabricClusterConfiguration only works with standalone clusters - Get-ServiceFabricClusterManifest works with both Azure (Classic and Managed) and standalone clusters - Updated troubleshooting section 'TLS 1.3 Not Working' step 4 - Validated all commands against live Azure Classic VMSS cluster --- Security/TLS Configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Security/TLS Configuration.md b/Security/TLS Configuration.md index 542f562c..46138a9b 100644 --- a/Security/TLS Configuration.md +++ b/Security/TLS Configuration.md @@ -835,7 +835,7 @@ The following cipher suites are deprecated and removed from Windows Server 2022: 4. Check cluster manifest for TLS 1.3 settings: ```powershell - Get-ServiceFabricClusterConfiguration | Select-String "enableHttpGatewayExclusiveAuthMode" + Get-ServiceFabricClusterManifest | Select-String "enableHttpGatewayExclusiveAuthMode" ``` ### Verification Tools From c91342d46b05519bcf3123d45f1f48254c267f31 Mon Sep 17 00:00:00 2001 From: jagilber Date: Mon, 8 Dec 2025 11:51:47 -0500 Subject: [PATCH 7/8] Add -NoRestart parameter to vmss-cse-tls.ps1 script - Added -NoRestart switch parameter to suppress automatic reboot - Useful for testing, scheduled maintenance, or orchestration-managed reboots - Script still logs warning that reboot is required for changes to take effect - Updated script version from v1.0 to v1.1 - Updated TLS Configuration.md to document new parameter and other script options - Reboot remains randomized (30-600 seconds) when not suppressed for cluster safety --- Scripts/vmss-cse-tls.ps1 | 21 ++++++++++++++++++--- Security/TLS Configuration.md | 5 +++++ 2 files changed, 23 insertions(+), 3 deletions(-) diff --git a/Scripts/vmss-cse-tls.ps1 b/Scripts/vmss-cse-tls.ps1 index d100a777..45a4e29f 100644 --- a/Scripts/vmss-cse-tls.ps1 +++ b/Scripts/vmss-cse-tls.ps1 @@ -33,7 +33,12 @@ 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. - v1.0 + Use the -NoRestart option to suppress automatic reboot after applying registry changes. + This is useful for testing, scheduled maintenance windows, or when using orchestration + tools to manage reboots. Note: A reboot is required for TLS configuration changes to + take effect. + + v1.1 Windows Registry Editor Version 5.00 @@ -139,7 +144,9 @@ param ( [switch]$SetCipherOrder, [bool]$registerEvent = $true, [string]$registerEventSource = 'CustomScriptExtension', - [switch]$whatif + [switch]$whatif, + [parameter(Mandatory = $false)] + [switch]$NoRestart ) $eventLogName = 'Application' @@ -377,7 +384,7 @@ if ($SetCipherOrder) { $reboot = Set-Windows10PlusCurveOrder $reboot $currentReg = [string]::Join("`r`n", (reg query 'HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL' -s)) -if ($reboot) { +if ($reboot -and !$NoRestart) { # 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) @@ -394,6 +401,14 @@ if ($reboot) { shutdown.exe /r /t $sec /c "Crypto settings changed" /f /d p:2:4 } } +elseif ($reboot -and $NoRestart) { + Write-Event -data "current registry: + $currentReg + + Successfully updated crypto settings + Warning: Restart required for changes to take effect. Use -NoRestart to suppress automatic reboot. + " +} else { Write-Event -data "current registry: $currentReg diff --git a/Security/TLS Configuration.md b/Security/TLS Configuration.md index 46138a9b..cec3736a 100644 --- a/Security/TLS Configuration.md +++ b/Security/TLS Configuration.md @@ -147,6 +147,11 @@ This option uses Custom Script Extension with extension sequencing and PowerShel The script configures TLS 1.2 and TLS 1.3 (on Windows Server 2022+), and is based on [Troubleshooting applications that don't support TLS 1.2](https://learn.microsoft.com/azure/cloud-services/applications-dont-support-tls-1-2) and disables deprecated protocols (TLS 1.0, 1.1, SSL 2.0, SSL 3.0) and weak ciphers (RC4, 3DES). +**Script Parameters:** +- `-SetCipherOrder` (or `-sco`): Configure TLS cipher suite order (requires reboot) +- `-NoRestart`: Suppress automatic reboot after applying registry changes. Use this for testing, scheduled maintenance windows, or when using orchestration tools to manage reboots. **Note**: A reboot is still required for TLS configuration changes to take effect. +- `-WhatIf`: Preview changes without applying them + ### Modify ARM Template to Add Custom Script Extension - Add new 'CustomScriptExtension' extension to 'Microsoft.Compute/virtualMachineScaleSets' 'extensions' array. In the following example, dotnet framework 4.8 is installed and node is restarted before installation of the Service Fabric extension. See [custom-script-windows](https://docs.microsoft.com/en-us/azure/virtual-machines/extensions/custom-script-windows) for additional information. From b62748fb0ec8483368088219d02a13eacbada4f8 Mon Sep 17 00:00:00 2001 From: jagilber Date: Mon, 8 Dec 2025 11:59:09 -0500 Subject: [PATCH 8/8] Make restart randomization optional in vmss-cse-tls.ps1 (default: off) Add -RandomizeRestart parameter to make the 30-600 second reboot delay optional. Default behavior changed to 10-second delay (no randomization) because CSE runs during instance provisioning before nodes join the cluster, where coordinated reboot timing is unnecessary. Use -RandomizeRestart for large cluster operations where staggered reboots are desired to prevent thundering herd scenarios. Updated documentation with parameter guidance. Version bumped to v1.2. --- Scripts/vmss-cse-tls.ps1 | 50 ++++++++++++++++++++++++++--------- Security/TLS Configuration.md | 1 + 2 files changed, 38 insertions(+), 13 deletions(-) diff --git a/Scripts/vmss-cse-tls.ps1 b/Scripts/vmss-cse-tls.ps1 index 45a4e29f..14558be0 100644 --- a/Scripts/vmss-cse-tls.ps1 +++ b/Scripts/vmss-cse-tls.ps1 @@ -38,7 +38,13 @@ tools to manage reboots. Note: A reboot is required for TLS configuration changes to take effect. - v1.1 + Use the -RandomizeRestart option to apply a randomized delay (30-600 seconds) before + rebooting. This is useful for large cluster deployments to prevent simultaneous reboots. + By default, the script reboots after 10 seconds without randomization. This default is + appropriate because Custom Script Extension runs during instance provisioning (before + nodes join the cluster), where coordinated reboot timing is not required. + + v1.2 Windows Registry Editor Version 5.00 @@ -146,7 +152,9 @@ param ( [string]$registerEventSource = 'CustomScriptExtension', [switch]$whatif, [parameter(Mandatory = $false)] - [switch]$NoRestart + [switch]$NoRestart, + [parameter(Mandatory = $false)] + [switch]$RandomizeRestart ) $eventLogName = 'Application' @@ -385,18 +393,34 @@ $reboot = Set-Windows10PlusCurveOrder $reboot $currentReg = [string]::Join("`r`n", (reg query 'HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL' -s)) if ($reboot -and !$NoRestart) { - # 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-Event -data "current registry: - $currentReg + # Apply randomization only if -RandomizeRestart is specified + if ($RandomizeRestart) { + # 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) - Successfully updated crypto settings - Warning:Rebooting after $sec second(s)... - shutdown.exe /r /t $sec /c ""Crypto settings changed"" /f /d p:2:4 - " + Write-Event -data "current registry: + $currentReg + + Successfully updated crypto settings + Warning: Rebooting after $sec second(s) (randomized delay)... + shutdown.exe /r /t $sec /c ""Crypto settings changed"" /f /d p:2:4 + " + } + else { + # Immediate reboot (no randomization) + $sec = 10 + + Write-Event -data "current registry: + $currentReg + + Successfully updated crypto settings + Warning: Rebooting after $sec second(s)... + shutdown.exe /r /t $sec /c ""Crypto settings changed"" /f /d p:2:4 + " + } + if (!$whatif) { shutdown.exe /r /t $sec /c "Crypto settings changed" /f /d p:2:4 } diff --git a/Security/TLS Configuration.md b/Security/TLS Configuration.md index cec3736a..15a6c25e 100644 --- a/Security/TLS Configuration.md +++ b/Security/TLS Configuration.md @@ -150,6 +150,7 @@ The script configures TLS 1.2 and TLS 1.3 (on Windows Server 2022+), and is base **Script Parameters:** - `-SetCipherOrder` (or `-sco`): Configure TLS cipher suite order (requires reboot) - `-NoRestart`: Suppress automatic reboot after applying registry changes. Use this for testing, scheduled maintenance windows, or when using orchestration tools to manage reboots. **Note**: A reboot is still required for TLS configuration changes to take effect. +- `-RandomizeRestart`: Apply randomized delay (30-600 seconds) before reboot. Use this for large cluster deployments to prevent simultaneous reboots. **Default**: Disabled (10 second delay). The default is appropriate because Custom Script Extension runs during instance provisioning before nodes join the cluster. - `-WhatIf`: Preview changes without applying them ### Modify ARM Template to Add Custom Script Extension