Metodtips för Transport Layer Security (TLS) med .NET Framework

Kommentar

Den här sidan innehåller .NET Framework TLS-information. Om du letar efter .NET TLS-information kan du läsa: Metodtips för TLS/SSL

.NET Framework stöder användningen av TLS-protokollet (Transport Layer Security) för att skydda nätverkskommunikationen.

Vad är TLS (Transport Layer Security)?

Varning

TLS 1.0 och 1.1 har blivit inaktuella av RFC8996. Det här dokumentet omfattar endast TLS 1.2 och TLS 1.3.

TLS-protokollet (Transport Layer Security) är en branschs senaste version av standarden som är utformad för att skydda sekretessen för information som kommuniceras via Internet. TLS 1.3 är en standard som ger säkerhetsförbättringar jämfört med tidigare versioner. Den här artikeln innehåller rekommendationer för att skydda .NET Framework-program som använder TLS-protokollet.

Vem kan dra nytta av det här dokumentet?

• Direkt använda API:erna System.Net (till exempel System.Net.Http.HttpClient och System.Net.Security.SslStream).
• Använd WCF-klienter och -tjänster direkt med hjälp av System.ServiceModel namnområdet.

TLS-stöd i .NET Framework

Eftersom .NET Framework är beroende Schannel av Windows, vilka versioner som kan förhandlas och vilken version som ska användas beror på operativsystemet.

Här är en uppdaterad exempeltabell som visar den högsta TLS-versionen som stöds för olika kombinationer av operativsystemversioner och .NET Framework-målversioner:

.NET Framework-målversion	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

Mer information finns i stöd för TLS-protokollversion i Schannel.

Rekommendationer

• För TLS 1.3, mål .NET Framework 4.8 eller senare. Kontrollera granska kodavsnittet hur du verifierar .target framework
• Ange inte TLS-versionen explicit, d.v.s. använd inte metodens överlagringar för SslStream att ta en explicit SslProtocols parameter.
  • På så sätt kan operativsystemet bestämma TLS-versionen.
  • Om du måste ange ServicePointManager.SecurityProtocolanger du det till SecurityProtocolType.SystemDefault. Det kommer också att använda os-standard.
  • Om du måste använda metodens överlagringar för SslStream att ta en explicit SslProtocols parameter skickar SslProtocols.SystemDefault du som argument. Det kommer också att använda os-standard.
• Utför en grundlig kodgranskning för att kontrollera att du inte uttryckligen anger en TLS- eller SSL-version.

Varning

Använd SslProtocols.Defaultinte eftersom den anger TLS-versionen till SSL3 och TLS 1.0 som är föråldrade.

När appen låter operativsystemet välja TLS-versionen:

• Den drar automatiskt nytta av nya TLS-protokoll som läggs till i framtiden.
• Operativsystemet blockerar protokoll som identifieras som inte säkra (t.ex. SSL3 och TLS 1.0).

Den här artikeln beskriver hur du aktiverar den starkaste tillgängliga säkerheten för den version av .NET Framework som appen riktar in sig på och körs på. När en app uttryckligen anger ett säkerhetsprotokoll och en version avregistrerar den sig från andra alternativ och väljer bort standardbeteendet för .NET Framework och operativsystemet. Om du vill att din app ska kunna förhandla om en TLS 1.3-anslutning förhindrar uttryckligen inställningen till en lägre TLS-version en TLS 1.3-anslutning.

Om du inte kan undvika att uttryckligen ange en protokollversion rekommenderar vi starkt att du anger TLS 1.2 eller TLS 1.3 (vilket är currently considered secure). Information om hur du identifierar och tar bort TLS 1.0-beroenden finns i vitboken Lösa TLS 1.0-problem .

WCF stöder TLS 1.2 som standard i .NET Framework 4.7. Från och med .NET Framework 4.7.1 är WCF som standard den operativsystemskonfigurerade versionen. Om ett program uttryckligen har konfigurerats med SslProtocols.Noneanvänder WCF standardinställningen för operativsystemet när du använder NetTcp-transporten.

