Skip to content

Commit 6ce910a

Browse files
vcsjonesvcsjones
authored
Cross-platform cryptography guide update for .NET 10 (#49615)
1 parent 76ec03a commit 6ce910a

File tree

1 file changed

+122
-14
lines changed

1 file changed

+122
-14
lines changed

‎docs/standard/security/cross-platform-cryptography.md‎

Lines changed: 122 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Cross-platform cryptography in .NET"
33
description: Learn about cryptographic capabilities on platforms supported by .NET.
4-
ms.date: "06/19/2020"
4+
ms.date: "11/04/2025"
55
ms.subservice: standard-library
66
helpviewer_keywords:
77
- "cryptography, cross-platform"
@@ -81,14 +81,12 @@ Since authenticated encryption requires newer platform APIs to support the algor
8181
| Cipher + Mode | Windows | Linux | macOS | iOS, tvOS, MacCatalyst | Android | Browser |
8282
|-------------------|-------------------------|----------------|---------|------------------------|---------------|---------|
8383
| AES-GCM | ✔️ | ✔️ | ✔️ | ⚠️ | ✔️ | ❌ |
84-
| AES-CCM | ✔️ | ✔️ | ⚠️ | ❌ | ✔️ | ❌ |
84+
| AES-CCM | ✔️ | ✔️ | ❌ | ❌ | ✔️ | ❌ |
8585
| ChaCha20Poly1305 | Windows 10 Build 20142+ | OpenSSL 1.1.0+ | ✔️ | ⚠️ | API Level 28+ | ❌ |
8686

8787
### AES-CCM on macOS
8888

89-
On macOS, the system libraries don't support AES-CCM for third-party code, so the <xref:System.Security.Cryptography.AesCcm> class uses OpenSSL for support. Users on macOS need to obtain an appropriate copy of OpenSSL (libcrypto) for this type to function, and it must be in a path that the system would load a library from by default. We recommend that you install OpenSSL from a package manager such as Homebrew.
90-
91-
The `libcrypto.0.9.7.dylib` and `libcrypto.0.9.8.dylib` libraries included in macOS are from earlier versions of OpenSSL and will not be used. The `libcrypto.35.dylib`, `libcrypto.41.dylib`, and `libcrypto.42.dylib` libraries are from LibreSSL and will not be used.
89+
Prior to .NET 10, AES-CCM worked if a supported version of OpenSSL was present and the dynamic library loader could locate it. OpenSSL support on macOS was removed in .NET 10.
9290

9391
### AES-GCM and ChaCha20Poly1305 on iOS, tvOS, and MacCatalyst
9492

@@ -173,11 +171,11 @@ Padding and digest support vary by platform:
173171
|--------------------------------------------------------------|---------|---------------|-----------------|-------------------------|-----------------|
174172
| <xref:System.Security.Cryptography.RSACryptoServiceProvider> | ✔️ | ⚠️<sup>1</sup> | ⚠️<sup>1</sup> | ⚠️<sup>1</sup> | ⚠️<sup>1</sup> |
175173
| <xref:System.Security.Cryptography.RSACng> | ✔️ | ❌ | ❌ | ❌ | ❌ |
176-
| <xref:System.Security.Cryptography.RSAOpenSsl> | ❌ | ✔️ | ⚠️<sup>2</sup> | ❌ | ❌ |
174+
| <xref:System.Security.Cryptography.RSAOpenSsl> | ❌ | ✔️ | ❌<sup>2</sup> | ❌ | ❌ |
177175

178176
<sup>1</sup> On non-Windows, <xref:System.Security.Cryptography.RSACryptoServiceProvider> can be used for compatibility with existing programs. In that case, any method that requires OS interop, such as opening a named key, throws a <xref:System.PlatformNotSupportedException>.
179177

180-
<sup>2</sup> On macOS, <xref:System.Security.Cryptography.RSAOpenSsl> works if OpenSSL is installed and an appropriate libcrypto dylib can be found via dynamic library loading. If an appropriate library can't be found, exceptions will be thrown.
178+
<sup>2</sup> On macOS, prior to .NET 10, <xref:System.Security.Cryptography.RSAOpenSsl> worked if OpenSSL was installed and an appropriate libcrypto dylib could be found via dynamic library loading. This support was removed in .NET 10.
181179

182180
### ECDSA
183181

@@ -210,9 +208,9 @@ ECDSA key curves are defined by the OS libraries and are subject to their limita
210208
| Type | Windows | Linux | macOS | iOS, tvOS, MacCatalyst | Android |
211209
|--------------------------------------------------|---------|-------|-------|------------------------|---------|
212210
| <xref:System.Security.Cryptography.ECDsaCng> | ✔️ | ❌ | ❌ | ❌ | ❌ |
213-
| <xref:System.Security.Cryptography.ECDsaOpenSsl> | ❌ | ✔️ | ⚠️\* | ❌ | ❌ |
211+
| <xref:System.Security.Cryptography.ECDsaOpenSsl> | ❌ | ✔️ | ❌\* | ❌ | ❌ |
214212

215-
\* On macOS, <xref:System.Security.Cryptography.ECDsaOpenSsl> works if OpenSSL is installed in the system and an appropriate libcrypto dylib can be found via dynamic library loading. If an appropriate library can't be found, exceptions will be thrown.
213+
\* On macOS, prior to .NET 10, <xref:System.Security.Cryptography.ECDsaOpenSsl> worked if OpenSSL was installed and an appropriate libcrypto dylib could be found via dynamic library loading. This support was removed in .NET 10.
216214

217215
### ECDH
218216

@@ -230,7 +228,7 @@ The <xref:System.Security.Cryptography.ECDiffieHellman> class supports the "raw"
230228

231229
ECDH key curves are defined by the OS libraries and are subject to their limitations.
232230

233-
| Elliptic Curve | Windows 10 | Windows 7 - 8.1 | Linux | macOS | iOS, tvOS, MacCatalyst | Android |
231+
| Elliptic Curve | Windows 10+ | Windows 7 - 8.1 | Linux | macOS | iOS, tvOS, MacCatalyst | Android |
234232
|------------------------------------|----------------|-----------------|----------------|-----------------|------------------------|----------------|
235233
| NIST P-256 (secp256r1) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
236234
| NIST P-384 (secp384r1) | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
@@ -255,9 +253,9 @@ ECDH key curves are defined by the OS libraries and are subject to their limitat
255253
| Type | Windows | Linux | macOS | iOS, tvOS, MacCatalyst | Android |
256254
|------------------------------------------------------------|---------|-------|-------|------------------------|----------|
257255
| <xref:System.Security.Cryptography.ECDiffieHellmanCng> | ✔️ | ❌ | ❌ | ❌ | ❌ |
258-
| <xref:System.Security.Cryptography.ECDiffieHellmanOpenSsl> | ❌ | ✔️ | ⚠️\* | ❌ | ❌ |
256+
| <xref:System.Security.Cryptography.ECDiffieHellmanOpenSsl> | ❌ | ✔️ | ❌\* | ❌ | ❌ |
259257

260-
\* On macOS, <xref:System.Security.Cryptography.ECDiffieHellmanOpenSsl> works if OpenSSL is installed and an appropriate libcrypto dylib can be found via dynamic library loading. If an appropriate library can't be found, exceptions will be thrown.
258+
\* On macOS, prior to .NET 10, <xref:System.Security.Cryptography.ECDiffieHellmanOpenSsl> worked if OpenSSL was installed and an appropriate libcrypto dylib could be found via dynamic library loading. This support was removed in .NET 10.
261259

262260
### DSA
263261

@@ -290,11 +288,103 @@ DSA (Digital Signature Algorithm) key generation is performed by the system libr
290288
|--------------------------------------------------------------|---------|----------------|-----------------|------------------------|----------------|
291289
| <xref:System.Security.Cryptography.DSACryptoServiceProvider> | ✔️ | ⚠️<sup>1</sup> | ⚠️<sup>1</sup> | ❌ | ⚠️<sup>1</sup> |
292290
| <xref:System.Security.Cryptography.DSACng> | ✔️ | ❌ | ❌ | ❌ | ❌ |
293-
| <xref:System.Security.Cryptography.DSAOpenSsl> | ❌ | ✔️ | ⚠️<sup>2</sup> | ❌ | ❌ |
291+
| <xref:System.Security.Cryptography.DSAOpenSsl> | ❌ | ✔️ | ❌<sup>2</sup> | ❌ | ❌ |
294292

295293
<sup>1</sup> On non-Windows, <xref:System.Security.Cryptography.DSACryptoServiceProvider> can be used for compatibility with existing programs. In that case, any method that requires system interop, such as opening a named key, throws a <xref:System.PlatformNotSupportedException>.
296294

297-
<sup>2</sup> On macOS, <xref:System.Security.Cryptography.DSAOpenSsl> works if OpenSSL is installed and an appropriate libcrypto dylib can be found via dynamic library loading. If an appropriate library can't be found, exceptions will be thrown.
295+
<sup>2</sup> On macOS, prior to .NET 10, <xref:System.Security.Cryptography.DSAOpenSsl> worked if OpenSSL was installed and an appropriate libcrypto dylib could be found via dynamic library loading. This support was removed in .NET 10.
296+
297+
## Post-quantum cryptography
298+
299+
Post-quantum algorithms are available starting in .NET 10. They're also available for .NET Framework using the Microsoft.Bcl.Cryptography NuGet package. The following support table indicates the platform support for the built-in operating system cryptographic components, such as those created from `Generate` or `ImportFromPem`. Implementations that derive from the base class might have different support behaviors.
300+
301+
For the built-in algorithms, an `IsSupported` static property is available to determine if the platform supports any of the parameter sets.
302+
303+
The native interop types for post-quantum algorithms do not support key generation or importing. They exist specifically for interop scenarios with the native platform types, such as an `EVP_PKEY` on OpenSSL or `CngKey` on Windows.
304+
305+
### ML-KEM
306+
307+
| Algorithm | Windows | Linux | Apple | Android | Browser |
308+
|--------------|-------------------------------|----------------|-------|---------|---------|
309+
| ML-KEM-512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
310+
| ML-KEM-768 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
311+
| ML-KEM-1024 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
312+
313+
#### Native interop ML-KEM
314+
315+
* <xref:System.Security.Cryptography.MLKemOpenSsl>: OpenSSL 3.5.0+
316+
* <xref:System.Security.Cryptography.MLKemCng>: Windows 11 Insiders (Latest)
317+
318+
### ML-DSA
319+
320+
ML-DSA has a pure and prehash variant (HashML-DSA). The following table reflects both the pure and prehash variants.
321+
322+
| Algorithm | Windows | Linux | Apple | Android | Browser |
323+
|---------------------------------------------|-------------------------------|----------------|-------|---------|---------|
324+
| ML-DSA-44 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
325+
| ML-DSA-65 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
326+
| ML-DSA-87 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
327+
| ML-DSA-44 External Mu (&#x3BC;)<sup>1</sup> | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
328+
| ML-DSA-65 External Mu (&#x3BC;)<sup>1</sup> | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
329+
| ML-DSA-87 External Mu (&#x3BC;)<sup>1</sup> | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
330+
331+
<sup>1</sup> External Mu support is for signing and verifying Mu only. Computation of Mu isn't supported.
332+
333+
#### Native interop ML-DSA
334+
335+
* <xref:System.Security.Cryptography.MLDsaOpenSsl>: OpenSSL 3.5.0+
336+
* <xref:System.Security.Cryptography.MLDsaCng>: Windows 11 Insiders (latest)
337+
338+
### SLH-DSA
339+
340+
SLH-DSA has a pure and prehash variant (HashSLH-DSA). The following table reflects both the pure and prehash variants.
341+
342+
| Algorithm | Windows | Linux | Apple | Android | Browser |
343+
|---------------------|---------|----------------|-------|---------|---------|
344+
| SLH-DSA-SHA2-128f | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
345+
| SLH-DSA-SHA2-128s | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
346+
| SLH-DSA-SHA2-192f | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
347+
| SLH-DSA-SHA2-192s | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
348+
| SLH-DSA-SHA2-256f | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
349+
| SLH-DSA-SHA2-256s | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
350+
| SLH-DSA-SHAKE-128f | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
351+
| SLH-DSA-SHAKE-128s | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
352+
| SLH-DSA-SHAKE-192f | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
353+
| SLH-DSA-SHAKE-192s | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
354+
| SLH-DSA-SHAKE-256f | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
355+
| SLH-DSA-SHAKE-256s | ❌ | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
356+
357+
#### Native interop SLH-DSA
358+
359+
* <xref:System.Security.Cryptography.SlhDsaOpenSsl>: OpenSSL 3.5.0+
360+
* <xref:System.Security.Cryptography.SlhDsaCng>: Not supported
361+
362+
### Composite ML-DSA
363+
364+
| Algorithm | Windows | Linux | Apple | Android | Browser |
365+
|----------------------------------------|-------------------------------|----------------|-------|---------|---------|
366+
| MLDSA44-RSA2048-PSS-SHA256 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
367+
| MLDSA44-RSA2048-PKCS15-SHA256 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
368+
| MLDSA44-Ed25519-SHA512 | ❌ | ❌ | ❌ | ❌ | ❌ |
369+
| MLDSA44-ECDSA-P256-SHA256 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
370+
| MLDSA65-RSA3072-PSS-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
371+
| MLDSA65-RSA3072-PKCS15-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
372+
| MLDSA65-RSA4096-PSS-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
373+
| MLDSA65-RSA4096-PKCS15-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
374+
| MLDSA65-ECDSA-P256-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
375+
| MLDSA65-ECDSA-P384-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
376+
| MLDSA65-ECDSA-brainpoolP256r1-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
377+
| MLDSA65-Ed25519-SHA512 | ❌ | ❌ | ❌ | ❌ | ❌ |
378+
| MLDSA87-ECDSA-P384-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
379+
| MLDSA87-ECDSA-brainpoolP384r1-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
380+
| MLDSA87-Ed448-SHAKE256 | ❌ | ❌ | ❌ | ❌ | ❌ |
381+
| MLDSA87-RSA3072-PSS-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
382+
| MLDSA87-RSA4096-PSS-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
383+
| MLDSA87-ECDSA-P521-SHA512 | Windows 11 Insiders (Latest) | OpenSSL 3.5.0+ | ❌ | ❌ | ❌ |
384+
385+
#### Native interop composite ML-DSA
386+
387+
* <xref:System.Security.Cryptography.CompositeMLDsaCng>: Not supported
298388

299389
## X.509 Certificates
300390

@@ -411,6 +501,24 @@ macOS doesn't support Offline CRL utilization, so `X509RevocationMode.Offline` i
411501

412502
macOS doesn't support a user-initiated timeout on CRL (Certificate Revocation List) / OCSP (Online Certificate Status Protocol) / AIA (Authority Information Access) downloading, so `X509ChainPolicy.UrlRetrievalTimeout` is ignored.
413503

504+
### Post-quantum cryptography certificates and PKCS12/PFX
505+
506+
Post-quantum certificate support also requires support from the primitive algorithm.
507+
508+
| Operation | Algorithm | Windows | Linux | Apple | Android | Browser |
509+
|-------------------------|-----------|---------|-------|-------|---------|---------|
510+
| PKCS#12 Import | ML-DSA | ✔️ | ✔️ | ❌ | ❌ | ❌ |
511+
| PKCS#12 Export | ML-DSA | ✔️ | ✔️ | ❌ | ❌ | ❌ |
512+
| Private Key Association | ML-DSA | ✔️ | ✔️ | ❌ | ❌ | ❌ |
513+
| &nbsp; | | | | | | |
514+
| PKCS#12 Import | ML-KEM | ❌ | ✔️ | ❌ | ❌ | ❌ |
515+
| PKCS#12 Export | ML-KEM | ❌ | ✔️ | ❌ | ❌ | ❌ |
516+
| Private Key Association | ML-KEM | ❌ | ✔️ | ❌ | ❌ | ❌ |
517+
| &nbsp; | | | | | | |
518+
| PKCS#12 Import | SLH-DSA | ❌ | ✔️ | ❌ | ❌ | ❌ |
519+
| PKCS#12 Export | SLH-DSA | ❌ | ✔️ | ❌ | ❌ | ❌ |
520+
| Private Key Association | SLH-DSA | ❌ | ✔️ | ❌ | ❌ | ❌ |
521+
414522
## Additional resources
415523

416524
* [.NET Cryptography Model](cryptography-model.md)

0 commit comments

Comments
 (0)