firmware_digest Namespace Reference

Classes
class	ImageError

Functions
dict	_parse_image (bytes data)
tuple[bytes, dict]	image_digest (str|os.PathLike path)
str	_git (*str args, str|None cwd=None)
dict	_record (str path, bytes digest, dict info, str board, str pio_env)
int	main ()

Variables
int	IMAGE_MAGIC = 0xE9
int	HEADER_LEN = 24
int	SEGMENT_HEADER_LEN = 8
int	HASH_LEN = 32

Detailed Description

The digest a board reports for its own firmware, read out of a built image.

An ESP32 app image built with a hash appended carries its SHA-256 as the last
32 bytes of the image. `esp_partition_get_sha256()` -- what `firmware_hash.h`
calls, and so what every board puts in its BoardHeartbeatPacket -- returns
*those bytes*, after recomputing them once to check they are right. It does not
hash the file. So the value to compare a board against is the appended digest,
NOT `sha256(firmware.bin)`: hashing the whole file folds the digest into its own
input and can never match a board. See FIRMWARE_HASH_VERIFICATION.md.

Usage:
    firmware_digest.py <firmware.bin>
    firmware_digest.py <firmware.bin> --verbose
    firmware_digest.py <firmware.bin> --record --board PT_Hotfire --env <pio env>

Function Documentation

_git()

str firmware_digest._git ( *str args, str | None cwd = None )

protected

Definition at line 106 of file firmware_digest.py.

Referenced by _record().

_parse_image()

dict firmware_digest._parse_image ( bytes data )

protected

Walk the image the way the ROM loader does, to find where it really ends.

We do not trust the file's length: a .bin can carry padding past the end of
the image, and then the appended digest is not the last 32 bytes of the file.

Definition at line 39 of file firmware_digest.py.

Referenced by image_digest().

_record()

dict firmware_digest._record ( str path, bytes digest, dict info, str board, str pio_env )

protected

Definition at line 110 of file firmware_digest.py.

References _git().

Referenced by main().

image_digest()

tuple[bytes, dict] firmware_digest.image_digest

(

str | os.PathLike

path

)

Return (digest, info) -- the 32 bytes a board running this image reports.

Definition at line 79 of file firmware_digest.py.

References _parse_image().

Referenced by main().

main()

int firmware_digest.main

(

void

)

Definition at line 157 of file firmware_digest.py.

References _record(), image_digest(), and main().

Variable Documentation

HASH_LEN

int firmware_digest.HASH_LEN = 32

Definition at line 32 of file firmware_digest.py.

HEADER_LEN

int firmware_digest.HEADER_LEN = 24

Definition at line 30 of file firmware_digest.py.

IMAGE_MAGIC

int firmware_digest.IMAGE_MAGIC = 0xE9

Definition at line 29 of file firmware_digest.py.

SEGMENT_HEADER_LEN

int firmware_digest.SEGMENT_HEADER_LEN = 8

Definition at line 31 of file firmware_digest.py.