psiphon-tunnel-core/MobileLibrary/iOS/USAGE.md

Using the Psiphon iOS Library

Overview

Psiphon Library for iOS enables you to easily embed Psiphon in your iOS app. You can then tunnel requests through Psiphon, ensuring that your app can't be blocked by censors.

The Psiphon Library is available as a XCFramework bundle .xcframework that can be easily included in your project using these instructions.

Requirements

Psiphon Library for iOS requires Xcode 11 or above. If using CocoaPods, CocoaPods version 1.10 or greater is required.

Using the Library in your App

First step: Review the sample app, located under SampleApps. This code is a canonical guide for integrating the Library.

Second step: Review the comments in PsiphonTunnel.h. They describe the interface and delegate requirements.

Setting up your project

1. Get the latest iOS release from the project's Releases page.

2. Add PsiphonTunnel.xcframework to project (drag into project tree).

3. In the "General" settings for the target, set "Deployment Target" to 9.3.

4. In the "Build Settings" for the target, under "Build Options", set "Enable Bitcode" to "No".

5. In the "Build Settings" for the target, click the + at the top, then "Add User-Defined Setting". Name the new setting STRIP_BITCODE_FROM_COPIED_FILES and set it to NO.

6. In the "Build Phases" for the target, add a "Copy Files" phase. Set "Destination" to "Frameworks". Add PsiphonTunnel.xcframework to the list. Ensure "Code Sign on Copy" is checked.

Compiling and testing

The following architecture targets are compiled into the Library's framework binary: arm64, and x86_64. This means that the Library can run on phones or in a simulator (on a 64-bit host system).

When run in a simulator, there may be errors shown in the device log. This does not seem to affect the execution of the app (or Library).

Proxying a web view

We have provided a reference implementation for proxying WKWebView in TunneledWebView. The shortcomings of this implementation are discussed in SampleApps/TunneledWebView/README.md.

*** Caveats ***

Risk of Online Certificate Status Protocol (OCSP) Leaks

On iOS, remote certificate revocation checks may be performed by the system when server certificates are validated. For example, when making an HTTPS request. When OCSP is used to determine the revocation status of a certificate the system will make a plaintext HTTP OCSP request if an OCSP response is not cached or stapled.

Unfortunately, these OCSP requests do not respect connection proxy dictionary settings or NSURLProtocol subclasses; instead they are performed out of process. The payload in each plaintext OCSP request leaks the identity of the certificate that is being validated.

The risk is that an observer can map the certificate's serial number back to the certificate to find more information about the website or server being accessed.

Other notes

If you encounter an app crash due to SIGPIPE, please let us know. This occurs in the debugger, but it's not clear if it happens in a production app (or is a problem). If you encounter a SIGPIPE breakpoint while running under the debugger, follow these instructions to disable it.