BinaryFormatter removed from .NET 9

[Guest Immo Landwerth]

Starting with .NET 9, we no longer include an implementation of [iCODE]BinaryFormatter[/iCODE] in the runtime (.NET Framework remains unchanged). The APIs are still present, but their implementation always throws an exception, regardless of project type. Hence, setting the existing backwards compatibility flag is no longer sufficient to use [iCODE]BinaryFormatter[/iCODE].

 

In this blog post, I’ll explain why this change was made and what options you have to move forward.

 

[HEADING=1]TL;DR: What should I do?[/HEADING]

 

You have two options to address the removal of [iCODE]BinaryFormatter[/iCODE]‘s implementation:

 

1. Migrate away from BinaryFormatter. We strongly recommend that you investigate options to stop using [iCODE]BinaryFormatter[/iCODE] due to the associated security risks. The BinaryFormatter migration guide lists several options.
   
2. Keep using BinaryFormatter. If you need to continue using [iCODE]BinaryFormatter[/iCODE] in .NET 9, you need to depend on the unsupported System.Runtime.Serialization.Formatters NuGet package, which restores the unsafe legacy functionality and replaces the throwing implementation.
   

 

 

Note

 

---

Please note that .NET Framework is unaffected by this change and continues to include an implementation of [iCODE]BinaryFormatter[/iCODE]. However, we still strongly recommend to stop using [iCODE]BinaryFormatter[/iCODE] from .NET Framework too, for the same reasons.

 

[HEADING=1]What’s the risk in using BinaryFormatter?[/HEADING]

 

Any deserializer, binary or text, that allows its input to carry information about the objects to be created is a security problem waiting to happen. There is a common weakness enumeration (CWE) that describes the issue: CWE-502 “Deserialization of Untrusted Data”. [iCODE]BinaryFormatter[/iCODE], included in the the initial release of .NET Framework in 2002, is such a deserializer. We also cover this in the BinaryFormatter security guide.

 

[HEADING=1]Why we removed BinaryFormatter[/HEADING]

 

We strongly believe that .NET should make it easy for customers to do the right thing and hard, if not impossible, to do the wrong thing. We generally refer to this as the “pit of success”.

 

Shipping a technology that is widely regarded as unsafe is counter to this goal. At the same time, we also have a responsibility to ensure customers can support and move their existing code forward. We can’t just remove widely used components from a .NET release, even when communicated long in advance. We also need a migration plan and stop gap options.

 

This removal was not a sudden change. Due to the known risks of using [iCODE]BinaryFormatter[/iCODE], we excluded it from .NET Core 1.0. But without a clear migration path to using something safer, customer demand led to [iCODE]BinaryFormatter[/iCODE] being included in .NET Core 2.0.

 

Since then, we have been on the path to removing [iCODE]BinaryFormatter[/iCODE], slowly turning it off by default in multiple project types but letting consumers opt-in via flags if still needed for backward compatibility:

 

• 2020: BinaryFormatter Obsoletion Plan
  
• 2023: .NET 8 Update: Implementation throws by default
  
• 2024: .NET 9 Update: Announced intention of removal early in the release cycle
  
• 2024: .NET 9 Update: Removal completed
  
• 2024: .NET 9 Breaking Change: In-box BinaryFormatter implementation removed and always throws
  

 

In .NET 9 we removed all remaining in-box dependencies on [iCODE]BinaryFormatter[/iCODE] and replaced the implementation with one that always throws.

 

[HEADING=1]Options to move forward[/HEADING]

 

New code should not take a dependency on [iCODE]BinaryFormatter[/iCODE]. For existing code, you should first investigate alternatives to [iCODE]BinaryFormatter[/iCODE]. In case you don’t control the serializer but only perform deserialization, you can consider only reading the [iCODE]BinaryFormatter[/iCODE] payload, without performing any deserialization. And if none of this works for you can bring the implementation back by depending on an (unsupported) compatibility package.

 

I’ll explore these options in more detail below.

 

[HEADING=2]Migrate-Away[/HEADING]

 

