Network Extension Provider Packaging

This is a topic that’s come up a few times on the forums, so I thought I’d write up a summary of the issues I’m aware of. If you have questions or comments, start a new thread in the App & System Services > Networking subtopic and tag it with Network Extension. That way I’ll be sure to see it go by.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

Network Extension Provider Packaging

There are two ways to package a network extension provider:

• App extension ( appex )
• System extension ( sysex )

Different provider types support different packaging on different platforms. See TN3134 Network Extension provider deployment for the details.

Some providers, most notably packet tunnel providers on macOS, support both appex and sysex packaging. Sysex packaging has a number of advantages:

• It supports direct distribution, using Developer ID signing.
• It better matches the networking stack on macOS. An appex is tied to the logged in user, whereas a sysex, and the networking stack itself, is global to the system as a whole.

Given that, it generally makes sense to package your Network Extension (NE) provider as a sysex on macOS. If you’re creating a new product that’s fine, but if you have an existing iOS product that you want to bring to macOS, you have to account for the differences brought on by the move to sysex packaging. Similarly, if you have an existing sysex product on macOS that you want to bring to iOS, you have to account for the appex packaging. This post summarises those changes.

Keep the following in mind while reading this post:

• The information here applies to all NE providers that can be packaged as either an appex or a sysex. When this post uses a specific provider type in an example, it’s just an example.
• Unless otherwise noted, any information about iOS also applies to iPadOS, tvOS, and visionOS.

Process Lifecycle

With appex packaging, the system typically starts a new process for each instance of your NE provider. For example, with a packet tunnel provider:

• When the users starts the VPN, the system creates a process and then instantiates and starts the NE provider in that process.
• When the user stops the VPN, the system stops the NE provider and then terminates the process running it.
• If the user starts the VPN again, the system creates an entirely new process and instantiates and starts the NE provider in that.

In contrast, with sysex packaging there’s typically a single process that runs all off the sysex’s NE providers. Returning to the packet tunnel provider example:

• When the users starts the VPN, the system instantiates and starts the NE provider in the sysex process.
• When the user stops the VPN, the system stops and deallocates the NE provider instances, but leaves the sysex process running.
• If the user starts the VPN again, the system instantiates and starts a new instances of the NE provider in the sysex process.

This lifecycle reflects how the system runs the NE provider, which in turn has important consequences on what the NE provider can do:

• An appex acts like a launchd agent [1], in that it runs in a user context and has access to that user’s state.
• A sysex is effectively a launchd daemon. It runs in a context that’s global to the system as a whole. It does not have access to any single user’s state. Indeed, there might be no user logged in, or multiple users logged in.

The rest of this post explores specific consequences of the NE provider lifecycle.

[1] It’s not actually run as a launchd agent. Rather, there’s a system launchd agent that acts as the host for the app extension.

App Groups

With an app extension, the app extension and its container app run as the same user. Thus it’s trivial to share state between them using an app group container.

Note When talking about extensions on Apple platforms, the container app is the app in which the extension is embedded and the host app is the app using the extension. For network extensions the host app is the system itself.

That’s not the case with a system extension. The system extension runs as root whereas the container app runs an the user who launched it. While both programs can claim access to the same app group, the app group container location they receive will be different. For the system extension that location will be inside the home directory for the root user. For the container app the location will be inside the home directory of the user who launched it.

This does not mean that app groups are useless in a Network Extension app. App groups are also a factor in communicating between the container app and its extensions, the subject of the next section.

IMPORTANT App groups have a long and complex history on macOS. For the full story, see App Groups: macOS vs iOS: Working Towards Harmony.

Communicating with Extensions

With an app extension there are two communication options:

• App-provider messages
• App groups

App-provider messages are supported by NE directly. In the container app, send a message to the provider by calling sendProviderMessage(_:responseHandler:) method. In the appex, receive that message by overriding the handleAppMessage(_:completionHandler:) method.

An appex can also implement inter-process communication (IPC) using various system IPC primitives. Both the container app and the appex claim access to the app group via the com.apple.security.application-groups entitlement. They can then set up IPC using various APIs, as explain in the documentation for that entitlement.

With a system extension the story is very different. App-provider messages are supported, but they are rarely used. Rather, most products use XPC for their communication. In the sysex, publish a named XPC endpoint by setting the NEMachServiceName property in its Info.plist. Listen for XPC connections on that endpoint using the XPC API of your choice.

Note For more information about the available XPC APIs, see XPC Resources.

