Document .NET 11 breaking change: TarReader validates checksums

[Copilot]

Starting in .NET 11 Preview 1, TarReader validates TAR archive entry checksums and throws InvalidDataException on mismatch. Previously, invalid checksums were silently ignored.

Changes

• Created docs/core/compatibility/core-libraries/11/tar-checksum-validation.md

  • Documents behavioral change with before/after code examples
  • Lists affected APIs: TarReader.GetNextEntry[Async], TarFile.ExtractToDirectory[Async]
  • Provides migration guidance for exception handling

• Updated docs/core/compatibility/11.md and toc.yml

  • Added entry to Core .NET libraries breaking changes table

Migration Pattern

try
{
    using var stream = File.OpenRead("archive.tar");
    using var reader = new TarReader(stream);
    
    while (reader.GetNextEntry() is not null)
    {
        // Process entries
    }
}
catch (InvalidDataException ex)
{
    // Handle corrupted/tampered TAR files
    Console.WriteLine($"Error reading TAR archive: {ex.Message}");
}

Related: dotnet/runtime#118577

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Breaking change]: Tar reading APIs verify header checksums when reading</issue_title>
<issue_description>### Description

Starting in .NET 11 Preview 1, the System.Formats.Tar.TarReader class now validates the checksum of TAR archive entries during the reading process. If an entry's checksum is invalid, the TarReader will throw an InvalidDataException. This change improves data integrity by ensuring that corrupted or tampered TAR files are detected and flagged during processing.

Previously, the TarReader would silently ignore checksum mismatches and continue reading the archive, potentially leading to the use of invalid or corrupted data.

This change was introduced in dotnet/runtime#118577.

Version

.NET 11 Preview 1

Previous behavior

When reading a TAR archive with an invalid checksum, the TarReader would ignore the checksum mismatch and continue processing the archive without throwing an exception.

Example

using System.Formats.Tar;
using System.IO;

using var stream = File.OpenRead("bad-cksum.tar");
using var reader = new TarReader(stream);

while (reader.GetNextEntry() is not null)
{
    // Process entries, even if the checksum is invalid
}

If the TAR file bad-cksum.tar contained an entry with an invalid checksum, the code would process the entry without any indication of the issue.

New behavior

When reading a TAR archive with an invalid checksum, the TarReader will throw an InvalidDataException and stop processing the archive.

Example

using System.Formats.Tar;
using System.IO;

try
{
    using var stream = File.OpenRead("bad-cksum.tar");
    using var reader = new TarReader(stream);

    while (reader.GetNextEntry() is not null)
    {
        // Process entries
    }
}
catch (InvalidDataException ex)
{
    Console.WriteLine($"Checksum validation failed: {ex.Message}");
}

If the TAR file bad-cksum.tar contains an entry with an invalid checksum, the code will throw an exception with a message indicating the checksum validation failure.

Type of breaking change

• Binary incompatible: Existing binaries might encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code might require source changes to compile successfully.
• Behavioral change: Existing binaries might behave differently at run time.

Reason for change

This change was introduced to improve the reliability and security of the System.Formats.Tar library. By validating checksums, the TarReader can detect and prevent the use of corrupted or tampered TAR files, ensuring that only valid data is processed.

Recommended action

If your application relies on the TarReader to process TAR archives, you should:

1. Update your code to handle the InvalidDataException that may be thrown when a checksum validation fails.
2. Ensure that the TAR files being processed are valid and have correct checksums. If you encounter checksum failures, verify the integrity of the source TAR files.
3. If you need to process TAR files with invalid checksums for specific scenarios, consider implementing custom error handling or preprocessing the files to correct the checksums.

Updated Example

using System.Formats.Tar;
using System.IO;

try
{
    using var stream = File.OpenRead("archive.tar");
    using var reader = new TarReader(stream);

    while (reader.GetNextEntry() is not null)
    {
        // Process entries
    }
}
catch (InvalidDataException ex)
{
    Console.WriteLine($"Error reading TAR archive: {ex.Message}");
    // Handle invalid checksum scenario
}

Feature area

Core .NET libraries

Affected APIs

System.Formats.Tar:

• TarReader.GetNextEntry
• TarReader.GetNextEntryAsync
• TarFile.ExtractToDirectory
• TarFile.ExtractToDirectoryAsync

For more details, see the pull request and the related issue.

---

Associated WorkItem - 543463</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Breaking change]: Tar reading APIs verify header checksums when reading #49394

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

---

Internal previews

📄 File	🔗 Preview link
docs/core/compatibility/11.md	Breaking changes in .NET 11
docs/core/compatibility/core-libraries/11/tar-checksum-validation.md	TAR-reading APIs verify header checksums when reading
docs/core/compatibility/toc.yml	docs/core/compatibility/toc

[Copilot]

Pull request overview

This PR documents a breaking change in .NET 11 where TarReader now validates TAR archive entry checksums and throws InvalidDataException when checksums are invalid, improving data integrity and security.

Key Changes

• Created comprehensive breaking change documentation for TAR checksum validation
• Updated breaking changes index and table of contents to include the new entry

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
docs/core/compatibility/core-libraries/11/tar-checksum-validation.md	New breaking change documentation with before/after examples, migration guidance, and affected APIs
docs/core/compatibility/11.md	Added TAR checksum validation entry to Core .NET libraries breaking changes table
docs/core/compatibility/toc.yml	Added navigation entry for the new breaking change documentation

[rzikm]

LGTM, thanks!