Skip to content

Run a virtual iPhone on an Apple Silicon Mac.

Swift
9.1 KB
Raw Blame
// VPhoneAEA.swift — the AEA1 prologue, and the key Apple hands back for it.
//
// This replaces `ipsw fw aea`, which was the last thing in the CFW install path
// that needed a Homebrew program on the machine running the install. Three
// shapes were used: `--info` (the archive's auth data), `--key` (the symmetric
// key) and `-o` (decrypt). The first two are here; the third is
// `/usr/bin/aea decrypt`, which ships with macOS.
//
// Two facts make this small. The prologue is a flat list of length-prefixed
// key/value records, so reading it needs no framework at all. And the key
// exchange is plain RFC 9180 HPKE — base mode, DHKEM(P-256, HKDF-SHA256),
// HKDF-SHA256, AES-256-GCM, empty `info` and empty `aad` — which CryptoKit
// implements, so there is no crypto written here either.
//
// The one thing that is not local is the private key: `fcs-key-url` points at
// wkms-public.apple.com and the archive cannot be opened without fetching it.
// That is Apple's design, not a dependency this project added — `ipsw` made the
// same request.

import CryptoKit
import Foundation

public enum VPhoneAEA {
    // MARK: - Errors

    public enum Error: Swift.Error, LocalizedError {
        case notAEA(URL)
        case truncatedPrologue(URL)
        case missingAuthField(String)
        case malformedFCSResponse
        case keyFetchFailed(URL, Int)

        public var errorDescription: String? {
            switch self {
            case let .notAEA(url):
                "\(url.lastPathComponent) is not an encrypted firmware archive."
            case let .truncatedPrologue(url):
                "\(url.lastPathComponent) is incomplete or damaged. Download the firmware again."
            case .missingAuthField:
                "The firmware file is missing decryption key information. Download the firmware again."
            case .malformedFCSResponse:
                "Unable to read the decryption key information in this firmware file. Download the firmware again."
            case let .keyFetchFailed(url, _):
                "Unable to download the decryption key from \(url.host() ?? url.absoluteString). Try again later."
            }
        }
    }

    // MARK: - Prologue

    /// The archive's authentication data: the key/value pairs `ipsw fw aea
    /// --info` prints, as they are stored.
    ///
    /// Layout, all little-endian: `AEA1`, a u32 profile, a u32 giving the size
    /// of everything that follows, then that many bytes of records. Each record
    /// is a u32 length — counting its own four bytes — followed by a
    /// NUL-separated key and value. The value is bytes, not text: `auth-data`
    /// is a protobuf.
    public static func authData(of url: URL) throws -> [String: Data] {
        let handle = try FileHandle(forReadingFrom: url)
        defer { try? handle.close() }

        guard let header = try handle.read(upToCount: 12), header.count == 12 else {
            throw Error.truncatedPrologue(url)
        }
        guard header.prefix(4) == Data("AEA1".utf8) else { throw Error.notAEA(url) }

        let size = Int(u32(header, 8))
        guard size > 0, size <= 16 * 1024 * 1024,
              let body = try handle.read(upToCount: size), body.count == size
        else { throw Error.truncatedPrologue(url) }

        var fields: [String: Data] = [:]
        var offset = 0
        while offset + 4 <= size {
            let length = Int(u32(body, offset))
            // A record has to carry its own header and at least a key; a length
            // that does not is a corrupt prologue, not an empty field.
            guard length > 4, offset + length <= size else { break }
            let record = body.subdata(in: (offset + 4) ..< (offset + length))
            if let separator = record.firstIndex(of: 0) {
                fields[String(decoding: record[..<separator], as: UTF8.self)] =
                    Data(record[(separator + 1)...])
            }
            offset += length
        }
        return fields
    }

    private static func u32(_ data: Data, _ offset: Int) -> UInt32 {
        data.withUnsafeBytes {
            $0.loadUnaligned(fromByteOffset: offset, as: UInt32.self).littleEndian
        }
    }

    // MARK: - Key