Du kan ställa frågor om det här dokumentet i metodtipsen för GitHub-problemet Transport Layer Security (TLS) med .NET Framework.

Granska koden och gör kodändringar

För ASP.NET program kontrollerar du elementet <system.web><httpRuntime targetFramework> i web.config för att kontrollera att du använder den avsedda målversionen av .NET Framework.

Information om Windows-formulär och andra program finns i Så här: Rikta in dig på en version av .NET Framework.

Använd följande avsnitt för att kontrollera att du inte använder en specifik TLS- eller SSL-version.

Om du uttryckligen måste ange ett säkerhetsprotokoll

Om du uttryckligen måste ange ett säkerhetsprotokoll i stället för att låta .NET eller operativsystemet välja säkerhetsprotokollet väljer du följande protokoll:

• För .NET Framework 3.5: TLS 1.2
• För .NET Framework 4.6.2 eller senare: TLS 1.3

Om du inte hittar angivna protokoll i uppräkningen kan du lägga till dem som en tilläggsfil. Se nedan:

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;
    }
}

Mer information finns i Support for TLS System Default Versions included in .NET Framework 3.5 on Windows 8.1 and Windows Server 2012 R2 .NET Framework 3.5 on Windows 8.1 and Windows Server 2012 R2( Support for TLS System Default Versions included in .NET Framework 3.5 on Windows 8.1 and Windows Server 2012 R2.

För System.Net API:er (HttpClient, SslStream)

Om din app är avsedd för .NET Framework 4.7 eller senare versioner

Följande avsnitt visar hur du konfigurerar programmet för användning currently considered secure versions av TLS. (TLS 1.2, TLS 1.3)

För HttpClient och HttpWebRequest

ServicePointManageranvänder .NET Framework 4.7 och senare versioner standardsäkerhetsprotokollet som konfigurerats i operativsystemet. Om du vill hämta standardalternativet för operativsystemet anger du om möjligt inte ett värde för ServicePointManager.SecurityProtocol egenskapen, som standard är SecurityProtocolType.SystemDefault.

Eftersom inställningen SecurityProtocolType.SystemDefault gör ServicePointManager att standardsäkerhetsprotokollet som konfigureras av operativsystemet används kan programmet köras på ett annat sätt beroende på vilket operativsystem det körs på. Till exempel använder Windows 10 TLS 1.2 medan Windows 11 använder TLS 1.3.

För SslStream

SslStream, med hjälp av .NET Framework 4.7 och senare versioner, är standard operativsystemet som väljer det bästa säkerhetsprotokollet och den bästa versionen. Använd om möjligt inte metodens överlagringar av den explicita SslProtocols parametern för att få det bästa valet för SslStream standardoperativsystemet. Annars skickar du SslProtocols.None. Vi rekommenderar att du inte använder Default. Inställningen SslProtocols.Default tvingar användningen av SSL 3.0 /TLS 1.0 och förhindrar TLS 1.2.

Ange inte något värde för SecurityProtocol egenskapen (för HTTP-nätverk).

Använd inte metodens överlagringar av SslStream som tar en explicit SslProtocols parameter (för TCP-sockets-nätverk). När du gör om din app till .NET Framework 4.7 eller senare versioner följer du rekommendationen om bästa praxis.

För WCF-program

Om din app är avsedd för .NET Framework 4.7 eller senare versioner

Följande avsnitt visar hur du konfigurerar programmet för användning currently considered secure versions av TLS. (TLS 1.2, TLS 1.3)

Använda TCP-transport med transportsäkerhet med certifikatautentiseringsuppgifter

WCF använder samma nätverksstack som resten av .NET Framework.

Om du riktar in dig på 4.7.1 är WCF konfigurerat så att operativsystemet kan välja det bästa säkerhetsprotokollet som standard om inte uttryckligen konfigurerats:

• I programkonfigurationsfilen.
• Eller i ditt program i källkoden.

Som standard är .NET Framework 4.7 och senare versioner konfigurerade att använda TLS 1.2 och tillåta anslutningar med TLS 1.1 eller TLS 1.0. Konfigurera WCF så att operativsystemet kan välja det bästa säkerhetsprotokollet genom att konfigurera bindningen så att den använder SslProtocols.None. Detta kan ställas in på SslProtocols. SslProtocols.None kan nås från Transport. NetTcpSecurity.Transport kan nås från Security.

Om du använder en anpassad bindning:

• Konfigurera WCF så att operativsystemet kan välja det bästa säkerhetsprotokollet genom att ange SslProtocols att använda SslProtocols.None.
• Eller konfigurera det protokoll som används med konfigurationssökvägen system.serviceModel/bindings/customBinding/binding/sslStreamSecurity:sslProtocols.

Om du inte använder en anpassad bindning och du ställer in WCF-bindningen med hjälp av konfigurationen anger du det protokoll som används med konfigurationssökvägen system.serviceModel/bindings/netTcpBinding/binding/security/transport:sslProtocols.

Använda meddelandesäkerhet med certifikatautentiseringsuppgifter

.NET Framework 4.7 och senare versioner använder som standard det protokoll som anges i SecurityProtocol egenskapen. När AppContextSwitch Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols har angetts till trueväljer WCF det bästa protokollet, upp till TLS 1.0.

Om din app riktar in sig på en tidigare .NET Framework-version än 4.7

Följande avsnitt visar hur du konfigurerar programmet för användning currently considered secure versions av TLS. (TLS 1.2, TLS 1.3)

Använda .NET Framework 4.6.2 med TCP-transportsäkerhet med certifikatautentiseringsuppgifter

WCF-ramverket väljer automatiskt det högsta protokoll som är tillgängligt upp till TLS 1.2 om du inte uttryckligen konfigurerar en protokollversion. Mer information finns i föregående avsnitt För WCF TCP-transport med transportsäkerhet med certifikatautentiseringsuppgifter.

Använda .NET Framework 3.5 med TCP-transportsäkerhet med certifikatautentiseringsuppgifter

Dessa versioner av WCF-ramverket anges uttryckligen för att använda värdena SSL 3.0 och TLS 1.0. Det går inte att ändra dessa värden. Du måste uppdatera och ommåla till NET Framework 4.6.2 eller senare versioner för att kunna använda TLS 1.2.

Konfigurera säkerhet via AppContext-växlar (för .NET Framework 4.6.2 eller senare versioner)

AppContext-växlarna som beskrivs i det här avsnittet är relevanta om din app riktar in sig på eller körs på .NET Framework 4.6.2 eller senare versioner. Om det är möjligt ska växlarna vara om möjligt, oavsett om det är false standard eller genom att uttryckligen ange dem. Om du vill konfigurera säkerhet via en eller båda växlarna ska du inte ange något säkerhetsprotokollvärde i koden. om du gör det åsidosätter du växeln(es).

För System.Net API:er (HttpClient, SslStream)

Växlarna har samma effekt oavsett om du utför HTTP-nätverk (ServicePointManager) eller TCP-socketnätverk (SslStream).

Switch.System.Net.DontEnableSchUseStrongCrypto

Ett värde för false för Switch.System.Net.DontEnableSchUseStrongCrypto gör att din app använder stark kryptografi. Värdet false för för DontEnableSchUseStrongCrypto använder säkrare nätverksprotokoll (TLS 1.2 och TLS 1.1) och blockerar protokoll som inte är säkra. Mer information finns i flaggan SCH_USE_STRONG_CRYPTO. Värdet true inaktiverar stark kryptografi för din app. Den här växeln påverkar endast klientanslutningar (utgående) i ditt program.

Om din app riktar in sig på .NET Framework 4.6.2 eller senare versioner, är den här växeln standardinställningen false. Det är en säker standard, vilket vi rekommenderar. Om din app körs på .NET Framework 4.6.2, men har en tidigare version som mål, är växlingen standardinställningen true. I så fall bör du uttryckligen ange den till false.

DontEnableSchUseStrongCrypto bör bara ha värdet true om du behöver ansluta till äldre tjänster som inte stöder stark kryptografi och inte kan uppgraderas.

Switch.System.Net.DontEnableSystemDefaultTlsVersions

Ett värde för false för Switch.System.Net.DontEnableSystemDefaultTlsVersions gör att din app tillåter att operativsystemet väljer protokollet. Ett värde för true gör att din app använder protokoll som valts av .NET Framework.

Om din app riktar in sig på .NET Framework 4.7 eller senare versioner är den här växeln standardinställningen false. Det är en säker standard som vi rekommenderar. Om din app körs på .NET Framework 4.7 eller senare versioner, men har en tidigare version som mål, är växlingen standardinställningen true. I så fall bör du uttryckligen ange den till false.

För WCF-program

Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols

Ett värde för false för Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols gör att ditt program använder värdet som definierats för ServicePointManager.SecurityProtocols meddelandesäkerhet med certifikatautentiseringsuppgifter. true Värdet använder det högsta tillgängliga protokollet, upp till TLS1.0

För program som riktar sig till .NET Framework 4.7 och senare versioner är det här värdet standardvärdet false. För program som riktar sig till .NET Framework 4.6.2 och tidigare är det här värdet standardvärdet true.

Switch.System.ServiceModel.DontEnableSystemDefaultTlsVersions

false Värdet för för Switch.System.ServiceModel.DontEnableSystemDefaultTlsVersions anger standardkonfigurationen så att operativsystemet kan välja protokoll. Ett värde för true anger standardvärdet till det högsta tillgängliga protokollet, upp till TLS1.2.

För program som riktar sig till .NET Framework 4.7.1 och senare versioner är det här värdet standardvärdet false. För program som riktar sig till .NET Framework 4.7 och tidigare är det här värdet standardvärdet true.

Mer information om TLS-protokoll finns i Mitigation: TLS Protocols (Minskning: TLS-protokoll). Mer information om AppContext växlar finns i <AppContextSwitchOverrides> Element.

Konfigurera säkerhet via Windows-registret

Varning

Om du anger registernycklar påverkas alla program i systemet. Använd endast det här alternativet om du har fullständig kontroll över datorn och kan styra ändringar i registret.

Om det inte är ett alternativ att ange en eller båda AppContext växlarna kan du styra de säkerhetsprotokoll som appen använder med Windows-registernycklarna som beskrivs i det här avsnittet. Du kanske inte kan använda en eller båda AppContext växlarna om din app körs på .NET Framework 3.5 eller om du inte kan redigera konfigurationsfilen. Om du vill konfigurera säkerhet med registret ska du inte ange något värde för säkerhetsprotokoll i koden. Detta åsidosätter registerinställningen.

Namnen på registernycklarna liknar namnen på motsvarande AppContext växlar, men utan DontEnable att namnet har förberetts. Växeln AppContext DontEnableSchUseStrongCrypto är till exempel registernyckeln SchUseStrongCrypto.

Dessa nycklar är tillgängliga i alla .NET Framework-versioner.

Alla registernycklar som beskrivs nedan har samma effekt oavsett om du utför HTTP-nätverk (ServicePointManager) eller TCP-socketnätverk (SslStream).

SchUseStrongCrypto

Registerposten HKEY_LOCAL_MACHINE\SOFTWARE\[Wow6432Node\]Microsoft\.NETFramework\<VERSION>: SchUseStrongCrypto har ett värde av typen DWORD. Värdet 1 gör att din app använder stark kryptografi. Den starka kryptografi använder säkrare nätverksprotokoll (TLS 1.2 och TLS 1.1) och blockerar protokoll som inte är säkra. Värdet 0 inaktiverar stark kryptografi. Mer information finns i flaggan SCH_USE_STRONG_CRYPTO. Den här registerinställningen påverkar endast klientanslutningar (utgående) i ditt program.

Om din app är avsedd för .NET Framework 4.6 eller senare versioner är den här nyckeln standardvärdet 1. Det är en säker standard som vi rekommenderar. Om din app är avsedd för .NET Framework 4.5.2 eller tidigare versioner är nyckeln standardvärdet 0. I så fall bör du uttryckligen ange värdet 1.

Den här nyckeln bör bara ha värdet 0 om du behöver ansluta till äldre tjänster som inte stöder stark kryptografi och inte kan uppgraderas.

SystemDefaultTlsVersions

Registerposten HKEY_LOCAL_MACHINE\SOFTWARE\[Wow6432Node\]Microsoft\.NETFramework\<VERSION>: SystemDefaultTlsVersions har ett värde av typen DWORD. Värdet 1 gör att din app tillåter att operativsystemet väljer protokollet. Värdet 0 gör att appen använder protokoll som valts av .NET Framework.

<VERSION> måste vara v4.0.30319 (för .NET Framework 4 och senare) eller v2.0.50727 (för .NET Framework 3.5).

Om din app är avsedd för .NET Framework 4.7 eller senare versioner, är den här nyckeln standardvärdet 1. Det är en säker standard som vi rekommenderar. Om din app är avsedd för .NET Framework 4.6.1 eller tidigare versioner är nyckeln standardvärdet 0. I så fall bör du uttryckligen ange värdet 1.

Mer information finns i Kumulativ uppdatering för Windows 10 version 1511 och Windows Server 2016 Technical Preview 4: 10 maj 2016.

Mer information om .NET Framework 3.5.1 finns i Support for TLS System Default Versions included in .NET Framework 3.5.1 on Windows 7 SP1 and Server 2008 R2 SP1 .NET Framework 3.5.1 on Windows 7 SP1 and Server 2008 R2 SP1.

Följande . REG-filen anger registerposterna och deras varianter till deras säkraste värden:

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

Konfigurera Schannel-protokoll i Windows-registret

Du kan använda registret för detaljerad kontroll över de protokoll som din klient- och/eller serverapp förhandlar om. Appens nätverk går via Schannel (som är ett annat namn för Säker kanal). Genom att Schannelkonfigurera kan du konfigurera appens beteende.

Börja med registernyckeln HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols . Under den nyckeln kan du skapa alla undernycklar i uppsättningen TLS 1.2, TLS 1.3. Under var och en av dessa undernycklar kan du skapa undernycklar Client och/eller Server. Under Client och Serverkan du skapa DWORD-värden DisabledByDefault (0 eller 1) och Enabled (0 eller 1).

Mer information finns i: TLS-registerinställningar – Schannel

Flaggan SCH_USE_STRONG_CRYPTO

När den är aktiverad (som standard, med en AppContext växel eller av Windows-registret) använder SCH_USE_STRONG_CRYPTO .NET Framework flaggan när din app initierar en TLS-anslutning till en server. .NET Framework skickar flaggan till för att Schannel instruera den att inaktivera kända svaga kryptografiska algoritmer, chiffersviter och TLS/SSL-protokollversioner som annars kan vara aktiverade för bättre samverkan. Mer information finns i:

• Säker kanal
• SCHANNEL_CRED struktur

Flaggan SCH_USE_STRONG_CRYPTO skickas också till Schannel för klientanslutningar (utgående) när du uttryckligen använder eller Tls12 Tls11 uppräknade värden för SecurityProtocolType eller SslProtocols. Flaggan SCH_USE_STRONG_CRYPTO används endast för anslutningar där ditt program agerar klientens roll. Du kan inaktivera svaga protokoll och algoritmer när dina program fungerar som serverns roll genom att konfigurera registerinställningarna för hela Schannel datorn.