Práticas recomendadas do protocolo TLS com o .NET Framework

Observação

Esta página contém informações do protocolo TLS do .NET Framework. Se você estiver procurando informações do protocolo TLS do .NET, confira: Melhores práticas de TLS/SSL

O .NET Framework dá suporte ao uso do protocolo TLS para proteger as comunicações de rede.

O que é o protocolo TLS?

Aviso

O TLS 1.0 e o 1.1 foram preteridos por RFC8996. Este documento abrange somente o TLS 1.2 e o TLS 1.3.

O protocolo TLS (Transport Layer Security) é uma versão mais recente do setor para o padrão criado para ajudar a proteger a privacidade das informações comunicadas pela Internet. O TLS 1.3 é um padrão que fornece aprimoramentos de segurança em relação às versões anteriores. Este artigo apresenta recomendações para proteger aplicativos .NET Framework que usam o protocolo TLS.

Quem pode se beneficiar deste documento?

• Usando diretamente as APIs do System.Net (por exemplo, System.Net.Http.HttpClient e System.Net.Security.SslStream).
• Usando diretamente clientes do WCF e serviços usando o namespace System.ServiceModel.

Suporte a TLS no .NET Framework

Como o .NET Framework depende do Schannel no Windows, as versões que podem ser negociadas e a versão que será usada dependem do sistema operacional.

Esta é uma tabela de exemplo atualizada mostrando a versão do TLS mais recente com suporte para diferentes combinações de versões do sistema operacional e versões de destino do .NET Framework:

Versão de Destino do .NET Framework	Windows 10	Windows 11
3,5	TLS 1.2	TLS 1.2
4.6.2	TLS 1.2	TLS 1.3
4.7	TLS 1.2	TLS 1.3
4.7.1	TLS 1.2	TLS 1.3
4.7.2	TLS 1.2	TLS 1.3
4.8	TLS 1.2	TLS 1.3
4.8.1	TLS 1.2	TLS 1.3

Para obter mais informações, confira Suporte à versão do protocolo TLS no Schannel.

Recomendações

• Para o TLS 1.3, direcione .NET Framework 4.8 ou versões posteriores. Confira a seção Auditar o seu código sobre como verificar o seu target framework.
• Não especifique explicitamente a versão do TLS, ou seja, não use as sobrecargas de método de SslStream que usam um parâmetro explícito SslProtocols.
  • Dessa forma, seu código deixará o sistema operacional decidir sobre a versão do TLS.
  • Se você precisar definir ServicePointManager.SecurityProtocol, defina-o como SecurityProtocolType.SystemDefault. Isso também usará o padrão do SO.
  • Se você precisar usar as sobrecargas de método de SslStream que usam um parâmetro explícito SslProtocols, passe SslProtocols.SystemDefault como argumento. Isso também usará o padrão do SO.
• Realize uma auditoria completa de código para verificar se que você não está especificando explicitamente uma versão do protocolo TLS ou SSL.

Aviso

Não use SslProtocols.Default, pois ele define a versão do TLS como SSL3 e do TLS como 1.0, que são obsoletas.

Quando seu aplicativo permite que o sistema operacional escolha a versão do protocolo TLS:

• Ele aproveita automaticamente os novos protocolos TLS adicionados no futuro.
• O sistema operacional bloqueia os protocolos que são descobertos como não seguros (por exemplo, SSL3 e TLS 1.0).

Este artigo explica como habilitar a segurança máxima disponível para a versão do .NET Framework para a qual seu aplicativo é destinado e na qual é executado. Quando um aplicativo define explicitamente um protocolo de segurança e versão, ele recusa qualquer outro dado alternativo e recusa o comportamento padrão do .NET Framework e sistema operacional. Se você quiser que seu aplicativo possa negociar uma conexão do TLS 1.3, configurar explicitamente para uma versão inferior do TLS impede uma conexão com o TLS 1.3.

Se você não puder evitar especificar uma versão de protocolo explicitamente, recomendamos que você especifique o TLS 1.2 ou o TLS 1.3 (que é currently considered secure). Para obter orientações sobre como identificar e remover as dependências do TLS 1.0, baixe o white paper Como solucionar o problema do TLS 1.0.

