Microsoft's edit · TLS registry settings

22 title: Transport Layer Security (TLS) registry settings

33 description: Learn about supported registry setting information for the Windows implementation of the Transport Layer Security (TLS) protocol.

44 ms.topic: article

5 −ms.date: 04/10/2023

5 +ms.date: 07/16/2024

66 ---

77

88 # Transport Layer Security (TLS) registry settings

99

1010 > Applies to: Windows Server 2022, Windows Server 2019, Windows Server 2016, Windows 11, Windows 10, and earlier versions as noted

1111

12 −This article explains the supported registry setting information for the Windows implementation of the Transport Layer Security (TLS) protocol and the Secure Sockets Layer (SSL) protocol through the SChannel Security Support Provider (SSP). The registry subkeys and entries covered in this article help you administer and troubleshoot the SChannel SSP, specifically the TLS and SSL protocols.

12 +This article explains the supported registry setting information for the Windows implementation of the Transport Layer Security (TLS) protocol and the Secure Sockets Layer (SSL) protocol through the SChannel Security Support Provider (SSP). The registry subkeys and entries covered in this article help you administer and troubleshoot the SChannel SSP, specifically the TLS, and SSL protocols.

1313

1414 > [!CAUTION]

1515 > This information is provided as a reference to use when you are troubleshooting or verifying that the required settings are applied. We recommend that you do not directly edit the registry unless there is no other alternative. Modifications to the registry are not validated by the Registry Editor or by the Windows operating system before they are applied. As a result, incorrect values can be stored, and this can result in unrecoverable errors in the system. When possible, instead of editing the registry directly, use Group Policy or other Windows tools such as the Microsoft Management Console (MMC). If you must edit the registry, use extreme caution.

2727 |4|Informational and Success events|

2828 |5|Error, Informational, and Success events|

2929 |6|Warning, Informational, and Success events|

30 −|7|Error, Warning, Informational and Success events|

30 +|7|Error, Warning, Informational, and Success events|

3131

3232 > [!NOTE]

3333 > You must reboot your device after changing the SChannel logging level.

7878

7979 This entry specifies client TLS session cache item lifetime in milliseconds. Beginning with Windows Server 2008 and Windows Vista the default is 10 hours. A value of **0** turns off TLS session caching on the client.

8080

81 −The first time a client connects to a server through the SChannel SSP, a full TLS/SSL handshake is performed. When this is complete, the master secret, cipher suite, and certificates are stored in the session cache on the respective client and server.

81 +The first time a client connects to a server through the SChannel SSP, a full TLS/SSL handshake is performed. When complete, the master secret, cipher suite, and certificates are stored in the session cache on the respective client and server.

8282

8383 Registry path: **HKLM SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL**

8484

136136

137137 ## KeyExchangeAlgorithm key sizes

138138

139 −These entries listed below may not exist in the registry by default and must be manually created. Use of key exchange algorithms should be controlled by configuring the cipher suite order.

139 +These following entries may not exist in the registry by default and must be manually created. Use of key exchange algorithms should be controlled by configuring the cipher suite order. To learn more about TLS/SSL cipher suite cryptographic algorithms, see [Cipher Suites in TLS/SSL (SChannel SSP)](/windows/win32/secauthn/cipher-suites-in-schannel).

140140

141141 # [Diffie-Hellman](#tab/diffie-hellman)

142142

144144

145145 Registry path: **HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\KeyExchangeAlgorithms\Diffie-Hellman**

146146

147 −To specify a minimum supported range of Diffie-Hellman key bit length for the TLS client, create a **ClientMinKeyBitLength** entry. After you've created the entry, change the DWORD value to the desired bit length. If not configured, 1024 bits will be the minimum.

147 +To specify a minimum supported range of Diffie-Hellman key bit length for the TLS client, create a **ClientMinKeyBitLength** entry. After you've created the entry, change the DWORD value to the desired bit length. If not configured, 1024 bits is the minimum.

148148

