Filter and tunnel network traffic with NetworkExtension

Hi, my name is Maria Alice Dos Santos, and I am part of the Internet Technologies team at Apple. I’m here to tell you all about the Network Extension framework and its latest advances in iOS and macOS 26.

Network Extension is a framework that provides a rich suite of APIs for you to build apps that extend and customize networking capabilities on Apple platforms.

Network Extension apps work seamlessly throughout the networking stack, integrated closely with Network framework, CFNetwork, WebKit, and Sockets API as well as system-level components like routing, traffic policy, and all types of system management. This allows Network Extension to achieve the desired functionalities in the most optimized manner, in terms of networking performance and security.

Network Extension is a powerful framework that lets you alter networking across the system. To make sure your app works consistently with other apps and with the system, it’s essential to pick the right API for the type of app you want to build.

In this session, I will introduce you to the wide range of apps you can create using Network Extension framework, and the ways you can create apps to access remote resources by using relays and VPNs. I will also discuss how you can create content filters using Network Extension, including a new way to create a URL-based filter in iOS and macOS 26.

Network Extension framework supports various ways for your apps to customize and extend networking capabilities.

On iOS, the Wi-Fi Management and Hotspots APIs allow your apps to configure Wi-Fi settings and interact with Wi-Fi hotspots. This includes the new NEHotspotHelper extension API in iOS 26.

iOS apps can also use the Local Push API. This is for apps used on networks without access to the Apple Push Notification service, like cruise ships or hospitals. This lets you support features like text messaging and Voice-over-IP calls while on the restricted network.

You can build a security app to protect DNS traffic from attacks by using the DNS Configuration and Proxy API.

You can install a DNS configuration and use this built-in encrypted DNS protocols, or proxy DNS traffic over your own security channel.

Mac apps can use the Transparent Proxy API, for example, to divert traffic for a specific website to a cloud-based security service for authentication and authorization.

You can also build apps that let people access remote resources securely, or apps that protect people by securely and privately filtering the content they access on the network.

Secure Remote Access is a broad category that covers many different ways people connect to internal systems securely from outside, or to protect personal traffic on unsecured networks by tunneling traffic from a device to a remote server.

With Network Extension, there are two main approaches to consider. Network relays and IP-based VPN. Use the one that best suits your need depending on the type of traffic you want to tunnel. Consider Network relays instead of traditional VPNs when you want to tunnel TCP or UDP traffic to access specific apps. For example, cloud-hosted enterprise apps, like for email or collaboration, are a great fit for relays. The MASQUE protocol enables secure proxying, optimized for performance. It can easily be integrated into modern cloud environments. And since the platform has built-in support for relays, you don't need to build your own extension to take advantage of it. You can just configure your relay settings and authentication using NERelayManager API, or through a configuration profile from the MDM server.

If you want to tunnel IP traffic, use the IP-based VPN option.

For example, IP-based VPNs can be used in the enterprise to extend the corporate network to employees, giving them full network access as if they were physically in the office. This solution is ideal for long-term trusted employees who need persistent or full tunnel access to the company network.

Or, highly regulated organizations, with stringent network security policies, may need to send all traffic from their managed devices through the corporate network.

People may also want to protect their traffic with a VPN over unsecured networks to preserve their privacy and anonymity.

To create an IP-based VPN tunnel, use the NEVPNManager API to leverage one of the built-in protocols, IKEv2 or IPsec, or use the NEPacketTunnelProvider to implement your own custom tunneling protocols. When creating an IP-based VPN, your implementation tells the system what traffic to tunnel, with specific included and excluded routes. On macOS, the routing table could be modified outside of your app by an administrator or another process. More precise routes could interfere with your VPN routes. Network Extension lets your app enforce its VPN routes to ensure they take precedence and are honored at all times.

Network Extension makes it easy for your app to manage your tunnels routing requirements. For a split-tunnel VPN, you can enable the enforceRoutes option to enforce both the included routes and excluded routes. For a full-tunnel VPN, you can turn on the includeAllNetworks option to enforce all traffic to be routed through your tunnel. When this option is enabled, any specified excludedRoutes will have no effect. Both of these options support configurable exceptions to allow a system-defined set of traffic to go outside the tunnel so that essential services work as expected while your VPN is running. For instance, turn on excludeLocalNetworks if you want local network services like AirDrop and AirPlay to bypass tunnel.

