Document .NET 11 breaking change: TarReader validates checksums

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
 

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 <xref:System.Formats.Tar.TarReader> class now validates the checksum of TAR archive entries during the reading process. If an entry's checksum is invalid, `TarReader` throws an <xref:System.IO.InvalidDataException>. 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 <xref:System.IO.InvalidDataException> 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 <xref:System.IO.InvalidDataException> 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
+
+- <xref:System.Formats.Tar.TarReader.GetNextEntry(System.Boolean)?displayProperty=fullName>
+- <xref:System.Formats.Tar.TarReader.GetNextEntryAsync(System.Boolean,System.Threading.CancellationToken)?displayProperty=fullName>
+- <xref:System.Formats.Tar.TarFile.ExtractToDirectory(System.IO.Stream,System.String,System.Boolean)?displayProperty=fullName>
+- <xref:System.Formats.Tar.TarFile.ExtractToDirectoryAsync(System.IO.Stream,System.String,System.Boolean,System.Threading.CancellationToken)?displayProperty=fullName>

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