O WCF dá suporte ao TLS 1.2 como o padrão no .NET Framework 4.7. A partir do .NET Framework 4.7.1, o WCF define a versão configurada do sistema operacional como padrão. Se um aplicativo for explicitamente configurado com SslProtocols.None, o WCF usará a configuração do sistema operacional padrão ao usar o transporte NetTcp.

É possível fazer perguntas sobre este documento na questão do GitHub Melhores práticas do TLS (Transport Layer Security) com o .NET Framework.

Auditar seu código e fazer alterações no código

Para aplicativos ASP.NET, inspecione o elemento <system.web><httpRuntime targetFramework> de web.config para verificar se você está usando a versão desejada de destino do .NET Framework.

Para o Windows Forms e outros aplicativos, confira Como definir a uma versão do .NET Framework como destino.

Use as seções a seguir para verificar se você não está usando uma versão específica do TLS ou SSL.

Se você precisar definir explicitamente um Protocolo de Segurança

Se você precisar definir explicitamente um protocolo de segurança em vez de permitir que o .NET ou o sistema operacional escolham o protocolo de segurança, escolha estes protocolos:

• Para .NET Framework 3.5: TLS 1.2
• Para .NET framework 4.6.2 ou versão posterior: TLS 1.3

Se você não encontrar os protocolos especificados na enumeração, poderá adicioná-los como um arquivo de extensão. Veja abaixo:

SslProtocolExtensions.cs

namespace System.Security.Authentication
{
    public static class SslProtocolsExtensions
    {
        // For .NET Framework 3.5
        public const SslProtocols Tls12 = (SslProtocols)3072;
        // For .NET Framework 4.6.2 and later
        public const SslProtocols Tls13 = (SslProtocols)12288;
    }
}

SecurityProtocolExtensions.cs

using System.Security.Authentication;

namespace System.Net
{
    public static class SecurityProtocolTypeExtensions
    {
        // For .NET Framework 3.5
        public const SecurityProtocolType Tls12 = (SecurityProtocolType)SslProtocolsExtensions.Tls12;
        // For .NET Framework 4.6.2 and later
        public const SecurityProtocolType Tls13 = (SecurityProtocolType)SslProtocolsExtensions.Tls13;
    }
}

Para obter mais informações, confira Suporte para versões padrão do sistema TLS incluídas no .NET Framework 3.5 no Windows 8.1 e no Windows Server 2012 R2.

Para APIs do System.Net (HttpClient, SslStream)

Se o aplicativo definir o .NET Framework 4.7 ou versões posteriores como destino

As seções a seguir mostram como configurar o aplicativo para usar o currently considered secure versions do TLS. (TLS 1.2, TLS 1.3)

Para HttpClient e HttpWebRequest

ServicePointManager, adotando o .NET Framework 4.7 e versões posteriores, usará o protocolo de segurança padrão configurado no sistema operacional. Para obter a opção padrão de SO, se possível, não defina um valor para a propriedade ServicePointManager.SecurityProtocol e ela assumirá SecurityProtocolType.SystemDefault como padrão.

Como a configuração SecurityProtocolType.SystemDefault faz com que ServicePointManager use o protocolo de segurança padrão configurado pelo sistema operacional, seu aplicativo pode ser executado de maneira diferente com base no SO em que está sendo executado. Por exemplo, o Windows 10 usa o TLS 1.2, enquanto o Windows 11 usa o TLS 1.3.

Para SslStream

O SslStream, usando o .NET Framework 4.7 e versões posteriores, define como padrão o sistema operacional com o melhor protocolo de segurança e versão. Para obter a melhor opção padrão de sistema operacional, se possível, não use as sobrecargas do método de SslStream que levam um parâmetro SslProtocols explícito. Caso contrário, passe SslProtocols.None. Recomendamos não usar o Default; configurar o SslProtocols.Default força o uso do SSL 3.0 /TLS 1.0 e impede o TLS 1.2.

Não defina um valor para a propriedade SecurityProtocol (para a rede HTTP).

Não use as sobrecargas de método do SslStream que levam um parâmetro SslProtocols explícito (para rede de soquetes TCP). Ao redirecionar seu aplicativo para o .NET Framework 4.7 ou versões posteriores, você estará seguindo a recomendação de melhores práticas.

Para Aplicativos WCF

Se o aplicativo definir o .NET Framework 4.7 ou versões posteriores como destino

