Verify kernel archive integrity by haoruilee · Pull Request #1703 · apple/container

haoruilee · 2026-06-12T06:05:58Z

Type of Change

Bug fix
New feature
Breaking change
Documentation update

Motivation and Context

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 on HTTPS and the release artifact remaining unchanged.

This change adds digest verification for kernel archives. The recommended/default kernel now has pinned digest metadata using an algorithm-prefixed value such as sha256:<hex>. container system kernel set --tar accepts --digest; remote tar URLs require it, and local tar archives can also be verified before unpacking and installation.

The system config also supports kernel.digest, and a custom kernel.url must provide a digest for that archive.

Testing

Tested locally
Added/updated tests
Added/updated docs

Validated locally:

git diff --check upstream/main...HEAD
swift test --filter KernelServiceTests
swift test --filter ConfigurationLoaderTests

kasc0206

审查意见 / Review

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

优点 / Strengths

End-to-end implementation: From CLI flag → config → XPC message → server-side verification, the full pipeline is covered
Backward compatible: sha256 is String? with default nil, so existing configs work unchanged
Smart defaults: Auto-populates the default SHA-256 when using the default kernel URL, while allowing custom values for custom URLs
No breaking API changes: All new parameters have sensible defaults
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 · 2026-06-14T23:04:16Z

Code Review Summary / 代码审查摘要

Strengths / 优点

End-to-end implementation: From CLI flag (--sha256) → Config (sha256 in TOML) → XPC message → server-side verification, the full pipeline is covered
端到端实现：从 CLI 参数到配置到 XPC 消息到服务端校验，完整链路覆盖
Backward compatible: sha256 is String? with default nil — existing configs work unchanged
向后兼容：sha256 为可选的 String? 类型，现有配置无需修改
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 可自行指定
No breaking API changes to callers: All new parameters have sensible defaults
无破坏性 API 变更：所有新参数都有合理的默认值
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 · 2026-06-29T22:11:40Z

@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 · 2026-06-29T23:54:05Z

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 · 2026-06-30T01:43:38Z

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 · 2026-06-30T09:22:28Z

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 · 2026-06-30T18:18:17Z

@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.

…rity # Conflicts: # Tests/CLITests/Subcommands/System/TestKernelSet.swift

haoruilee · 2026-07-01T07:05:27Z

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.

katiewasnothere · 2026-07-01T18:02:38Z

+|--------------|-----------|--------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
+| `binaryPath` | `String`  | `"opt/kata/share/kata-containers/vmlinux-6.18.15-186"`                                                 | Path **inside** the downloaded kernel archive that points to the kernel binary. |
+| `url`        | `URL`     | `"https://github.com/kata-containers/kata-containers/releases/download/3.28.0/kata-static-3.28.0-arm64.tar.zst"` | Archive to download when no kernel is installed. Encoded and decoded as a plain string in TOML. |
+| `digest`     | `String?` | `"sha256:f63d54507d1f18635d94475077e4c2330de4d8e05cedf25f7c38f063b0e66a91"`                             | Expected digest for the archive, for example `sha256:<hex>`. When unset for a custom URL, remote kernel downloads are not verified. |


I think we should require that a digest is provided

github-actions · 2026-07-01T18:45:03Z

Code Coverage

Tier	Line Coverage
Unit	23.42%
Integration	66.54%
Combined	75.48%

briansmith · 2026-07-02T16:01:07Z

    }

