Verify kernel archive integrity (apple#1703)

Closes apple#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 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.

Author: haoruilee

Package.swift

@@ -211,6 +211,7 @@ let package = Package(
             name: "ContainerAPIServiceTests",
             dependencies: [
                 .product(name: "Containerization", package: "containerization"),
+                "ContainerAPIService",
                 "ContainerResource",
                 "ContainerRuntimeLinuxClient",
                 "ContainerRuntimeClient",

Sources/ContainerCommands/System/Kernel/KernelSet.swift

@@ -47,18 +47,25 @@ extension Application {
         @Option(name: .customLong("tar"), help: "Filesystem path or remote URL to a tar archive containing a kernel file")
         var tarPath: String? = nil
 
+        @Option(name: .long, help: "Expected digest for the tar archive, for example sha256:<hex>. Required when --tar is a remote URL.")
+        var digest: String? = nil
+
         @OptionGroup
         public var logOptions: Flags.Logging
 
         public init() {}
 
         public func run() async throws {
-            let containerSystemConfig: ContainerSystemConfig = try await Application.loadContainerSystemConfig()
             if recommended {
+                let containerSystemConfig: ContainerSystemConfig = try await Application.loadContainerSystemConfig()
                 let url = containerSystemConfig.kernel.url
                 let path: String = containerSystemConfig.kernel.binaryPath
                 log.info("Installing the recommended kernel from \(url)...")
-                try await Self.downloadAndInstallWithProgressBar(tarRemoteURL: url, kernelFilePath: path, force: force)
+                try await Self.downloadAndInstallWithProgressBar(
+                    tarRemoteURL: url,
+                    kernelFilePath: path,
+                    expectedDigest: containerSystemConfig.kernel.digest,
+                    force: force)
                 return
             }
             guard tarPath != nil else {
@@ -68,6 +75,9 @@ extension Application {
         }
 
         private func setKernelFromBinary() async throws {
+            guard digest == nil else {
+                throw ArgumentParser.ValidationError("'--digest' can only be used with '--tar'")
+            }
             guard let binaryPath else {
                 throw ArgumentParser.ValidationError("missing argument '--binary'")
             }
@@ -84,16 +94,32 @@ extension Application {
                 throw ArgumentParser.ValidationError("missing argument '--tar")
             }
             let platform = try getSystemPlatform()
+            let remoteURL = URL(string: tarPath)
+            let remoteScheme = remoteURL?.scheme?.lowercased()
+            let isHTTPURL = remoteScheme == "http" || remoteScheme == "https"
             let localTarPath = URL(fileURLWithPath: tarPath, relativeTo: .currentDirectory()).path
             let fm = FileManager.default
-            if fm.fileExists(atPath: localTarPath) {
-                try await ClientKernel.installKernelFromTar(tarFile: localTarPath, kernelFilePath: binaryPath, platform: platform, force: force)
+            if !isHTTPURL && fm.fileExists(atPath: localTarPath) {
+                try await ClientKernel.installKernelFromTar(
+                    tarFile: localTarPath,
+                    kernelFilePath: binaryPath,
+                    platform: platform,
+                    expectedDigest: digest,
+                    force: force)
                 return
             }
-            guard let remoteURL = URL(string: tarPath) else {
+            guard let remoteURL else {
                 throw ContainerizationError(.invalidArgument, message: "invalid remote URL '\(tarPath)' for argument '--tar'. Missing protocol?")
             }
-            try await Self.downloadAndInstallWithProgressBar(tarRemoteURL: remoteURL, kernelFilePath: binaryPath, platform: platform, force: force)
+            guard let digest else {
+                throw ArgumentParser.ValidationError("'--digest' is required when '--tar' is a remote URL")
+            }
+            try await Self.downloadAndInstallWithProgressBar(
+                tarRemoteURL: remoteURL,
+                kernelFilePath: binaryPath,
+                platform: platform,
+                expectedDigest: digest,
+                force: force)
         }
 
         private func getSystemPlatform() throws -> SystemPlatform {
@@ -107,18 +133,29 @@ extension Application {
             }
         }
 
-        static func downloadAndInstallWithProgressBar(tarRemoteURL: URL, kernelFilePath: String, platform: SystemPlatform = .current, force: Bool) async throws {
+        static func downloadAndInstallWithProgressBar(
+            tarRemoteURL: URL,
+            kernelFilePath: String,
+            platform: SystemPlatform = .current,
+            expectedDigest: String,
+            force: Bool
+        ) async throws {
             let progressConfig = try ProgressConfig(
                 showTasks: true,
-                totalTasks: 2
+                totalTasks: 3
             )
             let progress = ProgressBar(config: progressConfig)
             defer {
                 progress.finish()
             }
             progress.start()
             try await ClientKernel.installKernelFromTar(
-                tarFile: tarRemoteURL.absoluteString, kernelFilePath: kernelFilePath, platform: platform, progressUpdate: progress.handler, force: force)
+                tarFile: tarRemoteURL.absoluteString,
+                kernelFilePath: kernelFilePath,
+                platform: platform,
+                progressUpdate: progress.handler,
+                expectedDigest: expectedDigest,
+                force: force)
             progress.finish()
         }
 

Sources/ContainerCommands/System/SystemStart.swift

@@ -157,7 +157,10 @@ extension Application {
             guard await !kernelExists() else {
                 return
             }
-            try await installDefaultKernel(kernelURL: containerSystemConfig.kernel.url, kernelBinaryPath: containerSystemConfig.kernel.binaryPath)
+            try await installDefaultKernel(
+                kernelURL: containerSystemConfig.kernel.url,
+                kernelBinaryPath: containerSystemConfig.kernel.binaryPath,
+                kernelDigest: containerSystemConfig.kernel.digest)
         }
 
         private func installInitialFilesystem(initImage: String) async throws {
@@ -171,7 +174,7 @@ extension Application {
             }
         }
 
-        private func installDefaultKernel(kernelURL: URL, kernelBinaryPath: String) async throws {
+        private func installDefaultKernel(kernelURL: URL, kernelBinaryPath: String, kernelDigest: String) async throws {
             var shouldInstallKernel = false
             if kernelInstall == nil {
                 print("No default kernel configured.")
@@ -191,7 +194,11 @@ extension Application {
                 return
             }
             log.info("Installing kernel...")
-            try await KernelSet.downloadAndInstallWithProgressBar(tarRemoteURL: kernelURL, kernelFilePath: kernelBinaryPath, force: true)
+            try await KernelSet.downloadAndInstallWithProgressBar(
+                tarRemoteURL: kernelURL,
+                kernelFilePath: kernelBinaryPath,
+                expectedDigest: kernelDigest,
+                force: true)
         }
 
         private func initImageExists(containerSystemConfig: ContainerSystemConfig) async -> Bool {

Sources/ContainerPersistence/ContainerSystemConfig.swift

@@ -168,35 +168,50 @@ final public class KernelConfig: Codable, Sendable {
     public static let defaultBinaryPath = "opt/kata/share/kata-containers/vmlinux-6.18.15-186"
     public static let defaultURL: URL =
         URL(string: "https://github.com/kata-containers/kata-containers/releases/download/3.28.0/kata-static-3.28.0-arm64.tar.zst")!
+    public static let defaultDigest = "sha256:f63d54507d1f18635d94475077e4c2330de4d8e05cedf25f7c38f063b0e66a91"
 
     private enum CodingKeys: String, CodingKey {
         case binaryPath
         case url
+        case digest
     }
 
     public let binaryPath: String
     public let url: URL
+    public let digest: String
 
-    public init(
-        binaryPath: String = defaultBinaryPath,
-        url: URL = defaultURL
-    ) {
+    public init(binaryPath: String = defaultBinaryPath, url: URL = defaultURL, digest: String = defaultDigest) {
         self.binaryPath = binaryPath
         self.url = url
+        self.digest = digest
     }
 
     public init(from decoder: any Decoder) throws {
         let container = try decoder.container(keyedBy: CodingKeys.self)
         self.binaryPath =
             try container.decodeIfPresent(String.self, forKey: .binaryPath)
             ?? Self.defaultBinaryPath
-        if let urlString = try container.decodeIfPresent(String.self, forKey: .url),
-            let parsed = URL(string: urlString)
-        {
+        if let urlString = try container.decodeIfPresent(String.self, forKey: .url) {
+            guard let parsed = URL(string: urlString) else {
+                throw DecodingError.dataCorruptedError(
+                    forKey: .url,
+                    in: container,
+                    debugDescription: "invalid kernel URL '\(urlString)'")
+            }
             self.url = parsed
         } else {
             self.url = Self.defaultURL
         }
+        if let digest = try container.decodeIfPresent(String.self, forKey: .digest) {
+            self.digest = digest
+        } else if self.url.absoluteString == Self.defaultURL.absoluteString {
+            self.digest = Self.defaultDigest
+        } else {
+            throw DecodingError.dataCorruptedError(
+                forKey: .digest,
+                in: container,
+                debugDescription: "kernel.digest is required when kernel.url is not the default URL")
+        }
     }
 
     // JSONEncoder special-cases URL to encode as absoluteString, but third-party
@@ -209,6 +224,7 @@ final public class KernelConfig: Codable, Sendable {
         var container = encoder.container(keyedBy: CodingKeys.self)
         try container.encode(binaryPath, forKey: .binaryPath)
         try container.encode(url.absoluteString, forKey: .url)
+        try container.encode(digest, forKey: .digest)
     }
 }
 

Sources/Services/ContainerAPIService/Client/ClientKernel.swift

@@ -42,15 +42,23 @@ extension ClientKernel {
         try await client.send(message)
     }
 
-    public static func installKernelFromTar(tarFile: String, kernelFilePath: String, platform: SystemPlatform, progressUpdate: ProgressUpdateHandler? = nil, force: Bool)
-        async throws
-    {
+    public static func installKernelFromTar(
+        tarFile: String,
+        kernelFilePath: String,
+        platform: SystemPlatform,
+        progressUpdate: ProgressUpdateHandler? = nil,
+        expectedDigest: String? = nil,
+        force: Bool
+    ) async throws {
         let client = newClient()
         let message = XPCMessage(route: .installKernel)
 
         message.set(key: .kernelTarURL, value: tarFile)
         message.set(key: .kernelFilePath, value: kernelFilePath)
         message.set(key: .kernelForce, value: force)
+        if let expectedDigest {
+            message.set(key: .kernelDigest, value: expectedDigest)
+        }
 
         let platformData = try JSONEncoder().encode(platform)
         message.set(key: .systemPlatform, value: platformData)

Sources/Services/ContainerAPIService/Client/XPC+.swift

@@ -112,6 +112,7 @@ public enum XPCKeys: String {
     case kernelFilePath
     case systemPlatform
     case kernelForce
+    case kernelDigest
 
     /// Init image reference
     case initImage

Sources/Services/ContainerAPIService/Server/Kernel/KernelHarness.swift

@@ -35,6 +35,7 @@ public struct KernelHarness: Sendable {
         let kernelFilePath = try message.kernelFilePath()
         let platform = try message.platform()
         let force = try message.kernelForce()
+        let expectedDigest = message.kernelDigest()
 
         guard let kernelTarUrl = try message.kernelTarURL() else {
             // We have been given a path to a kernel binary on disk
@@ -47,7 +48,12 @@ public struct KernelHarness: Sendable {
 
         let progressUpdateService = ProgressUpdateService(message: message)
         try await self.service.installKernelFrom(
-            tar: kernelTarUrl, kernelFilePath: kernelFilePath, platform: platform, progressUpdate: progressUpdateService?.handler, force: force)
+            tar: kernelTarUrl,
+            kernelFilePath: kernelFilePath,
+            platform: platform,
+            progressUpdate: progressUpdateService?.handler,
+            expectedDigest: expectedDigest,
+            force: force)
         return message.reply()
     }
 
@@ -85,13 +91,17 @@ extension XPCMessage {
         guard let kernelTarURLString = self.string(key: .kernelTarURL) else {
             return nil
         }
-        guard let k = URL(string: kernelTarURLString) else {
-            throw ContainerizationError(.invalidArgument, message: "cannot parse URL from \(kernelTarURLString)")
+        if let k = URL(string: kernelTarURLString), k.scheme != nil {
+            return k
         }
-        return k
+        return URL(fileURLWithPath: kernelTarURLString)
     }
 
     fileprivate func kernelForce() throws -> Bool {
         self.bool(key: .kernelForce)
     }
+
+    fileprivate func kernelDigest() -> String? {
+        self.string(key: .kernelDigest)
+    }
 }