diff --git a/docs/core/compatibility/3.1-5.0.md b/docs/core/compatibility/3.1-5.0.md index eabc866044bfb..437b0994caae8 100644 --- a/docs/core/compatibility/3.1-5.0.md +++ b/docs/core/compatibility/3.1-5.0.md @@ -338,11 +338,16 @@ If you're migrating from version 3.1 of .NET Core, ASP.NET Core, or EF Core to v ## Cryptography +- [Default FeedbackSize value for instances created by TripleDES.Create changed](#default-feedbacksize-value-for-instances-created-by-tripledescreate-changed) - [Instantiating default implementations of cryptographic abstractions is not supported](#instantiating-default-implementations-of-cryptographic-abstractions-is-not-supported) - [Default TLS cipher suites for .NET on Linux](#default-tls-cipher-suites-for-net-on-linux) - [System.Security.Cryptography APIs not supported on Blazor WebAssembly](#systemsecuritycryptography-apis-not-supported-on-blazor-webassembly) - [System.Security.Cryptography.Oid is functionally init-only](#systemsecuritycryptographyoid-is-functionally-init-only) +[!INCLUDE [tripledes-default-feedback-size-change](../../../includes/core-changes/cryptography/5.0/tripledes-default-feedback-size-change.md)] + +*** + [!INCLUDE [instantiating-default-implementations-of-cryptographic-abstractions-not-supported](../../../includes/core-changes/cryptography/5.0/instantiating-default-implementations-of-cryptographic-abstractions-not-supported.md)] *** diff --git a/docs/core/compatibility/cryptography.md b/docs/core/compatibility/cryptography.md index 26f10e7a2546a..e4350efc2d871 100644 --- a/docs/core/compatibility/cryptography.md +++ b/docs/core/compatibility/cryptography.md @@ -9,6 +9,7 @@ The following breaking changes are documented on this page: | Breaking change | Version introduced | | - | :-: | +| [Default FeedbackSize value for instances created by TripleDES.Create changed](#default-feedbacksize-value-for-instances-created-by-tripledescreate-changed) | 5.0 | | [Instantiating default implementations of cryptographic abstractions is not supported](#instantiating-default-implementations-of-cryptographic-abstractions-is-not-supported) | 5.0 | | [Default TLS cipher suites for .NET on Linux](#default-tls-cipher-suites-for-net-on-linux) | 5.0 | | [System.Security.Cryptography APIs not supported on Blazor WebAssembly](#systemsecuritycryptography-apis-not-supported-on-blazor-webassembly) | 5.0 | @@ -22,6 +23,10 @@ The following breaking changes are documented on this page: ## .NET 5.0 +[!INCLUDE [tripledes-default-feedback-size-change](../../../includes/core-changes/cryptography/5.0/tripledes-default-feedback-size-change.md)] + +*** + [!INCLUDE [instantiating-default-implementations-of-cryptographic-abstractions-not-supported](../../../includes/core-changes/cryptography/5.0/instantiating-default-implementations-of-cryptographic-abstractions-not-supported.md)] *** diff --git a/includes/core-changes/cryptography/5.0/tripledes-default-feedback-size-change.md b/includes/core-changes/cryptography/5.0/tripledes-default-feedback-size-change.md new file mode 100644 index 0000000000000..281aa7315286a --- /dev/null +++ b/includes/core-changes/cryptography/5.0/tripledes-default-feedback-size-change.md @@ -0,0 +1,56 @@ +### Default FeedbackSize value for instances created by TripleDES.Create changed + +The default value for the property on the instance returned from has changed from 64 to 8 to make migration from .NET Framework easier. This property, unless used directly in caller code, is used only when the property is . + +Support for the mode was first added to .NET for the 5.0 RC1 release, so only .NET 5.0 RC1 and .NET 5.0 RC2 applications should be impacted by this change. + +#### Change description + +In .NET Core and previous pre-release versions of .NET 5.0, `TripleDES.Create().FeedbackSize` has a default value of 64. Starting in the RTM version of .NET 5.0, `TripleDES.Create().FeedbackSize` has a default value of 8. + +#### Reason for change + +In .NET Framework, the base class defaults the value of to 64, but the class overwrites the default to 8. When the property was introduced to .NET Core in version 2.0, this same behavior was preserved. However, in .NET Framework, returns an instance of , so the default value from the algorithm factory is 8. For .NET Core and .NET 5+, the algorithm factory returns a non-public implementation, which, until now, had a default value of 64. + +Changing the implementation class' value to 8 allows for applications written for .NET Framework that specified the cipher mode as but didn't explicitly assign the property, to continue to function on .NET 5. + +#### Version introduced + +5.0 RTM + +#### Recommended action + +Applications that encrypt or decrypt data in the RC1 or RC2 versions of .NET 5.0 do so with CFB64, when the following conditions are met: + +- With a instance from . +- Using the default value for . +- With the property set to . + +To maintain this behavior, assign the property to `64`. + +Not all `TripleDES` implementations use the same default for . We recommend that if you use the cipher mode on instances, you should always explicitly assign the property value. + +```csharp +TripleDES cipher = TripleDES.Create(); +cipher.Mode = CipherMode.CFB; +// Explicitly set the FeedbackSize for CFB to control between CFB8 and CFB64. +cipher.FeedbackSize = 8; +``` + +#### Category + +- Cryptography + +#### Affected APIs + +- +- + +