Document breaking change in crypto introduced in 3.0 (#20366)

Author: krwq

docs/core/compatibility/2.2-3.0.md

@@ -324,6 +324,7 @@ If you're migrating from version 2.2 to version 3.0 of .NET Core, ASP.NET Core,
 - [EnvelopedCms defaults to AES-256 encryption](#envelopedcms-defaults-to-aes-256-encryption)
 - [Minimum size for RSAOpenSsl key generation has increased](#minimum-size-for-rsaopenssl-key-generation-has-increased)
 - [.NET Core 3.0 prefers OpenSSL 1.1.x to OpenSSL 1.0.x](#net-core-30-prefers-openssl-11x-to-openssl-10x)
+- [CryptoStream.Dispose transforms final block only when writing](#cryptostreamdispose-transforms-final-block-only-when-writing)
 
 [!INCLUDE [begin-trusted-cert-linux](~/includes/core-changes/cryptography/3.0/begin-trusted-cert-linux.md)]
 
@@ -341,6 +342,10 @@ If you're migrating from version 2.2 to version 3.0 of .NET Core, ASP.NET Core,
 
 ***
 
+[!INCLUDE [CryptoStream.Dispose transforms final block only when writing](~/includes/core-changes/cryptography/3.0/cryptography-cryptostream-dispose-final-block-write.md)]
+
+***
+
 ## Entity Framework Core
 
 [Entity Framework Core breaking changes](/ef/core/what-is-new/ef-core-3.0/breaking-changes)

docs/core/compatibility/2.2-3.1.md

@@ -322,6 +322,7 @@ If you're migrating from version 2.2 to version 3.1 of .NET Core, ASP.NET Core,
 - [EnvelopedCms defaults to AES-256 encryption](#envelopedcms-defaults-to-aes-256-encryption)
 - [Minimum size for RSAOpenSsl key generation has increased](#minimum-size-for-rsaopenssl-key-generation-has-increased)
 - [.NET Core 3.0 prefers OpenSSL 1.1.x to OpenSSL 1.0.x](#net-core-30-prefers-openssl-11x-to-openssl-10x)
+- [CryptoStream.Dispose transforms final block only when writing](#cryptostreamdispose-transforms-final-block-only-when-writing)
 
 [!INCLUDE [begin-trusted-cert-linux](~/includes/core-changes/cryptography/3.0/begin-trusted-cert-linux.md)]
 
@@ -339,6 +340,10 @@ If you're migrating from version 2.2 to version 3.1 of .NET Core, ASP.NET Core,
 
 ***
 
+[!INCLUDE [CryptoStream.Dispose transforms final block only when writing](~/includes/core-changes/cryptography/3.0/cryptography-cryptostream-dispose-final-block-write.md)]
+
+***
+
 ## Entity Framework Core
 
 [Entity Framework Core breaking changes](/ef/core/what-is-new/ef-core-3.0/breaking-changes)

docs/core/compatibility/cryptography.md

@@ -14,6 +14,7 @@ The following breaking changes are documented on this page:
 | [EnvelopedCms defaults to AES-256 encryption](#envelopedcms-defaults-to-aes-256-encryption) | 3.0 |
 | [Minimum size for RSAOpenSsl key generation has increased](#minimum-size-for-rsaopenssl-key-generation-has-increased) | 3.0 |
 | [.NET Core 3.0 prefers OpenSSL 1.1.x to OpenSSL 1.0.x](#net-core-30-prefers-openssl-11x-to-openssl-10x) | 3.0 |
+| [CryptoStream.Dispose transforms final block only when writing](#cryptostreamdispose-transforms-final-block-only-when-writing) | 3.0 |
 | [Boolean parameter of SignedCms.ComputeSignature is respected](#boolean-parameter-of-signedcmscomputesignature-is-respected) | 2.1 |
 
 ## .NET 5.0
@@ -40,6 +41,10 @@ The following breaking changes are documented on this page:
 
 ***
 
+[!INCLUDE [CryptoStream.Dispose transforms final block only when writing](~/includes/core-changes/cryptography/3.0/cryptography-cryptostream-dispose-final-block-write.md)]
+
+***
+
 ## .NET Core 2.1
 
 [!INCLUDE [Boolean parameter of SignedCms.ComputeSignature is respected](~/includes/core-changes/cryptography/2.1/compute-signature-silent-parameter.md)]

includes/core-changes/cryptography/3.0/cryptography-cryptostream-dispose-final-block-write.md

@@ -0,0 +1,40 @@
+### CryptoStream.Dispose transforms final block only when writing
+
+The <xref:System.Security.Cryptography.CryptoStream.Dispose%2A?displayProperty=nameWithType> method, which is used to finish `CryptoStream` operations, no longer attempts to transform the final block when reading.
+
+#### Change description
+
+In previous .NET versions, if a user performed an incomplete read when using <xref:System.Security.Cryptography.CryptoStream> in <xref:System.Security.Cryptography.CryptoStreamMode.Read> mode, the <xref:System.Security.Cryptography.CryptoStream.Dispose%2A> method could throw an exception (for example, when using AES with padding). The exception was thrown because the final block was attempted to be transformed but the data was incomplete.
+
+In .NET Core 3.0 and later versions, <xref:System.Security.Cryptography.CryptoStream.Dispose%2A> no longer tries to transform the final block when reading, which allows for incomplete reads.
+
+#### Reason for change
+
+This change enables incomplete reads from the crypto stream when a network operation is cancelled, without the need to catch an exception.
+
+#### Version introduced
+
+3.0
+
+#### Recommended action
+
+Most apps should not be affected by this change.
+
+If your application previously caught an exception in case of an incomplete read, you can delete that `catch` block.
+If your app used transforming of the final block in hashing scenarios, you might need to ensure that the entire stream is read before it's disposed.
+
+#### Category
+
+Cryptography
+
+#### Affected APIs
+
+- <xref:System.Security.Cryptography.CryptoStream.Dispose%2A?displayProperty=fullName>
+
+<!--
+
+#### Affected APIs
+
+- `M:System.Security.Cryptography.CryptoStream.Dispose`
+
+-->