Network Extension Framework Entitlements

At WWDC 2015 Apple announced two major enhancements to the Network Extension framework:

• Network Extension providers — These are app extensions that let you insert your code at various points within the networking stack, including:

  • Packet tunnels via NEPacketTunnelProvider
  • App proxies via NEAppProxyProvider
  • Content filters via NEFilterDataProvider and NEFilterControlProvider

• Hotspot Helper (NEHotspotHelper) — This allows you to create an app that assists the user in navigating a hotspot (a Wi-Fi network where the user must interact with the network in order to get access to the wider Internet).

Originally, using any of these facilities required authorisation from Apple. Specifically, you had to apply for, and be granted access to, a managed capability. In Nov 2016 this policy changed for Network Extension providers. Any developer can now use the Network Extension provider capability like they would any other capability.

There is one exception to this rule: Network Extension app push providers, introduced by iOS 14 in 2020, still requires that Apple authorise the use of a managed capability. To apply for that, follow the link in Local Push Connectivity.

Also, the situation with Hotspot Helpers remains the same: Using a Hotspot Helper, requires that Apple authorise that use via a managed capability. To apply for that, follow the link in Hotspot Helper.

IMPORTANT Pay attention to this quote from the documentation:

NEHotspotHelper is only useful for hotspot integration. There are both technical and business restrictions that prevent it from being used for other tasks, such as accessory integration or Wi-Fi based location.

The rest of this document answers some frequently asked questions about the Nov 2016 change.

#1 — Has there been any change to the OS itself?

No, this change only affects the process by which you get the capabilities you need in order to use existing Network Extension framework facilities. Previously these were managed capabilities, meaning their use was authorised by Apple. Now, except for app push providers and Hotspot Helper, you can enable the necessary capabilities using Xcode’s Signing & Capabilities editor or the Developer website.

IMPORTANT Some Network Extension providers have other restrictions on their use. For example, a content filter can only be used on a supervised device. These restrictions are unchanged. See TN3134 Network Extension provider deployment for the details.

#2 — How exactly do I enable the Network Extension provider capability?

In the Signing & Capabilities editor, add the Network Extensions capability and then check the box that matches the provider you’re creating.

In the Certificates, Identifiers & Profiles section of the Developer website, when you add or edit an App ID, you’ll see a new capability listed, Network Extensions. Enable that capability in your App ID and then regenerate the provisioning profiles based on that App ID.

A newly generated profile will include the com.apple.developer.networking.networkextension entitlement in its allowlist; this is an array with an entry for each of the supported Network Extension providers. To confirm that this is present, dump the profile as shown below.

$ security cms -D -i NETest.mobileprovision 
…
<plist version="1.0">
<dict>
   …
   <key>Entitlements</key>
   <dict>
       <key>com.apple.developer.networking.networkextension</key>
       <array> 
           <string>packet-tunnel-provider</string>
           <string>content-filter-provider</string> 
           <string>app-proxy-provider</string> 
           … and so on …
       </array>
       …
   </dict>
   …
</dict>
</plist>

#3 — I normally use Xcode’s Signing & Capabilities editor to manage my entitlements. Do I have to use the Developer website for this?

No. Xcode 11 and later support this capability in the Signing & Capabilities tab of the target editor (r. 28568128 ).

#4 — Can I still use Xcode’s “Automatically manage signing” option?

Yes. Once you modify your App ID to add the Network Extension provider capability, Xcode’s automatic code signing support will include the entitlement in the allowlist of any profiles that it generates based on that App ID.

#5 — What should I do if I previously applied for the Network Extension provider managed capability and I’m still waiting for a reply?

Consider your current application cancelled, and use the new process described above.

#6 — What should I do if I previously applied for the Hotspot Helper managed capability and I’m still waiting for a reply?

Apple will continue to process Hotspot Helper managed capability requests and respond to you in due course.

#7 — What if I previously applied for both Network Extension provider and Hotspot Helper managed capabilities?

Apple will ignore your request for the Network Extension provider managed capability and process it as if you’d only asked for the Hotspot Helper managed capability.

#8 — On the Mac, can Developer ID apps host Network Extension providers?

Yes, but there are some caveats:

• This only works on macOS 10.15 or later.

• Your Network Extension provider must be packaged as a system extension, not an app extension.

• You must use the *-systemextension values for the Network Extension entitlement (com.apple.developer.networking.networkextension).

For more on this, see Exporting a Developer ID Network Extension.

#9 — After moving to the new process, my app no longer has access to the com.apple.managed.vpn.shared keychain access group. How can I regain that access?

Access to this keychain access group requires another managed capability. If you need that, please open a DTS tech support incident and we’ll take things from there.

IMPORTANT This capability is only necessary if your VPN supports configuration via a configuration profile and needs to access credentials from that profile (as discussed in the Profile Configuration section of the NETunnelProviderManager Reference). Many VPN apps don’t need this facility.

Opening a DTS tech support incident (TSI) will consume a TSI asset. However, as this is not a technical issue but an administrative one, we’ll assign a replacement TSI asset back to your account.

If you were previously granted the Network Extension managed capability (via the process in place before Nov 2016), make sure you mention that; restoring your access to the com.apple.managed.vpn.shared keychain access group should be straightforward in that case.

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

Revision History

• 2023-01-11 Added a discussion of Network Extension app push providers. Added a link to Exporting a Developer ID Network Extension. Added a link to TN3134. Made significant editorial changes.

• 2020-02-27 Fixed the formatting. Updated FAQ#3. Made minor editorial changes.

• 2020-02-16 Updated FAQ#8 to account for recent changes. Updated FAQ#3 to account for recent Xcode changes. Made other editorial changes.

• 2016-01-25 Added FAQ#9.

• 2016-01-6 Added FAQ#8.

• 2016-11-11 Added FAQ#5, FAQ#6 and FAQ#7.

• 2016-11-11 First posted.