You should first investigate whether you can replace [iCODE]BinaryFormatter[/iCODE] with another serializer. We have four recommendations:

 

• Text-based. If a binary serialization format is not a requirement, you can consider using JSON or XML serialization formats. These serializers are included in .NET and are supported by us.
   
  
  • JSON using System.Text.Json
    
  • XML using System.Runtime.Serialization.DataContractSerializer
    

• Binary If a compact binary representation is important for your scenarios, the following serialization formats and open-source serializers are recommended:

 

• MessagePack using MessagePack for C#
  
• Protocol Buffers using protobuf-net
  

 

Since [iCODE]DataContractSerializer[/iCODE] honors the same attribute and interface as [iCODE]BinaryFormatter[/iCODE] (namely [iCODE][serializable][/iCODE] and [iCODE]ISerializable[/iCODE]), it’s probably the easiest one to migrate to. If your migration goals include adopting a modern and performant serializer or a format with better cross-platform interoperability, the other options should be considered.

 

[HEADING=2]Read BinaryFormatter Payloads[/HEADING]

 

If your code doesn’t control the serialization but only the deserialization, use the new [iCODE]NrbfDecoder[/iCODE] to read BinaryFormatter payloads. This allows you to read the encoded data without any deserialization. It’s the equivalent of using a JSON/XML reader without the deserializer:

 

using System.Formats.Nrbf;

void Read(Stream payload)
{
   SerializationRecord rootObject = NrbfDecoder.Decode(payload);

   if (rootObject is PrimitiveTypeRecord primitiveRecord)
   {
       Console.WriteLine($"It was a primitive value: '{primitiveRecord.Value}'");
   }
   else if (rootObject is ClassRecord classRecord)
   {
       Console.WriteLine($"It was a class record of '{classRecord.TypeName.AssemblyQualifiedName}' type name.");
   }
   else if (rootObject is SZArrayRecord<byte> arrayOfBytes)
   {
       Console.WriteLine($"It was an array of `{arrayOfBytes.Length}`-many bytes.");
   }
}

 

For more details, check out the Nrbf documentation.

 

[HEADING=2]BinaryFormatter compatibility package[/HEADING]

 

If you have explored the options and determined you can’t migrate away from [iCODE]BinaryFormatter[/iCODE], you can also install the unsupported System.Runtime.Serialization.Formatters NuGet package and set the compatibility switch to true:

 

<PropertyGroup>
 <TargetFramework>net9.0</TargetFramework>
 <EnableUnsafeBinaryFormatterSerialization>true</EnableUnsafeBinaryFormatterSerialization>
</PropertyGroup>

<ItemGroup>
 <PackageReference Include="System.Runtime.Serialization.Formatters" Version="9.0.0" />
</ItemGroup>

 

The package replaces the in-box implementation of [iCODE]BinaryFormatter[/iCODE] with a functioning one, including its vulnerabilities and risks. It’s meant as a stopgap if you can’t wait with migrating to .NET 9 while not having replaced the usages of [iCODE]BinaryFormatter[/iCODE] yet.

 

Since the [iCODE]BinaryFormatter[/iCODE] API still exists and this package only replaces the in-box implementation you only need to reference it from application projects. Existing code that is compiled against [iCODE]BinaryFormatter[/iCODE] will continue to work.

 

Caution

 

---

The compatibility package is not supported and unsafe. We strongly recommend against taking a dependency on this package and to instead migrate away from [iCODE]BinaryFormatter[/iCODE].

 

[HEADING=1]Summary[/HEADING]

 

Since the start of .NET Core we have been on a path of deprecating [iCODE]BinaryFormatter[/iCODE], due to its security risks.

 

Starting with .NET 9, we no longer ship an implementation with the runtime. We recommend that you migrate away from BinaryFormatter. If that doesn’t work for you can either start reading the binary payloads without deserializing or you can take a dependency on the unsupported compatibility package.

 

The post BinaryFormatter removed from .NET 9 appeared first on .NET Blog.

 

Continue reading...