As seções a seguir mostram como configurar o aplicativo para usar o currently considered secure versions do TLS. (TLS 1.2, TLS 1.3)

Uso do transporte de TCP usando a segurança de transporte com credenciais de certificado

O WCF usa a mesma pilha de rede do restante do .NET Framework.

Se você estiver definindo o 4.7.1 como destino, o WCF é configurado para permitir que o sistema operacional escolha o melhor protocolo de segurança por padrão, a menos que explicitamente configurado:

• No seu arquivo de configuração do aplicativo.
• Ou, no seu aplicativo no código-fonte.

Por padrão, o .NET Framework 4.7 e versões posteriores são configuradas para usar o TLS 1.2 e permitem conexões usando o TLS 1.1 ou TLS 1.0. Configure o WCF para permitir que o sistema operacional escolha o melhor protocolo de segurança configurando a associação para usar SslProtocols.None. Isso pode ser definido em SslProtocols. SslProtocols.None pode ser acessado em Transport. NetTcpSecurity.Transport pode ser acessado em Security.

Se você estiver usando uma associação personalizada:

• Configure o WCF para permitir que o sistema operacional escolha o melhor protocolo de segurança configurando SslProtocols para usar SslProtocols.None.
• Ou configure o protocolo usado com o caminho de configuração system.serviceModel/bindings/customBinding/binding/sslStreamSecurity:sslProtocols.

Se você não estiver utilizando uma associação personalizada e estiver definindo sua associação do WCF usando a configuração, defina o protocolo usado com o caminho de configuração system.serviceModel/bindings/netTcpBinding/binding/security/transport:sslProtocols.

Uso de Segurança de Mensagens com as credenciais de certificado

O .NET Framework 4.7 e versões posteriores usam por padrão o protocolo especificado na propriedade SecurityProtocol. Quando o AppContextSwitch Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols é definido como true, o WCF escolhe o melhor protocolo, até o TLS 1.0.

Se o aplicativo definir uma versão do .NET Framework anterior à 4.7 como destino

As seções a seguir mostram como configurar o aplicativo para usar o currently considered secure versions do TLS. (TLS 1.2, TLS 1.3)

Uso do .NET Framework 4.6.2 usando a segurança de transporte do TCP com Credenciais de Certificado

A estrutura do WCF escolhe automaticamente o maior protocolo disponível até o TLS 1.2, a menos que você configure explicitamente uma versão do protocolo. Para saber mais, confira a seção anterior Para transporte de TCP do WCF usando a segurança de transporte com credenciais de certificado.

Para o WCF usando o .NET Framework 3.5 usando a segurança de transporte do TCP com Credenciais de Certificado

Essas versões da estrutura do WCF são especificadas explicitamente para usar valores do protocolo SSL 3.0 e TLS 1.0. Esses valores não podem ser alterados. É preciso atualizar e redirecionar para o .NET Framework 4.6.2 ou versões posteriores para usar o TLS 1.2.

Configurar a segurança por meio das opções AppContext (para o .NET Framework 4.6.2 ou versões posteriores)

As opções AppContext descritas nesta seção serão relevantes se o aplicativo for destinado ou executado no .NET Framework 4.6.2 ou versões posteriores. Seja por padrão ou definindo-as explicitamente, as opções devem ser false se possível. Se você quiser configurar a segurança por meio de uma ou ambas as opções, não especifique um valor de protocolo de segurança no seu código; isso pode substituir as opções.

Para APIs do System.Net (HttpClient, SslStream)

As opções têm o mesmo efeito, seja para uma rede HTTP (ServicePointManager) ou uma rede de soquetes TCP (SslStream).

Switch.System.Net.DontEnableSchUseStrongCrypto

Um valor false para Switch.System.Net.DontEnableSchUseStrongCrypto faz com que seu aplicativo use criptografia forte. Um valor false para DontEnableSchUseStrongCrypto usa protocolos de rede mais seguros (TLS 1.2 e TLS 1.1) e bloqueia protocolos não seguros. Para saber mais, confira O sinalizador SCH_USE_STRONG_CRYPTO. Um valor true desabilita uma criptografia forte para o aplicativo. Essa opção afeta apenas conexões de cliente (de saída) no seu aplicativo.

