Upgrading archive 3 to 4
Breaking3.6.1 → 4.6.0Breaking13Security9Deprecated2New37Changed40Fixed123Other1
SecurityFixes symlink scopes for extractFileToDisk that could overwrite an existing file on disk outside the output dir.Advisory ↗
BreakingUpgrade verdict
13 breaking changes and 9 security fixes.
In plain terms
- Damaged archives now decode quietly by default instead of raising an error. You must ask for errors or checksum checks explicitly.
- Extraction helpers now skip damaged entries by default and only raise errors when you ask them to.
- Two checksum helper classes are gone, so code that used them will stop compiling.
- If your code calls decodeBuffer on a decoder, you now need to call decodeStream instead.
Must act Top 5 of 24 that need code or config changes
Dart SDK requirement changed in 4.0.0: ^3.0.0 → >=3.0.0 <4.0.0.
What you must change
Breaking13
All decoders and extraction helpers no longer throw on damaged data by default; use throwOnError and verify to opt in.
XZDecoderTarDecoderZipDecoderGZipDecoderZLibDecoderBZip2DecoderZstdDecoderextractFileToDiskextractFileToDisk accepts verify and throwOnError; extractArchiveToDisk and extractArchiveToDiskSync accept throwOnError, and damaged archives no longer throw by default.
extractFileToDiskextractArchiveToDiskextractArchiveToDiskSyncverifythrowOnErrorRemoves the Adler32 and Crc32 classes.
Adler32Crc32Renames decodeBuffer to decodeStream in the various decoder classes.
decodeBufferdecodeStreamRenames InputStream to InputMemoryStream.
InputStreamInputMemoryStreamRenames OutputStream to OutputMemoryStream.
OutputStreamOutputMemoryStreamAll decoders now honor verify: true instead of ignoring it, with documented gaps in dart:io based gzip and zlib decoders.
GZipDecoderZLibDecoderGZipDecoderWebZLibDecoderWebAdds writeRange and reserve to OutputStream and readInto and viewBytes to InputStream; implementers must add them.
OutputStream.writeRangeOutputStream.reserveInputStream.readIntoInputStream.viewBytesZip entry lastModTime is now seconds since epoch; the old DOS value moves to ArchiveFile.lastModDosTime.
lastModTimeArchiveFile.lastModDosTimeCompressionType gains lzma and xz values, so exhaustive switches over it need new cases.
CompressionTypeCompressionType.lzmaCompressionType.xzArchiveFile.lastModDateTime now returns a local DateTime from lastModTime in seconds since epoch, and ZipDecoder reads the UT extra field so ZipEncoder output round-trips across time zones.
ArchiveFile.lastModDateTimelastModTimeZipDecoderZipEncoderextractFileToDisk now calls callback for a zip entry after it is written, as it does for tar, instead of during central directory reading.
extractFileToDiskZipDirectory.read no longer reads every entry's local header; ZipFileHeader reads its file lazily.
ZipDirectory.readZipFileHeaderZipFileHeader.fileZipDecoderZipDirectorySecurity9
Fixes symlink scopes for extractFileToDisk that could overwrite an existing file on disk outside the output dir.
extractFileToDiskFixes XZDecoder hanging forever on a truncated .xz read from a file or decode stream, including .tar.xz in extractFileToDisk.
XZDecoderextractFileToDiskLimits tar long name and pax header entries to TarFile.maxMetadataSize (1 MB) to prevent huge memory use from small archives.
TarFile.maxMetadataSizeAdds maxOutputSize to decodeBytes and decodeStream on GZipDecoder, ZLibDecoder, BZip2Decoder and ZstdDecoder, and maxSize to extraction functions.
maxOutputSizedecodeBytesdecodeStreamGZipDecoderZLibDecoderBZip2DecoderZstdDecodermaxSizeZstdDecoder now checks content size as each block decodes and refuses blocks that overflow it, even past maxWindowSize.
ZstdDecodermaxWindowSizeXZDecoder limits the LZMA2 dictionary to maxDictionarySize (256 MB default), takes maxOutputSize, and no longer preallocates gigabytes from a tiny archive's index.
XZDecodermaxDictionarySizemaxOutputSizeExtraction creates symbolic links after all other entries and refuses links whose path runs through another link.
extractTarFiles now keeps entries inside the output directory and decodes as it reads instead of using a leftover temp file.
extractTarFilesextractFileToDiskFixes a zip64 compressed size overflow that could crash the decoder when reading an untrusted archive; sizes are now clamped to bytes present.
Deprecations to plan for
Deprecated2
Deprecates AesDecrypt in favor of the exported AesCtr; Sha1, HmacSha1, pbkdf2HmacSha1 and Sha256 are now exported.
AesDecryptAesCtrSha1HmacSha1pbkdf2HmacSha1Sha256Deprecates the ignored fileSize parameter of the FileBuffer read methods.
FileBufferfileSize