# img4tool

> tihmstar's command-line tool and C++ library for Apple's IMG4 firmware container format. It prints the ASN.1 contents of IMG4 files, IM4P payload containers and IM4M signing manifests, including payload types, descriptions and key bags, and extracts IM4P or IM4M parts from IMG4 or SHSH files and payloads from IM4P files, decompressing LZSS or BVX2 (LZFSE) data and decrypting it when given an IV and key. It can also check an IM4M ticket or a signed IMG4 against a BuildManifest, convert IM4M files to SHSH, and build or rename containers for restore tooling.

- Type: Tool
- Targets: Firmware
- Category: Firmware tools
- Relationship: Foundation tool
- Sources reviewed: 2026-10-27
- Added to the catalog: 2026-11-03
- Original resource: <https://github.com/tihmstar/img4tool>
- Primary source: <https://github.com/tihmstar/img4tool/blob/bb2d63494c58993f5c8ce2ed7df207ab1063587b/README.md>
- Catalog page: <https://awesomerea.org/resources/img4tool/>
- Record JSON: <https://awesomerea.org/resources/img4tool/record.json>
- Chinese version: [简体中文](https://awesomerea.org/zh/resources/img4tool/index.md)

## Requirements & limits

- Latest release at review: build 218, published 2026-01-29, which provides the CI's macOS and Ubuntu buildroot archives rather than packaged installers. The reviewed master commit (merged 2026-08-20) is two commits ahead of it, merging a fix to the generator argument. The version number is the repository's commit count.
- Source builds use autoconf, automake, libtool and pkg-config with a C++11 compiler and require tihmstar's libgeneral. libplist-2.0 (for SHSH reading, verification and conversion) and a crypto backend (OpenSSL, or CommonCrypto on macOS) for decryption and payload hash checks are optional; without one, decryption fails and verification warns that it cannot check payload hashes. BVX2 support needs Apple's libcompression or liblzfse, and an optional libfwkeyfetch build adds a key-lookup option.
- Input files are the user's own IMG4, IM4P, IM4M or SHSH files and BuildManifests. The repository is source only and commits no Apple firmware, tickets or keys, and decrypting a payload requires an IV and key that the user supplies. The bundled LZSS decoder (lzssdec.c) is adapted, per its header, from Jonathan Levin's joker code.
- LGPL-3.0 license. Container creation, renaming and the IM4R generator option exist for restore workflows.

## Primary sources

1. <https://github.com/tihmstar/img4tool/blob/bb2d63494c58993f5c8ce2ed7df207ab1063587b/README.md>
2. <https://github.com/tihmstar/img4tool/blob/bb2d63494c58993f5c8ce2ed7df207ab1063587b/img4tool/main.cpp#L44-L199>
3. <https://github.com/tihmstar/img4tool/blob/bb2d63494c58993f5c8ce2ed7df207ab1063587b/img4tool/img4tool.cpp>
4. <https://github.com/tihmstar/img4tool/blob/bb2d63494c58993f5c8ce2ed7df207ab1063587b/img4tool/lzssdec.c#L1-L8>
5. <https://github.com/tihmstar/img4tool/blob/bb2d63494c58993f5c8ce2ed7df207ab1063587b/configure.ac>
6. <https://github.com/tihmstar/img4tool/blob/bb2d63494c58993f5c8ce2ed7df207ab1063587b/.github/workflows/main.yml>
7. <https://github.com/tihmstar/img4tool/blob/bb2d63494c58993f5c8ce2ed7df207ab1063587b/LICENSE>
8. <https://github.com/tihmstar/img4tool/releases/tag/218>

## More in Firmware and hardware

- [payload dumper](https://awesomerea.org/resources/payload-dumper/index.md) · Tool
- [PMCA-RE RELOADED](https://awesomerea.org/resources/pmca-re-reloaded/index.md) · Tool
- [ThisFirmwareDoesNotExist](https://awesomerea.org/resources/thisfirmwaredoesnotexist/index.md) · Tool
- [intel_ma](https://awesomerea.org/resources/intel-ma/index.md) · Tool
- [qemu-rtd2841](https://awesomerea.org/resources/qemu-rtd2841/index.md) · Tool
- [MS4X](https://awesomerea.org/resources/ms4x/index.md) · Tool

## About this entry

The description was reviewed against primary sources.
Original editorial content: MIT. Linked projects, papers and assets retain their own rights and licenses.