-    @Test func customKernelURLWithoutDigestLeavesDigestUnset() async throws {
+    @Test func customKernelURLWithoutDigestThrows() async throws {


How about a test where the digest doesn't match the file contents?

How about tests where:

The digest algorithm is "sha1" (should fail).

The digest algorithm is "sha256" and the digest is correct but truncated by one byte (should fail).

The digest algorithm is "sha256" but the digest value is a correct SHA-1 (should fail).

👍🏻 The archive content mismatch case is covered by installKernelFromLocalTarRejectsDigestMismatchWithoutInstalling, and I added coverage for sha1, truncated sha256, and a valid SHA-1 value passed as sha256.

katiewasnothere · 2026-07-02T18:17:48Z

-        binaryPath: String = defaultBinaryPath,
-        url: URL = defaultURL
-    ) {
+    public init(binaryPath: String = defaultBinaryPath) {


Why do we want this init?

Good point, the extra overload isn’t needed. I collapsed this into a single initializer with defaults for binaryPath, url, and digest.

katiewasnothere · 2026-07-02T18:18:20Z

+        self.digest = Self.defaultDigest
+    }
+
+    public init(binaryPath: String = defaultBinaryPath, url: URL, digest: String) {


url and digest should have their default values set here

katiewasnothere · 2026-07-02T18:25:09Z

+        let digestResult = try provider.value(forKey: AbsoluteConfigKey(ConfigKey("kernel.digest")), type: .string)
+        guard digestResult.value != nil else {
+            throw ContainerizationError(
+                .invalidArgument,
+                message: "kernel.digest is required in '\(path)' when kernel.url configures a custom archive"


We could check for this in the decoder instead of having a custom validation function. What do you think?

I think the decoder check is still useful, but not sufficient for the layered config case.

The rule I’m trying to enforce is: if a config layer overrides kernel.url with a non-default archive, that same layer must also provide the digest for that archive. The digest is tied to the archive contents, so it should not be inherited from another layer.

The decoder only sees the merged snapshot, so it can tell whether the final config has both kernel.url and kernel.digest, but it can’t tell which file each value came from. That means it would accept a custom URL from a higher precedence file paired with the default digest from a lower precedence file, which is the case this validation is meant to reject.

I kept this as a premerge loader validation and added a comment to make that layering requirement clearer.

The rule I’m trying to enforce is: if a config layer overrides kernel.url with a non-default archive, that same layer must also provide the digest for that archive.

In my opinion it doesn't matter if we get the kernel url and kernel digest from different layers in a layered config case. If the digest does not match the kernel url's contents when we go to fetch the kernel, the user will get an error. I could see having the values in separate layers being useful. Is there a specific scenario you want to prevent with this?

katiewasnothere · 2026-07-02T18:28:13Z

+        let fileIOThreadPool = NIOThreadPool(numberOfThreads: 1)
+        fileIOThreadPool.start()
+
+        let delegate = try HashingFileDownloadDelegate(


A follow up to this PR or future work could be to look into if we can do something similar to what is done for fetching image blobs here

Agreed, that seems worth exploring as follow up work. I’d keep it separate from this PR since this one is focused on kernel archive integrity.

katiewasnothere · 2026-07-07T17:19:29Z

        }
    }

+    static func verifyDigest(of file: URL, expected: String) throws {


Do we need this function when we have the one below on line 195?

Agreed. I removed the extra string overload and updated the tests.

katiewasnothere · 2026-07-08T22:52:07Z

+
+// Mirrors AsyncHTTPClient's file download delegate while updating an optional
+// SHA-256 hasher from the same response chunks that are written to disk.
+private final class HashingFileDownloadDelegate: @unchecked Sendable, HTTPClientResponseDelegate {


After talking with others, I think for now we should just remove this in favor of downloading the whole tar in the kernel service and then calling verifyDigest(of file: URL, expected: ExpectedDigest) to incrementally compute the hash like we do if there's a local tar. This will make this PR more scoped and we can optimize further later by looking into the suggestion here. After removing this part, I'm ready to approve.

katiewasnothere

LGTM! Thank you!

kasc0206 approved these changes Jun 14, 2026

View reviewed changes

jglogan requested a review from katiewasnothere June 15, 2026 17:16

haoruilee force-pushed the feat/kernelintegrity branch from d24095e to 76e26b9 Compare June 30, 2026 08:14

haoruilee changed the title ~~Verify kernel archive SHA-256 digests~~ Verify kernel archive integrity Jun 30, 2026

Verify kernel archive integrity

ea5cceb

haoruilee force-pushed the feat/kernelintegrity branch from 76e26b9 to ea5cceb Compare June 30, 2026 08:17

haoruilee added 2 commits July 1, 2026 13:50

Use digest for kernel archive verification

911c8fb

Merge remote-tracking branch 'upstream/main' into codex/pr-1703-integ…

82c788d

…rity # Conflicts: # Tests/CLITests/Subcommands/System/TestKernelSet.swift

katiewasnothere reviewed Jul 1, 2026

View reviewed changes

Require digest for remote kernel archives

04169a0

briansmith reviewed Jul 2, 2026

View reviewed changes

katiewasnothere reviewed Jul 2, 2026

View reviewed changes

Address kernel digest review feedback

0415795

katiewasnothere reviewed Jul 7, 2026

View reviewed changes

Address kernel digest review comments

8cc0875

katiewasnothere reviewed Jul 8, 2026

View reviewed changes

Simplify kernel archive verification

303e8cb

katiewasnothere approved these changes Jul 13, 2026

View reviewed changes

katiewasnothere merged commit 57b07fa into apple:main Jul 13, 2026
3 checks passed

Uh oh!

Conversation

haoruilee commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Type of Change

Motivation and Context

Testing

Uh oh!

kasc0206 left a comment

Choose a reason for hiding this comment

审查意见 / Review

优点 / Strengths

Suggestion

已验证 / Verified

Uh oh!

kasc0206 commented Jun 14, 2026

Code Review Summary / 代码审查摘要

Strengths / 优点

Suggestion / 建议

Verification / 验证

Uh oh!

katiewasnothere commented Jun 29, 2026

Uh oh!

briansmith commented Jun 29, 2026

Uh oh!

haoruilee commented Jun 30, 2026

Uh oh!

haoruilee commented Jun 30, 2026

Uh oh!

katiewasnothere commented Jun 30, 2026

Uh oh!

haoruilee commented Jul 1, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

katiewasnothere left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

haoruilee commented Jun 12, 2026 •

edited

Loading

github-actions Bot commented Jul 1, 2026 •

edited

Loading