Best practices voor Transport Layer Security (TLS) met .NET Framework

Notitie

Deze pagina bevat TLS-informatie over .NET Framework. Als u op zoek bent naar .NET TLS-informatie, raadpleegt u: Aanbevolen procedures voor TLS/SSL

.NET Framework ondersteunt het gebruik van het TLS-protocol (Transport Layer Security) om netwerkcommunicatie te beveiligen.

Wat is Transport Layer Security (TLS)?

Waarschuwing

TLS 1.0 en 1.1 zijn afgeschaft door RFC8996. In dit document worden alleen TLS 1.2 en TLS 1.3 behandeld.

Het TLS-protocol (Transport Layer Security) is een industrieversie van de standaard die is ontworpen om de privacy van informatie die via internet wordt gecommuniceerd te beschermen. TLS 1.3 is een standaard die beveiligingsverbeteringen biedt ten opzichte van eerdere versies. Dit artikel bevat aanbevelingen voor het beveiligen van .NET Framework-toepassingen die gebruikmaken van het TLS-protocol.

Wie kan profiteren van dit document?

• Rechtstreeks met behulp van de System.Net API's (bijvoorbeeld System.Net.Http.HttpClient en System.Net.Security.SslStream).
• Rechtstreeks gebruikmaken van WCF-clients en -services met behulp van de System.ServiceModel naamruimte.

TLS-ondersteuning in .NET Framework

Aangezien .NET Framework afhankelijk is van Schannel Windows, welke versies kunnen worden onderhandeld en welke versie wordt gebruikt, is afhankelijk van het besturingssysteem.

Hier volgt een bijgewerkte voorbeeldtabel met de meest ondersteunde TLS-versie voor verschillende combinaties van besturingssysteemversies en .NET Framework-doelversies:

.NET Framework-doelversie	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

Zie ondersteuning voor TLS-protocolversies in Schannel voor meer informatie.

Aanbevelingen

• Voor TLS 1.3 richt u zich op .NET Framework 4.8 of hoger. Controleer de sectie Uw code controleren hoe u uw target framework.
• Geef de TLS-versie niet expliciet op, d.w. gebruik niet de overbelasting van SslStream de methode die een expliciete SslProtocols parameter neemt.
  • Op die manier laat uw code het besturingssysteem beslissen over de TLS-versie.
  • Als u dit moet instellen ServicePointManager.SecurityProtocol, stelt u deze in op SecurityProtocolType.SystemDefault. Dit maakt ook gebruik van de standaardinstelling van het besturingssysteem.
  • Als u de overbelasting van SslStream de methode moet gebruiken voor een expliciete SslProtocols parameter, geeft u het argument door SslProtocols.SystemDefault . Dit maakt ook gebruik van de standaardinstelling van het besturingssysteem.
• Voer een grondige codecontrole uit om te controleren of u geen TLS- of SSL-versie expliciet opgeeft.

Waarschuwing

Gebruik niet SslProtocols.Default, omdat de TLS-versie is ingesteld op SSL3 en TLS 1.0 die verouderd zijn.

Wanneer uw app toestaat dat het besturingssysteem de TLS-versie kiest:

• Het maakt automatisch gebruik van nieuwe TLS-protocollen die in de toekomst zijn toegevoegd.
• Het besturingssysteem blokkeert protocollen die niet zijn beveiligd (bijvoorbeeld SSL3 en TLS 1.0).

In dit artikel wordt uitgelegd hoe u de sterkste beveiliging inschakelt die beschikbaar is voor de versie van .NET Framework waarop uw app is gericht en wordt uitgevoerd. Wanneer een app expliciet een beveiligingsprotocol en -versie instelt, wordt er voor elk ander alternatief gekozen en wordt het standaardgedrag van .NET Framework en het besturingssysteem uitgeschakeld. Als u wilt dat uw app kan onderhandelen over een TLS 1.3-verbinding, voorkomt u expliciet dat een TLS 1.3-verbinding wordt ingesteld op een lagere TLS-versie.

Als u niet kunt voorkomen dat u expliciet een protocolversie opgeeft, raden we u ten zeerste aan TLS 1.2 of TLS 1.3 op te geven (dat wil currently considered securegezegd). Voor hulp bij het identificeren en verwijderen van TLS 1.0-afhankelijkheden downloadt u het technisch document over het oplossen van problemen met TLS 1.0 .

