.ITB File Format

FIT image: flattened image tree

Introduction

A FIT image (flattened image tree, .itb) is U-Boot’s newer way of packaging what it boots. It is a devicetree blob: the same header, memory reservation block, structure block and strings block, with the files themselves, the kernel, the devicetree, the RAM disk, as properties of nodes in the tree. Compared with the legacy uImage it holds several images in one file, can say which combination boots on which board, and carries stronger hashes and signatures. A FIT is made by mkimage from a source file (.its) that is itself devicetree source.

The property names and value lists on this page are from the FIT specification (the project that U-Boot’s own documentation of the format moved to, read through a page summary; the descriptions are in our own words).

The tree

  • The root node has description (optional), timestamp (mandatory: mkimage sets it) and #address-cells (when load or entry addresses are used).
  • /images (mandatory): one node for each image, with at least one.
  • /configurations (mandatory): a default property naming one configuration, and one node for each configuration.

Images

Each node of /images is one file. Its properties:

  • description, type, compression: mandatory.
  • arch (for standalone, kernel, firmware, ramdisk and devicetree images), os (kernel), load and entry (firmware and kernel): where they apply.
  • data: the bytes of the file, unless the data is external (below).
  • data-size, data-offset, data-position: external data. phase ("spl" or "u-boot") is optional.
  • sub-nodes hash-1, hash-2…, signature-1…, and a few others (dm-verity, logo, os-info).

The values of type are kernel, kernel_noload, ramdisk, flat_dt, script, firmware, standalone, filesystem, fpga, tee, multi and about thirty-five more named for chips and boot ROMs; compression is none, gzip, bzip2, lzma, lzo, lz4 or zstd; arch and os are lower-case names such as arm64, arm, riscv, x86_64 and linux, u-boot, efi. The viewer lists the full sets and reports a value that is not in them.

Hashes and signatures

A hash-N sub-node has algo and value: the digest of the image’s data. The sizes are crc32 4 bytes, md5 16, sha1 20, sha256 32, sha384 48 and sha512 64 (and crc16-ccitt, 2). The viewer works out crc32, md5, sha1, sha256, sha384 and sha512 over the data, compares, and says matches or does not match with the digest the data really gives. It does not verify crc16-ccitt, because the polynomial and start value are not in the source it read. A signature-N sub-node (algo such as sha256,rsa2048, key-name-hint, value) needs a public key to check, and the file does not contain one, so signatures are listed as not verified.

Configurations

A configuration node has description (mandatory) and names images: kernel (or firmware; one is mandatory), fdt, ramdisk, loadables (a list), script, fpga, and a compatible string list that a boot loader can match against a board. The viewer shows the table of configurations, marks the default, and reports a name that is not an image of /images and a default that is not a configuration.

External data

With mkimage -E the images’ data is not in the tree but after it, so that a loader can read the header, take totalsize bytes and fetch the images later. Each image then has data-offset (the offset from the end of the blob, which is rounded up to a multiple of 4) and data-size, or data-position (a fixed memory address, which is not in the file). The viewer follows data-offset and hashes the bytes there; for data-position the hash is not checked.

What the viewer shows

A .itb opens as a devicetree, with every node and property, plus the FIT tables: the images (name, type, architecture, OS, compression, load and entry addresses, size, and the result of each hash), the hashes, and the configurations. Each image’s data opens as the file it is: a kernel as an ARM64 Image or zImage by its magic, a gzip image as gzip, a flat_dt image as a devicetree. The mandatory properties above are checked. No real .itb was available for these pages: the checks were made on built images, with Node’s crypto and zlib as the second route for the hashes, and on a FIT compiled by dtc.

Not described

Known, not yet covered

  • Viewer: signatures are listed but not verified; the dm-verity, logo and os-info sub-nodes, shared image data and the phase property are shown as ordinary properties, not interpreted.
  • Viewer: the crc16-ccitt hash is not worked out.
  • Reference: the multi-step loading and boot process parts of the specification, and the security chapter.