Contents

NEURLFilterManager

A class you use to configure and control a URL filter.

Declaration

class NEURLFilterManager

Overview

The system performs URL filtering on your behalf according to your configuration and URL data set. The system filters all URL requests initiated with the WebKit and URLSession APIs.

During URL filtering, the system performs sub-URL generation to enumurate all possible sub-URLs for the URL in question. For example, this URL:

https://www.sub1.example.com/a/b/c?id=123#fragment

Parses into the following sub-URLs:

  • example.com

  • example.com/

  • example.com/a

  • example.com/a/

  • example.com/a/b

  • example.com/a/b/

  • example.com/a/b/c

  • example.com/a/b/c/

  • example.com/a/b/c/?id=123

  • example.com/a/b/c/?id=123#fragment

  • example.com/a/b/c?id=123

  • example.com/a/b/c?id=123#fragment

  • example.com:443

  • example.com:443/

  • example.com:443/a

  • example.com:443/a/

  • example.com:443/a/b

  • example.com:443/a/b/

  • example.com:443/a/b/c

  • example.com:443/a/b/c/

  • example.com:443/a/b/c/?id=123

  • example.com:443/a/b/c/?id=123#fragment

  • example.com:443/a/b/c?id=123

  • example.com:443/a/b/c?id=123#fragment

  • sub1.example.com

  • sub1.example.com/

  • sub1.example.com/a

  • sub1.example.com/a/

  • sub1.example.com/a/b

  • sub1.example.com/a/b/

  • sub1.example.com/a/b/c

  • sub1.example.com/a/b/c/

  • sub1.example.com/a/b/c/?id=123

  • sub1.example.com/a/b/c/?id=123#fragment

  • sub1.example.com/a/b/c?id=123

  • sub1.example.com/a/b/c?id=123#fragment

  • sub1.example.com:443

  • sub1.example.com:443/

  • sub1.example.com:443/a

  • sub1.example.com:443/a/

  • sub1.example.com:443/a/b

  • sub1.example.com:443/a/b/

  • sub1.example.com:443/a/b/c

  • sub1.example.com:443/a/b/c/

  • sub1.example.com:443/a/b/c/?id=123

  • sub1.example.com:443/a/b/c/?id=123#fragment

  • sub1.example.com:443/a/b/c?id=123

  • sub1.example.com:443/a/b/c?id=123#fragment

The manager matches each of these sub-URLs against your Bloom filter and then against the PIR URL database if there’s a Bloom filter match. The verdict determines if the app blocks the requested URL. Note that the manager Punycodes the requested URL before parsing; be sure to Punycode your own URL dataset before constructing your Bloom filter and PIR database.

Neither the Bloom filter nor PIR supports wildcards or regular expressions. For a more flexible URL matching solution, use the urlParsingConfiguration property to select the URL components, including the scheme, domain, path, query, and fragment, that you want to include in the parsing results. You can also use the urlParsingRegularExpression property to implement custom parsing.

Instances of this class are thread-safe.

Configure the PIR server

URL filtering requires that your app’s information property list contain a top-level NSPIRConfiguration dictionary. The dictionary includes two keys:

PIRServerURL

(Required) The URL of the PIR server. The value of this key is equivalent to the pirServerURL property.

PrivacyPassIssuerURL

(Optional) The URL of the Privacy Pass Issuer. The value of this key is equivalent to the pirPrivacyPassIssuerURL property. If absent, the PrivacyPassIssuerURL defaults to the value of PIRServerURL.

An NSPIRConfiguration dictionary may look like this example:

<key>NSPIRConfiguration</key>
<dict>
    <key>PIRServerURL</key>
    <string>https://pir.example.com</string>
    <key>PrivacyPassIssuerURL</key>
    <string>https://issuer.example.com</string>
</dict>

See the PIRService - NEURLFilter documentation for updated security guidance to configure your PIR server to support a URL filter.

Topics

Obtaining the shared instance

Working with a Private Information Retrieval server

Working with the filter configuration

Customizing filter parsing behavior

Working with filter statuses

Managing filter life cycle

Producing filtering reports

Identifying app and extension bundles

Handling errors

Describing the filter

See Also

URL filters