WCF ondersteunt TLS 1.2 als standaardinstelling in .NET Framework 4.7. Vanaf .NET Framework 4.7.1 is WCF standaard ingesteld op de geconfigureerde versie van het besturingssysteem. Als een toepassing expliciet is geconfigureerd met SslProtocols.None, gebruikt WCF de standaardinstelling van het besturingssysteem bij gebruik van het NetTcp-transport.

U kunt vragen stellen over dit document in de best practices voor Transport Layer Security (TLS) van GitHub met .NET Framework.

Uw code controleren en codewijzigingen aanbrengen

Voor ASP.NET toepassingen controleert u het <system.web><httpRuntime targetFramework> element web.config om te controleren of u de beoogde versie van .NET Framework gebruikt.

Zie Instructies voor Windows Forms en andere toepassingen : Een versie van .NET Framework targeten.

Gebruik de volgende secties om te controleren of u geen specifieke TLS- of SSL-versie gebruikt.

Als u expliciet een beveiligingsprotocol moet instellen

Als u expliciet een beveiligingsprotocol moet instellen in plaats van .NET of het besturingssysteem het beveiligingsprotocol te laten kiezen, kiest u deze protocollen:

• Voor .NET Framework 3.5: TLS 1.2
• Voor .NET Framework 4.6.2 of hoger: TLS 1.3

Als u de opgegeven protocollen in enum niet kunt vinden, kunt u deze toevoegen als extensiebestand. Zie hieronder:

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

Zie Ondersteuning voor standaardversies van TLS-systeem die zijn opgenomen in .NET Framework 3.5 op Windows 8.1 en Windows Server 2012 R2 voor meer informatie.

Voor System.Net API's (HttpClient, SslStream)

Als uw app is gericht op .NET Framework 4.7 of nieuwere versies

In de volgende secties ziet u hoe u uw toepassing configureert voor gebruik currently considered secure versions van TLS. (TLS 1.2, TLS 1.3)

Voor HttpClient en HttpWebRequest

ServicePointManagermet .NET Framework 4.7 en latere versies wordt het standaardbeveiligingsprotocol gebruikt dat is geconfigureerd in het besturingssysteem. Als u de standaardoptie voor het besturingssysteem wilt ophalen, moet u, indien mogelijk, geen waarde instellen voor de ServicePointManager.SecurityProtocol eigenschap, die standaard wordt ingesteld SecurityProtocolType.SystemDefaultop .

Omdat de SecurityProtocolType.SystemDefault instelling ervoor zorgt dat het ServicePointManager standaardbeveiligingsprotocol wordt gebruikt dat door het besturingssysteem is geconfigureerd, kan uw toepassing anders worden uitgevoerd op basis van het besturingssysteem waarop het wordt uitgevoerd. Windows 10 gebruikt bijvoorbeeld TLS 1.2 terwijl Windows 11 TLS 1.3 gebruikt.

Voor SslStream

SslStreammet .NET Framework 4.7 en latere versies wordt standaard het besturingssysteem gekozen voor het beste beveiligingsprotocol en de beste versie. Als u de beste keuze voor het standaardbesturingssysteem wilt krijgen, moet u, indien mogelijk, niet de overbelasting van SslStream de methode gebruiken die een expliciete SslProtocols parameter gebruikt. Anders geeft u door SslProtocols.None. U wordt aangeraden geen gebruik te maken Defaultvan ; het instellen SslProtocols.Default dwingt het gebruik van SSL 3.0 /TLS 1.0 af en voorkomt TLS 1.2.

Stel geen waarde in voor de SecurityProtocol eigenschap (voor HTTP-netwerken).

Gebruik niet de overbelasting van SslStream de methode waarvoor een expliciete SslProtocols parameter wordt gebruikt (voor TCP sockets-netwerken). Wanneer u uw app opnieuw op .NET Framework 4.7 of nieuwere versies wilt toepassen, volgt u de aanbevolen procedures.

Voor WCF-toepassingen

Als uw app is gericht op .NET Framework 4.7 of nieuwere versies

In de volgende secties ziet u hoe u uw toepassing configureert voor gebruik currently considered secure versions van TLS. (TLS 1.2, TLS 1.3)

TCP-transport gebruiken met transportbeveiliging met certificaatreferenties

WCF maakt gebruik van dezelfde netwerkstack als de rest van .NET Framework.

Als u zich richt op 4.7.1, is WCF zo geconfigureerd dat het besturingssysteem standaard het beste beveiligingsprotocol kan kiezen, tenzij dit expliciet is geconfigureerd:

• In uw toepassingsconfiguratiebestand.
• Of in uw toepassing in de broncode.

Standaard zijn .NET Framework 4.7 en latere versies geconfigureerd voor het gebruik van TLS 1.2 en zijn verbindingen toegestaan met TLS 1.1 of TLS 1.0. Configureer WCF zodat het besturingssysteem het beste beveiligingsprotocol kan kiezen door uw binding te configureren voor gebruik SslProtocols.None. Dit kan worden ingesteld op SslProtocols. SslProtocols.None kan worden geopend vanaf Transport. NetTcpSecurity.Transport kan worden geopend vanaf Security.

Als u een aangepaste binding gebruikt:

• Configureer WCF zodat het besturingssysteem het beste beveiligingsprotocol kan kiezen door de instelling SslProtocols te gebruiken SslProtocols.None.
• Of configureer het protocol dat wordt gebruikt met het configuratiepad system.serviceModel/bindings/customBinding/binding/sslStreamSecurity:sslProtocols.

Als u geen aangepaste binding gebruikt en u uw WCF-binding instelt met behulp van de configuratie, stelt u het protocol in dat wordt gebruikt met het configuratiepadsystem.serviceModel/bindings/netTcpBinding/binding/security/transport:sslProtocols.

Berichtbeveiliging gebruiken met certificaatreferenties

.NET Framework 4.7 en latere versies gebruiken standaard het protocol dat is opgegeven in de SecurityProtocol eigenschap. Wanneer de AppContextSwitch Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols is ingesteld trueop, kiest WCF het beste protocol, maximaal TLS 1.0.

Als uw app is gericht op een .NET Framework-versie ouder dan 4.7

In de volgende secties ziet u hoe u uw toepassing configureert voor gebruik currently considered secure versions van TLS. (TLS 1.2, TLS 1.3)

.NET Framework 4.6.2 gebruiken met TCP-transportbeveiliging met certificaatreferenties

Het WCF-framework kiest automatisch het hoogste protocol dat beschikbaar is tot TLS 1.2, tenzij u expliciet een protocolversie configureert. Zie de voorgaande sectie voor WCF TCP-transport met behulp van transportbeveiliging met certificaatreferenties voor meer informatie.

.NET Framework 3.5 gebruiken met TCP-transportbeveiliging met certificaatreferenties

Deze versies van het WCF-framework worden expliciet opgegeven voor het gebruik van waarden SSL 3.0 en TLS 1.0. Deze waarden kunnen niet worden gewijzigd. U moet NET Framework 4.6.2 of hoger bijwerken en opnieuw targeten om TLS 1.2 te kunnen gebruiken.

Beveiliging configureren via AppContext-switches (voor .NET Framework 4.6.2 of nieuwere versies)

De AppContext-switches die in deze sectie worden beschreven, zijn relevant als uw app is gericht op of wordt uitgevoerd op .NET Framework 4.6.2 of nieuwere versies. De schakelopties moeten, ongeacht of ze standaard of expliciet worden ingesteld, indien mogelijk zijn false . Als u beveiliging wilt configureren via een of beide switches, geeft u geen waarde voor het beveiligingsprotocol op in uw code; Als u dit doet, worden de schakeloptie(sen) overschreven.

Voor System.Net API's (HttpClient, SslStream)

De switches hebben hetzelfde effect, ongeacht of u HTTP-netwerken (ServicePointManager) of TCP-sockets (SslStream) uitvoert.

Switch.System.Net.DontEnableSchUseStrongCrypto

Een waarde die false ervoor Switch.System.Net.DontEnableSchUseStrongCrypto zorgt dat uw app sterke cryptografie gebruikt. Een waarde voor het gebruik van false DontEnableSchUseStrongCrypto veiligere netwerkprotocollen (TLS 1.2 en TLS 1.1) en blokkeert protocollen die niet beveiligd zijn. Zie de vlag SCH_USE_STRONG_CRYPTO voor meer informatie. Een waarde voor het uitschakelen van true sterke cryptografie voor uw app. Deze switch is alleen van invloed op clientverbindingen (uitgaande) in uw toepassing.

Als uw app is gericht op .NET Framework 4.6.2 of nieuwere versies, wordt deze schakeloptie standaard ingesteld falseop . Dat is een veilige standaardwaarde, die we aanbevelen. Als uw app wordt uitgevoerd op .NET Framework 4.6.2, maar gericht is op een eerdere versie, wordt de schakeloptie standaard ingesteld trueop . In dat geval moet u deze expliciet instellen op false.

