Práticas recomendadas de TLS (Transport Layer Security) com o .NET Framework

Nota

Esta página contém informações TLS do .NET Framework. Se você estiver procurando informações sobre TLS do .NET, consulte: Práticas recomendadas de TLS/SSL

O .NET Framework suporta o uso do protocolo TLS (Transport Layer Security) para proteger as comunicações de rede.

O que é Transport Layer Security (TLS)?

Aviso

TLS 1.0 e 1.1 foi preterido por RFC8996. Este documento abrange apenas TLS 1.2 e TLS 1.3.

O protocolo Transport Layer Security (TLS) é uma versão mais recente do padrão projetada para ajudar a proteger a privacidade das informações comunicadas pela Internet. O TLS 1.3 é um padrão que fornece melhorias 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 beneficiar deste documento?

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

Suporte a TLS no .NET Framework

Como o .NET Framework depende do Schannel Windows, quais versões podem ser negociadas e qual versão será usada depende do sistema operacional.

Aqui está uma tabela de exemplo atualizada mostrando a versão TLS mais alta suportada 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, consulte Suporte à versão do protocolo TLS no Schannel.

Recomendações

• Para TLS 1.3, o .NET Framework 4.8 ou posterior de destino. Marque a seção Auditar seu código como verificar seu target framework.
• Não especifique a versão do TLS explicitamente, ou seja, não use as sobrecargas de SslStream método que tomam um parâmetro explícito SslProtocols .
  • Dessa forma, seu código permitirá que o sistema operacional decida sobre a versão TLS.
  • Se tiver de definir ServicePointManager.SecurityProtocol, defina-o como SecurityProtocolType.SystemDefault. Isso também usará o padrão do sistema operacional.
  • Se você deve usar as sobrecargas de SslStream método de que tomar um parâmetro explícito SslProtocols , em seguida, passar SslProtocols.SystemDefault como argumento. Isso também usará o padrão do sistema operacional.
• Execute uma auditoria de código completa para verificar se você não está especificando uma versão TLS ou SSL explicitamente.

Aviso

Não use SslProtocols.Default, porque ele define a versão TLS para SSL3 e TLS 1.0 que estão obsoletos.

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

• Ele aproveita automaticamente os novos protocolos TLS adicionados no futuro.
• O SO bloqueia protocolos que se descobre não serem seguros (por exemplo, SSL3 e TLS 1.0).

Este artigo explica como habilitar a segurança mais forte disponível para a versão do .NET Framework que seu aplicativo destina e executa. Quando um aplicativo define explicitamente um protocolo e uma versão de segurança, ele exclui qualquer outra alternativa e exclui o comportamento padrão do .NET Framework e do sistema operacional. Se você quiser que seu aplicativo seja capaz de negociar uma conexão TLS 1.3, definir explicitamente para uma versão TLS inferior impede uma conexão TLS 1.3.

Se você não puder evitar especificar uma versão do protocolo explicitamente, é altamente recomendável especificar TLS 1.2 ou TLS 1.3 (que é currently considered secure). Para obter orientação sobre como identificar e remover dependências do TLS 1.0, baixe o white paper Resolvendo o problema do TLS 1.0.

WCF suporta TLS 1.2 como o padrão no .NET Framework 4.7. A partir do .NET Framework 4.7.1, o WCF assume como padrão a versão configurada do sistema operacional. Se um aplicativo estiver explicitamente configurado com SslProtocols.Noneo , o WCF usará a configuração padrão do sistema operacional ao usar o transporte NetTcp.

Você pode fazer perguntas sobre este documento no problema do GitHub Transport Layer Security (TLS) práticas recomendadas com o .NET Framework.

Audite seu código e faça alterações no código

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

Para Windows Forms e outros aplicativos, consulte Como direcionar uma versão do .NET Framework.

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

Se tiver de 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 posterior: TLS 1.3

Se você não conseguir encontrar protocolos especificados no enum, 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, consulte Suporte para versões padrão do sistema TLS incluídas no .NET Framework 3.5 no Windows 8.1 e Windows Server 2012 R2.

