diff --git a/docs/core/compatibility/8.0.md b/docs/core/compatibility/8.0.md index d15b9b95611ce..78f04eb9f364d 100644 --- a/docs/core/compatibility/8.0.md +++ b/docs/core/compatibility/8.0.md @@ -1,7 +1,7 @@ --- title: Breaking changes in .NET 8 description: Navigate to the breaking changes in .NET 8. -ms.date: 01/19/2023 +ms.date: 01/24/2023 no-loc: [Blazor, Razor, Kestrel] --- # Breaking changes in .NET 8 @@ -14,9 +14,16 @@ If you're migrating an app to .NET 8, the breaking changes listed here might aff > > This article is a work in progress. It's not a complete list of breaking changes in .NET 8. To query breaking changes that are still pending publication, see [Issues of .NET](https://issuesof.net/?q=%20is:open%20-label:Documented%20is:issue%20(label:%22Breaking%20Change%22%20or%20label:breaking-change)%20(repo:dotnet/docs%20or%20repo:aspnet/Announcements)%20group:repo%20(label:%22:checkered_flag:%20Release:%20.NET%208%22%20or%20label:8.0.0)%20sort:created-desc). +## Cryptography + +| Title | Type of change | Introduced | +| -------------------------------------------------------------------------------------------------------- | ----------------- | ---------- | +| [AesGcm authentication tag size on macOS](cryptography/8.0/aesgcm-auth-tag-size.md) | Behavioral change | Preview 1 | +| [RSA.EncryptValue and RSA.DecryptValue obsolete](cryptography/8.0/rsa-encrypt-decrypt-value-obsolete.md) | Behavioral change | Preview 1 | + ## Windows Forms | Title | Type of change | Introduced | | ----------------------------------------------------------------------------------------------------- | ----------------- | ---------- | -| [Top-level forms scale minimum and maximum size to DPI](windows-forms/8.0/forms-scale-size-to-dpi.md) | Behavioral change | Preview 1 | | [Anchor layout changes](windows-forms/8.0/anchor-layout.md) | Behavioral change | Preview 1 | +| [Top-level forms scale minimum and maximum size to DPI](windows-forms/8.0/forms-scale-size-to-dpi.md) | Behavioral change | Preview 1 | diff --git a/docs/core/compatibility/cryptography/8.0/aesgcm-auth-tag-size.md b/docs/core/compatibility/cryptography/8.0/aesgcm-auth-tag-size.md new file mode 100644 index 0000000000000..0ca61fa8f960f --- /dev/null +++ b/docs/core/compatibility/cryptography/8.0/aesgcm-auth-tag-size.md @@ -0,0 +1,44 @@ +--- +title: "Breaking change: AesGcm authentication tag size on macOS" +description: Learn about the .NET 8 breaking change in cryptography where AesGcm on macOS only supports 16-byte (128-bit) authentication tags. +ms.date: 01/24/2023 +--- +# AesGcm authentication tag size on macOS + + on macOS only supports 16-byte (128-bit) authentication tags when using or in .NET 8 and later versions. + +## Previous behavior + +On macOS, and supported authentication tag sizes ranging from 12 to 16 bytes, provided OpenSSL was available. + +In addition, the property reported that it supported sizes ranging from 12 to 16 bytes, inclusive. + +## New behavior + +On macOS, and support 16-byte authentication tags only. If you use a smaller tag size on macOS, an is thrown at run time. + +The property returns a value of 16 as the supported tag size. + +## Version introduced + +.NET 8 Preview 1 + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +The class on macOS previously relied on OpenSSL for underlying support. OpenSSL is an external dependency that needed to be installed and configured separately from .NET. now uses Apple's CryptoKit to provide an implementation of Advanced Encryption Standard with Galois/Counter Mode (AES-GCM) so that OpenSSL is no longer a dependency for using . + +The CryptoKit implementation of AES-GCM does not support authentication tag sizes other than 128-bits (16-bytes). + +## Recommended action + +Use 128-bit authentication tags with for macOS support. + +## Affected APIs + +- +- +- diff --git a/docs/core/compatibility/cryptography/8.0/rsa-encrypt-decrypt-value-obsolete.md b/docs/core/compatibility/cryptography/8.0/rsa-encrypt-decrypt-value-obsolete.md new file mode 100644 index 0000000000000..8e26027e2ae86 --- /dev/null +++ b/docs/core/compatibility/cryptography/8.0/rsa-encrypt-decrypt-value-obsolete.md @@ -0,0 +1,46 @@ +--- +title: "RSA.EncryptValue and RSA.DecryptValue are obsolete" +description: Learn about the .NET 8 breaking change in cryptography where RSA.EncryptValue and RSA.DecryptValue are marked obsolete. +ms.date: 01/24/2023 +--- +# RSA.EncryptValue and RSA.DecryptValue are obsolete + +The following methods are obsolete in .NET 8 (and later versions): + +- +- +- +- + +All references to these methods will result in a [SYSLIB0048](../../../../fundamentals/syslib-diagnostics/syslib0048.md) warning at compile time. + +## Previous behavior + +Previously, code could call the [affected methods](#affected-apis) without any compilation warnings. However, they threw a at run time. + +## New behavior + +Starting in .NET 8, calling the [affected methods](#affected-apis) produces a `SYSLIB0048` compilation warning. + +## Version introduced + +.NET 8 Preview 1 + +## Type of breaking change + +This change can affect [source compatibility](../../categories.md#source-compatibility). + +## Reason for change + +The affected methods were never implemented and always threw a . Since the purpose of these methods is unclear and they shouldn't be called, they were marked as obsolete. + +## Recommended action + +To encrypt or decrypt with RSA, use or instead. + +## Affected APIs + +- +- +- +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index eb251ba758fb3..e4f82defe86e2 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -4,6 +4,22 @@ items: - name: Breaking changes by version expanded: true items: + - name: .NET 8 + items: + - name: Overview + href: 8.0.md + - name: Cryptography + items: + - name: AesGcm authentication tag size on macOS + href: cryptography/8.0/aesgcm-auth-tag-size.md + - name: RSA.EncryptValue and RSA.DecryptValue are obsolete + href: cryptography/8.0/rsa-encrypt-decrypt-value-obsolete.md + - name: Windows Forms + items: + - name: Anchor layout changes + href: windows-forms/8.0/anchor-layout.md + - name: Top-level forms scale size to DPI + href: windows-forms/8.0/forms-scale-size-to-dpi.md - name: .NET 7 items: - name: Overview @@ -662,16 +678,6 @@ items: items: - name: ASP.NET Core items: - - name: .NET 8 - items: - - name: Overview - href: 8.0.md - - name: Windows Forms - items: - - name: Anchor layout changes - href: windows-forms/8.0/anchor-layout.md - - name: Top-level forms scale size to DPI - href: windows-forms/8.0/forms-scale-size-to-dpi.md - name: .NET 7 items: - name: API controller actions try to infer parameters from DI @@ -1016,6 +1022,12 @@ items: href: corefx.md - name: Cryptography items: + - name: .NET 8 + items: + - name: AesGcm authentication tag size on macOS + href: cryptography/8.0/aesgcm-auth-tag-size.md + - name: RSA.EncryptValue and RSA.DecryptValue are obsolete + href: cryptography/8.0/rsa-encrypt-decrypt-value-obsolete.md - name: .NET 7 items: - name: Dynamic X509ChainPolicy verification time diff --git a/docs/core/compatibility/unsupported-apis.md b/docs/core/compatibility/unsupported-apis.md index eb1cd6f589d19..ddf449afd4ffe 100644 --- a/docs/core/compatibility/unsupported-apis.md +++ b/docs/core/compatibility/unsupported-apis.md @@ -2,7 +2,7 @@ title: Unsupported APIs on .NET Core and .NET 5+ titleSuffix: "" description: Learn which .NET APIs always throw an exception on .NET Core and .NET 5 and later versions. -ms.date: 11/23/2021 +ms.date: 01/24/2023 --- # APIs that always throw exceptions on .NET Core and .NET 5+ @@ -271,6 +271,10 @@ This article organizes the affected APIs by namespace. | | All | | | Linux and macOS | | | Linux and macOS | +| | All | +| | All | +| | All | +| | All | | | All | | | All | | | All | diff --git a/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md b/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md index 7ddc69e274751..8b4dfbe9de595 100644 --- a/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md +++ b/docs/fundamentals/syslib-diagnostics/obsoletions-overview.md @@ -2,7 +2,7 @@ title: Obsolete features in .NET 5+ titleSuffix: "" description: Learn about APIs that are marked as obsolete in .NET 5 and later versions that produce SYSLIB compiler warnings. -ms.date: 11/07/2022 +ms.date: 01/24/2023 --- # Obsolete features in .NET 5+ @@ -68,6 +68,7 @@ The following table provides an index to the `SYSLIB0XXX` obsoletions in .NET 5+ | [SYSLIB0045](syslib0045.md) | Warning | Cryptographic factory methods accepting an algorithm name are obsolete. Use the parameterless `Create` factory method on the algorithm type instead. | | [SYSLIB0046](syslib0046.md) | Warning | The method might corrupt the process and should not be used in production code. | | [SYSLIB0047](syslib0047.md) | Warning | is obsolete. Use `XmlResolver.ThrowingResolver` instead when attempting to forbid XML external entity resolution. | +| [SYSLIB0048](syslib0048.md) | Warning | and are obsolete. Use and instead. | ## Suppress warnings diff --git a/docs/fundamentals/syslib-diagnostics/syslib0048.md b/docs/fundamentals/syslib-diagnostics/syslib0048.md new file mode 100644 index 0000000000000..527b31c645e80 --- /dev/null +++ b/docs/fundamentals/syslib-diagnostics/syslib0048.md @@ -0,0 +1,51 @@ +--- +title: SYSLIB0048 warning - RSA.EncryptValue and DecryptValue are obsolete +description: Learn about the obsoletion of the RSA.EncryptValue and RSA.DecryptValue methods that generates compile-time warning SYSLIB0048. +ms.date: 04/08/2022 +--- +# SYSLIB0048: RSA.EncryptValue and DecryptValue are obsolete + +The following methods are obsolete, starting in .NET 8. Calling them in code generates warning `SYSLIB0048` at compile time. + +- +- +- +- + +## Workaround + +Use and instead. + +## Suppress a warning + +If you must use the obsolete APIs, you can suppress the warning in code or in your project file. + +To suppress only a single violation, add preprocessor directives to your source file to disable and then re-enable the warning. + +```csharp +// Disable the warning. +#pragma warning disable SYSLIB0048 + +// Code that uses obsolete API. +// ... + +// Re-enable the warning. +#pragma warning restore SYSLIB0048 +``` + +To suppress all the `SYSLIB0048` warnings in your project, add a `` property to your project file. + +```xml + + + ... + $(NoWarn);SYSLIB0048 + + +``` + +For more information, see [Suppress warnings](obsoletions-overview.md#suppress-warnings). + +## See also + +- [RSA.EncryptValue and RSA.DecryptValue are obsolete](../../core/compatibility/cryptography/8.0/rsa-encrypt-decrypt-value-obsolete.md) diff --git a/docs/toc/tools-diagnostics/toc.yml b/docs/toc/tools-diagnostics/toc.yml index 56d1ccfb596b5..acf8c77a6b0b9 100644 --- a/docs/toc/tools-diagnostics/toc.yml +++ b/docs/toc/tools-diagnostics/toc.yml @@ -1444,6 +1444,8 @@ items: href: ../../fundamentals/syslib-diagnostics/syslib0046.md - name: SYSLIB0047 href: ../../fundamentals/syslib-diagnostics/syslib0047.md + - name: SYSLIB0048 + href: ../../fundamentals/syslib-diagnostics/syslib0048.md - name: Source-generated code items: - name: Overview