DontEnableSchUseStrongCrypto mag alleen een waarde hebben als true u verbinding wilt maken met verouderde services die geen ondersteuning bieden voor sterke cryptografie en niet kunnen worden geüpgraded.

Switch.System.Net.DontEnableSystemDefaultTlsVersions

Een waarde van false de Switch.System.Net.DontEnableSystemDefaultTlsVersions oorzaak is dat uw app het besturingssysteem toestaat het protocol te kiezen. Een waarde die true ervoor zorgt dat uw app protocollen gebruikt die zijn gekozen door .NET Framework.

Als uw app is gericht op .NET Framework 4.7 of nieuwere versies, wordt deze schakeloptie standaard ingesteld falseop . Dat is een veilige standaardwaarde die we aanbevelen. Als uw app wordt uitgevoerd op .NET Framework 4.7 of nieuwere versies, maar gericht is op een eerdere versie, wordt de schakeloptie standaard ingesteld trueop . In dat geval moet u deze expliciet instellen op false.

Voor WCF-toepassingen

Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols

Een waarde die false ervoor Switch.System.ServiceModel.DisableUsingServicePointManagerSecurityProtocols zorgt dat uw toepassing de waarde gebruikt die is ServicePointManager.SecurityProtocols gedefinieerd voor berichtbeveiliging met behulp van certificaatreferenties. Een waarde van het gebruik van true het hoogste protocol dat beschikbaar is, maximaal TLS1.0

Voor toepassingen die zijn gericht op .NET Framework 4.7 en latere versies, wordt deze waarde standaard ingesteld falseop . Voor toepassingen die gericht zijn op .NET Framework 4.6.2 en eerder, wordt deze waarde standaard ingesteld trueop .

Switch.System.ServiceModel.DontEnableSystemDefaultTlsVersions

Een waarde voor het instellen van false Switch.System.ServiceModel.DontEnableSystemDefaultTlsVersions de standaardconfiguratie zodat het besturingssysteem het protocol kan kiezen. Een waarde van het instellen van true de standaardwaarde op het hoogste protocol dat beschikbaar is, tot TLS1.2.

Voor toepassingen die gericht zijn op .NET Framework 4.7.1 en latere versies, wordt deze waarde standaard ingesteld op false. Voor toepassingen die zijn gericht op .NET Framework 4.7 en eerder, wordt deze waarde standaard ingesteld op true.

Zie Risicobeperking: TLS-protocollen voor meer informatie over TLS-protocollen. Zie voor meer informatie over AppContext schakelopties <AppContextSwitchOverrides> Element.

Beveiliging configureren via het Windows-register

Waarschuwing

Het instellen van registersleutels is van invloed op alle toepassingen op het systeem. Gebruik deze optie alleen als u volledig beheer hebt over de computer en wijzigingen in het register kunt beheren.

Als het instellen van een of beide AppContext schakelopties geen optie is, kunt u de beveiligingsprotocollen beheren die door uw app worden gebruikt met de Windows-registersleutels die in deze sectie worden beschreven. Mogelijk kunt u een of beide AppContext schakelopties niet gebruiken als uw app wordt uitgevoerd op .NET Framework 3.5 of als u het configuratiebestand niet kunt bewerken. Als u beveiliging wilt configureren met het register, geeft u geen waarde voor het beveiligingsprotocol op in uw code; Als u dit doet, wordt de registerinstelling overschreven.

De namen van de registersleutels zijn vergelijkbaar met de namen van de bijbehorende AppContext schakelopties, maar zonder een DontEnable voorbehorend aan de naam. De switch is bijvoorbeeld AppContext de registersleutel genaamd SchUseStrongCrypto.DontEnableSchUseStrongCrypto

Deze sleutels zijn beschikbaar in alle .NET Framework-versies.

Alle registersleutels die hieronder worden beschreven, hebben hetzelfde effect, ongeacht of u HTTP-netwerken (ServicePointManager) of TCP-socketsnetwerken (SslStream) uitvoert.

SchUseStrongCrypto

De HKEY_LOCAL_MACHINE\SOFTWARE\[Wow6432Node\]Microsoft\.NETFramework\<VERSION>: SchUseStrongCrypto registervermelding heeft een waarde van het type DWORD. Een waarde van 1 zorgt ervoor dat uw app sterke cryptografie gebruikt. De sterke cryptografie maakt gebruik van veiligere netwerkprotocollen (TLS 1.2 en TLS 1.1) en blokkeert protocollen die niet beveiligd zijn. Een waarde van 0 schakelt sterke cryptografie uit. Zie de vlag SCH_USE_STRONG_CRYPTO voor meer informatie. Deze registerinstelling is alleen van invloed op clientverbindingen (uitgaande) verbindingen in uw toepassing.