In the container app, connect to that named XPC endpoint using the XPC Mach service name API. For example, with NSXPCConnection, initialise the connection with init(machServiceName:options:), passing in the string from NEMachServiceName. To maximise security, set the .privileged flag.

Note XPC Resources has a link to a post that explains why this flag is important.

If the container app is sandboxed — necessary if you ship on the Mac App Store — then the endpoint name must be prefixed by an app group ID that’s accessible to that app, lest the App Sandbox deny the connection. See app groups documentation for the specifics.

When implementing an XPC listener in your sysex, keep in mind that:

• Your sysex’s named XPC endpoint is registered in the global namespace. Any process on the system can open a connection to it [1]. Your XPC listener must be prepared for this. If you want to restrict connections to just your container app, see XPC Resources for a link to a post that explains how to do that.
• Your sysex only gets one named XPC endpoint, and thus one XPC listener. If your sysex includes multiple NE providers, take that into account when you design your XPC protocol.

[1] Assuming that connection isn’t blocked by some other mechanism, like the App Sandbox.

Inter-provider Communication

A sysex can include multiple types of NE providers. For example, a single sysex might include a content filter and a DNS proxy provider. In that case the system instantiates all of the NE providers in the same sysex process. These instances can communicate without using IPC, for example, by storing shared state in global variables (with suitable locking, of course).

It’s also possible for a single container app to contain multiple sysexen, each including a single NE provider. In that case the system instantiates the NE providers in separate processes, one for each sysex. If these providers need to communicate, they have to use IPC.

In the appex case, the system instantiates each provider in its own process. If two providers need to communicate, they have to use IPC.

Managing Secrets

An appex runs in a user context and thus can store secrets, like VPN credentials, in the keychain. On macOS this includes both the data protection keychain and the file-based keychain. It can also use a keychain access group to share secrets with its container app. See Sharing access to keychain items among a collection of apps.

Note If you’re not familiar with the different types of keychain available on macOS, see TN3137 On Mac keychain APIs and implementations.

A sysex runs in the global context and thus doesn’t have access to user state. It also doesn’t have access to the data protection keychain. It must use the file-based keychain, and specifically the System keychain. That means there’s no good way to share secrets with the container app.

Instead, do all your keychain operations in the sysex. If the container app needs to work with a secret, have it pass that request to the sysex via IPC. For example, if the user wants to use a digital identity as a VPN credential, have the container app get the PKCS#12 data and password and then pass that to the sysex so that it can import the digital identity into the keychain.

Memory Limits

iOS imposes strict memory limits an NE provider appexen [1]. macOS imposes no memory limits on NE provider appexen or sysexen.

[1] While these limits are not documented officially, you can get a rough handle on the current limits by reading the posts in this thread.

Frameworks

If you want to share code between a Mac app and its embedded appex, use a structure like this:

MyApp.app/
    Contents/
        MacOS/
            MyApp
        PlugIns/
            MyExtension.appex/
                Contents/
                    MacOS/
                        MyExtension
                    …
        Frameworks/
            MyFramework.framework/
                …

There’s one copy of the framework, in the app’s Frameworks directory, and both the app and the appex reference it.

This approach works for an appex because the system always loads the appex from your app’s bundle. It does not work for a sysex. When you activate a sysex, the system copies it to a protected location. If that sysex references a framework in its container app, it will fail to start because that framework isn’t copied along with the sysex.

The solution is to structure your app like this:

MyApp.app/
    Contents/
        MacOS/
            MyApp
        Library/
            SystemExtensions/
                MyExtension.systemextension/
                    Contents/
                        MacOS/
                            MyExtension
                        Frameworks/
                            MyFramework.framework/
                                …
                        …

That is, have both the app and the sysex load the framework from the sysex’s Frameworks directory. When the system copies the sysex to its protected location, it’ll also copy the framework, allowing the sysex to load it.

To make this work you have to change the default rpath configuration set up by Xcode. Read Dynamic Library Standard Setup for Apps to learn how that works and then tweak things so that:

• The framework is embedded in the sysex, not the container app.
• The container app has an additional LC_RPATH load command for the sysex’s Frameworks directory (@executable_path/../Library/SystemExtensions/MyExtension.systemextension/Contents/Frameworks).
• The sysex’s LC_RPATH load command doesn’t reference the container app’s Frameworks directory (@executable_path/../../../../Frameworks) but instead points to the sysex’s Framweorks directory (@executable_path/../Frameworks).