[Breaking change]: Tar reading APIs verify header checksums when reading

[rzikm]

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.