    /// The archive's symmetric key, in the `base64:…` spelling `aea` takes for
    /// `-key-value` — and the spelling `ipsw fw aea --key` printed, so the call
    /// sites did not have to change.
    ///
    /// Three steps, none of them optional: `fcs-key-url` names a one-time P-256
    /// private key that Apple serves as a PEM; `fcs-response` carries the HPKE
    /// encapsulated key and the wrapped symmetric key; opening the second with
    /// the first gives 32 bytes.
    public static func symmetricKey(of url: URL) async throws -> String {
        let fields = try authData(of: url)

        guard let keyURLBytes = fields["com.apple.wkms.fcs-key-url"],
              let keyURL = URL(string: String(decoding: keyURLBytes, as: UTF8.self))
        else { throw Error.missingAuthField("com.apple.wkms.fcs-key-url") }

        guard let responseBytes = fields["com.apple.wkms.fcs-response"] else {
            throw Error.missingAuthField("com.apple.wkms.fcs-response")
        }
        guard let response = try JSONSerialization.jsonObject(with: responseBytes) as? [String: String],
              let encapsulated = response["enc-request"].flatMap({ Data(base64Encoded: $0) }),
              let wrapped = response["wrapped-key"].flatMap({ Data(base64Encoded: $0) })
        else { throw Error.malformedFCSResponse }

        let session = URLSession(configuration: .ephemeral)
        defer { session.invalidateAndCancel() }
        let (pem, urlResponse) = try await session.data(from: keyURL)
        if let http = urlResponse as? HTTPURLResponse, http.statusCode != 200 {
            throw Error.keyFetchFailed(keyURL, http.statusCode)
        }

        let privateKey = try P256.KeyAgreement.PrivateKey(
            pemRepresentation: String(decoding: pem, as: UTF8.self),
        )
        var recipient = try HPKE.Recipient(
            privateKey: privateKey,
            ciphersuite: HPKE.Ciphersuite(
                kem: .P256_HKDF_SHA256,
                kdf: .HKDF_SHA256,
                aead: .AES_GCM_256,
            ),
            info: Data(),
            encapsulatedKey: encapsulated,
        )
        return try "base64:" + (recipient.open(wrapped)).base64EncodedString()
    }

    // MARK: - Re-encryption metadata

    /// The auth data in the form `aea -auth-data-value` takes it, matching what
    /// this project fed back into a rebuilt archive when it parsed `ipsw fw aea
    /// --info` output instead of the file.
    ///
    /// The shape is inherited, not chosen. `ipsw` printed a field either as
    /// text or as a hex dump, depending on whether it looked printable, and the
    /// parser on this end turned the first into the text's bytes and the second
    /// into the *base64 spelling* of the bytes. Reproducing that split keeps a
    /// re-encrypted archive byte-identical to the ones this path has always
    /// produced; "fixing" it would change every archive the CFW installer
    /// writes, silently, for no benefit.
    public static func reencryptionMetadata(of url: URL) throws -> [String: String] {
        try authData(of: url).mapValues { value in
            if let text = printableText(value) {
                "hex:" + Data(text.utf8).hexString
            } else {
                "hex:" + Data(value.base64EncodedString().utf8).hexString
            }
        }
    }

    /// What `ipsw` would have printed as text rather than hex-dumped: valid
    /// UTF-8 with no control bytes in it, trimmed the way the old parser
    /// trimmed the lines it joined.
    private static func printableText(_ data: Data) -> String? {
        guard !data.contains(where: { $0 < 0x20 && $0 != 0x09 && $0 != 0x0A && $0 != 0x0D }),
              let text = String(data: data, encoding: .utf8)
        else { return nil }
        return text.trimmingCharacters(in: .whitespacesAndNewlines)
    }
}

private extension Data {
    var hexString: String {
        map { String(format: "%02x", $0) }.joined()
    }
}

// MARK: - Running one async call from synchronous code

/// Wait for an async call from a synchronous caller.
///
/// The firmware pipeline is straight-line synchronous code from `main.swift`
/// down, and `VPhoneAEA.symmetricKey` is the only step anywhere in it that
/// touches the network. Threading `async` through every frame between them —
/// the Command command, the cryptex patcher, half of FirmwarePatcher — to serialise
/// on one HTTPS GET would buy nothing.
///
/// `Task.detached` and a semaphore, deliberately: the task must not inherit the
/// caller's actor, or a call made on the main actor would block the queue the
/// work is waiting to run on.
public func vphoneRunBlocking<T: Sendable>(
    _ body: @escaping @Sendable () async throws -> T,
) throws -> T {
    let semaphore = DispatchSemaphore(value: 0)
    nonisolated(unsafe) var result: Result<T, Swift.Error>!
    Task.detached {
        do { result = try await .success(body()) } catch { result = .failure(error) }
        semaphore.signal()
    }
    semaphore.wait()
    return try result.get()
}