A high-performance, cross-platform command-line utility for extracting and repacking LG official firmware files (.kdz). This tool is written in modern C++ and is designed for power users, developers, and researchers who need to inspect or modify LG device firmware.

LG's official firmware is distributed in a proprietary container format known as KDZ. Inside a KDZ file, the core operating system images are contained within a .dz archive, which itself is a container for compressed partition chunks. This tool provides a complete solution to deconstruct these files into their base components and, crucially, to rebuild them back into a valid KDZ file that can be flashed to a device.

The tool uses multi-threading to accelerate the computationally intensive tasks of compression and decompression, significantly speeding up the workflow.

• Full KDZ Support: Parses and builds KDZ format versions V1, V2, and V3.
• Firmware Extraction: Extracts all contents from a KDZ file, including:
  • The main .dz firmware archive.
  • Supporting DLLs and dylib files.
  • The SecurePartition block.
  • V3-specific metadata maps (suffix_map, sku_map, etc.).
• Partition Image Reconstruction: Reconstructs full partition images (e.g., system.img, boot.img) from compressed chunks within the .dz file, correctly handling sparse layouts.
• Firmware Repacking: Repacks an extracted directory—including any modified partition images—back into a single, flashable KDZ file with updated checksums.
• High Performance: Leverages a thread pool to perform parallel compression (zlib/zstd) and decompression, maximizing CPU usage for faster operation.
• Metadata Management: On extraction, generates a comprehensive metadata.json file that describes the entire structure of the original KDZ. This file is the blueprint for the repacking process.
• Cross-Platform: Built with CMake, allowing it to be compiled and run on Windows, macOS, and Linux.

The tool operates in two main modes: extract and repack.

1. Parse KDZ Header: The tool first reads the main KDZ header to identify its version (V1/V2/V3) and locate all primary components like the .dz archive and any accompanying .dll files.
2. Parse DZ & Secure Partition: It then parses the SecurePartition block and the main .dz header, verifying magic numbers and checksums to ensure file integrity.
3. Decompress in Parallel: The core task of decompression is parallelized. Each compressed data chunk from the .dz file is assigned to a worker thread.
4. Reconstruct Images: As chunks are decompressed, they are written to the correct sparse offset within their corresponding output image file (e.g., 0.boot.img). This reconstructs the original, full-sized partition images for all the partitions (e.g., boot, system, modem).
5. Extract Components: Ancillary files (.dll, .dylib, suffix_map.dat, etc.) are extracted into a components subdirectory.
6. Generate Metadata: Finally, all structural information—offsets, sizes, checksums, version info, partition layouts, and more—is saved to a human-readable metadata.json file.

1. Read Metadata: The repacking process is driven entirely by the metadata.json file from an extracted firmware directory.
2. Compress in Parallel: The tool reads the raw partition images (.img), slices them into chunks according to the metadata, and compresses each chunk in a worker thread.
3. Rebuild DZ Archive: It calculates new MD5 hashes for the compressed chunks and assembles them into a new .dz file in memory. A new main DZ header is generated with updated chunk_hdrs_hash, data_hash, and header_crc.
4. Rebuild Secure Partition: The SecurePartition block is rebuilt from the information stored in the metadata.
5. Assemble Final KDZ: The tool creates the final KDZ file. It writes the rebuilt .dz archive, the SecurePartition block, and the other components from the components directory at their original offsets.
6. Write Final Header: With all data in place, the final offsets and sizes are known. The tool constructs the definitive KDZ header (V1, V2, or V3) and writes it to the beginning of the file, completing the process.

To build this project, you will need:

• A C++17 compliant compiler (e.g., GCC, Clang, MSVC)
• CMake (version 3.15 or newer)
• Zlib library (development headers)
• Zstandard (zstd) library (development headers)

The project can be built using a standard C++ compiler and CMake. For example, under Linux distros, you can compile with a command like this:

mkdir build && cd build
cmake ..
make -j$(nproc)

The tool is operated via the command line with two main commands: extract and repack.

A tool to extract and repack LG KDZ firmware.
Usage: ./kdz-tool <command> [options]

Commands:
  extract    Extract a KDZ file to a folder.
  repack     Repack an extracted folder into a KDZ file.

General Options:
  -h, --help           Show this help message and exit.

This command parses a KDZ file and extracts its contents into a specified directory. If no directory is provided, it will only print the header information without writing any files.

Syntax:

./kdz-tool extract <kdz_file> [-d <path>] [--no-verify]

• <kdz_file>: Path to the input KDZ firmware file.
• -d, --dest <path>: The directory to extract files to.
• --no-verify: (Optional) Skip the full DZ data hash verification for a faster initial parse. Useful for quick inspection.

Example:

./kdz-tool extract G850UM20A_00_NAO_US_OP_0416.kdz -d G850_extracted

After extraction, the output directory will have the following structure:

G850_extracted/
├── 0.abl.img
├── 0.aop.img
├── 0.boot.img
├── ... (other partition images)
├── components/
│   ├── LGE_COMMON.dll
│   ├── LGE_VER.dll
│   ├── suffix_map.dat
│   └── ... (other components)
└── metadata.json

This command rebuilds a KDZ file from an extracted directory containing partition images, components, and a metadata.json file.

Syntax:

./kdz-tool repack <input_dir> <output_file>

• <input_dir>: Path to the directory containing extracted files and metadata.json.
• <output_file>: Path for the new output KDZ file to be created.

Example:

./kdz-tool repack G850_extracted my_custom_firmware.kdz

This project is licensed under the MIT License. See the LICENSE file for details.

This tool relies on several excellent open-source libraries:

• nlohmann/json: For easy and robust JSON parsing and serialization.
• zlib: For handling zlib compression.
• Zstandard (zstd): For handling zstd compression.
• The MD5 implementation is based on the work of bzflag, available at www.zedwood.com.

Total Size: 1304 Bytes

V1 Record Structure (V1_RECORD_FMT) Size: 264 Bytes

Total Size: 1320 Bytes

V2/V3 Record Structure (V2_RECORD_FMT) Size: 272 Bytes

Total Size: 1320 Bytes

Total Size: 82448 Bytes, Fixed Offset: 1320

Size: 528 Bytes

Size: 80 Bytes

Total Size: 512 Bytes

Total Size: 124 Bytes

Total Size: 512 Bytes

• All multi-byte integer types (such as short, int, long) are stored in Little-endian format.
• All size units are in Bytes.