Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:TP-Link firmware header

From ReverseEngineering.wiki
Format
Magic 00 00 00 01 or 00 00 00 02, then "TP-LINK Technologies"
Extensions .bin
Endianness big
On this wiki Facts · Code · Notes · Topics

The 512-byte big-endian header (version 0x01000000 or 0x02000000, vendor string "TP-LINK Technologies", hardware id/revision, two MD5 fields, kernel/rootfs offsets) on classic TP-Link router images, plus the "safeloader" container of newer devices.

Classic header (mktplinkfw)

struct fw_header in OpenWrt firmware-utils mktplinkfw.c (lines 33-60) is 512 bytes and every field is written with htonl/htons, i.e. big-endian. The offsets below were computed from that struct.

Offset Size Field
0x00 4 version: 0x01000000 (v1) or 0x02000000 (v2) (lines 30-31)
0x04 24 vendor_name: default "TP-LINK Technologies", NUL padded
0x1C 36 fw_version: default "ver. 1.0"
0x40 4 hw_id
0x44 4 hw_rev
0x48 4 region_code
0x4C 16 md5sum1
0x5C 4 unk2
0x60 16 md5sum2
0x70 4 unk3
0x74 4 kernel_la: kernel load address
0x78 4 kernel_ep: entry point
0x7C 4 fw_length
0x80 4 kernel_ofs (the tool writes 0x200)
0x84 4 kernel_len
0x88 4 rootfs_ofs
0x8C 4 rootfs_len
0x90 4 boot_ofs
0x94 4 boot_len
0x98 2+2+2 ver_hi, ver_mid, ver_lo (the "x.y.z" firmware version)
0x9E 130 padding
0x120 32 + 32 region_str1, region_str2 ("00000000;XXXXXXXX;" and "XXXXXXXX" hex of the 4-char country name)
0x160 160 padding

In fill_header (lines 364-420) the header is zeroed, the kernel starts right after the header, and for a non-combined image (a flash-sized update) the layout table gives fw_length (the whole flash window, e.g. 0x3C0000 for 4M) and the rootfs offset (e.g. 0x100000 or 0x140000). binwalk recognises the header by the bytes 01 00 00 00 "TP-LINK Technologies" 00 00 00 00 "ver. 1.0" (src/signatures/tplink.rs line 9).

MD5 rule

md5sum1 is the MD5 of the whole image with the md5sum1 field first filled with a fixed 16-byte per-format salt; there are two salts, one for images without a boot loader part (boot_len 0) and one for images with it (lines 109-117 and 449-455, 418). A checker therefore copies the field out, writes the salt in, hashes the file and compares. The salt values are in the source and not reproduced here. Which fields v2 uses differently is not visible in this tool, which writes the same struct for both versions. Unverified: that md5sum2 and the unknown fields are zero in current images.

Parsing quirk

binwalk's parser starts at offset 0x40 and reads fields little-endian (src/structures/tplink.rs lines 14-71), while the writer above is big-endian, so the load address and entry point binwalk prints for these images should be byte-swapped before use. Unverified: check against a real image.

TP-Link RTOS headers (recognition)

binwalk also knows a 0x94-byte big-endian header with the ASCII "IMG0" (0x494D4730) at offset 20, a data_size at 24 (total size = data_size + 20), model number u16 at 28 and hardware revision major/minor bytes at 30 and 31 (src/structures/tplink.rs lines 84-115).

Safeloader images (newer devices)

tplink-safeloader.c (BSD-2-Clause) builds the container of TP-Link Pharos and many later routers (lines 130-157, 3778-3835):

Offset Content
0x00 image size (4 bytes big-endian, including this preamble)
0x04 16-byte MD5 of a fixed 16-byte salt followed by all bytes from 0x14 on (lines 185-196, 3778-3785)
0x14 vendor information length (4 bytes BE), then the vendor text, 0xFF padded to 0x1000 bytes
0x1014 image partition table, 0x800 bytes, 0xFF padded: lines like fwup-ptn <name> base 0x%05x size 0x%05x\t\r\n (lines 3747-3776)
0x1814 the partitions, back to back

The partitions include soft-version, support-list, os-image, file-system; the flash partition table of a device (the partition-table partition) starts with bytes 00 04 00 00 followed by lines partition <name> base 0x.. size 0x.. (lines 3584-3612). The support-list partition is a text starting SupportList: followed by one MODEL(VENDOR|REGION|...):hwrev line per accepted device, (sources use CRLF or LF per device, e.g. line 206). Unverified: that the on-device updater compares this list with the device's own model and hardware revision. Each meta partition starts with an 8-byte header (length BE, zero); soft-version holds a pad byte 0xFF, major/minor/patch, BCD year/month/day, a revision and optionally a compat level (lines 111-128, 3622-3664).

Other image variants are told apart by the bytes after the preamble (lines 4215-4250): the string fw-type:Cloud (payload at 0x1014 as above), ?NEW (payload at 0x1050), a leading length of at most 0x1000 (vendor type), or otherwise the default type. Recognising the fw-type: string, the fwup-ptn table and the SupportList: text is enough to find the kernel and rootfs partitions. Unverified: what an official firmware's encrypted or signed variants look like; this page does not cover them.

Sources

openwrt/firmware-utils src/mktplinkfw.c (GPL-2.0-only), src/tplink-safeloader.c (BSD-2-Clause); ReFirmLabs/binwalk (MIT). See Technique:Unpacking firmware update containers.

Code & repositories

  • https://github.com/openwrt/firmware-utils @ 0179ab1e367f756ac108a485f26585661d4c528c · license: GPL-2.0-or-later (declared by the contributor; GitHub's detector did not recognize a license file)
    Image-building tools for router firmware: trx.c, mkchkimg.c, mktplinkfw.c, tplink-safeloader.c, seama.c/seama.h; per-file licenses (GPL-2.0-or-later, GPL-2.0-only, BSD-2-Clause, BSD-3-Clause, LGPL-2.1-or-later)
    Tested on: source read, not run: source read, not built · checked 2026-10-19; last activity 2026-10-12
  • https://github.com/ReFirmLabs/binwalk @ 26713972e3f9f52dc37d4a421c4554b0bd9e82ef · license: MIT
    binwalk 3 (Rust): signature and header parsers for TRX, CHK, SEAMA, TP-Link and other firmware formats
    Tested on: source read, not run: source read, not built · checked 2026-10-19; last activity 2026-08-11