https://developer.apple.com/forums/thread/707294
General:
Forums subtopic: App & System Services > Networking
DevForums tag: Network Extension
Network Extension framework documentation
Routing your VPN network traffic article
Filtering traffic by URL sample code
Filtering Network Traffic sample code
TN3120 Expected use cases for Network Extension packet tunnel providers technote
TN3134 Network Extension provider deployment technote
TN3165 Packet Filter is not API technote
Network Extension and VPN Glossary forums post
Debugging a Network Extension Provider forums post
Exporting a Developer ID Network Extension forums post
Network Extension vs ad hoc techniques on macOS forums post
Network Extension Provider Packaging forums post
NWEndpoint History and Advice forums post
Extra-ordinary Networking forums post
Wi-Fi management:
Wi-Fi Fundamentals forums post
TN3111 iOS Wi-Fi API overview technote
How to modernize your captive network developer news post
iOS Network Signal Strength forums post
See also Networking Resources.
Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"
Network Extension
RSS for tagCustomize and extend the core networking features of iOS, iPad OS, and macOS using Network Extension.
Posts under Network Extension tag
200 Posts
Selecting any option will automatically load the page
Post
Replies
Boosts
Views
Activity
I am trying to setup a system-wide DNS-over-TLS for iOS that can be turned off and on from within the app, and I'm struggling with the implementation details. I've searched online, searched forums here, used ChatGPT, and I'm getting conflicting information or code that is simply wrong. I can't find example code that is valid and gets me moving forward.
I think I need to use NEDNSProxyProvider via the NetworkExtension. Does that sound correct? I have NetworkExtension -> DNS Proxy Capability set in both the main app and the DNSProxy extension.
Also, I want to make sure this is even possible without an MDM. I see conflicting information, some saying this is opened up, but things like https://developer.apple.com/documentation/Technotes/tn3134-network-extension-provider-deployment saying a device needs to be managed. How do private DNS apps do this without MDM?
From some responses in the forums it sounds like we need to parse the DNS requests that come in to the handleNewFlow function. Is there good sample code for this parsing?
I saw some helpful information from Eskimo (for instance https://developer.apple.com/forums/thread/723831 ) and Matt Eaton ( https://developer.apple.com/forums/thread/665480 )but I'm still confused.
So, if I have a DoT URL, is there good sample code somewhere for what startProxy, stopProxy, and handleNewFlow might look like? And valid code to call it from the main app?
I haven’t been able to get this to work at any level! I’m running into multiple issues, any light shed on any of these would be nice:
I can’t implement a bloom filter that produces the same output as can be found in the SimpleURLFilter sample project, after following the textual description of it that’s available in the documentation. No clue what my implementation is doing wrong, and because of the nature of hashing, there is no way to know. Specifically:
The web is full of implementations of FNV-1a and MurmurHash3, and they all produce different hashes for the same input. Can we get the proper hashes for some sample strings, so we know which is the “correct” one?
Similarly, different implementations use different encodings for the strings to hash. Which should we use here?
The formulas for numberOfBits and numberOfHashes give Doubles and assign them to Ints. It seems we should do this conversing by rounding them, is this correct?
Can we get a sample correct value for the combined hash, so we can verify our implementations against it?
Or ignoring all of the above, can we have the actual code instead of a textual description of it? 😓
I managed to get Settings to register my first attempt at this extension in beta 1. Now, in beta 2, any other project (including the sample code) will redirect to Settings, show the Allow/Deny message box, I tap Allow, and then nothing happens. This must be a bug, right?
Whenever I try to enable the only extension that Settings accepted (by setting its isEnabled to true), its status goes to .stopped and the error is, of course, .unknown. How do I debug this?
While the extension is .stopped, ALL URL LOADS are blocked on the device. Is this to be expected? (shouldFailClosed is set to false)
Is there any way to manually reload the bloom filter? My app ships blocklist updates with background push, so it would be wasteful to fetch the filter at a fixed interval. If so, can we opt out of the periodic fetch altogether?
I initially believed the API to be near useless because I didn’t know of its “fuzzy matching” capabilities, which I’ve discovered by accident in a forum post. It’d be nice if those were documented somewhere!
Thanks!!
Hello,
I have been playing around the the SimpleURLFilter sample code. I keep getting this error upon installed the filter profile on the device:
mapError unexpected error domain NEVPNConnectionErrorDomainPlugin code 7
which then causes this error:
Received filter status change: <FilterStatus: 'stopped' errorMessage: 'The operation couldn’t be completed. (NetworkExtension.NEURLFilterManager.Error error 14.)'>
I can't find much info about code 7.
Here is the configuration I am trying to run:
<Configuration: pirServerURL: 'http://MyComputer.local:8080' pirAuthenticationToken: 'AAAA' pirPrivacyPassIssuerURL: 'http://MyComputer.local:8080' enabled: 'true' shouldFailClosed: 'true' controlProviderBundleIdentifier: 'krpaul.SimpleURLFilter.SimpleURLFilterExtension' prefilterFetchInterval: '2700.0'>
I've been wondering what is the memory limit for network extensions. Specifically, I'm using the NEPacketTunnelProvider extension point.The various posts on this forum mention 5 MB and 6 MB for 32-bit and 64-bit respectively. However I find that (at least on iOS 10) the upper limit seems to be 15 MB. Is this the new memory limit for extensions?
We currently have a PacketTunnelProvider providing a VPN connection to managed devices. Our profile locks this down with OnDemandEnabled and OnDemandUserOverrideDisabled set to true.
We've had reports of the OnDemand feature not kicking in on macOS when switching profiles or creating new profiles for managed users (but this works for the initial user login). When switching profiles, OnDemand does not enable; however, if the user manually enables the VPN and then disables, OnDemand will now correctly turn the connection back on.
The installed profile contains:
OnDemandEnabled: 1
OnDemandRules: Connect Action for WiFi, Cellular, and Ethernet
OnDemandUserOverrideDisabled: 1
From sysdiagnose logs, I see some interesting logs for nesessionmanager:
Handling a network changed event
Resetting VPN On Demand
Found 0 registrations for [...].PacketTunnel
Failed to find [...].PacketTunnel app extension using neagent
Plugin is not available in launch services
Plugin is not installed
(I also see some failures with LSApplicationProxy, but not sure if those are relevant.)
Eventually, I see:
Plugin is installed
Enabling VPN On Demand
And things seem to kick off more as expected from that point on.
Do we have any guidance on how to address this issue? We also have a ticket submitted with Feedback Assistant.
1) Blocked page UX
When a URL is blocked, the browser typically shows a generic error like “"Safari cannot open the page because it couldn’t load any data,” with no indication that the page was blocked by a policy.
Is there any plan to add an API that allows developers to present a custom “blocked” page or remediation action, similar to NEFilterControlProvider’s remediationMap?
Even a minimal hook (custom HTML, deep link, or support URL) would make the experience clearer for users.
2) Cross‑app link‑opening behavior
With a block rule in place, direct navigation in Safari is blocked as expected. However, tapping the same URL in a messaging app (e.g., WhatsApp) opens Safari - and the page loads, not blocked.
Repro steps:
Configure a URL Filter extension that blocks https://example.com.
Case A: Open a browser and type the URL in the address bar → blocked (expected).
Case B: Tap the same URL in WhatsApp (or another messenger) → a browser opens and the page loads (unexpected).
iOS version - 26.0
How often do we see control filter start and stop?
I read somewhere that data filter is long lived and control Filter is short lived.
When does the operating system kills the control filter process?
I have been playing around with the new URL Filtering API. I have successfully installed and configured the sample code, Installed the example app to my iPhone, and am also running the PIR server locally on my Mac.
In my input.txtpb file, I simply have 2 endpoints:
rows: [{
keyword: "instagram.com",
value: "1"
},
{
keyword: "youtube.com/shorts",
value: "1"
}]
Neither of these are blocked when I attempt to load them from either a browser, or their dedicated apps.
Are there any debugging tips I should know about?
Additionally, I have also noticed a few times I have left the filter running on my phone, after leaving my LAN (where the PIR server is running), suddenly throughout the day I'm having random, completely unrelated endpoints blocked on my phone. I thought this API was never supposed to produce false positives (without calling back to the PIR server for confirmation).
Hi guys, I need to configure a VPN to work only for specific apps. I already have a supervised iPhone, and I’ve successfully configured the VPN, but right now it applies to the whole phone. I need it to work just for some apps.
I tried using both Apple Configurator and iMazing, but I can’t find this option there.
We have a customer reporting a bunch of problems with our (Transparent Proxy Provider-based) suite. Looking at a sysdiagnose, I see that our GUI applet was killed:
Termination Reason: Namespace PORT_SPACE, Code 14123288431434181290 (Limit 305834 ports) Exceeded system-wide per-process Port Limit
Looking at the top.txt file from it, I see that it has 193,086 ports -- compared to about ~250 on one of my test systems.
Has anyone run into this? Any idea what might be causing it? (I'm still poring over the sysdiagnose, but I don't see any kernel logs around that time -- except that our process does close a dozen or so ports because of cancellation.)
Hi, I have a VPN product for macOS. When activated, it creates a virtual interface that capture all outgoing traffic for the VPN. the VPN encrypt it, and send it to the tunnel gateway. The gateway then decapsulates the packet and forwards it to the original destination.
To achieve this, The vpn modifies the routing table with the following commands:
# after packets were encoded with the vpn protocol, re-send them through
# the physical interface
/sbin/route add -host <tunnel_gateway_address_in_physical_subnet> <default_gateway> -ifp en0 > /dev/null 2>&1
# remove the default rule for en0 and replace it with scoped rule
/sbin/route delete default <default_gateway> -ifp en0 > /dev/null 2>&1
/sbin/route add default <default_gateway> -ifscope en0 > /dev/null 2>&1
# create new rule for the virtual interface that will catch all packets
# for the vpn
/sbin/route add default <tunnel_gateway_address_in_tunnel_subnet> -ifp utunX > /dev/null 2>&1
This works in most cases. However, there are scenarios where the VPN process may crash, stop responding, or another VPN product may alter the routing table. When that happens, packets may no longer go out through the correct interface.
Question: Is there a way to reliably reconstruct the routing table from scratch in such scenarios? Ideally, I would like to rebuild the baseline rules for the physical interface (e.g., en0) and then reapply the VPN-specific rules on top. Are there APIs, system utilities, or best practices in macOS for restoring the original routing configuration before reapplying custom VPN routes?
Thanks
Hi,
I am developing the browser based on Chromium, which initially relies on the nw_browser stack for discovering locally available network resources.
We have observed an issue where, after each software update—specifically, whenever additional files are written into the application bundle—a popup appears requesting the user to allow local network access, even if this permission was already granted.
The behavior is reproducible: simply overwriting files in the app bundle (we are using rsync as Chromium), even while the application is already running, causes the prompt to reappear.
We have also noticed that Chromium itself exhibits the same behavior.
Also I found the mess in system settings, it has several Google Chrome for example: https://www.loom.com/share/da401f39ab134628807d77f1ca3185f5?from_recorder=1&focus_title=1
We would like to provide a smoother experience for our users and avoid confusing them with repeated permission prompts.
Could you please advise on possible approaches or best practices to improve our update mechanism in this regard?
Hello everyone,
I'm encountering an issue while trying to publish an app on TestFlight. The app in question is Home Assistant, which I've compiled from the source. I am able to compile and install the app on my device without any problems. My company's developer account is properly configured, and I have set Xcode to automatically manage the provisioning profile.
The archive is also created successfully, but when I attempt to upload it to Apple Store Connect for testing via TestFlight, I receive the following error:
ERROR: [ContentDelivery.Uploader] Asset validation failed (90525) Missing Entitlement. The bundle 'Home Assistant.app/PlugIns/HomeAssistant-Extensions-PushProvider.appex' is missing entitlement 'com.apple.developer.networking.networkextension'. (ID: ceac6dcc-9c76-412e-8ea7-f2d2845f8013)
I've made several attempts to resolve this issue to no avail. For instance, if I add the missing capability manually, then I am informed that the provisioning profile is incorrect. However, checking the network extension settings on my company's dev account, I see nothing related to push notifications, which are located elsewhere. Thus, I am stuck in a loop where either the provisioning file is correct but the entitlement is missing, or if the entitlement is present, then the provisioning profile is deemed incorrect.
URL:https://contentdelivery.itunes.apple.com
status code: 409 (conflict)
httpBody: {
"errors" : [ {
"id" : "ceac6dcc-9c76-412e-8ea7-f2d2845f8013",
"status" : "409",
"code" : "STATE_ERROR.VALIDATION_ERROR.90525",
"title" : "Asset validation failed",
"detail" : "Missing Entitlement. The bundle 'Home Assistant.app/PlugIns/HomeAssistant-Extensions-PushProvider.appex' is missing entitlement 'com.apple.developer.networking.networkextension'."
}, {
"id" : "9ff2143b-3c00-4912-b59f-8342fa6fe5c0",
"status" : "409",
"code" : "STATE_ERROR.VALIDATION_ERROR.90525",
"title" : "Asset validation failed",
"detail" : "Missing Entitlement. The bundle 'Home Assistant.app' is missing entitlement 'com.apple.developer.networking.networkextension'."
} ]
}
=======================================
2024-01-10 23:19:35.506 ERROR: [ContentDelivery.Uploader] Asset validation failed (90525) Missing Entitlement. The bundle 'Home Assistant.app/PlugIns/HomeAssistant-Extensions-PushProvider.appex' is missing entitlement 'com.apple.developer.networking.networkextension'. (ID: ceac6dcc-9c76-412e-8ea7-f2d2845f8013)
2024-01-10 23:19:35.506 DEBUG: [ContentDelivery.Uploader] Error Domain=ContentDelivery Code=90525 "Asset validation failed" UserInfo={NSLocalizedFailureReason=Missing Entitlement. The bundle 'Home Assistant.app/PlugIns/HomeAssistant-Extensions-PushProvider.appex' is missing entitlement 'com.apple.developer.networking.networkextension'. (ID: ceac6dcc-9c76-412e-8ea7-f2d2845f8013), NSUnderlyingError=0x6000022b6430 {Error Domain=IrisAPI Code=-19241 "Asset validation failed" UserInfo={status=409, detail=Missing Entitlement. The bundle 'Home Assistant.app/PlugIns/HomeAssistant-Extensions-PushProvider.appex' is missing entitlement 'com.apple.developer.networking.networkextension'., id=ceac6dcc-9c76-412e-8ea7-f2d2845f8013, code=STATE_ERROR.VALIDATION_ERROR.90525, title=Asset validation failed, NSLocalizedFailureReason=Missing Entitlement. The bundle 'Home Assistant.app/PlugIns/HomeAssistant-Extensions-PushProvider.appex' is missing entitlement 'com.apple.developer.networking.networkextension'., NSLocalizedDescription=Asset validation failed}}, iris-code=STATE_ERROR.VALIDATION_ERROR.90525, NSLocalizedDescription=Asset validation failed}
2024-01-10 23:19:35.507 ERROR: [ContentDelivery.Uploader] Asset validation failed (90525) Missing Entitlement. The bundle 'Home Assistant.app' is missing entitlement 'com.apple.developer.networking.networkextension'. (ID: 9ff2143b-3c00-4912-b59f-8342fa6fe5c0)
2024-01-10 23:19:35.507 DEBUG: [ContentDelivery.Uploader] Error Domain=ContentDelivery Code=90525 "Asset validation failed" UserInfo={NSLocalizedFailureReason=Missing Entitlement. The bundle 'Home Assistant.app' is missing entitlement 'com.apple.developer.networking.networkextension'. (ID: 9ff2143b-3c00-4912-b59f-8342fa6fe5c0), NSUnderlyingError=0x6000022b6640 {Error Domain=IrisAPI Code=-19241 "Asset validation failed" UserInfo={status=409, detail=Missing Entitlement. The bundle 'Home Assistant.app' is missing entitlement 'com.apple.developer.networking.networkextension'., id=9ff2143b-3c00-4912-b59f-8342fa6fe5c0, code=STATE_ERROR.VALIDATION_ERROR.90525, title=Asset validation failed, NSLocalizedFailureReason=Missing Entitlement. The bundle 'Home Assistant.app' is missing entitlement 'com.apple.developer.networking.networkextension'., NSLocalizedDescription=Asset validation failed}}, iris-code=STATE_ERROR.VALIDATION_ERROR.90525, NSLocalizedDescription=Asset validation failed}
2024-01-10 23:19:35.507 DEBUG: [ContentDelivery.Uploader] swinfo errors: (
"Error Domain=ContentDelivery Code=90525 \"Asset validation failed\" UserInfo={NSLocalizedFailureReason=Missing Entitlement. The bundle 'Home Assistant.app/PlugIns/HomeAssistant-Extensions-PushProvider.appex' is missing entitlement 'com.apple.developer.networking.networkextension'. (ID: ceac6dcc-9c76-412e-8ea7-f2d2845f8013), NSUnderlyingError=0x6000022b6430 {Error Domain=IrisAPI Code=-19241 \"Asset validation failed\" UserInfo={status=409, detail=Missing Entitlement. The bundle 'Home Assistant.app/PlugIns/HomeAssistant-Extensions-PushProvider.appex' is missing entitlement 'com.apple.developer.networking.networkextension'., id=ceac6dcc-9c76-412e-8ea7-f2d2845f8013, code=STATE_ERROR.VALIDATION_ERROR.90525, title=Asset validation failed, NSLocalizedFailureReason=Missing Entitlement. The bundle 'Home Assistant.app/PlugIns/HomeAssistant-Extensions-PushProvider.appex' is missing entitlement 'com.apple.developer.networking.networkextension'., NSLocalizedDescription=Asset validation failed}}, iris-code=STATE_ERROR.VALIDATION_ERROR.90525, NSLocalizedDescription=Asset validation failed}",
"Error Domain=ContentDelivery Code=90525 \"Asset validation failed\" UserInfo={NSLocalizedFailureReason=Missing Entitlement. The bundle 'Home Assistant.app' is missing entitlement 'com.apple.developer.networking.networkextension'. (ID: 9ff2143b-3c00-4912-b59f-8342fa6fe5c0), NSUnderlyingError=0x6000022b6640 {Error Domain=IrisAPI Code=-19241 \"Asset validation failed\" UserInfo={status=409, detail=Missing Entitlement. The bundle 'Home Assistant.app' is missing entitlement 'com.apple.developer.networking.networkextension'., id=9ff2143b-3c00-4912-b59f-8342fa6fe5c0, code=STATE_ERROR.VALIDATION_ERROR.90525, title=Asset validation failed, NSLocalizedFailureReason=Missing Entitlement. The bundle 'Home Assistant.app' is missing entitlement 'com.apple.developer.networking.networkextension'., NSLocalizedDescription=Asset validation failed}}, iris-code=STATE_ERROR.VALIDATION_ERROR.90525, NSLocalizedDescription=Asset validation failed}"
)
I have added a Network Extension to my iOS project to use the WireGuard library. Everything was working fine up to Xcode 16, but after updating, I’m facing a build issue.
The build fails with the following error:
No such file or directory: '@rpath/WireGuardNetworkExtensioniOS.debug.dylib'
I haven’t explicitly added any .dylib to my project. The Network Extension target builds and runs fine on Xcode 16.
In my app I have Local Push connectivity for local push notifications. My app has proper entitlment granted by Apple and NEAppPushProvider was working perfectly on older iOS versions before iOS26.
The problem I faced with iOS26: when i enable VPN - NEAppPushProvider stops with reason
/** @const NEProviderStopReasonNoNetworkAvailable There is no network connectivity. */
case noNetworkAvailable = 3.
But device is still connected to proper SSID that is included to matchSSIDs.
I discovered it only happens if my VPN config file include this line
redirect-gateway def1
without that line NEAppPushProvider works as expected with enabled VPN.
I use OpenVPN app.
Is it a bug of iOS26 or I need some additional setup?
Please help!
We have observed an internet access issue after the device enters idle mode on iOS 26 beta 9. Although the Ivanti Secure Access Client appears connected, users are unable to access any resources (internet or intranet) after unlocking the device from idle. When we check the log socket connection looks not disrupted, packets are tunnelled but no resource access. Split tunnel enabled and proxy PAC configured. This was observed on both iOS and iPadOS 26 beta.
Steps to reproduce:
Connecting to the internet, launching the Ivanti client, locking the device, and then unlocking it after a brief period of idle. The issue occurs when the VPN remains connected but no resources are accessible.
I can develop a PacketTunnelProvider on Mac with xcode.
I work with my self codesign.
But when I sign it with Developer ID after read https://developer.apple.com/forums/thread/737894 , it still fail when I turn on the vpn .
I’m developing a iOS VPN app, and I need to execute a task in the main app even when it’s in the background or killed state. I know the Network Extension continues running during those times. Is there a way for the extension to immediately notify the app or trigger a task on the app side?
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).