ZEROPACK Specifications

Usage

# Pack
cargo run -- pack ./data output.zp

# Unpack
cargo run -- unpack output.zp ./extracted

# Pack with password
cargo run -- pack ./data output.zp --password secret123

# Unpack encrypted container
cargo run -- unpack output.zp ./extracted --password secret123

# List container files
cargo run -- list input.zp --password secret123

# Force list for large TOC containers
cargo run -- list input.zp --force

# Force unpack for large TOC containers
cargo run -- unpack input.zp ./extracted --force

Packing (pack/create)

• <input_dir>: Path to the directory to be packed.
• <output_file>: Path for the resulting container file.
• --password: Optional string to enable container encryption.

Unpacking (unpack/extract)

• <input_file>: Path to the ZEROPACK container.
• <output_dir>: Destination directory for extracted files.
• --password: Required if the container is encrypted.
• --filter: Extract only one directory or only some files from archive.
• --force: Bypass TOC size safety limit (256 MB).

Listing

View the contents of a container without extracting files to the disk.

cargo run -- list <input_file> [--password PASSWORD] [--filter PATTERN] [--force]

• --password: Required if the container is encrypted.
• --filter: Extract only one directory or only some files from archive.
• --force: Bypass TOC size safety limit (256 MB).

TOC Safety Limit

To defend against potential DoS attacks caused by malformed or intentionally bloated TOC sections, the default maximum TOC size limit is set to 256 MB.

Operations list, unpack (extract) will refuse to process containers exceeding this limit unless the --force flag is provided.

This protection is available since 11.2.3.

Container Structure

General

• MAGIC
• TOC_OFFSET (uint64 offset from file start to TOC)
• BINARY BLOBS (file data)
• TOC_LEN (32-bit unsigned integer specifying the size of the JSON TOC)
• TOC (JSON description of structure, offsets, and sizes)
• HASH: SHA-256 checksum of the TOC data for integrity verification

Encryption

• Argon2id key derivation
• HKDF-SHA256 derives 5 subkeys
• AES-256-GCM chunk encryption
• HMAC-SHA256

Files

Block types:

• "meta": contains JSON { uuid, original_name }
• "file": encrypted file content
• "tree": JSON describing directory structure and UUIDs

TOC (Table of Contents)

TOC describes hierarchy of each file by UUID:

{
  "version": 11.2.1,
  "salt": "<base64-salt>",
  "compression": <0-9>,
  "keys": {
    "<uuid>": {
      "name": "<encrypted-or-plain-filename>",
      "iv": "<base64-iv-if-encrypted>",
      "tag": "<base64-tag-if-encrypted>"
    }
  },
  "files": {
    "<uuid>": {
      "offset": <int>,
      "length": <int>
    }
  },
  "tree": { ...directory hierarchy with UUIDs... }
}