Or turn on other exceptions to allow services like calls and messaging, the Apple Push Notification service, and device communication to bypass the tunnel. Most of these exceptions are enabled by default, but allow customization to fit your security need.

Network Extension is the supported API to build a VPN app. It works seamlessly with other networking and system components. Building a VPN app with anything else is highly discouraged.

Avoid using Packet Filter or directly modifying the routing table on the Mac. This is not supported and risk clashing with traffic filtering and routing rules installed by the system or other apps. If your VPN app doesn’t use Network Extension today, you should migrate as soon as possible. This will ensure your app remains compatible with the system and all of its key functionality that your customers expect, like working in harmony with features such as AirDrop, Mac Virtual Display, Xcode, as well as Continuity features like sidecar. Use NEPacketTunnelProvider only to tunnel IP traffic. Using it to accomplish any other goals is not recommended. NEPacketTunnelProvider operates at the IP layer, and will not receive flow or application level metadata needed to do other things, like proxying DNS requests or content filtering.

If your goal is to filter content, use the Content Filter API, which I will cover next. The Content Filter API allows you to introspect traffic on device to monitor or to make filtering decisions as traffic flows through the networking stack. A common use case is a personal firewall, which examines and blocks traffic flows that are deemed malicious for a personal device. Or an enterprise traffic monitoring app, for managed devices, to monitor all inbound and outbound network traffic, for employees in highly secure environments.

Create a subclass of one or both of the content filter providers to get the desired traffic.

NEFilterDataProvider provides you with TCP and UDP flows, as well as other IP protocol traffic, such as ICMP.

For mac apps, a subclass of NEFilterPacketProvider will get Layer 2 packets.

Filter providers cannot modify traffic, but simply provide a filter verdict to the system, either to allow or drop the flow. iOS system-wide content filter is supported on supervised devices only.

Content filters using NEFilterDataProvider and NEFilterPacketProvider are great if your app needs to filter content based on the traffic flow or through packet inspection. But sometimes you might want to filter based on application-level metadata, like the URL. With a traditional content filter, your app can make filtering decisions based on the traffic-level information, like the host and port of this HTTPS request.

But some apps may not want to block entire sites, but instead filter specific resources.

HTTPS requests are encrypted, so a traditional content filter would not have access to the necessary detail of the URL request to make an accurate filtering decision, like the specific resource requested, or query parameters in the URL.

Starting in iOS 26, you can create a new type of filter, a URL Filter, which makes content filtering decisions based on the full URL.

Network Extension URL Filter allows you to filter system-wide HTTP and HTTPS requests, matching against the full URL of the request. This technology allows you to build apps that block specific resources on the internet. For example, you can build a parental control app to protect children from harmful websites. An app for schools might use a filter to prevent students from accessing social media, gambling, or other sensitive content across many websites. Or enterprises may want to block non-work-related content for employees.

At Apple, we believe privacy is a fundamental human right. URL Filtering uses state-of-the-art cryptography to let you build apps that effectively make filtering decisions based on the full URL, without compromising privacy.

URLs can reveal sensitive information like unique identifiers, or browsing history. Network Extension is designed to allow you to build a content filter that makes accurate filtering decisions based on the full URL. But the URL contents are not revealed to the app, and all database queries to the backend servers are anonymized to protect privacy. The entire chain of backend servers, both Apple’s and your servers, will have no access to any of the content and identity information. URL Filtering is performed with your URL data set, containing URLs you want to block. You provide an on-device prefilter and an off-device database server for URL lookups.

The system performs the entire filtering process on your behalf with your data set. Your app does not execute in the filtering path and has no access to traffic.

The system performs on-device prefilter to improve performance and may perform off-device database lookups for final verdicts. All off-device database exchanges are protected to ensure content and identity privacy preservation. With strong privacy preservation, URL Filters are supported on both managed and unmanaged devices.

Before I go into how the feature works, I will introduce the technologies that serve as the building blocks. There are four technologies that URL Filter relies on, and they are: Bloom filters, Private Information Retrieval, Privacy Pass, and Oblivious HTTP Relay.

I will start with Bloom filters.

For URL Filtering, Network Extension will use the Bloom filter you build with your URL data set containing URLs you want to block. A Bloom filter is constructed from a predefined data set by hashing each element in the set using multiple hash functions and setting the corresponding bits in a fixed-size bit array.

Once built, you can use the Bloom filter to test whether an element is a member of the set. Bloom filters will never produce false negatives, but may produce false positives.

Your Bloom filter will be used as a prefilter for a quick check. If the match is negative, the checked URL is definitively not part of your URL data set and will be allowed immediately without further verification. If the match is positive, the match result is not definitive due to potential false positives. Further verification, such as an off-device database lookup, will be necessary to reach a conclusive verdict.

Using a Bloom filter as a prefilter greatly reduces off-device database lookups, improving performance.

The second key technology is Private Information Retrieval. Private Information Retrieval, or PIR, enables a client to perform a database lookup against a server hosting a keyword-value database without revealing the queried keyword and the lookup result to the server. It relies on Homomorphic Encryption, which allows computation on encrypted data, enabling Private Information Retrieval server to perform database lookups on encrypted queries. So server has no access to the query or the response contents.

Here's how it works. The Client on device generates the encryption key and keeps it private on device, which encrypts all queries sent to the server. The server then uses the encrypted queries to perform database lookups.

The server cannot decrypt the query at any time during processing.

The server sends back encrypted responses to the Client. The Client receives and decrypts responses on device. Only the Client, not even the server, can decrypt the response from the server. The Client then uses the lookup results. Private Information Retrieval is already a technology used for many privacy-preserving features, like the Live Caller ID Lookup API.

For URL Filtering, Private Information Retrieval server performs URL lookups with encrypted queries, which allows the server to provide filtering capabilities without learning which URLs are being requested and what results are being returned. The third key technology is Privacy Pass.

Private Information Retrieval uses Privacy Pass for anonymous authentication to your server. This lets you ensure your server is only responding to queries from authenticated and authorized devices, without being able to track individual request histories.

Each device goes through an initial attestation to get a long-term credential, which then can be used to retrieve a collection of cryptographically blind-signed tokens from the Privacy Pass Issuer. The device uses these tokens to authenticate with your server without revealing identity. The last key technology is Oblivious HTTP Relay.

Oblivious HTTP Relay is a privacy-preserving proxy that hides the IP address of the origin, which helps prevent the server from tracking and linking requests over time.

It has three entities, the Client, the Relay, and the Gateway.

The Client encrypts requests using the public key of the Gateway. It then sends the encrypted request to the Relay. The relay removes the client’s IP address from the incoming requests and forwards the requests to the Gateway. The Gateway decrypts the request and sends them to the target resource. The Relay doesn’t learn anything about the content of the requests, while the Gateway and the target resource don’t know where the traffic is coming from.

I have introduced the four technologies. I will now walk through how to set up the solution and how URL Filtering works.

Starting with your URL Filter app installed on the device, your app will provide Network Extension, your URL data set, as a Bloom filter, as well as a URL database hosted on your Private Information Retrieval server, servicing URL lookups.

Your server setup also includes a Privacy Pass Issuer for anonymous authentication.

Your URL Filter app tells Network Extension where to reach your Private Information Retrieval server, Your app also implements a new app extension to fetch your Bloom filter onto device.

All database queries and responses are exchanged over the Oblivious HTTP Relay hosted by Apple.

This means the Oblivious HTTP Gateway will be hosted by you to forward traffic to your server.

Request using Oblivious HTTP for URL Filtering flow through an Apple-hosted Oblivious HTTP Relay.

This is a capability that you must apply for, using the request form available in the documentation. Apple will validate your server configuration for Oblivious HTTP Relay before approval.

This must be completed before you can distribute your app on the App Store, with TestFlight, ad-hoc, developer-ID, or enterprise-signed builds.

Development-signed builds are exempt from this requirement, allowing you to start building and testing your filtering app right away.

With all the pieces in place, I will work-through an example to show how URL Filtering works.

URL Filtering will be performed solely by the system. Your app and app extension do not execute in this path. The system will examine all the URL requests, checking each URL against your data set.

In this example, a browser initiates an URL request to some specific resource at example.com. The system will check the requested URL against the Bloom filter first. A negative match from the Bloom filter means for sure the URL is not in your data set.

The URL will be allowed, and the browser will proceed with the HTTP request.

