diff --git a/docs/core/compatibility/11.md b/docs/core/compatibility/11.md index 38e7062d947b6..272db2a37ed3a 100644 --- a/docs/core/compatibility/11.md +++ b/docs/core/compatibility/11.md @@ -20,6 +20,7 @@ If you're migrating an app to .NET 11, the breaking changes listed here might af |-------------------------------------------------------------------|-------------------| | [Environment.TickCount made consistent with Windows timeout behavior](core-libraries/11/environment-tickcount-windows-behavior.md) | Behavioral change | | [MemoryStream maximum capacity updated and exception behavior changed](core-libraries/11/memorystream-max-capacity.md) | Behavioral change | +| [TAR-reading APIs verify header checksums when reading](core-libraries/11/tar-checksum-validation.md) | Behavioral change | ## Globalization diff --git a/docs/core/compatibility/core-libraries/11/tar-checksum-validation.md b/docs/core/compatibility/core-libraries/11/tar-checksum-validation.md new file mode 100644 index 0000000000000..25fa13a4f0ab2 --- /dev/null +++ b/docs/core/compatibility/core-libraries/11/tar-checksum-validation.md @@ -0,0 +1,85 @@ +--- +title: "Breaking change: TAR-reading APIs verify header checksums when reading" +description: "Learn about the breaking change in .NET 11 where TarReader validates checksums and throws InvalidDataException for invalid entries." +ms.date: 01/09/2026 +ai-usage: ai-assisted +--- + +# TAR-reading APIs verify header checksums when reading + +The class now validates the checksum of TAR archive entries during the reading process. If an entry's checksum is invalid, `TarReader` throws an . This change improves data integrity by ensuring that corrupted or tampered TAR files are detected and flagged during processing. + +## Version introduced + +.NET 11 Preview 1 + +## Previous behavior + +Previously, when reading a TAR archive with an invalid checksum, `TarReader` ignored the checksum mismatch and continued processing the archive without throwing an exception. + +Example code: + +```csharp +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 + +Starting in .NET 11, when reading a TAR archive with an invalid checksum, `TarReader` throws an and stops processing the archive. The exception message indicates the checksum validation failure. + +## Type of breaking change + +This change is a [behavioral change](../../categories.md#behavioral-change). + +## Reason for change + +This change was introduced to improve the reliability and security of the `System.Formats.Tar` library. By validating checksums, `TarReader` can detect and prevent the use of corrupted or tampered TAR files, ensuring that only valid data is processed. For more information, see [dotnet/runtime#118577](https://github.com/dotnet/runtime/pull/118577) and [dotnet/runtime#117455](https://github.com/dotnet/runtime/issues/117455). + +## Recommended action + +If your application relies on the `TarReader` to process TAR archives: + +- Update your code to handle the that might be thrown when a checksum validation fails. +- 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. +- 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: + +```csharp +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. +} +``` + +## Affected APIs + +- +- +- +- diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 1286012e0f7ba..5329e18fe6a5b 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -14,6 +14,8 @@ items: href: core-libraries/11/environment-tickcount-windows-behavior.md - name: MemoryStream maximum capacity updated and exception behavior changed href: core-libraries/11/memorystream-max-capacity.md + - name: TAR-reading APIs verify header checksums when reading + href: core-libraries/11/tar-checksum-validation.md - name: Globalization items: - name: Japanese Calendar minimum supported date corrected