Verify kernel archive integrity

[haoruilee]

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Motivation and Context

Closes #1687

The default kernel archive is downloaded from a remote release URL during first-run setup and via container system kernel set --recommended. Previously, the archive contents were not verified after download, so integrity depended only on HTTPS and the release artifact remaining unchanged.

This change adds integrity verification for kernel archives. The recommended/default kernel now has pinned integrity metadata using an algorithm-prefixed value such as sha256-<hex>, and container system kernel set --tar accepts --integrity so custom local or remote tar archives can be verified before unpacking and installation.

Testing

• Tested locally
• Added/updated tests
• Added/updated docs

Validated on macOS:

• swift test --filter KernelServiceTests passed
• swift test --filter ConfigurationLoaderTests passed
• .build/debug/container system kernel set --help shows --integrity <integrity>
• .build/debug/container system kernel set --binary /tmp/nonexistent --integrity sha256-0000000000000000000000000000000000000000000000000000000000000000 rejects --integrity without --tar

[kasc0206]

审查意见 / Review

This is a well-crafted security improvement. The SHA-256 digest verification for kernel downloads is an important addition.

优点 / Strengths

1. End-to-end implementation: From CLI flag → config → XPC message → server-side verification, the full pipeline is covered
2. Backward compatible: sha256 is String? with default nil, so existing configs work unchanged
3. Smart defaults: Auto-populates the default SHA-256 when using the default kernel URL, while allowing custom values for custom URLs
4. No breaking API changes: All new parameters have sensible defaults
5. Proper error messaging: The --sha256 can only be used with --tar

Suggestion

• Consider adding a --sha256-verify flag with --sha256-verify=false to allow users to explicitly skip verification, rather than relying on nil meaning "no verification". But this is optional — current behavior is reasonable.

已验证 / Verified

• Code compiles with swift build ✅
• Follows existing project patterns (XPC keys, Config struct, ProgressBar)

Great contribution!

[kasc0206]

Code Review Summary / 代码审查摘要

Strengths / 优点

1. End-to-end implementation: From CLI flag (--sha256) → Config (sha256 in TOML) → XPC message → server-side verification, the full pipeline is covered
   端到端实现：从 CLI 参数到配置到 XPC 消息到服务端校验，完整链路覆盖
2. Backward compatible: sha256 is String? with default nil — existing configs work unchanged
   向后兼容：sha256 为可选的 String? 类型，现有配置无需修改
3. Smart defaults: Auto-populates the default SHA-256 when using the default kernel URL, while allowing custom values for custom URLs
   智能默认值：使用默认内核 URL 时自动填充默认 SHA-256，自定义 URL 可自行指定
4. No breaking API changes to callers: All new parameters have sensible defaults
   无破坏性 API 变更：所有新参数都有合理的默认值
5. CLI validation: --sha256 correctly rejected when used without --tar
   CLI 参数校验：--sha256 不带 --tar 时正确报错

Suggestion / 建议

Consider adding a --sha256-verify / --sha256-verify=false flag to let users explicitly skip verification. Currently, nil means "no verification", which is reasonable but implicit.
考虑增加 --sha256-verify 标志，让用户能显式关闭校验。当前 nil 表示"不校验"是合理的但较隐晦。

Verification / 验证

• Code compiles with swift build ✅
• Follows existing project patterns (XPC keys config, ProgressBar, Config struct)

Great contribution! / 优秀的贡献！

[katiewasnothere]

@haoruilee Thank you for the contribution! Could you add commit signatures to your commits? See https://github.com/apple/containerization/blob/main/CONTRIBUTING.md#pull-requests

We definitely want this change, but I think we should change the flags, config fields, and XPC key names to exclude the name of the algorithm so we can support other hashing algorithms in the future. Maybe we should call this just checksum instead? What do you think?

[briansmith]

Perhaps then the values should be prefixed with the digest algorithm.

Perhaps it is worth just copying Subresource Integrity syntax, using "integrity" instead of "checksum" and prefixing the digest algorithm name with a dash in the values, e.g. integrity: "sha256-f63d54507d1f18635d94475077e4c2330de4d8e05cedf25f7c38f063b0e66a91" instead of sha256 = "f63d54507d1f18635d94475077e4c2330de4d8e05cedf25f7c38f063b0e66a91" that the PR currently implements.

(Note that using a dash instead of colon prevents any ambiguity with content-addressible-by-digest URI schemes like sha256: that.)

[haoruilee]

Hi @katiewasnothere @briansmith ,

Thanks, that makes sense. I read these suggestions as complementary, the external names should avoid hard coding SHA-256, while the value itself should still carry the digest algorithm.

I’ll update the PR to archive this and add commit signatures and revise the tests and docs accordingly.

[haoruilee]

Hi @katiewasnothere

Updated, thanks for your suggestion. I renamed the API surface from sha256 to integrity, with values using sha256-<hex> syntax, and updated tests/docs/PR description accordingly.

Could you please take another look when you have a chance?

[katiewasnothere]

@haoruilee Thanks for the update! @briansmith this is a good suggestion, but naming the flag integrity and using a algorithm-hex format is inconsistent with other similar cases in this repo. Thinking about it some more, I think we should name the flag digest and use the format algorithm:hex.

[haoruilee]

Hi @katiewasnothere ,

Thanks, I’ve updated the PR to rename the flag field to digest and use the algorithm:hex format. Docs and tests are updated as well.