Se o aplicativo for destinado ao .NET Framework 4.6.2 ou versões posteriores, essa opção será definida como false por padrão. Esse é um padrão seguro que recomendamos. Se o aplicativo for executado em .NET Framework 4.6.2, mas for destinado a uma versão anterior, a opção será definida como true por padrão. Nesse caso, defina-a explicitamente como false.

DontEnableSchUseStrongCrypto só deve ter um valor true se você precisar se conectar a serviços herdados que não suportem criptografia forte e não possam ser atualizados.

Switch.System.Net.DontEnableSystemDefaultTlsVersions

Um valor false para Switch.System.Net.DontEnableSystemDefaultTlsVersions faz com que seu aplicativo permita que o sistema operacional escolha o protocolo. Um valor true faz com que seu aplicativo use protocolos escolhidos pelo .NET Framework.

Se o aplicativo for destinado ao .NET Framework 4.7 ou versões posteriores, essa opção será definida como false por padrão. Esse é um padrão seguro que recomendamos. Se o aplicativo for executado no .NET Framework 4.7 ou versões posteriores, mas for destinado a uma versão anterior, a opção será definida como true por padrão. Nesse caso, defina-a explicitamente como false.

Para aplicativos WCF

Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols

Um valor false para Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols faz com que seu aplicativo use o valor definido no ServicePointManager.SecurityProtocols para segurança de mensagem usando credenciais de certificado. Um valor true usa o maior protocolo disponível, até o TLS1.0

Para aplicativos destinados ao .NET Framework 4.7 e versões posteriores, o valor padrão é false. Para aplicativos destinados ao .NET Framework 4.6.2 e versões anteriores, o valor padrão é true.

Switch.System.ServiceModel.DontEnableSystemDefaultTlsVersions

Um valor false para Switch.System.ServiceModel.DontEnableSystemDefaultTlsVersions define a configuração padrão para permitir que o sistema operacional escolha o protocolo. Um valor true define o padrão como o maior protocolo disponível, até o TLS1.2.

Para aplicativos destinados ao .NET Framework 4.7.1 e versões posteriores, o valor padrão é false. Para aplicativos destinados ao .NET Framework 4.7 e versões anteriores, o valor padrão é true.

Para saber mais sobre os protocolos TLS, confira Mitigação: protocolos TLS. Para saber mais sobre as opções AppContext, confira <AppContextSwitchOverrides> Element.

Configure a segurança por meio do Registro do Windows

Aviso

Definir as chaves do Registro afeta todos os aplicativos no sistema. Use esta opção somente se você estiver no controle total do computador e puder controlar as alterações ao Registro.

Se configurar uma ou ambas as opções AppContext não for uma opção, será possível controlar os protocolos de segurança que seu aplicativo usa com as chaves do Registro do Windows descritas nesta seção. Você não poderá usar uma ou ambas as opções AppContext se o aplicativo executar no .NET Framework 3.5 ou se não for possível editar o arquivo de configuração. Se você quiser configurar a segurança com o Registro, não especifique um valor de protocolo de segurança no seu código; isso substituirá a configuração do Registro.

Os nomes das chaves do Registro são similares aos nomes das opções AppContext correspondentes, mas sem um DontEnable anexado ao nome. Por exemplo, a opção AppContextDontEnableSchUseStrongCrypto é a chave do Registro chamada SchUseStrongCrypto.

Essas chaves estão disponíveis em todas as versões do .NET Framework.

Todas as chaves do Registro descritas abaixo têm o mesmo efeito, seja para uma rede HTTP (ServicePointManager) ou uma rede de soquetes TCP (SslStream).

SchUseStrongCrypto

A entrada do registro HKEY_LOCAL_MACHINE\SOFTWARE\[Wow6432Node\]Microsoft\.NETFramework\<VERSION>: SchUseStrongCrypto tem um valor do tipo DWORD. Um valor 1 faz com que seu aplicativo use criptografia forte. A criptografia forte usa protocolos de rede mais seguros (TLS 1.2 e TLS 1.1) e bloqueia protocolos não seguros. Um valor 0 desabilita a criptografia forte. Para saber mais, confira O sinalizador SCH_USE_STRONG_CRYPTO. Essa configuração de registro afeta apenas conexões de cliente (de saída) em seu aplicativo.

Se o aplicativo for destinado ao .NET Framework 4.6 ou versões posteriores, o valor dessa chave será definido como 1 por padrão. Esse é um padrão seguro que recomendamos. Se o aplicativo for destinado ao .NET Framework 4.5.2 ou versões anteriores, a chave será definida como 0 por padrão. Nesse caso, defina o valor explicitamente como 1.

