diff --git a/docs/core/compatibility/10.0.md b/docs/core/compatibility/10.0.md index 2d92b51f5a69a..07d6f374888e2 100644 --- a/docs/core/compatibility/10.0.md +++ b/docs/core/compatibility/10.0.md @@ -64,6 +64,7 @@ If you're migrating an app to .NET 10, the breaking changes listed here might af | [CoseSigner.Key can be null](cryptography/10.0/cosesigner-key-null.md) | Behavioral/source incompatible change | Preview 7 | | [MLDsa and SlhDsa 'SecretKey' members renamed](cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey.md) | Source incompatible | RC 1 | | [OpenSSL cryptographic primitives aren't supported on macOS](cryptography/10.0/openssl-macos-unsupported.md) | Behavioral change | Preview 6 | +| [OpenSSL 1.1.1 or later required on Unix](cryptography/10.0/openssl-version-requirement.md) | Behavioral change | GA | | [X500DistinguishedName validation is stricter](cryptography/10.0/x500distinguishedname-validation.md) | Behavioral change | Preview 1 | | [X509Certificate and PublicKey key parameters can be null](cryptography/10.0/x509-publickey-null.md) | Behavioral/source incompatible change | Preview 3 | | [Environment variable renamed to DOTNET_OPENSSL_VERSION_OVERRIDE](cryptography/10.0/version-override.md) | Behavioral change | Preview 1 | diff --git a/docs/core/compatibility/cryptography/10.0/openssl-version-requirement.md b/docs/core/compatibility/cryptography/10.0/openssl-version-requirement.md new file mode 100644 index 0000000000000..3c9c7da74ae40 --- /dev/null +++ b/docs/core/compatibility/cryptography/10.0/openssl-version-requirement.md @@ -0,0 +1,38 @@ +--- +title: "Breaking change: .NET 10 requires OpenSSL 1.1.1 or later on Unix" +description: "Learn about the breaking change in .NET 10 where OpenSSL 1.1.1 or later is required on Unix platforms." +ms.date: 11/04/2025 +ai-usage: ai-assisted +ms.custom: https://github.com/dotnet/docs/issues/49487 +--- +# .NET 10 requires OpenSSL 1.1.1 or later on Unix + +Starting in .NET 10, OpenSSL 1.1.1 or later is required on Unix platforms where .NET uses OpenSSL for cryptography, such as Linux. If OpenSSL 1.1.1 isn't available on a platform that requires it, the application will fail to start. .NET 10 on macOS doesn't use OpenSSL and isn't impacted by this change. + +## Version introduced + +.NET 10 GA + +## Previous behavior + +.NET applications supported OpenSSL versions prior to 1.1.1, such as 1.0.2 and 1.1.0. + +## New behavior + +Starting in .NET 10, .NET applications require OpenSSL 1.1.1 or later. If OpenSSL 1.1.1 isn't available on a platform that requires it, the application will fail to start. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +OpenSSL prior to OpenSSL 1.1.1 is outdated and isn't supported by mainstream Linux or Unix distributions. Supporting these out-of-date OpenSSL versions increases complexity of maintenance, and that effort is better spent on supporting modern versions of OpenSSL. + +## Recommended action + +Use a distribution of Linux or Unix that includes OpenSSL 1.1.1 or later. + +## Affected APIs + +None. diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index ec9c94695b2f9..084502fd419de 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -78,6 +78,8 @@ items: href: cryptography/10.0/mldsa-slhdsa-secretkey-to-privatekey.md - name: OpenSSL cryptographic primitives not supported on macOS href: cryptography/10.0/openssl-macos-unsupported.md + - name: OpenSSL 1.1.1 or later required on Unix + href: cryptography/10.0/openssl-version-requirement.md - name: X500DistinguishedName validation is stricter href: cryptography/10.0/x500distinguishedname-validation.md - name: X509Certificate and PublicKey key parameters can be null