From a61643fd6381104c3c8846ab030c60ee5ea8dc0a Mon Sep 17 00:00:00 2001 From: Rich Lander Date: Thu, 14 Nov 2024 16:26:28 -0800 Subject: [PATCH 1/3] Add TLS 1.2 breaking change --- docs/core/compatibility/8.0.md | 1 + .../8.0/default-ciphers-for-tls-changed.md | 50 +++++++++++++++++++ docs/core/compatibility/toc.yml | 2 + 3 files changed, 53 insertions(+) create mode 100644 docs/core/compatibility/containers/8.0/default-ciphers-for-tls-changed.md 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..2d021367cf749 --- /dev/null +++ b/docs/core/compatibility/containers/8.0/default-ciphers-for-tls-changed.md @@ -0,0 +1,50 @@ +--- +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 will prevent applications from securely connecting to servers that do not 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) do not 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 5 + +## 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 + +Upgrade components that do not support TLS 1.3. This is required to create secure workflows. + +More information is available at [dotnet/dotnet-docker #6039](https://github.com/dotnet/dotnet-docker/issues/6039). + +## Affected APIs + +None. + +## See also diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index deccf90e56836..be8b1060a937f 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 From a347c6d6e9b4cbbbe64f5edd61505e4788e29f38 Mon Sep 17 00:00:00 2001 From: Rich Lander Date: Thu, 14 Nov 2024 16:46:09 -0800 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- .../containers/8.0/default-ciphers-for-tls-changed.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) 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 index 2d021367cf749..be0e67e2e2207 100644 --- 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 @@ -7,11 +7,11 @@ ms.date: 08/29/2024 .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 will prevent applications from securely connecting to servers that do not support TLS 1.3. +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) do not configure default cipher suites for OpenSSL. +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 @@ -27,7 +27,7 @@ Debian 12 and Ubuntu 24.04 do not configure default cipher suites for OpenSSL. A ## Version introduced -.NET 5 +.NET 8 container images ## Type of change @@ -39,12 +39,10 @@ Debian and Ubuntu maintainers presumably made this change to align with industry ## Recommended action -Upgrade components that do not support TLS 1.3. This is required to create secure workflows. +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. - -## See also From 57b9c6b369931c01c90fe17151ad98d234af6674 Mon Sep 17 00:00:00 2001 From: Rich Lander Date: Thu, 14 Nov 2024 16:48:01 -0800 Subject: [PATCH 3/3] Update other part of TOC --- docs/core/compatibility/toc.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index be8b1060a937f..26f43ea865046 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -1260,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