149149 To specify a maximum supported range of Diffie-Hellman key bit length for the TLS client, create a **ClientMaxKeyBitLength** entry. After you've created the entry, change the DWORD value to the desired bit length.

150150

165165 > [!NOTE]

166166 > Configured elliptic curves determine the cryptographic strength of the ECDHE key exchange. For more information, see [Manage Transport Layer Security (TLS)](manage-tls.md#configuring-tls-ecc-curve-order).

167167

168 −To learn more about TLS/SSL cipher suite cryptographic algorithms, see:

169 −

170 −- [Cipher Suites in TLS/SSL (SChannel SSP)](/windows/win32/secauthn/cipher-suites-in-schannel)

171 −- [Demystifying SChannel](https://techcommunity.microsoft.com/t5/core-infrastructure-and-security/demystifying-schannel/ba-p/259233) (blog)

172 −

173168 ## MaximumCacheSize

174169

175170 This entry controls the maximum number of TLS sessions to cache. Setting MaximumCacheSize to **0** disables the

184179

185180 ## Messaging – fragment parsing

186181

187 −This entry controls the maximum allowed size of a TLS handshake message that will be accepted. Messages larger than the allowed size won't be accepted and the TLS handshake will fail. These entries don't exist in the registry by default.

182 +This entry controls the maximum allowed size of a TLS handshake message that's accepted. Messages larger than the allowed size isn't accepted and the TLS handshake fails. These entries don't exist in the registry by default.

188183

189 −When you set the value to **0x0**, fragmented messages aren't processed and will cause the TLS handshake to fail. This makes TLS clients or servers on the current machine noncompliant with the TLS RFCs.

184 +When you set the value to **0x0**, fragmented messages aren't processed and causes the TLS handshake to fail. This makes TLS clients or servers on the current machine noncompliant with the TLS RFCs.

190185

191 −The maximum allowed size can be increased up to 2^16 bytes. Allowing a client or server to read and store large amounts of unverified data from the network isn't a good idea and will consume additional memory for each security context.

186 +The maximum allowed size can be increased up to 2^16 bytes. Allowing a client or server to read and store large amounts of unverified data from the network isn't a good idea and consumes additional memory for each security context.

192187

193188 Added in Windows 7 and Windows Server 2008 R2: An update that enables Internet Explorer in Windows XP, in Windows Vista, or in Windows Server 2008 to parse fragmented TLS/SSL handshake messages is available.

194189

195190 Registry path: **HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Messaging**

196191

197 −To specify a maximum allowed size of fragmented TLS handshake messages that the TLS client will accept, create a **MessageLimitClient** entry. After you've created the entry, change the DWORD value to the desired bit length. If not configured, the default value is **0x8000** bytes.

192 +To specify a maximum allowed size of fragmented TLS handshake messages that the TLS client accepts, create a **MessageLimitClient** entry. After you've created the entry, change the DWORD value to the desired bit length. If not configured, the default value is **0x8000** bytes.

198193

199 −To specify a maximum allowed size of fragmented TLS handshake messages that the TLS server will accept when there's no client authentication, create a **MessageLimitServer** entry. After you've created the entry, change the DWORD value to the desired bit length. If not configured, the default value is **0x4000** bytes.

194 +To specify a maximum allowed size of fragmented TLS handshake messages that the TLS server accepts when there's no client authentication, create a **MessageLimitServer** entry. After you've created the entry, change the DWORD value to the desired bit length. If not configured, the default value is **0x4000** bytes.

200195

201 −To specify a maximum allowed size of fragmented TLS handshake messages that the TLS server will accept when there's client authentication, create a **MessageLimitServerClientAuth** entry. After you've created the entry, change the DWORD value to the desired bit length. If not configured, the default value is **0x8000** bytes.

196 +To specify a maximum allowed size of fragmented TLS handshake messages that the TLS server accepts when there's client authentication, create a **MessageLimitServerClientAuth** entry. After you've created the entry, change the DWORD value to the desired bit length. If not configured, the default value is **0x8000** bytes.

202197

203198 ## SendTrustedIssuerList

204199

205200 TLS servers may send a list of the distinguished names of acceptable certificate authorities when requesting client authentication. This may help TLS clients select an appropriate TLS client certificate. SChannel-based TLS servers don't send this trusted issuer list by default because it exposes the certificate authorities trusted by the server to passive observers and also increases the amount of data exchanged in the course of the TLS handshake. Setting this value to **1** causes SChannel-based servers to send their lists of trusted issuers.

206201

207 −Not sending a list of trusted issuers might impact what the client sends when it's asked for a client certificate. For example, when Internet Explorer receives a request for client authentication, it only displays the client certificates that chain up to one of the certification authorities that is sent by the server. If the server didn't send a list, Internet Explorer displays all of the client certificates that are installed on the client.

202 +Not sending a list of trusted issuers might impact what the client sends when it's asked for a client certificate. For example, when Microsoft Edge receives a request for client authentication, it only displays the client certificates that chain up to one of the certification authorities that's sent by the server. If the server didn't send a list, Microsoft Edge displays all of the client certificates that are installed on the client.

208203

209 −This behavior might be desirable. For example, when PKI environments include cross certificates, the client and server certificates won't have the same root CA; therefore, Internet Explorer cannot choose a certificate that chains up to one of the server's CAs. TLS clients may offer any available client certificate when a server does not send the trusted issuer list. This entry doesn't exist in the registry by default.

204 +This behavior might be desirable. For example, when PKI environments include cross certificates, the client and server certificates won't have the same root CA. Therefore, Microsoft Edge can't choose a certificate that chains up to one of the server's CAs. TLS clients may offer any available client certificate when a server doesn't send the trusted issuer list. This entry doesn't exist in the registry by default.

210205

211206 ### Default Send Trusted Issuer List behavior

212207

268263

269264 Switching a (D)TLS or SSL protocol version to **Disabled** state may cause [AcquireCredentialsHandle](/windows/win32/secauthn/acquirecredentialshandle--schannel) calls to fail due to the lack of protocol versions enabled system-wide and at the same time allowed by particular SSPI callers. In addition, reducing the set of **Enabled** (D)TLS and SSL versions may break interoperability with remote peers.

270265

271 −Once the (D)TLS or SSL protocol version settings have been modified, they take effect on connections established using credential handles opened by subsequent [AcquireCredentialsHandle](/windows/win32/secauthn/acquirecredentialshandle--schannel) calls. (D)TLS and SSL client and server applications and services tend to reuse credential handles for multiple connections, for performance reasons. In order to get these applications to reacquire their credential handles, an application or service restart may be required.

266 +Once the (D)TLS or SSL protocol version settings are modified, they take effect on connections established using credential handles opened by subsequent [AcquireCredentialsHandle](/windows/win32/secauthn/acquirecredentialshandle--schannel) calls. (D)TLS and SSL client and server applications and services tend to reuse credential handles for multiple connections, for performance reasons. In order to get these applications to reacquire their credential handles, an application, or service restart may be required.

272267

273268 These registry settings only apply to SChannel SSP and don't affect any third-party (D)TLS and SSL implementations that may be installed on the system.

269 +

270 +> [!WARNING]

271 +> Attempting to create or adjust any SChannel registry settings that are not explicitly detailed in this article isn't recommended due to potential risks and unintended consequences that may arise from unsupported configurations.

272 +

273 +To learn about managing the TLS cipher suite using PowerShell, see [TLS command reference](https://learn.microsoft.com/en-us/powershell/module/tls). If interested in managing TLS settings via Group Policy, see [Configuring TLS Cipher Suite Order by using Group Policy](/windows-server/security/tls/manage-tls#configuring-tls-cipher-suite-order-by-using-group-policy).

TLS registry settings

Microsoft's edit · 16 Jul 2024 23:14 UTC