From 67dc4b9d1a52abdf9a2eaa5ea0484d56abc3d009 Mon Sep 17 00:00:00 2001 From: Stu Hume Date: Mon, 7 Jul 2025 13:45:22 -0400 Subject: [PATCH 1/5] new page with ios devices management for air gapped --- .../managing-airgapped-ios-devcies.adoc | 69 +++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devcies.adoc diff --git a/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devcies.adoc b/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devcies.adoc new file mode 100644 index 000000000..c5da1ac83 --- /dev/null +++ b/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devcies.adoc @@ -0,0 +1,69 @@ +```asciidoc += Managing iOS Devices in Air‑Gapped Kobiton Environments +:doctype: process +:leveloffset: 1 +:toc: left +:toclevels: 2 + +This document outlines Kobiton’s standardized process for enabling iOS device management within air‑gapped environments—data centers or secured labs isolated from the internet. It addresses Apple’s security requirements (e.g., personalized Developer Disk Images and certificate verification) and provides step-by-step guidance to maintain device operability without compromising security. + +== Requirements from Apple + +1. **Developer Certificate Verification** + Apple requires all provisioning profiles and signing certificates to be verified against their servers on first installation. This validation must occur online at least once. Subsequent launches will rely on cached credentials. + +2. **Personalized Developer Disk Image (DDI)** + For iOS 17+, each device requires a unique, Apple‑personalized DDI via a TSS request to Apple servers (`https://gs.apple.com/TSS`). This signature is stored locally on the device and does not require internet access after the initial retrieval—but may expire over time. + +== Process Overview + +=== 1. Initial Setup & Certificate Verification +* Prepare a **dedicated, internet‑connected macOS host** with supported Xcode (e.g., Xcode 16.4 on macOS 15.5). +* Connect each iOS device via **USB** and enable Developer Mode / USB debugging. +* Launch Xcode with the device active and foregrounded to establish trust and verify the certificate. + +=== 2. Personalized DDI Acquisition +* For each iOS 17+ device: +** Connect via USB to the internet‑connected macOS host. +** Let Xcode request and download the personalized DDI signature from Apple. +** Confirm that the personalization ticket is recorded locally on the device. + +=== 3. Air‑Gapped Deployment +* Remove the device from the online macOS host. +* Connect it via USB or Cambrionix hub to the air‑gapped Kobiton device host. +* Launch Kobiton’s `deviceControl` to mount and load the DDI. +* If verification fails, reconnect the device to the internet‑enabled host and refresh credentials. + +=== 4. Monitoring & Remediation +Kobiton logs will alert on: +* DDI mount failures +* `deviceControl` launch issues +These typically indicate expired credentials or missing certificates. In such cases, repeat steps 1 and 2. + +== System Administrator Checklist +* A secure macOS machine with **Xcode installed** and internet access. +* iOS devices connected via USB with **Developer Mode enabled**. +* Kobiton’s `deviceConnect` deployed on air‑gapped hosts. +* Physical USB access to devices in the lab while maintaining network isolation. + +== Troubleshooting & Common Errors + +[cols="1,2,3", options="header"] +|=== +| Symptom | Likely Cause | Recommended Action +| `deviceControl failed to launch` | Certificate expired or missing provisioning | Reconnect to internet host and re-verify certificate +| `DDI mount error` | Missing or expired personalization ticket | Repeat personalized DDI process via internet host +| New device not recognized | No provisioning profile or mismatched certificate | Update provisioning, ensure UDID is included +|=== + +== Future Enhancements +Kobiton plans to store **personalization tickets per device** by default—reducing dependency on initial setup hosts and supporting multi-node labs more robustly. + +== Summary +Kobiton’s process enables secure iOS device management in air‑gapped environments by: +* Using an online macOS host for Apple compliance steps +* Mounting devices offline following credential and DDI setup +* Maintaining a repeatable, compliant workflow even as Apple's requirements evolve + +For detailed configuration, USB hub setup guidance, provisioning profile help, or Kobiton log analysis, consult the official Kobiton documentation or contact support. +``` From b5810c196cb6cb5074d5ff5b553b49fe5d92ee47 Mon Sep 17 00:00:00 2001 From: Tung Manh Hoang Date: Tue, 8 Jul 2025 14:55:14 +0700 Subject: [PATCH 2/5] Revised structure and wordings - WIP --- .../managing-airgapped-ios-devcies.adoc | 31 +++++++++++-------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devcies.adoc b/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devcies.adoc index c5da1ac83..cf8120681 100644 --- a/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devcies.adoc +++ b/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devcies.adoc @@ -1,25 +1,31 @@ -```asciidoc = Managing iOS Devices in Air‑Gapped Kobiton Environments -:doctype: process -:leveloffset: 1 -:toc: left -:toclevels: 2 + +:navtitle: Managing iOS Devices in Air-Gapped Environments This document outlines Kobiton’s standardized process for enabling iOS device management within air‑gapped environments—data centers or secured labs isolated from the internet. It addresses Apple’s security requirements (e.g., personalized Developer Disk Images and certificate verification) and provides step-by-step guidance to maintain device operability without compromising security. == Requirements from Apple -1. **Developer Certificate Verification** - Apple requires all provisioning profiles and signing certificates to be verified against their servers on first installation. This validation must occur online at least once. Subsequent launches will rely on cached credentials. +* **Developer Certificate Verification** + ++ + +Apple requires all provisioning profiles and signing certificates to be verified against their servers on first installation. This validation must occur online at least once. Subsequent launches will rely on cached credentials. + +* **Personalized Developer Disk Image (DDI)** -2. **Personalized Developer Disk Image (DDI)** - For iOS 17+, each device requires a unique, Apple‑personalized DDI via a TSS request to Apple servers (`https://gs.apple.com/TSS`). This signature is stored locally on the device and does not require internet access after the initial retrieval—but may expire over time. ++ + +For iOS 17+, each device requires a unique, Apple‑personalized DDI via a TSS request to Apple servers (https://gs.apple.com/TSS). This signature is stored locally on the device and does not require internet access after the initial retrieval—but may expire over time. == Process Overview -=== 1. Initial Setup & Certificate Verification -* Prepare a **dedicated, internet‑connected macOS host** with supported Xcode (e.g., Xcode 16.4 on macOS 15.5). -* Connect each iOS device via **USB** and enable Developer Mode / USB debugging. +=== Initial Setup & Certificate Verification + +* Prepare a **dedicated, internet‑connected macOS host** with supported Xcode (e.g., Xcode 16.4 on macOS 15.5). + +* Connect each iOS device via **USB** and enable Developer Mode. + * Launch Xcode with the device active and foregrounded to establish trust and verify the certificate. === 2. Personalized DDI Acquisition @@ -66,4 +72,3 @@ Kobiton’s process enables secure iOS device management in air‑gapped environ * Maintaining a repeatable, compliant workflow even as Apple's requirements evolve For detailed configuration, USB hub setup guidance, provisioning profile help, or Kobiton log analysis, consult the official Kobiton documentation or contact support. -``` From 4f0003db1127fdd7d985e7b2caeb9ddfdc9ca64c Mon Sep 17 00:00:00 2001 From: Tung Manh Hoang Date: Tue, 8 Jul 2025 15:02:51 +0700 Subject: [PATCH 3/5] Revised structure and wordings - WIP --- .../managing-airgapped-ios-devcies.adoc | 23 ++++++++++++------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devcies.adoc b/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devcies.adoc index cf8120681..8b2bd2b69 100644 --- a/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devcies.adoc +++ b/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devcies.adoc @@ -28,25 +28,31 @@ For iOS 17+, each device requires a unique, Apple‑personalized DDI via a TSS r * Launch Xcode with the device active and foregrounded to establish trust and verify the certificate. -=== 2. Personalized DDI Acquisition -* For each iOS 17+ device: +=== Personalized DDI Acquisition + +* For each iOS 17+ device: ** Connect via USB to the internet‑connected macOS host. ** Let Xcode request and download the personalized DDI signature from Apple. ** Confirm that the personalization ticket is recorded locally on the device. -=== 3. Air‑Gapped Deployment +=== Air‑Gapped Deployment + * Remove the device from the online macOS host. * Connect it via USB or Cambrionix hub to the air‑gapped Kobiton device host. -* Launch Kobiton’s `deviceControl` to mount and load the DDI. +* xref:device-lab-management:deviceConnect/restart-deviceconnect-services.adoc[Restart deviceConnect services,window=read-later] on the Mac mini to mount and load the DDI. * If verification fails, reconnect the device to the internet‑enabled host and refresh credentials. -=== 4. Monitoring & Remediation +=== Monitoring & Remediation + Kobiton logs will alert on: -* DDI mount failures -* `deviceControl` launch issues -These typically indicate expired credentials or missing certificates. In such cases, repeat steps 1 and 2. + +* DDI mount failures. +* `deviceControl` (Kobiton mobile agent) launch issues. + +These typically indicate expired credentials or missing certificates. In such cases, repeat the steps in the _Personalized DDI Acquisition_ and _Air‑Gapped Deployment_ sections. == System Administrator Checklist + * A secure macOS machine with **Xcode installed** and internet access. * iOS devices connected via USB with **Developer Mode enabled**. * Kobiton’s `deviceConnect` deployed on air‑gapped hosts. @@ -67,6 +73,7 @@ Kobiton plans to store **personalization tickets per device** by default—reduc == Summary Kobiton’s process enables secure iOS device management in air‑gapped environments by: + * Using an online macOS host for Apple compliance steps * Mounting devices offline following credential and DDI setup * Maintaining a repeatable, compliant workflow even as Apple's requirements evolve From b9499a2b90b74329b648d3b8e7d96767b976edb1 Mon Sep 17 00:00:00 2001 From: Tung Manh Hoang Date: Tue, 8 Jul 2025 15:05:02 +0700 Subject: [PATCH 4/5] Fix typo in doc file name and added navigation --- docs/modules/device-lab-management/nav.adoc | 3 ++- ...ed-ios-devcies.adoc => managing-airgapped-ios-devices.adoc} | 0 2 files changed, 2 insertions(+), 1 deletion(-) rename docs/modules/device-lab-management/pages/standalone/{managing-airgapped-ios-devcies.adoc => managing-airgapped-ios-devices.adoc} (100%) diff --git a/docs/modules/device-lab-management/nav.adoc b/docs/modules/device-lab-management/nav.adoc index 43af59cd1..23e069249 100644 --- a/docs/modules/device-lab-management/nav.adoc +++ b/docs/modules/device-lab-management/nav.adoc @@ -15,4 +15,5 @@ ** xref:android-devices/prepare-android-device.adoc[] ** xref:android-devices/add-android-device.adoc[] * Standalone/On-Prem -** xref:standalone/collect-standalone-logs.adoc[] \ No newline at end of file +** xref:standalone/collect-standalone-logs.adoc[] +** xref:standalone/managing-airgapped-ios-devices.adoc[] \ No newline at end of file diff --git a/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devcies.adoc b/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devices.adoc similarity index 100% rename from docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devcies.adoc rename to docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devices.adoc From 4228e8f78379148c29b67a6e0e3d61e6fa850110 Mon Sep 17 00:00:00 2001 From: Tung Manh Hoang Date: Thu, 10 Jul 2025 14:56:28 +0700 Subject: [PATCH 5/5] Added DDI transfer section --- .../pages/ios-devices/add-ios-device.adoc | 14 +++++++++----- .../standalone/managing-airgapped-ios-devices.adoc | 8 ++++++++ 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/docs/modules/device-lab-management/pages/ios-devices/add-ios-device.adoc b/docs/modules/device-lab-management/pages/ios-devices/add-ios-device.adoc index 234da9dc0..9f3cf3f54 100644 --- a/docs/modules/device-lab-management/pages/ios-devices/add-ios-device.adoc +++ b/docs/modules/device-lab-management/pages/ios-devices/add-ios-device.adoc @@ -158,6 +158,8 @@ Wait until the device screen changes to the below before continuing. There will image::device-lab-management:device-lab-management-add-android-screen-changes-to-blue.PNG[width=300, alt="device screen changes and shows Kobiton name and logo"] + + [#preload-ddi-air-gapped] === Preload DDI for air-gapped Mac mini hosts @@ -169,7 +171,7 @@ Access any macOS machine with Internet access. This will be referred to as the I [NOTE] Kobiton software, such as deviceConnect and deviceShare, does not need to be installed on the Internet Mac. -Ensure *Xcode* is installed on the Internet Mac. Make sure the Xcode version is compatible with the iOS 17 device. +Ensure *Xcode* is installed on the Internet Mac. Make sure the Xcode version on the Internet Mac is the same as the air-gapped Mac. [IMPORTANT] Make sure the Xcode version on the Internet Mac *is the same or greater* than the version on the Mac mini host to transfer the DDI to. @@ -190,17 +192,19 @@ Unplug the device from the Internet Mac. Repeat the above processes for all iOS/iPadOS 17 and later devices to be hosted on the air-gapped Mac mini. +// tag::ddi[] + Open *Finder* on the Internet Mac. Press *Shift + Command + G* on the keyboard, then input the following path depending on the version of Xcode: +* `/Library/Developer/CoreDevice/CandidateDDIs/iOS_DDI.dmg` or `~/Library/Developer/CoreDevice/CandidateDDIs/iOS_DDI.dmg`, depending on where Xcode is installed (Xcode 16.3 and later) + * `/Library/Developer/DeveloperDiskImages` (Xcode 16 and above) * `~/Library/Developer/DeveloperDiskImages` (Xcode below 16) -Copy the 2 files `iOS_DDI-version.plist` and `iOS_DDI.dmg` to the *air-gapped Mac mini* that will host the iOS/iPadOS 17 and later devices. Put the copied file into the following folder on the air-gapped Mac mini: - -* `/Library/Developer/DeveloperDiskImages` if the current Xcode version is 16 or above. +Copy the 2 files `iOS_DDI-version.plist` and `iOS_DDI.dmg` to the same location on the *air-gapped Mac mini* that will host the iOS/iPadOS 17 and later devices. -* ``~/Library/Developer/DeveloperDiskImages ``if the current Xcode version is below 16. +// end::ddi[] Repeat the above process for all air-gapped Mac mini hosts with iOS/iPadOS 17 and later devices. diff --git a/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devices.adoc b/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devices.adoc index 8b2bd2b69..a663164e1 100644 --- a/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devices.adoc +++ b/docs/modules/device-lab-management/pages/standalone/managing-airgapped-ios-devices.adoc @@ -42,6 +42,14 @@ For iOS 17+, each device requires a unique, Apple‑personalized DDI via a TSS r * xref:device-lab-management:deviceConnect/restart-deviceconnect-services.adoc[Restart deviceConnect services,window=read-later] on the Mac mini to mount and load the DDI. * If verification fails, reconnect the device to the internet‑enabled host and refresh credentials. +=== Air‑Gapped Deployment DDI Transfer + +For air-gapped or datacenter environments where it’s cumbersome to follow manual steps to allow Xcode to download this file, administrators can copy the base image from the Internet macOS host to the air-gapped host. + +Follow the steps from the previous sections to generate the DDI on the Internet host. + +include::device-lab-management:ios-devices/add-ios-device.adoc[tag=ddi] + === Monitoring & Remediation Kobiton logs will alert on: