Hash calculation

Introduction

Most developers will be familiar with computing the hash of file data, using a well known hash function and key. For example when you run:

$ sha256sum /dev/null
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 /dev/null

then a standard hash algorithm and initial value (key) are applied across the file's data bytes, resulting in a 256-bit hash summary representation of the file contents.

For SWUPD's operation, we need to ensure not just the correctness of the data bytes, but also the file metadata. SWUPD cares about file user and group ownerships, permission modes, extended attributes, and the device ID when the file is a UNIX device special file (compare struct stat's st_rdev field (man fstatat) to SWUPD's struct update_stat).

The client application ships with a "hashdump" command that outputs a file's SWUPD hash. Based on the above, files that do not have the same SWUPD hash must either have different metadata or different data. In a shell, without SWUPD, you can compare metadata from two files with:

$ ls -alZ file1 file2

and you can compare their content using your preferred data hash helper:

$ sha256sum file1 file2

Note that a hash of all zero's (0000000...) in SWUPD has a special meaning: file has no hash. This can happen for a number of reasons, such as:

the file does not exist
the file is a deleted file in a Manifest
an internal error happened that caused the hash computation to fail

Technical details

SWUPD uses HMAC with SHA256 to calculate hashes, as follows.

Definitions

The update_stat struct is defined as:

struct update_stat {
	uint64_t st_mode;
	uint64_t st_uid;
	uint64_t st_gid;
	uint64_t st_rdev;
	uint64_t st_size;
};

All fields above are taken from a struct stat after calling lstat.