Files
alkane-os/ci/check-afw.py
T

559 lines
24 KiB
Python
Executable File

#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Verify an .afw OS install bundle before it can be published or installed.
The gate is deliberately strict and offline. It reads the tar itself instead of
trusting GNU tar, checks the fixed member order, rejects path traversal and
non-regular members, verifies every payload size and SHA-256 against the
manifest, checks the board/arch and bootloader policy, checks each image against
its partition ceiling, and refuses a signed bundle it cannot verify.
Exit codes: 0 pass, 1 failure, 2 usage error.
"""
import argparse
import hashlib
import json
from pathlib import Path
import sys
import afw_boards
BLOCK = 512
MAX_MANIFEST = 64 * 1024
MAX_ARCHIVE = 512 * 1024 * 1024
AM335X_MAP = {
"mtd0": (0x0000000, 0x20000, True, True, 0, None),
"mtd1": (0x0020000, 0x20000, True, True, 0, None),
"mtd2": (0x0040000, 0x20000, True, True, 0, None),
"mtd3": (0x0060000, 0x20000, True, True, 0, None),
"mtd4": (0x0080000, 0x1C0000, True, True, 0, None),
"mtd5": (0x0240000, 0x20000, True, True, 0, None),
"mtd6": (0x0260000, 0x20000, False, True, 2, "dtb"),
"mtd7": (0x0280000, 0x500000, False, True, 3, "kernel"),
"mtd8": (0x0800000, 0x1400000, False, True, 1, "rootfs"),
"mtd9": (0x1C00000, 0x200000, True, False, 0, None),
"mtd10": (0x1E00000, 0x200000, True, False, 0, None),
"mtd11": (0x2000000, 0x6000000, True, False, 0, None),
}
AM335X_HOLE = (0x780000, 0x80000)
AM335X_CHIP = 0x8000000
AM335X_TARGETS = {"kernel": "mtd7", "dtb": "mtd6", "rootfs": "mtd8"}
AM335X_FORMATS = {"kernel": "uimage", "dtb": "fdt", "rootfs": "uimage"}
AM335X_CEILINGS = {"kernel": 0x500000, "dtb": 0x20000, "rootfs": 0x1400000}
class AfwError(Exception):
pass
def fail(message):
raise AfwError(message)
def parse_octal(field, name):
text = field.split(b"\0", 1)[0].strip()
if not text:
return 0
if any(byte >= 0x80 for byte in text):
fail(f"{name}: base-256 tar numbers are not part of this format")
try:
return int(text, 8)
except ValueError:
fail(f"{name}: invalid octal field")
def safe_member_name(name):
if not name or len(name) > 255:
fail(f"unsafe member name length: {name!r}")
if name.startswith("/") or name.startswith("./"):
fail(f"absolute or ./-prefixed member is not allowed: {name!r}")
if "\\" in name or "\0" in name:
fail(f"member name contains a forbidden character: {name!r}")
parts = name.split("/")
if any(part in ("", ".", "..") for part in parts):
fail(f"path traversal or empty component in member name: {name!r}")
if any(ord(character) < 0x20 for character in name):
fail(f"control character in member name: {name!r}")
return name
def read_tar(path):
try:
size = path.stat().st_size
except OSError as error:
fail(f"cannot read {path}: {error}")
if size == 0 or size > MAX_ARCHIVE:
fail(f"archive size {size} is outside the accepted range")
if size % BLOCK:
fail(f"archive length {size} is not a multiple of {BLOCK} (truncated tar)")
data = path.read_bytes()
members = []
offset = 0
zero_blocks = 0
while offset < len(data):
block = data[offset : offset + BLOCK]
offset += BLOCK
if block == b"\0" * BLOCK:
zero_blocks += 1
if zero_blocks == 2:
break
continue
if zero_blocks:
fail("non-zero data appears between end-of-archive blocks")
if block[257:262] != b"ustar":
fail("member header is not POSIX ustar")
stored = parse_octal(block[148:156], "tar checksum")
header = bytearray(block)
header[148:156] = b" " * 8
if sum(header) != stored:
fail("tar header checksum mismatch")
name = block[0:100].split(b"\0", 1)[0].decode("utf-8", "strict")
prefix = block[345:500].split(b"\0", 1)[0].decode("utf-8", "strict")
if prefix:
name = f"{prefix}/{name}"
safe_member_name(name)
typeflag = block[156:157]
if typeflag not in (b"\0", b"0"):
fail(f"member {name!r} is not a regular file (typeflag {typeflag!r})")
length = parse_octal(block[124:136], f"size of {name}")
if length > MAX_ARCHIVE:
fail(f"member {name!r} is too large")
padded = (length + BLOCK - 1) // BLOCK * BLOCK
if offset + padded > len(data):
fail(f"member {name!r} runs past the end of the archive (truncated tar)")
payload = data[offset : offset + length]
offset += padded
members.append((name, payload))
if zero_blocks < 2:
fail("archive has no two-block end marker (truncated tar)")
if any(data[offset:]):
fail("non-zero trailing bytes after the end-of-archive marker")
if not members:
fail("archive has no members")
names = [name for name, _ in members]
if len(names) != len(set(names)):
fail("archive has duplicate member names")
return members
def require(condition, message):
if not condition:
fail(message)
def is_hex(value, length=64):
return (
isinstance(value, str)
and len(value) == length
and all(character in "0123456789abcdef" for character in value)
)
def check_format(manifest, image, payload, name):
fmt = image["format"]
if fmt == "fit":
require(payload.startswith(b"\xd0\x0d\xfe\xed"), f"{name} is not a FIT")
require(b"config@cv1835_miner_emmc" in payload, f"{name} has no default CV config")
require(b"signature@" not in payload, f"{name} carries signature@ nodes")
elif fmt == "fdt":
require(payload.startswith(b"\xd0\x0d\xfe\xed"), f"{name} is not an FDT")
elif fmt == "arm64-image":
require(len(payload) >= 64 and payload[0x38:0x3C] == b"ARMd", f"{name} is not an arm64 Image")
elif fmt == "cpio-gzip":
require(payload.startswith(b"\x1f\x8b"), f"{name} is not gzip-compressed")
elif fmt == "uimage":
require(payload.startswith(b"\x27\x05\x19\x56"), f"{name} is not a legacy uImage")
if manifest["board"] == "am335x":
require(len(payload) >= 64, f"{name} has no complete uImage header")
# ARM (2); kernel type 2, ramdisk type 3; gzip ramdisk.
require(payload[29] == 2, f"{name} is not an ARM uImage")
if image["name"] == "rootfs" or image["role"] == "rootfs":
require(payload[30] == 3, f"{name} must be a type-3 ramdisk uImage")
else:
require(payload[30] == 2, f"{name} must be a type-2 kernel uImage")
def verify_signature(manifest_bytes, manifest, signature_member, public_key):
signature = manifest.get("signature")
require(isinstance(signature, dict), "manifest signature is not an object")
kind = signature.get("type")
if kind == "unsigned":
require(signature_member is None, "unsigned manifest carries a signature member")
require(signature.get("member") is None, "unsigned manifest names a signature member")
return "unsigned"
require(kind == "ed25519", f"unsupported signature type {kind!r}")
require(signature.get("member") == "manifest.json.sig", "signature member name is wrong")
require(signature_member is not None, "ed25519 manifest has no signature member")
require(len(signature_member) == 64, "manifest.json.sig must be exactly 64 bytes")
key_hex = public_key or signature.get("public_key_hex")
require(is_hex(key_hex), "ed25519 manifest needs a 32-byte public key")
if public_key and signature.get("public_key_hex") not in (None, public_key):
fail("--public-key differs from the manifest public_key_hex")
try:
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
except ImportError:
fail("Ed25519 verification needs the Python cryptography package")
try:
Ed25519PublicKey.from_public_bytes(bytes.fromhex(key_hex)).verify(
signature_member, manifest_bytes
)
except InvalidSignature:
fail("manifest.json.sig does not verify against the public key")
return "ed25519"
def validate_am335x(manifest, images, partitions, install_images):
require(manifest["arch"] == "arm", "am335x must be arm")
require(
manifest["bootloader_policy"] == "preserve",
"am335x must preserve mtd0-5",
)
for image in images:
lowered = f"{image['name']} {image['file']}".lower()
require(
"spl" not in lowered and "u-boot" not in lowered and "uboot" not in lowered,
f"am335x bundle carries an spl/u-boot member: {image['file']!r}",
)
require(len(install_images) == 3, "am335x installs exactly kernel, dtb and rootfs")
require(
{image["name"] for image in install_images} == set(AM335X_TARGETS),
"am335x install images must be named kernel, dtb and rootfs",
)
for image in install_images:
name = image["name"]
require(
image["format"] == AM335X_FORMATS[name],
f"am335x {name} format must be {AM335X_FORMATS[name]}",
)
require(
image["partition"] == AM335X_TARGETS[name],
f"am335x {name} must target {AM335X_TARGETS[name]}",
)
require(
image["size"] <= AM335X_CEILINGS[name],
f"am335x {name} ({image['size']} B) exceeds the "
f"0x{AM335X_CEILINGS[name]:x}-byte mtd ceiling",
)
seen = {}
for partition in partitions:
name = partition["name"]
require(name in AM335X_MAP, f"unknown am335x partition {name!r}")
if name not in AM335X_MAP:
continue
seen[name] = partition
offset, size, secure, boot_critical, write_order, image_name = AM335X_MAP[name]
require(partition["offset"] == offset, f"am335x {name} offset must be 0x{offset:x}")
require(partition["size"] == size, f"am335x {name} size must be 0x{size:x}")
require(partition["secure"] is secure, f"am335x {name} secure flag is wrong")
require(
partition["boot_critical"] is boot_critical,
f"am335x {name} boot_critical flag is wrong",
)
require(
partition["write_order"] == write_order,
f"am335x {name} write_order must be {write_order}",
)
require(
partition.get("image") == image_name,
f"am335x {name} image must be {image_name!r}",
)
start = partition["offset"]
end = start + partition["size"]
hole_start, hole_size = AM335X_HOLE
require(
not (start < hole_start + hole_size and end > hole_start),
f"am335x {name} overlaps the 0x780000-0x800000 hole",
)
if name in {f"mtd{index}" for index in range(0, 6)}:
require(
partition["write_order"] == 0 and partition.get("image") is None,
f"am335x {name} is preserved and must not be written",
)
require(set(seen) == set(AM335X_MAP), "am335x manifest partition map is incomplete")
require(
seen["mtd7"]["offset"] + seen["mtd7"]["size"] == AM335X_HOLE[0],
"am335x mtd7 must end at the 0x780000 hole",
)
require(
seen["mtd8"]["offset"] == AM335X_HOLE[0] + AM335X_HOLE[1],
"am335x mtd8 must start at 0x800000 after the hole",
)
total = sum(part["size"] for part in partitions)
require(total == AM335X_CHIP - AM335X_HOLE[1], "am335x partition sizes must sum to 0x7F80000")
def validate(path, allow_unsigned=False, public_key=None, expect_board=None, plan_path=None):
members = read_tar(Path(path))
if members[0][0] != "manifest.json":
fail("first member must be manifest.json")
manifest_bytes = members[0][1]
if len(manifest_bytes) > MAX_MANIFEST:
fail(f"manifest.json is {len(manifest_bytes)} bytes, over the 64 KiB cap")
try:
manifest = json.loads(manifest_bytes)
except (ValueError, UnicodeDecodeError) as error:
fail(f"manifest.json is not valid JSON: {error}")
require(isinstance(manifest, dict), "manifest.json must be an object")
required = (
"schema",
"format",
"board",
"arch",
"version",
"build_date",
"sdk_revision",
"os_revision",
"payload_type",
"bootloader_policy",
"signature",
"partitions",
"images",
"boot_switch",
"preflight",
"recovery",
"marker",
"kernel_version",
)
for key in required:
require(key in manifest, f"manifest is missing {key!r}")
require(manifest["schema"] == 2, "only .afw schema 2 is accepted")
require(manifest["format"] == "afw", "manifest format is not afw")
require(manifest["payload_type"] == "os", "payload_type must be os")
board = manifest["board"]
require(afw_boards.known_board(board), f"unknown board family {board!r}")
profile = afw_boards.board(board)
require(manifest["arch"] == profile["arch"], f"board {board} must use {profile['arch']}")
require(
manifest["bootloader_policy"] == profile["bootloader_policy"],
f"board {board} requires bootloader_policy {profile['bootloader_policy']}",
)
require(
manifest["bootloader_policy"] in ("include", "preserve"),
"bootloader_policy must be include or preserve",
)
if expect_board is not None:
require(board == expect_board, f"bundle is for {board}, expected {expect_board}")
for field in ("sdk_revision", "os_revision"):
require(is_hex(manifest[field], 40), f"{field} must be a 40-character revision")
require(isinstance(manifest["version"], str) and manifest["version"], "version is empty")
require(isinstance(manifest["build_date"], str) and manifest["build_date"], "build_date is empty")
require(isinstance(manifest["marker"], str) and manifest["marker"], "marker is empty")
require(
isinstance(manifest["kernel_version"], str) and manifest["kernel_version"],
"kernel_version is empty",
)
for field in ("boot_switch", "preflight", "recovery"):
require(isinstance(manifest[field], dict), f"{field} must be an object")
images = manifest["images"]
partitions = manifest["partitions"]
require(isinstance(images, list) and images, "images must be a non-empty list")
require(isinstance(partitions, list) and partitions, "partitions must be a non-empty list")
image_names = set()
install_images = []
for image in images:
require(isinstance(image, dict), "image entry is not an object")
for key in ("name", "file", "role", "format", "size", "sha256", "install"):
require(key in image, f"image entry is missing {key!r}")
name = image["name"]
require(isinstance(name, str) and name and name not in image_names, f"duplicate image {name!r}")
image_names.add(name)
require(image["role"] in afw_boards.SAFE_IMAGE_ROLES, f"image {name} has an unknown role")
require(image["format"] in afw_boards.SAFE_IMAGE_FORMATS, f"image {name} has an unknown format")
require(isinstance(image["size"], int) and image["size"] > 0, f"image {name} has no size")
require(is_hex(image["sha256"]), f"image {name} has no sha256")
require(isinstance(image["install"], bool), f"image {name} install flag is not a bool")
safe_member_name(image["file"])
require(image["file"].startswith("payload/"), f"image {name} is outside payload/")
require(image["file"] not in ("payload/manifest.json",), f"image {name} reuses a reserved name")
if image["install"]:
require(image.get("partition"), f"installable image {name} has no partition")
install_images.append(image)
require(install_images, "bundle has no installable image")
partition_names = set()
for partition in partitions:
require(isinstance(partition, dict), "partition entry is not an object")
for key in ("name", "device", "offset", "size", "secure", "boot_critical", "write_order"):
require(key in partition, f"partition entry is missing {key!r}")
name = partition["name"]
require(isinstance(name, str) and name and name not in partition_names, f"duplicate partition {name!r}")
partition_names.add(name)
device = partition["device"]
require(isinstance(device, str) and device.startswith("/dev/"), f"partition {name} has a bad device")
require(isinstance(partition["size"], int) and partition["size"] > 0, f"partition {name} has no size")
require(partition["offset"] >= 0, f"partition {name} has a negative offset")
require(isinstance(partition["secure"], bool), f"partition {name} secure is not a bool")
require(isinstance(partition["boot_critical"], bool), f"partition {name} boot_critical is not a bool")
require(isinstance(partition["write_order"], int) and partition["write_order"] >= 0, f"partition {name} write_order")
if "boot0" in device:
require(partition["secure"], "boot0 must be declared secure")
require(partition["write_order"] == 0, "boot0 must not be in the write order")
require(partition.get("image") is None, "boot0 must not carry an install image")
image_name = partition.get("image")
if image_name is not None:
require(image_name in image_names, f"partition {name} names missing image {image_name!r}")
for image in images:
if image.get("partition") is None:
continue
matches = [item for item in partitions if item["name"] == image["partition"]]
require(len(matches) == 1, f"image {image['name']} names an unknown partition")
partition = matches[0]
require(not partition["secure"], f"image {image['name']} targets a secure partition")
require(
image["size"] <= partition["size"],
f"image {image['name']} ({image['size']} B) exceeds partition "
f"{partition['name']} ({partition['size']} B)",
)
if board == "am335x":
validate_am335x(manifest, images, partitions, install_images)
if board == "cv1835":
require(len(install_images) == 1 and install_images[0]["name"] == "p1", "cv1835 installs only p1")
p1 = install_images[0]
require(p1["format"] == "fit", "cv1835 p1 must be a FIT")
require(p1["size"] == 16 * 1024 * 1024, "cv1835 p1 must be the 16 MiB padded FIT")
p1_parts = [item for item in partitions if item["name"] == "p1"]
require(len(p1_parts) == 1, "cv1835 manifest must plan p1")
require(p1_parts[0]["size"] == 16 * 1024 * 1024, "cv1835 p1 partition must be 16 MiB")
require(p1_parts[0]["device"] == "/dev/mmcblk0p1", "cv1835 p1 device is wrong")
require(not p1_parts[0]["secure"], "cv1835 p1 must not be secure")
require(p1_parts[0]["write_order"] == 1, "cv1835 p1 must be written once")
if manifest["bootloader_policy"] == "preserve":
require(
not any(image["role"] == "bootloader" for image in images),
"bootloader_policy is preserve but the bundle carries a bootloader image",
)
else:
require(
any(image["role"] == "bootloader" for image in images),
"bootloader_policy is include but the bundle has no bootloader image",
)
signature = manifest["signature"]
require(isinstance(signature, dict), "signature must be an object")
kind = signature.get("type")
if kind == "unsigned":
if not allow_unsigned:
fail("bundle is unsigned; pass --allow-unsigned for bench-only use")
elif kind != "ed25519":
fail(f"unsupported signature type {kind!r}")
expected = [image["file"] for image in images]
signature_member = None
body = members[1:]
if signature.get("member") is not None:
require(len(body) >= 1 and body[0][0] == "manifest.json.sig", "signature member must be second")
signature_member = body[0][1]
body = body[1:]
verify_signature(manifest_bytes, manifest, signature_member, public_key)
actual = [name for name, _ in body]
require(actual == expected, "payload members are missing, extra, or out of manifest order")
for (name, payload), image in zip(body, images):
require(len(payload) == image["size"], f"size mismatch for {name}")
digest = hashlib.sha256(payload).hexdigest()
require(digest == image["sha256"], f"sha256 mismatch for {name}")
check_format(manifest, image, payload, name)
summary = {
"file": str(path),
"board": board,
"arch": manifest["arch"],
"version": manifest["version"],
"bootloader_policy": manifest["bootloader_policy"],
"signature": kind,
"marker": manifest["marker"],
"kernel_version": manifest["kernel_version"],
"members": [name for name, _ in members],
"payloads": [
{"name": image["name"], "file": image["file"], "size": image["size"], "sha256": image["sha256"]}
for image in images
],
"install": [
{
"image": image["name"],
"partition": image["partition"],
"size": image["size"],
}
for image in install_images
],
}
if plan_path:
plan = json.loads(Path(plan_path).read_text())
require(plan.get("board") == board, "plan board differs from manifest board")
require(plan.get("arch") == manifest["arch"], "plan arch differs from manifest arch")
require(
plan.get("bootloader_policy") == manifest["bootloader_policy"],
"plan bootloader policy differs from manifest",
)
plan_parts = {item["name"]: item for item in plan.get("partitions", [])}
for partition in partitions:
if partition["name"] not in plan_parts:
continue
require(
int(plan_parts[partition["name"]]["size"]) == partition["size"],
f"plan size for {partition['name']} differs from the manifest",
)
return summary
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("afw")
parser.add_argument("--allow-unsigned", action="store_true")
parser.add_argument("--public-key", help="Ed25519 public key hex, or a file containing it")
parser.add_argument("--expect-board")
parser.add_argument("--plan", help="plan JSON to cross-check")
parser.add_argument("--json", action="store_true")
parser.add_argument("--quiet", action="store_true")
args = parser.parse_args()
public_key = args.public_key
if public_key and len(public_key) != 64:
try:
public_key = Path(public_key).read_text().strip()
except OSError as error:
parser.error(f"cannot read public key: {error}")
try:
summary = validate(
Path(args.afw),
allow_unsigned=args.allow_unsigned,
public_key=public_key,
expect_board=args.expect_board,
plan_path=args.plan,
)
except AfwError as error:
print(f"afw: FAIL {args.afw}: {error}", file=sys.stderr)
return 1
except (OSError, ValueError) as error:
print(f"afw: FAIL {args.afw}: {error}", file=sys.stderr)
return 1
if args.json:
print(json.dumps(summary, indent=2))
elif not args.quiet:
print(f"afw: OK {args.afw}")
print(
f" board {summary['board']} arch {summary['arch']} version {summary['version']} "
f"bootloader {summary['bootloader_policy']} signature {summary['signature']}"
)
print(f" marker {summary['marker']} kernel {summary['kernel_version']}")
for item in summary["payloads"]:
print(f" payload {item['name']}: {item['size']} B sha256 {item['sha256']}")
for item in summary["install"]:
print(f" install {item['image']} -> {item['partition']} ({item['size']} B)")
return 0
if __name__ == "__main__":
sys.exit(main())