GeneralZip
Namespace: GeneralZip, GeneralZip.Abstractions | Main Entry Points: GeneralZip.CompressAsync / ExtractAsync, GeneralZipReader, GeneralZipWriter | NuGet Package: GeneralZip
1. Component Overview
1.1 Introduction
GeneralZip is a cross-format, encryption-capable (including Chinese national crypto), event-driven compression library for .NET. It covers a dozen-plus common archive/compression formats — ZIP, 7z, RAR, TAR, GZ, BZ2, XZ, Zstd, LZ4, Brotli, CPIO, ISO9660, and CAB — with one unified API, detecting formats automatically by magic bytes when opening an archive. The whole compress/extract pipeline is event-driven (progress, interactive password prompts, overwrite decisions, error policies), every API accepts a CancellationToken, and parallel compress/extract, stream-to-stream operations, and IAsyncEnumerable entry enumeration are supported. For encryption, it ships with WinZip AES (universal interoperability), SM4-GM (Chinese national crypto, implemented as a documented custom ZIP extension), and the SM2-GM national-crypto envelope (public-key sealing, no shared password), switchable via a single EncryptionAlgorithm switch. The core package has zero third-party NuGet dependencies: the SM3/SM4/SM2 cryptographic primitives and the TAR/CPIO containers are pure C# implementations locked by GB/T standard test vectors, while 7z/bzip2/xz/zstd/lz4/brotli come from an optional Rust native core that degrades gracefully when missing.
One-line Append / Remove / Convert, stream-to-stream overloads, parallel compress/extract, glob entry filters, ZIP extended compression methods (BZip2/Zstd/LZMA), SM2-GM envelope encryption, a pluggable KDF registry, split-volume ZIP, Unix attributes/symlinks, the CPIO/ISO9660/CAB/Brotli formats, and the gz command-line tool — see the release log for the full list.
Core Capabilities:
| Capability | Description |
|---|---|
| One API, Many Formats | All formats map to the unified entry model IArchiveEntry; facade, reader, and writer behave identically across formats — learn once, use everywhere |
| Magic-Byte Detection | Formats are identified by file header signatures first, with extension fallback; content that disagrees with the extension still opens correctly |
| Encryption & National Crypto | WinZip AES-128/256 (AE-2, interoperable with WinZip/7-Zip/Windows Explorer) + SM4-GM (SM4-CTR + SM3-HMAC, documented container spec); legacy ZipCrypto is readable |
| Event-Driven | Entry lifecycle, per-entry and overall progress, interactive password prompts (PasswordRequired), overwrite queries (OverwriteQuery), error reports (ErrorReport) |
| Cancellation & Progress | Every API accepts a CancellationToken; dual progress channels (events and IProgress<ArchiveProgress>) with percentage, throughput, and ETA |
| Safe Extraction | Rejects absolute paths and path-traversal entries; wrong passwords fail fast via verifier bytes (constant-time comparison), never silently producing corrupt data |
| Zero Third-Party Dependencies | No third-party NuGet packages beyond Microsoft-maintained ones; SM3/SM4/TAR/CRC32 are pure C# implementations locked by GB/T 32905-2016 / GB/T 32907-2016 vectors |
| Graceful Degradation | When the Rust native core is missing, ZIP/TAR/TAR.GZ/GZ (fully managed) and all ZIP-family encryption keep working; only 7z/RAR and native codecs become unavailable |
| Open Extension | Dual extension points — format registry (IArchiveFormat) and encryption registry (IEncryptionProvider) — custom formats/algorithms register in one line |
Business Problems Solved:
- Applications receive archives from many sources (zip / tar.gz / 7z / rar / gz …); pulling in a dedicated library per format fragments APIs and bloats dependencies
- Regulated industries (government, finance) require archiving with the Chinese national SM4 algorithm, which mainstream compression libraries do not provide
- End-user applications need progress bars, password prompts, overwrite confirmation, and failure retry — yet most libraries only expose two functions: compress and extract
- Handling archives from untrusted sources requires protection against path traversal and other extraction attacks
- Third-party compression dependencies create security-audit and upgrade burden
GeneralZip is a general-purpose compression component independent of GeneralUpdate within the GeneralLibrary family: it knows nothing about version numbers, update strategies, or server protocols — it only packs and unpacks. Patch-package generation, data backup, log archiving, and encrypted exports can all reuse its unified API and encryption capabilities directly.
Business Use Cases:
- File backup and archiving for desktop/server applications (ZIP / TAR.GZ)
- Generating and unpacking update patch packages and data export packages
- Encrypted archiving for national-crypto compliance scenarios (SM4-GM)
- Single-file compression for logs and data (GZ / XZ / ZSTD / LZ4)
- Format detection, integrity verification, and safe extraction of externally sourced archives
- Backend support for interactive extraction UIs (password prompts, overwrite confirmation, error retry)
1.2 Environment & Dependencies
| Item | Description |
|---|---|
| Version | 2.0.0 |
| Target Frameworks | netstandard2.0, net8.0 (netstandard2.0 supports .NET Framework 4.6.1+ / .NET Core 2.0+ / .NET 5+) |
| NuGet Dependencies | Only Microsoft-maintained packages: Microsoft.Bcl.AsyncInterfaces, System.Text.Json (both netstandard2.0 only); zero third-party NuGet dependencies in the core package |
| Native Core | Bundled Rust cdylib generalzip_native (provides 7z / RAR / BZ2 / XZ / ZSTD / LZ4 / Brotli); the NuGet package ships prebuilt binaries for win-x64, linux-x64, linux-musl-x64, linux-arm64, win-arm64, win-x86, osx-x64, osx-arm64 |
| Degradation Policy | Without the native core, 7z/RAR and native codecs are unavailable; everything else (ZIP/TAR/TAR.GZ/CPIO/GZ + all ZIP-family encryption) is unaffected |
| License | MIT |
2. Feature List
| Feature | Description | Type | Required | Notes & Constraints |
|---|---|---|---|---|
| One-Line Compression | Directory or single file → archive; extension picks the format | Basic | Recommended | CompressAsync; every API cancellable |
| One-Line Extraction | Archive → directory, returns a result summary | Basic | Recommended | ExtractAsync, returns ArchiveResult |
| Format Detection | Magic bytes first, extension fallback | Basic | Optional | DetectFormat, returns null when unrecognized |
| Streaming Write | Add files/directories/streams entry by entry, Finish to finalize | Basic | Optional | GeneralZipWriter; Dispose finalizes automatically |
| Streaming Read | Entry enumeration, lazy decompression streams, single-entry extraction | Basic | Optional | GeneralZipReader.OpenEntryStream |
| Integrity Testing | CRC/HMAC/structure verification without touching disk | Basic | Optional | Test / TestAll |
| Encrypted Write | WinZip AES-128/256, SM4-GM (ZIP container) | Advanced | Optional | EncryptionAlgorithm + Password |
| Encrypted Read | ZipCrypto / WinZip AES / SM4-GM / 7z AES-256 / RAR | Advanced | Optional | Password preset or event-driven |
| Progress Reporting | Dual channel (events + IProgress<T>) with throughput and ETA | Advanced | Optional | Per-entry, roughly every 64 KB |
| Interactive Policies | Password prompts, overwrite decisions (5), error policies (3) | Advanced | Optional | OverwritePolicy / ErrorPolicy |
| Safe Extraction | Rejects absolute-path and path-traversal entries | Basic | Automatic | Recorded in ArchiveResult.Failures |
| Custom Formats | Implement IArchiveFormat and register | Advanced | Optional | GeneralZip.Registry.Register |
| Custom Encryption | Implement IEncryptionProvider and register | Advanced | Optional | GeneralZip.Encryption.Register |
| Native Formats | 7z (LZMA2, read/write + AES-256), RAR4/RAR5 (read-only) | Advanced | Optional | Requires the Rust native core |
| Native Codecs | BZ2 / XZ / ZSTD / LZ4 / Brotli, TAR.BZ2 | Advanced | Optional | Requires the Rust native core; callback-streaming transcode, zero temp files |
| One-Line Append/Remove/Convert | Append entries to an existing archive, delete entries by name/predicate, cross-format conversion | Advanced | Optional | Append / Remove / Convert, read→rewrite semantics |
| Stream-to-Stream Operations | Stream→Stream compress/extract/test without touching disk | Advanced | Optional | Compress / Extract / Test stream overloads |
| Parallel Compress/Extract | Entry-level parallelism: staged fragments on write, per-worker reopen on read | Advanced | Optional | MaxDegreeOfParallelism, default 1 (serial) |
| Glob Entry Filters | ** cross-layer matching and character classes, include/exclude | Advanced | Optional | IncludePatterns / ExcludePatterns |
| Split-Volume ZIP | Split into .001/.002/… by byte cap; opening .001 auto-concatenates | Advanced | Optional | ArchiveWriteOptions.VolumeSize |
| Unix Attributes/Symlinks | Unix mode read/write, symlink writing (skipped by default) | Advanced | Optional | IUnixEntry / SymlinkPolicy / PreserveUnixAttributes |
| Command-Line Tool | gz dotnet global tool: a/x/t/l/c/rm/i/detect/keygen | Advanced | Optional | GeneralZip.Cli |
Format & Encryption Matrix
| Format | Read | Write | Encrypted Read | Encrypted Write | Implementation |
|---|---|---|---|---|---|
| ZIP (Store/Deflate/BZip2/Zstd/LZMA/Zip64) | ✓ | ✓ | ZipCrypto / WinZip AES / SM4-GM / SM2-GM | ✓ | In-house engine (pure C#) |
| 7z (LZMA2) | ✓ | ✓ | AES-256 | AES-256 | Rust native core |
| RAR4/RAR5 | ✓ | — (proprietary) | ✓ password | — | Rust native core |
| TAR / TAR.GZ | ✓ | ✓ | — | — | In-house ustar + .NET GZipStream |
| TAR.BZ2 | ✓ | ✓ | — | — | In-house ustar + native core |
| GZ (.gz/.gzip) | ✓ | ✓ | — | — | .NET built-in GZipStream |
| BZ2 / XZ / ZSTD / LZ4 / Brotli | ✓ | ✓ | — | — | Rust native core (callback streaming, zero temp files) |
| CPIO (newc/odc/binary) | ✓ | ✓ (newc) | — | — | In-house container (pure C#) |
| ISO9660 (+Joliet/Rock Ridge) | ✓ | — (read-only) | — | — | In-house engine (pure C#) |
| CAB | ✓ (NONE-stored) | — (read-only) | — | — | In-house engine (pure C#) |
Why some cells are "—":
- RAR cannot be written — the RAR compression algorithm is proprietary to RARLAB, and the public unrar license explicitly forbids using it to implement a compressor. Reading (including password decryption) is fully supported via the native core.
- TAR / GZ / BZ2 / XZ / ZSTD / LZ4 / Brotli / CPIO have no encryption column — these format specifications have no encryption mechanism at all: there is nowhere to store KDF parameters, IVs, or authentication tags. When encryption is needed, encrypt-then-compress at the application layer, or switch to ZIP + WinZip AES / SM4-GM / SM2-GM.
- ISO9660 / CAB are read-only — write support is not implemented; only NONE-stored CAB folders are readable (MSZIP/LZX compressed folders are explicitly unsupported).
- SM4-GM is ZIP-only by design — ZIP's extra field mechanism naturally supports third-party extensions, and the container binary spec is fully documented in docs/CRYPTO-SPEC.md. Injecting custom encryption into a standardized container like 7z would produce archives no other tool can open.
- ZipCrypto writing is off by default — legacy 56-bit weak encryption, legacy-compatibility only; enable explicitly with
AllowWeakZipCrypto = true.
3. API Reference
3.1 Configuration Fields (Properties)
ArchiveWriteOptions (creating archives):
| Field | Type | Default | Required | Allowed Values | Description |
|---|---|---|---|---|---|
Level | CompressionLevelChoice | Optimal | No | NoCompression(0) / Fastest(1) / Optimal(2) / SmallestSize(3) | Compression level; on the ZIP write side SmallestSize maps to Deflate Optimal and NoCompression uses the Store method (no compression) |
EncryptionAlgorithm | string? | null (no encryption) | Required when encrypting | "ZipCrypto" / "WinZipAES128" / "WinZipAES256" / "SM4-GM" / custom AlgorithmId | Encryption algorithm identifier, resolved by name from the default encryption registry |
Password | string? | null | Required when EncryptionAlgorithm is set | — | Encryption password; obtain it from your secret store, never hard-code |
KdfIterations | int | 10_000 | No | Positive integer | KDF iteration count (algorithms that support custom KDFs, e.g. SM4-GM) |
EncryptionProvider | IEncryptionProvider? | null | No | — | Directly injects an encryption provider; takes priority over registry lookup by EncryptionAlgorithm |
EntryNameEncoding | Encoding | UTF-8 (no BOM) | No | — | Entry name encoding; the default value also sets the ZIP UTF-8 flag (0x0800) so Chinese names never garble |
ArchiveComment | string? | null | No | — | Archive-level comment (supported by some formats) |
DefaultLastWriteTime | DateTimeOffset? | null | No | — | Used when an entry provides no timestamp; null means current time |
Progress | IProgress<ArchiveProgress>? | null | No | — | Progress sink; usable in parallel with events |
ZipCompressionMethod | ZipCompressionMethodChoice | Auto (Deflate) | No | Auto(0) / Deflate(1) / BZip2(2) / Zstd(3) / Lzma(4) | ZIP entry compression method (ignored by other formats); extended methods interoperate with 7-Zip / Info-ZIP |
MaxDegreeOfParallelism | int | 1 (serial) | No | ≥1 | Entry-level parallel compression degree (staged fragments on write) |
VolumeSize | long | 0 (no split) | No | Bytes | Split-volume ZIP: split into .001/.002/… by cap; opening .001 auto-concatenates |
KdfAlgorithmId | string? | null (algorithm default) | No | KdfId from the registry | KDF provider switch (built-in SM3-PBKDF2 / PBKDF2-SHA256) |
RecipientPublicKey | string? | null | Required for SM2-GM encryption | hex public key (04||X||Y 130 chars, or X||Y 128 chars) | SM2-GM envelope recipient public key (passwordless write path) |
AllowWeakZipCrypto | bool | false | No | true / false | Whether writing ZipCrypto (weak legacy encryption) is allowed; must be enabled explicitly |
ArchiveOpenOptions (opening archives):
| Field | Type | Default | Required | Allowed Values | Description |
|---|---|---|---|---|---|
Password | string? | null | Required for encrypted archives | — | Preset password (effective for the first prompt only); invalidated when PasswordProvider is set |
PasswordProvider | IPasswordProvider? | null | No | — | Dynamic password supplier (prompts and other interactive scenarios); returning null means give up |
MaxPasswordAttempts | int | 3 | No | Positive integer | Max password attempts per entry/whole archive; exceeding throws |
EntryNameEncoding | Encoding? | null | No | — | Entry name encoding; when null the format decides (ZIP prefers the UTF-8 flag, otherwise falls back to IBM437) |
Progress | IProgress<ArchiveProgress>? | null | No | — | Progress sink |
SourceName | string? | null | No | — | Source file name; used by single-file codec formats to derive the entry name (filled automatically by the facade) |
ExtractionOptions (extracting):
| Field | Type | Default | Required | Allowed Values | Description |
|---|---|---|---|---|---|
OverwritePolicy | OverwritePolicy | Throw | No | Throw(0) / Overwrite(1) / Skip(2) / Ask(3) / Rename(4) | Policy when the target already exists; Ask raises the OverwriteQuery event |
ErrorPolicy | ErrorPolicy | Throw | No | Throw(0) / SkipAll(1) / RaiseEvent(2) | Per-entry error policy; RaiseEvent raises the ErrorReport event |
MaxRenameAttempts | int | 64 | No | Positive integer | Auto-rename limit (name (2).ext style); exceeding throws |
Filter | Predicate<IArchiveEntry>? | null | No | — | Extract only entries matching the predicate (directory entries excepted) |
Flatten | bool | false | No | true / false | Ignore entry paths, extract everything into the destination root |
PreserveTimestamps | bool | true | No | true / false | Write back file timestamps; disable in CI scenarios if desired |
PropagateEventExceptions | bool | false | No | true / false | Whether exceptions thrown by event handlers propagate; by default they are isolated and treated as Skip |
MaxRetryPerEntry | int | 3 | No | Positive integer | Upper limit on consecutive Retry decisions under the RaiseEvent policy |
BufferSize | int | 81920 | No | Positive integer | Per-entry copy buffer size (bytes) |
MaxDegreeOfParallelism | int | 1 (serial) | No | ≥1 | Entry-level parallel extraction degree (per-worker archive reopen) |
IncludePatterns | IReadOnlyList<string>? | null (all) | No | Glob patterns | Extract only entries matching any pattern (** cross-layer, character classes) |
ExcludePatterns | IReadOnlyList<string>? | null | No | Glob patterns | Skip entries matching any pattern (takes priority over include patterns) |
SymlinkPolicy | SymlinkPolicy | Skip | No | Enum | Symbolic-link entry handling policy (safe-by-default) |
PreserveUnixAttributes | bool | false | No | true / false | Preserve Unix mode bits on extraction (requires entries providing IUnixEntry) |
Event Response Enums:
| Enum Value | Numeric | Description |
|---|---|---|
OverwriteAction.Overwrite | 0 | Overwrite directly |
OverwriteAction.Skip | 1 | Skip the entry (default response) |
OverwriteAction.Rename | 2 | Auto-rename (name (2).ext) |
OverwriteAction.Abort | 3 | Abort the entire extraction (equivalent to cancel) |
ErrorAction.Retry | 0 | Retry the entry |
ErrorAction.Skip | 1 | Skip the entry (default response) |
ErrorAction.Abort | 2 | Abort the entire extraction |