Essa chave só deve ter um valor 0 se você precisar se conectar a serviços herdados que não deem suporte à criptografia forte e não possam ser atualizados.

SystemDefaultTlsVersions

A entrada do registro HKEY_LOCAL_MACHINE\SOFTWARE\[Wow6432Node\]Microsoft\.NETFramework\<VERSION>: SystemDefaultTlsVersions tem um valor do tipo DWORD. Um valor 1 faz com que seu aplicativo permita que o sistema operacional escolha o protocolo. Um valor 0 faz com que seu aplicativo use protocolos escolhidos pelo .NET Framework.

A <VERSION> deve ser v4.0.30319 (para o .NET Framework 4 e superior) ou v2.0.50727 (para .NET Framework 3.5).

Se o aplicativo for destinado ao .NET Framework 4.7 ou versões posteriores, o valor dessa chave será definido como 1 por padrão. Esse é um padrão seguro que recomendamos. Se o aplicativo for destinado ao .NET Framework 4.6.1 ou versões anteriores, a chave será definida como 0 por padrão. Nesse caso, defina o valor explicitamente como 1.

Para saber mais, confira Atualização Cumulativa para Windows 10 Versão 1511 e Windows Server 2016 Technical Preview 4: 10 de maio de 2016.

Para saber mais sobre o .NET Framework 3.5.1, confira Suporte para Versões Padrão do Sistema TLS incluídas no .NET Framework 3.5.1 no Windows 7 SP1 e no Windows Server 2008 R2 SP1.

O arquivo .REG a seguir define as entradas do Registro e suas variantes para seus valores mais seguros:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\.NETFramework\v2.0.50727]
"SystemDefaultTlsVersions"=dword:00000001
"SchUseStrongCrypto"=dword:00000001

[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\.NETFramework\v4.0.30319]
"SystemDefaultTlsVersions"=dword:00000001
"SchUseStrongCrypto"=dword:00000001

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v2.0.50727]
"SystemDefaultTlsVersions"=dword:00000001
"SchUseStrongCrypto"=dword:00000001

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\v4.0.30319]
"SystemDefaultTlsVersions"=dword:00000001
"SchUseStrongCrypto"=dword:00000001

Configure os protocolos Schannel no Registro do Windows

Você pode usar o registro para um controle refinado sobre os protocolos que seu aplicativo servidor e/ou cliente negocia. A rede do seu aplicativo passa pelo Schannel (que é outro nome para Canal Seguro). Configurando o Schannel, é possível configurar o comportamento do seu aplicativo.

Comece com a chave do Registro do HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols. Sob essa chave, é possível criar qualquer subchave no conjunto TLS 1.2, TLS 1.3. Em cada uma dessas subchaves, é possível criar subchaves Client e/ou Server. Em Client e Server, é possível criar valores DWORD DisabledByDefault (0 ou 1) e Enabled (0 ou 1).

Para obter mais informações, confira: Configurações do Registro TLS – Schannel

O sinalizador SCH_USE_STRONG_CRYPTO

Quando ele é habilitado (por padrão, por uma opção AppContext ou pelo Registro do Windows), o .NET Framework usa o sinalizador SCH_USE_STRONG_CRYPTO quando seu aplicativo inicia uma conexão do TLS com o servidor. O .NET Framework passa o sinalizador para Schannel a fim de instruí-lo a desativar algoritmos criptográficos fracos conhecidos, pacotes de codificação e versões do protocolo TLS/SSL que possam ser habilitadas para uma melhor interoperabilidade. Para obter mais informações, consulte:

• Canal Seguro
• Estrutura SCHANNEL_CRED

O sinalizador SCH_USE_STRONG_CRYPTO também é transmitido a Schannel para conexões (de saída) com o cliente quando você usa explicitamente os valores enumerados Tls11 ou Tls12 de SecurityProtocolType ou SslProtocols. O sinalizador SCH_USE_STRONG_CRYPTO é usado apenas para conexões em que seu aplicativo atua na função de cliente. Você pode desabilitar protocolos e algoritmos fracos quando seus aplicativos atuam na função de servidor, definindo as configurações de registro Schannel em todo o computador.