Para APIs System.Net (HttpClient, SslStream)

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

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

Para HttpClient e HttpWebRequest

ServicePointManager, usando 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 de sistema operacional padrão, se possível, não defina um valor para a ServicePointManager.SecurityProtocol propriedade, cujo padrão é .SecurityProtocolType.SystemDefault

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

Para SslStream

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

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

Não use as sobrecargas de SslStream método que tomam um parâmetro explícito SslProtocols (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 práticas recomendadas.

Para aplicativos WCF

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

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

Usando o transporte TCP usando a segurança de transporte com credenciais de certificado

WCF usa a mesma pilha de rede como o resto do .NET Framework.

Se você estiver visando a versão 4.7.1, o WCF será configurado para permitir que o sistema operacional escolha o melhor protocolo de segurança por padrão, a menos que explicitamente configurado:

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

Por padrão, o .NET Framework 4.7 e versões posteriores são configurados para usar TLS 1.2 e permitir conexões usando TLS 1.1 ou TLS 1.0. Configure o WCF para permitir que o sistema operacional escolha o melhor protocolo de segurança configurando sua associação para usar SslProtocols.Noneo . 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 definindo SslProtocols o uso SslProtocols.Nonedo .
• Ou configure o protocolo usado com o caminho system.serviceModel/bindings/customBinding/binding/sslStreamSecurity:sslProtocolsde configuração.

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

Usando a Segurança de Mensagens com credenciais de certificado

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

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

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

Usando o .NET Framework 4.6.2 usando a segurança de transporte TCP com credenciais de certificado

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

Usando o .NET Framework 3.5 usando a segurança de transporte TCP com credenciais de certificado

Essas versões da estrutura WCF são explicitamente especificadas para usar valores SSL 3.0 e TLS 1.0. Estes valores não podem ser alterados. Você deve 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 de opções AppContext (para .NET Framework 4.6.2 ou versões posteriores)

As opções AppContext descritas nesta seção são relevantes se seu aplicativo tiver como destino ou for executado no .NET Framework 4.6.2 ou versões posteriores. Seja por padrão ou definindo-os explicitamente, os switches 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 em seu código; fazer isso substituiria o(s) switch(es).

Para APIs System.Net (HttpClient, SslStream)

Os switches têm o mesmo efeito se você estiver fazendo rede HTTP (ServicePointManager) ou rede de soquetes TCP (SslStream).

Switch.System.Net.DontEnableSchUseStrongCrypto

Um valor de false for Switch.System.Net.DontEnableSchUseStrongCrypto faz com que seu aplicativo use criptografia forte. Um valor de for DontEnableSchUseStrongCrypto usa protocolos de false rede mais seguros (TLS 1.2 e TLS 1.1) e bloqueia protocolos que não são seguros. Para obter mais informações, consulte O sinalizador SCH_USE_STRONG_CRYPTO. Um valor de true desativa a criptografia forte para seu aplicativo. Essa opção afeta apenas as conexões de cliente (de saída) em seu aplicativo.

Se o seu aplicativo tiver como destino o .NET Framework 4.6.2 ou versões posteriores, essa opção terá como padrão .false Esse é um padrão seguro, que recomendamos. Se o seu aplicativo for executado no .NET Framework 4.6.2, mas tiver como destino uma versão anterior, a opção assumirá como truepadrão . Nesse caso, você deve defini-lo explicitamente como false.

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

Switch.System.Net.DontEnableSystemDefaultTlsVersions

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

Se o seu aplicativo tiver como destino o .NET Framework 4.7 ou versões posteriores, essa opção será padronizada para false. Esse é um padrão seguro que recomendamos. Se o seu aplicativo for executado no .NET Framework 4.7 ou versões posteriores, mas tiver como destino uma versão anterior, a opção assumirá como truepadrão . Nesse caso, você deve defini-lo explicitamente como false.

Para aplicativos WCF

Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols

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

Para aplicativos destinados ao .NET Framework 4.7 e versões posteriores, esse valor assume como falsepadrão . Para aplicativos destinados ao .NET Framework 4.6.2 e versões anteriores, esse valor assume como truepadrão .

Switch.System.ServiceModel.DontEnableSystemDefaultTlsVersions

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

Para aplicativos destinados ao .NET Framework 4.7.1 e versões posteriores, esse valor assume como falsepadrão . Para aplicativos destinados ao .NET Framework 4.7 e versões anteriores, esse valor assume como truepadrão .

Para obter mais informações sobre protocolos TLS, consulte Mitigação: protocolos TLS. Para obter mais informações sobre AppContext switches, consulte <AppContextSwitchOverrides> Element.

Configurar a segurança através do Registo do Windows

Aviso

A configuração de chaves do Registro afeta todos os aplicativos no sistema. Use essa opção somente se você estiver no controle total da máquina e puder controlar as alterações no registro.

Se definir uma ou ambas as AppContext opções não for uma opção, você poderá controlar os protocolos de segurança que seu aplicativo usa com as chaves do Registro do Windows descritas nesta seção. Talvez você não consiga usar uma ou ambas as opções se seu AppContext aplicativo for executado no .NET Framework 3.5 ou se não puder 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 em seu código; Isso substitui a configuração do Registro.

Os nomes das chaves do Registro são semelhantes aos nomes das opções correspondentes AppContext , mas sem um DontEnable prepended para o nome. Por exemplo, a AppContext opção DontEnableSchUseStrongCrypto é 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 se você estiver fazendo rede HTTP (ServicePointManager) ou rede de soquetes TCP (SslStream).

SchUseStrongCrypto

A HKEY_LOCAL_MACHINE\SOFTWARE\[Wow6432Node\]Microsoft\.NETFramework\<VERSION>: SchUseStrongCrypto entrada do Registro tem um valor do tipo DWORD. Um valor de 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 que não são seguros. Um valor de 0 desativa a criptografia forte. Para obter mais informações, consulte O sinalizador SCH_USE_STRONG_CRYPTO. Essa configuração do Registro afeta apenas as conexões de cliente (de saída) em seu aplicativo.

Se o seu aplicativo tiver como destino o .NET Framework 4.6 ou versões posteriores, esse padrão de chave será o valor 1. Esse é um padrão seguro que recomendamos. Se o seu aplicativo tiver como destino o .NET Framework 4.5.2 ou versões anteriores, o padrão da chave será 0. Nesse caso, você deve definir explicitamente seu valor como 1.

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

SystemDefaultTlsVersions

A HKEY_LOCAL_MACHINE\SOFTWARE\[Wow6432Node\]Microsoft\.NETFramework\<VERSION>: SystemDefaultTlsVersions entrada do Registro tem um valor do tipo DWORD. Um valor de 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.

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

Se o seu aplicativo tiver como destino o .NET Framework 4.7 ou versões posteriores, esse padrão será o valor 1. Esse é um padrão seguro que recomendamos. Se o seu aplicativo tiver como destino o .NET Framework 4.6.1 ou versões anteriores, o padrão da chave será 0. Nesse caso, você deve definir explicitamente seu valor como 1.

Para obter mais informações, consulte Atualização cumulativa para Windows 10 versão 1511 e Windows Server 2016 Technical Preview 4: 10 de maio de 2016.

Para obter mais informações com o .NET Framework 3.5.1, consulte Suporte para versões padrão do sistema TLS incluídas no .NET Framework 3.5.1 no Windows 7 SP1 e Server 2008 R2 SP1.

O seguinte . O arquivo REG 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

Configurar protocolos Schannel no Registro do Windows

Você pode usar o registro para controle refinado sobre os protocolos que seu aplicativo cliente e/ou servidor negocia. A rede do seu aplicativo passa pelo Schannel (que é outro nome para Secure Channel). Ao configurar Schannelo , você pode configurar o comportamento do seu aplicativo.

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

Para obter mais informações, consulte: Configurações do Registro TLS - Schannel

A bandeira SCH_USE_STRONG_CRYPTO

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

• Canal Seguro
• SCHANNEL_CRED estrutura

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