Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion Package.swift
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,9 @@ let package = Package(
resources: [.process("data/download-list-20220723.json"),
.process("data/download-list-20231115.json"),
.process("data/download-error.json"),
.process("data/download-unknown-error.json")
.process("data/download-unknown-error.json"),
.copy("data/apple-aea-certificate-chain.pem"),
.copy("data/self-signed-certificate-chain.pem")
],
swiftSettings: swiftSettings
)
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -407,7 +407,7 @@ xcodeinstall install --name "Xcode_26.5.xip" --xcode-version "26.5-custom"
```

The installation process:
1. Extracts the `.xip` file (this takes several minutes)
1. Extracts the `.xip` or `.aea` file (this takes several minutes). An `.aea` archive is installed only when its signature traces back to Apple's root certificate.
2. Moves to `/Applications/Xcode-{version}.app` (version auto-detected from filename)
3. Installs additional system packages
4. Creates a symlink `/Applications/Xcode.app` pointing to the newly installed version
Expand Down
260 changes: 260 additions & 0 deletions Sources/xcodeinstall/API/AppleEncryptedArchive.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,260 @@
//
// AppleEncryptedArchive.swift
// xcodeinstall
//
// Apple ships some Xcode releases as an Apple Encrypted Archive (.aea).
// The archive is not encrypted: it uses the signature-only profile
// `hkdf_sha256_hmac__none__ecdsa_p256`, so no key or password is needed.
// Its content is an LZMA-compressed Apple Archive (.aar) holding Xcode.app.
//
// The public key that checks the signature travels inside the archive, in the
// auth data, as a PEM certificate chain. Trusting that key blindly would only
// prove the file is intact, not that Apple made it. So the chain is evaluated
// with the Security framework and must end at Apple Root CA - G3 before its
// leaf key is used to verify the archive.
//

import AppleArchive
import CryptoKit
import Foundation
import Security
import System

enum AppleEncryptedArchiveError: Error, Equatable {
case cannotOpenArchive
case notAnAppleEncryptedArchive
case unsupportedProfile(String)
case malformedAuthData
case missingCertificateChain
case invalidCertificateChain
case untrustedCertificateChain(String)
case notSignedByApple
case unsupportedSigningKey
case extractionFailed(String)
}

/// Key-value entries stored in the auth data block of an Apple Encrypted Archive.
///
/// Each entry is laid out as a little-endian `UInt32` holding the entry size
/// (header included), a NUL-terminated UTF-8 key, then the value bytes.
nonisolated struct AEAAuthData: Equatable {

let entries: [String: Data]

init(entries: [String: Data]) {
self.entries = entries
}

init(_ data: Data) throws {
let bytes = [UInt8](data)
var entries: [String: Data] = [:]
var offset = 0

while offset < bytes.count {
guard bytes.count - offset >= 4 else {
throw AppleEncryptedArchiveError.malformedAuthData
}
let size =
Int(bytes[offset])
| Int(bytes[offset + 1]) << 8
| Int(bytes[offset + 2]) << 16
| Int(bytes[offset + 3]) << 24
let end = offset + size
guard size > 4, end <= bytes.count else {
throw AppleEncryptedArchiveError.malformedAuthData
}
guard let nul = bytes[(offset + 4)..<end].firstIndex(of: 0),
let key = String(bytes: bytes[(offset + 4)..<nul], encoding: .utf8)
else {
throw AppleEncryptedArchiveError.malformedAuthData
}
entries[key] = Data(bytes[(nul + 1)..<end])
offset = end
}
self.entries = entries
}
}

/// Turns the PEM certificate chain found in an archive into the key that
/// verifies its signature, after checking the chain leads to Apple's root.
nonisolated struct AppleSigningCertificateChain {

/// The auth data key under which Apple stores the signing certificate chain.
static let authDataKey = "com.apple.ias.signature.certificate-chain"

/// SHA-256 of the DER encoding of Apple Root CA - G3, the only root accepted.
static let appleRootCAG3SHA256 = "63343abfb89a6a03ebb57e9b3f5fa7be7c4f5c756f3017b3a8c488c3653e9179"

let certificates: [SecCertificate]

init(pem: Data) throws {
guard let text = String(data: pem, encoding: .utf8) else {
throw AppleEncryptedArchiveError.invalidCertificateChain
}
let begin = "-----BEGIN CERTIFICATE-----"
let end = "-----END CERTIFICATE-----"

var certificates: [SecCertificate] = []
var rest = Substring(text)
while let beginRange = rest.range(of: begin) {
guard let endRange = rest.range(of: end, range: beginRange.upperBound..<rest.endIndex) else {
throw AppleEncryptedArchiveError.invalidCertificateChain
}
let base64 = rest[beginRange.upperBound..<endRange.lowerBound]
.filter { !$0.isWhitespace }
guard let der = Data(base64Encoded: String(base64)),
let certificate = SecCertificateCreateWithData(nil, der as CFData)
else {
throw AppleEncryptedArchiveError.invalidCertificateChain
}
certificates.append(certificate)
rest = rest[endRange.upperBound...]
}

guard !certificates.isEmpty else {
throw AppleEncryptedArchiveError.invalidCertificateChain
}
self.certificates = certificates
}

/// Evaluates the chain against the system trust store, requires it to end at
/// Apple Root CA - G3, and returns the leaf certificate's P-256 public key.
///
/// - Parameter date: the moment the chain must be valid at. Tests pin it so a
/// recorded chain keeps verifying after its leaf certificate expires.
func verifiedSigningKey(at date: Date = Date()) throws -> P256.Signing.PublicKey {
var trust: SecTrust?
let status = SecTrustCreateWithCertificates(
certificates as CFArray,
SecPolicyCreateBasicX509(),
&trust
)
guard status == errSecSuccess, let trust else {
throw AppleEncryptedArchiveError.invalidCertificateChain
}
SecTrustSetVerifyDate(trust, date as CFDate)
SecTrustSetNetworkFetchAllowed(trust, false)

var error: CFError?
guard SecTrustEvaluateWithError(trust, &error) else {
let reason = error.map { CFErrorCopyDescription($0) as String } ?? "unknown reason"
throw AppleEncryptedArchiveError.untrustedCertificateChain(reason)
}

// A chain any public CA vouches for is not enough: Apple must have issued it.
guard let chain = SecTrustCopyCertificateChain(trust) as? [SecCertificate],
let root = chain.last,
Self.sha256Hex(of: root) == Self.appleRootCAG3SHA256
else {
throw AppleEncryptedArchiveError.notSignedByApple
}

guard let leafKey = SecCertificateCopyKey(certificates[0]),
let x963 = SecKeyCopyExternalRepresentation(leafKey, nil) as Data?,
let key = try? P256.Signing.PublicKey(x963Representation: x963)
else {
throw AppleEncryptedArchiveError.unsupportedSigningKey
}
return key
}

private static func sha256Hex(of certificate: SecCertificate) -> String {
let der = SecCertificateCopyData(certificate) as Data
return SHA256.hash(data: der).map { String(format: "%02x", $0) }.joined()
}
}

/// Verifies and expands an Apple Encrypted Archive.
nonisolated struct AppleEncryptedArchive {

let file: URL

/// Reads the certificate chain from the archive and returns the verified
/// Apple signing key.
func appleSigningKey(at date: Date = Date()) throws -> P256.Signing.PublicKey {
let (stream, context) = try open()
defer { try? stream.close() }

guard let rawAuthData = context.authData else {
throw AppleEncryptedArchiveError.missingCertificateChain
}
guard let pem = try AEAAuthData(rawAuthData).entries[AppleSigningCertificateChain.authDataKey] else {
throw AppleEncryptedArchiveError.missingCertificateChain
}
return try AppleSigningCertificateChain(pem: pem).verifiedSigningKey(at: date)
}

/// Checks the archive signature with `signingKey` and extracts its content
/// into `directory`. A bad signature makes the extraction throw.
///
/// The work is CPU and disk bound and takes about a minute for Xcode, so it
/// runs on the concurrent executor instead of the caller's actor.
@concurrent
func extract(to directory: URL, signingKey: P256.Signing.PublicKey) async throws {
let (fileStream, context) = try open()
defer { try? fileStream.close() }

do {
try context.setSigningPublicKey(signingKey)
} catch {
throw AppleEncryptedArchiveError.extractionFailed("can not use the signing key: \(error)")
}

guard
let decryptionStream = ArchiveByteStream.decryptionStream(
readingFrom: fileStream,
encryptionContext: context
)
else {
throw AppleEncryptedArchiveError.extractionFailed("can not verify the archive signature")
}
defer { try? decryptionStream.close() }

guard let decodeStream = ArchiveStream.decodeStream(readingFrom: decryptionStream) else {
throw AppleEncryptedArchiveError.extractionFailed("can not decode the archive")
}
defer { try? decodeStream.close() }

// The archive records attributes, such as the owner, that only root may set.
// Like `aa extract`, skip those instead of failing the whole extraction.
guard
let extractStream = ArchiveStream.extractStream(
extractingTo: FilePath(directory.path),
flags: [.ignoreOperationNotPermitted]
)
else {
throw AppleEncryptedArchiveError.extractionFailed("can not write to \(directory.path)")
}

do {
_ = try ArchiveStream.process(readingFrom: decodeStream, writingTo: extractStream)
// closing the extract stream flushes the last entries to disk
try extractStream.close()
} catch {
try? extractStream.close()
throw AppleEncryptedArchiveError.extractionFailed("\(error)")
}
}

private func open() throws -> (ArchiveByteStream, ArchiveEncryptionContext) {
guard
let stream = ArchiveByteStream.fileStream(
path: FilePath(file.path),
mode: .readOnly,
options: [],
permissions: []
)
else {
throw AppleEncryptedArchiveError.cannotOpenArchive
}
guard let context = ArchiveEncryptionContext(from: stream) else {
try? stream.close()
throw AppleEncryptedArchiveError.notAnAppleEncryptedArchive
}
guard context.profile == .hkdf_sha256_hmac__none__ecdsa_p256 else {
try? stream.close()
throw AppleEncryptedArchiveError.unsupportedProfile(context.profile.description)
}
return (stream, context)
}
}
8 changes: 5 additions & 3 deletions Sources/xcodeinstall/API/Install.swift
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,8 @@ enum InstallerError: Error, Equatable {
case fileDoesNotExistOrIncorrect
case xCodeUnxipDirectoryDoesntExist
case xCodeXIPInstallationError
case xCodeAEASignatureError
case xCodeAEAInstallationError
case xCodeMoveInstallationError
case xCodePKGInstallationError
case CLToolsInstallationError
Expand All @@ -37,7 +39,7 @@ enum SupportedInstallation {
static func supported(_ file: String) -> SupportedInstallation {
if file.hasPrefix("Command Line Tools for Xcode") && file.hasSuffix(".dmg") {
return .xCodeCommandLineTools
} else if file.hasPrefix("Xcode") && file.hasSuffix(".xip") {
} else if file.hasPrefix("Xcode") && (file.hasSuffix(".xip") || file.hasSuffix(".aea")) {
return .xCode
} else {
return .unsupported
Expand Down Expand Up @@ -113,8 +115,8 @@ class ShellInstaller {
/// Install Xcode or Xcode Command Line Tools
/// At this stage, we do support only these two installation.
///
/// **Xcode** is provided as a XIP file. The installation procedure is as follow:
/// - It is uncompressed
/// **Xcode** is provided as a XIP file or as an Apple Encrypted Archive (AEA). The installation procedure is as follow:
/// - It is uncompressed (for an AEA, after checking Apple signed it)
/// - It is moved to /Applications
/// - Four packages are installed
/// - `/Applications/Xcode.app/Contents/Resources/Packages/XcodeSystemResources.pkg`
Expand Down
59 changes: 48 additions & 11 deletions Sources/xcodeinstall/API/InstallXcode.swift
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
// Created by Stormacq, Sebastien on 29/08/2022.
//

import CryptoKit
import Subprocess
import libunxip

Expand All @@ -20,7 +21,7 @@ extension ShellInstaller {

func installXcode(at src: URL, version: String? = nil) async throws {

// unXIP, mv, 4 PKG to install, activate (symlink + xcode-select)
// unXIP or unAEA, mv, 4 PKG to install, activate (symlink + xcode-select)
let hasVersion = version != nil
let totalSteps = 2 + PKGTOINSTALL.count + (hasVersion ? 1 : 0)
var currentStep: Int = 0
Expand All @@ -30,17 +31,26 @@ extension ShellInstaller {
// first uncompress file
log.debug("Decompressing files")
currentStep += 1
self.progressBar.update(
step: currentStep,
total: totalSteps,
text: "Expanding Xcode xip (this might take a while)"
)
if src.pathExtension == "aea" {
self.progressBar.update(
step: currentStep,
total: totalSteps,
text: "Expanding Xcode aea (this might take a while)"
)
try await self.uncompressAEA(atURL: src)
} else {
self.progressBar.update(
step: currentStep,
total: totalSteps,
text: "Expanding Xcode xip (this might take a while)"
)

do {
try await self.uncompressXIP(atURL: src)
} catch {
log.error("Failed to extract XIP file: \(error)")
throw InstallerError.xCodeXIPInstallationError
do {
try await self.uncompressXIP(atURL: src)
} catch {
log.error("Failed to extract XIP file: \(error)")
throw InstallerError.xCodeXIPInstallationError
}
}

// second move file to /Applications (versioned if version provided)
Expand Down Expand Up @@ -127,6 +137,33 @@ extension ShellInstaller {
}
}

// verify and expand an Apple Encrypted Archive (.aea) next to the archive.
// The archive must be signed by a certificate chain ending at Apple's root.
func uncompressAEA(atURL file: URL) async throws {

guard self.fileHandler.fileExists(file: file, fileSize: 0) else {
log.error("File to expand does not exist : \(file.path)")
throw InstallerError.fileDoesNotExistOrIncorrect
}

let archive = AppleEncryptedArchive(file: file)

let signingKey: P256.Signing.PublicKey
do {
signingKey = try archive.appleSigningKey()
} catch {
log.error("The archive is not signed by Apple: \(error)")
throw InstallerError.xCodeAEASignatureError
}

do {
try await archive.extract(to: file.deletingLastPathComponent(), signingKey: signingKey)
} catch {
log.error("Failed to extract AEA file: \(error)")
throw InstallerError.xCodeAEAInstallationError
}
}

func moveApp(at src: URL, version: String? = nil) async throws -> String {

let fileName: String
Expand Down
Loading
Loading