diff --git a/docs/core/compatibility/8.0.md b/docs/core/compatibility/8.0.md index e2a4269aa9320..faffeb511bc96 100644 --- a/docs/core/compatibility/8.0.md +++ b/docs/core/compatibility/8.0.md @@ -29,6 +29,7 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff | ----------------------------------------------------------------------- | ----------------- | | ['ca-certificates' package removed from Alpine images](containers/8.0/ca-certificates-package.md) | Binary incompatible | | [Debian container images upgraded to Debian 12](containers/8.0/debian-version.md) | Binary incompatible/behavioral change | +| [Debian container images no longer support TLS 1.2](./containers/8.0/default-ciphers-for-tls-changed.md) | Behavioral change | | [Default ASP.NET Core port changed to 8080](containers/8.0/aspnet-port.md) | Behavioral change | | [Kerberos package removed from Alpine and Debian images](containers/8.0/krb5-libs-package.md) | Binary incompatible | | ['libintl' package removed from Alpine images](containers/8.0/libintl-package.md) | Behavioral change | diff --git a/docs/core/compatibility/containers/8.0/default-ciphers-for-tls-changed.md b/docs/core/compatibility/containers/8.0/default-ciphers-for-tls-changed.md new file mode 100644 index 0000000000000..be0e67e2e2207 --- /dev/null +++ b/docs/core/compatibility/containers/8.0/default-ciphers-for-tls-changed.md @@ -0,0 +1,48 @@ +--- +title: "Debian 12 container images no longer support TLS 1.2" +description: Learn about the breaking change in containers where .NET 8 Debian container images no longer support TLS 1.2. +ms.date: 08/29/2024 +--- +# Debian 12 container images no longer support TLS 1.2 + +.NET 8 Debian 12 container images use different default cipher suites for TLS than .NET 7 Debian 11 container images. The same is true for .NET 8 Ubuntu 24.04 containers images as compared to Ubuntu 22.04. + +This change prevents applications from securely connecting to servers that don't support TLS 1.3. + +.NET, on Linux, respects the OpenSSL configuration for default cipher suites when doing TLS/SSL via the class or higher-level operations, such as HTTPS via the class. When default cipher suites aren't explicitly configured, .NET on Linux uses a tightly restricted list of permitted cipher suites. This behavior was [added in .NET 5 as a breaking change](../../cryptography/5.0/default-cipher-suites-for-tls-on-linux.md). + +Debian 12 and Ubuntu 24.04 do not configure default cipher suites for OpenSSL. Alpine (all known versions) doesn't configure default cipher suites for OpenSSL. + +## Previous behavior + +.NET 6 and 7 Debian images are based on Debian 11. Debian 11 includes a setting in `/etc/ssl/openssl.cnf` that configures TLS 1.2 as the minimum supported protocol. This setting is honored by OpenSSL, including when used within .NET apps. + +.NET 8 Ubuntu 22.04 images are configured the same way as Debian 11. + +## New behavior + +.NET 8 Debian images are based on Debian 12. Debian 12 does not configure a minimum protocol version in `/etc/ssl/openssl.cnf`. As a result, The .NET default ciphers are used on Debian 12 or higher, making TLS 1.3 the minimum protocol version. + +.NET 8 Ubuntu 24.04 images are configured the same way as Debian 12 and also set TLS 1.3 as the minimum protocol version. + +## Version introduced + +.NET 8 container images + +## Type of change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +Debian and Ubuntu maintainers presumably made this change to align with industry standards. TLS 1.2 has not been considered secure for many years. The .NET 5 change was made for the same rationale. + +## Recommended action + +To create secure workflows, upgrade components that don't support TLS 1.3. + +More information is available at [dotnet/dotnet-docker #6039](https://github.com/dotnet/dotnet-docker/issues/6039). + +## Affected APIs + +None. diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index deccf90e56836..26f43ea865046 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -160,6 +160,8 @@ items: href: containers/8.0/ca-certificates-package.md - name: Container images upgraded to Debian 12 href: containers/8.0/debian-version.md + - name: Container images no longer support TLS 1.2 + href: containers/8.0/default-cipher-suites-for-tls-on-linux.md - name: Default ASP.NET Core port changed to 8080 href: containers/8.0/aspnet-port.md - name: Kerberos package removed from Alpine and Debian images @@ -1258,6 +1260,8 @@ items: href: containers/8.0/ca-certificates-package.md - name: Container images upgraded to Debian 12 href: containers/8.0/debian-version.md + - name: Container images no longer support TLS 1.2 + href: containers/8.0/default-cipher-suites-for-tls-on-linux.md - name: Default ASP.NET Core port changed to 8080 href: containers/8.0/aspnet-port.md - name: Kerberos package removed from Alpine and Debian images