Als uw app is gericht op .NET Framework 4.6 of nieuwere versies, wordt deze sleutel standaard ingesteld op een waarde van 1. Dat is een veilige standaardwaarde die we aanbevelen. Als uw app is gericht op .NET Framework 4.5.2 of eerdere versies, wordt de sleutel standaard ingesteld op 0. In dat geval moet u de waarde expliciet instellen op 1.

Deze sleutel mag alleen een waarde van 0 hebben als u verbinding wilt maken met verouderde services die geen ondersteuning bieden voor sterke cryptografie en niet kunnen worden bijgewerkt.

SystemDefaultTlsVersions

De HKEY_LOCAL_MACHINE\SOFTWARE\[Wow6432Node\]Microsoft\.NETFramework\<VERSION>: SystemDefaultTlsVersions registervermelding heeft een waarde van het type DWORD. Een waarde van 1 zorgt ervoor dat uw app het protocol kan kiezen door het besturingssysteem. Een waarde van 0 zorgt ervoor dat uw app protocollen gebruikt die zijn gekozen door .NET Framework.

<VERSION> moet v4.0.30319 (voor .NET Framework 4 en hoger) of v2.0.50727 (voor .NET Framework 3.5) zijn.

Als uw app is gericht op .NET Framework 4.7 of hoger, wordt deze sleutel standaard ingesteld op een waarde van 1. Dat is een veilige standaardwaarde die we aanbevelen. Als uw app is gericht op .NET Framework 4.6.1 of eerdere versies, wordt de sleutel standaard ingesteld op 0. In dat geval moet u de waarde expliciet instellen op 1.

Zie Cumulatieve update voor Windows 10 versie 1511 en Windows Server 2016 Technical Preview 4: 10 mei 2016 voor meer informatie.

Zie Ondersteuning voor standaardversies van TLS-systeem opgenomen in .NET Framework 3.5.1 op Windows 7 SP1 en Server 2008 R2 SP1 voor meer informatie over .NET Framework 3.5.1.

Het volgende . Reg-bestand stelt de registervermeldingen en hun varianten in op hun meest veilige waarden:

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

Schannel-protocollen configureren in het Windows-register

U kunt het register gebruiken voor fijnmazige controle over de protocollen die uw client- en/of server-app onderhandelt. Het netwerk van uw app gaat via Schannel (een andere naam voor Secure Channel). Door deze te Schannelconfigureren, kunt u het gedrag van uw app configureren.

Begin met de HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols registersleutel. Onder die sleutel kunt u alle subsleutels in de set TLS 1.2maken. TLS 1.3 Onder elk van deze subsleutels kunt u subsleutels Client en/of Servermaken. Onder Client en Serverkunt u DWORD-waarden DisabledByDefault (0 of 1) en Enabled (0 of 1) maken.

Zie voor meer informatie: TLS-registerinstellingen - Schannel

De vlag SCH_USE_STRONG_CRYPTO

Wanneer deze optie is ingeschakeld (standaard door een switch of door het Windows-register), gebruikt .NET Framework de SCH_USE_STRONG_CRYPTO vlag wanneer uw app een TLS-verbinding met een server initieert.AppContext .NET Framework geeft de vlag door om deze opdracht te Schannel geven om bekende zwakke cryptografische algoritmen, coderingssuites en TLS/SSL-protocolversies uit te schakelen die anders kunnen worden ingeschakeld voor betere interoperabiliteit. Zie voor meer informatie:

• Beveiligd kanaal
• SCHANNEL_CRED structuur

De SCH_USE_STRONG_CRYPTO vlag wordt ook doorgegeven aan Schannel voor clientverbindingen (uitgaande) verbindingen wanneer u expliciet de Tls11 of Tls12 opgesomde waarden van SecurityProtocolType of SslProtocols. De SCH_USE_STRONG_CRYPTO vlag wordt alleen gebruikt voor verbindingen waarbij uw toepassing de rol van de client optreedt. U kunt zwakke protocollen en algoritmen uitschakelen wanneer uw toepassingen de rol van de server uitvoeren door de registerinstellingen voor de hele Schannel computer te configureren.