Cryptography breaking changes for .NET 8 (#33699)

gewarren · web-flow · commit a42fef31b69e · 2023-01-24T16:02:31.000-08:00
diff --git 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
@@ -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
+
+<xref:System.Security.Cryptography.AesGcm> on macOS only supports 16-byte (128-bit) authentication tags when using <xref:System.Security.Cryptography.AesGcm.Encrypt%2A> or <xref:System.Security.Cryptography.AesGcm.Decrypt%2A> in .NET 8 and later versions.
+
+## Previous behavior
+
+On macOS, <xref:System.Security.Cryptography.AesGcm.Encrypt%2A?nameWithType> and <xref:System.Security.Cryptography.AesGcm.Decrypt%2A?nameWithType> supported authentication tag sizes ranging from 12 to 16 bytes, provided OpenSSL was available.
+
+In addition, the <xref:System.Security.Cryptography.AesGcm.TagByteSizes?displayProperty=nameWithType> property reported that it supported sizes ranging from 12 to 16 bytes, inclusive.
+
+## New behavior
+
+On macOS, <xref:System.Security.Cryptography.AesGcm.Encrypt%2A?nameWithType> and <xref:System.Security.Cryptography.AesGcm.Decrypt%2A?nameWithType> support 16-byte authentication tags only. If you use a smaller tag size on macOS, an <xref:System.ArgumentException> is thrown at run time.
+
+The <xref:System.Security.Cryptography.AesGcm.TagByteSizes?displayProperty=nameWithType> 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 <xref:System.Security.Cryptography.AesGcm> 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. <xref:System.Security.Cryptography.AesGcm> 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 <xref:System.Security.Cryptography.AesGcm>.
+
+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 <xref:System.Security.Cryptography.AesGcm> for macOS support.
+
+## Affected APIs
+
+- <xref:System.Security.Cryptography.AesGcm.TagByteSizes?displayProperty=fullName>
+- <xref:System.Security.Cryptography.AesGcm.Encrypt%2A?displayProperty=fullName>
+- <xref:System.Security.Cryptography.AesGcm.Decrypt%2A?displayProperty=fullName>
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
@@ -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):
+
+- <xref:System.Security.Cryptography.RSA.EncryptValue(System.Byte[])?displayProperty=nameWithType>
+- <xref:System.Security.Cryptography.RSA.DecryptValue(System.Byte[])?displayProperty=nameWithType>
+- <xref:System.Security.Cryptography.RSACryptoServiceProvider.EncryptValue(System.Byte[])?displayProperty=nameWithType>
+- <xref:System.Security.Cryptography.RSACryptoServiceProvider.DecryptValue(System.Byte[])?displayProperty=nameWithType>
+
+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 <xref:System.NotSupportedException> 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 <xref:System.NotSupportedException>. 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 <xref:System.Security.Cryptography.RSA.Encrypt%2A?displayProperty=nameWithType> or <xref:System.Security.Cryptography.RSA.Decrypt%2A?displayProperty=nameWithType> instead.
+
+## Affected APIs
+
+- <xref:System.Security.Cryptography.RSA.EncryptValue(System.Byte[])?displayProperty=fullName>
+- <xref:System.Security.Cryptography.RSA.DecryptValue(System.Byte[])?displayProperty=fullName>
+- <xref:System.Security.Cryptography.RSACryptoServiceProvider.EncryptValue(System.Byte[])?displayProperty=fullName>
+- <xref:System.Security.Cryptography.RSACryptoServiceProvider.DecryptValue(System.Byte[])?displayProperty=fullName>
diff --git 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
@@ -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.
 | <xref:System.Security.Cryptography.KeyedHashAlgorithm.Create(System.String)?displayProperty=nameWithType> | All |
 | <xref:System.Security.Cryptography.ProtectedData.Protect%2A?displayProperty=nameWithType> | Linux and macOS |
 | <xref:System.Security.Cryptography.ProtectedData.Unprotect%2A?displayProperty=nameWithType> | Linux and macOS |
+| <xref:System.Security.Cryptography.RSACryptoServiceProvider.DecryptValue(System.Byte[])?displayProperty=fullName> | All |
+| <xref:System.Security.Cryptography.RSACryptoServiceProvider.EncryptValue(System.Byte[])?displayProperty=fullName> | All |
+| <xref:System.Security.Cryptography.RSA.DecryptValue(System.Byte[])?displayProperty=fullName> | All |
+| <xref:System.Security.Cryptography.RSA.EncryptValue(System.Byte[])?displayProperty=fullName> | All |
 | <xref:System.Security.Cryptography.RSA.FromXmlString%2A?displayProperty=nameWithType> | All |
 | <xref:System.Security.Cryptography.RSA.ToXmlString%2A?displayProperty=nameWithType> | All |
 | <xref:System.Security.Cryptography.SymmetricAlgorithm.Create?displayProperty=nameWithType> | All |
diff --git 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 <xref:System.Runtime.ControlledExecution.Run(System.Action,System.Threading.CancellationToken)?displayProperty=nameWithType> method might corrupt the process and should not be used in production code. |
 | [SYSLIB0047](syslib0047.md) | Warning | <xref:System.Xml.XmlSecureResolver> is obsolete. Use `XmlResolver.ThrowingResolver` instead when attempting to forbid XML external entity resolution. |
+| [SYSLIB0048](syslib0048.md) | Warning | <xref:System.Security.Cryptography.RSA.EncryptValue(System.Byte[])?displayProperty=nameWithType> and <xref:System.Security.Cryptography.RSA.DecryptValue(System.Byte[])?displayProperty=nameWithType> are obsolete. Use <xref:System.Security.Cryptography.RSA.Encrypt%2A?displayProperty=nameWithType> and <xref:System.Security.Cryptography.RSA.Decrypt%2A?displayProperty=nameWithType> instead. |
 
 ## Suppress warnings
 
diff --git a/docs/fundamentals/syslib-diagnostics/syslib0048.md 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.
+
+- <xref:System.Security.Cryptography.RSA.EncryptValue(System.Byte[])?displayProperty=fullName>
+- <xref:System.Security.Cryptography.RSA.DecryptValue(System.Byte[])?displayProperty=fullName>
+- <xref:System.Security.Cryptography.RSACryptoServiceProvider.EncryptValue(System.Byte[])?displayProperty=fullName>
+- <xref:System.Security.Cryptography.RSACryptoServiceProvider.DecryptValue(System.Byte[])?displayProperty=fullName>
+
+## Workaround
+
+Use <xref:System.Security.Cryptography.RSA.Encrypt%2A?displayProperty=nameWithType> and <xref:System.Security.Cryptography.RSA.Decrypt%2A?displayProperty=nameWithType> 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 `<NoWarn>` property to your project file.
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+   ...
+   <NoWarn>$(NoWarn);SYSLIB0048</NoWarn>
+  </PropertyGroup>
+</Project>
+```
+
+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
@@ -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
