astral-tokio-tar

[!WARNING]

This library is in the process of being deprecated. We encourage external users of it to migrate away from it since non-security enhancements and bugfixes are unlikely to be prioritized. For (the majority of) users who need strict tar encoding and decoding, we recommend astral-codec as a potential alternative.

A tokio-based tar archive reader and writer.

Provenance

This crate is a fork of edera-dev/tokio-tar, which was a fork of vorot93/tokio-tar, which was a fork of dignifiedquire/async-tar, which is based on alexcrichton/tar-rs.

As compared to the async tar crates, this crate includes a variety of performance improvements and missing patches from alexcrichton/tar-rs.

As compared to alexcrichton/tar-rs, this crate features the following modifications:

• Setting preserve_permissions to false will avoid setting any permissions on extracted files. In alexcrichton/tar-rs, setting preserve_permissions to false will still set read, write, and execute permissions on extracted files, but will avoid setting extended permissions (e.g., setuid, setgid, and sticky bits).
• Setting allow_external_symlinks to false will avoid extracting symlinks that point outside the unpack target. Operations that write outside the unpack directory are always denied; but by default, symlinks that read outside the unpack directory are allowed.

See the changelog for a more detailed list of changes.

Security Considerations

Securely extracting an arbitrary (potentially malicious) archive to disk requires understanding the properties of the host OS and filesystem. Failing to account for how different OSes and filesystems process byte sequences in paths may allow an attacker to bypass application-level path filters by exploiting behaviors like:

• Unicode normalization: some OSes (like macOS) use Unicode's NFD normalization form for path handling, meaning that distinct byte sequences within an archive can normalize to the same path on disk.
• Case folding: Some filesystems are case-insensitive or case-preseving, meaning that entries whose paths only vary by case may result in the same path on disk. For example, both APFS (macOS) and NTFS (Windows) exhibit case-insensitive/preserving behavior.
• Path equivalence: Other OS- or filesystem-specific rules that treat distinct byte sequences as the same file.

License

This project is licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.