Now the browser initiates another URL request for a different resource on example.com, which gets a positive match from the Bloom filter. Due to potential false positives, a positive match means the URL may be in your data set.

In this case, the system will perform an off-device lookup with your Private Information Retrieval server by sending an encrypted query to the server. At the server, Database Lookup is performed with the received encrypted query to get a match result. The server has no knowledge of what is being queried or what is being returned. The server encrypts the match result and replies back.

The system on device decrypts the response. If the returned result indicates a match, the URL will be denied and the browser will fail the request.

Network Extension URL Filtering is system-wide. Checking all HTTP requests sent via Apple networking APIs, such as WebKit and URLSession. However, for apps that are not using these networking APIs, their HTTP traffic will not be checked automatically by the system. For those of you building a web browser or any app not using WebKit or URLSession, adopt the participation API to check all URL requests before sending. Call NEURLFilter verdictForURL with the URL of the request, and honor the returned verdict by failing the request if the URL is denied. Now that you know how URL Filters work, I will explain the steps for you to create one. You will set up your Private Information Retrieval server and create your Bloom filter. Then, build your URL Filter app and app extension.

I will start with Private Information Retrieval server setup.

Use the sample code to get started, which provides a sample Private Information Retrieval server. At the project repository, you will find sample implementations of the Private Information Retrieval server as well as a Privacy Pass Issuer.

To customize the server for URL Filtering, create an use case with a specific name format. The use case name must have the bundle identifier of your app as the prefix, followed by the string url.filtering.

Private Information Retrieval server stores data records in a key-value format. For Network Extension URL Filter, format your data set accordingly, setting each record with the URL string as the key and the value to the integer 1. The second step is to build your Bloom filter. Build the Bloom filter with your URL data set with the specified hash functions and method, documented for the NEURLFilterControlProvider API Depending on how static or dynamic your data set is, decide how to deliver your Bloom filter onto device and how often you want to update it.

For static data set that rarely changes, include your Bloom filter in your app bundle and let your app extension fetch it from your app bundle resources. Subsequent Bloom filter updates can be included together with your app updates. For dynamic data set that changes frequently, configure the system to trigger fetching periodically. When the system triggers the fetch, your app extension can download the Bloom Filter from your server. Next step is to build your URL Filter app. Add the new Network Extension url-filter-provider entitlement to your app, which allows you to use the URL Filter APIs. Use NEURLFilterManager API in your app to create configuration and manage your URL Filter. Import Network Extension Framework and use the NEURLFilterManager shared singleton instance. You can configure and enable your URL Filter in a few steps.

First, load the latest snapshot of the URL Filter configuration from disk if any. Then set the required attribute in your configuration to tell the system how to reach and talk to your Private Information Retrieval server, Configure other optional parameters to fine tune your URL Filter.

Finally, enable and save your URL Filter configuration. Now your URL Filter will take effect.

URL Filter supports both consumer as well as enterprise deployments. For Scale enterprise deployment of your URL Filter app, push the URL Filter configuration profile via Mobile Device Management onto managed devices.

The existing Content Filter payload now supports: a new key to enable the URL Filter feature, as well as a new dictionary to configure the URLFilterParameters. MDM URL Filter configuration requires device supervision.

Next step is to build your URL Filter App Extension.

To create your app extension, use the new URL Filter app extension template in Xcode. Implement the NEURLFilterControlProvider protocol as your app extension. This protocol allows your app extension to fetch your Bloom filter onto device. Import the Network Extension framework and implement the NEURLFilterControlProvider protocol. Your implementation of the fetchPrefilter function, will be invoked by the system, to fetch your Bloom filter, according to the interval you configured. In your implementation, fetch the Bloom filter and return it to the system. Your implementation can retrieve your Bloom filter data either from your app bundle resources or by downloading it from your server. And before you submit your app to the App Store or TestFlight, make sure that your capability request has been submitted and approved, so that requests can flow to your Oblivious HTTP Gateway. Network Extension is such a powerful framework that allows you to tunnel and filter traffic and much more. Review how you use Network Extension. Use the appropriate API that helps you build apps that deliver the desired functionality and work well with the system. Use Network relays for secure remote access for TCP and UDP traffic. Use Network Extension to build your VPN solutions. Create powerful content filters using Network Extension URL Filter API. To get you started, check out the sample server and app. Thanks for watching.