General: Forums subtopic: App & System Services > Networking TN3151 Choosing the right networking API Networking Overview document — Despite the fact that this is in the archive, this is still really useful. TLS for App Developers forums post Choosing a Network Debugging Tool documentation WWDC 2019 Session 712 Advances in Networking, Part 1 — This explains the concept of constrained networking, which is Apple’s preferred solution to questions like How do I check whether I’m on Wi-Fi? TN3135 Low-level networking on watchOS TN3179 Understanding local network privacy Adapt to changing network conditions tech talk Understanding Also-Ran Connections forums post Extra-ordinary Networking forums post Foundation networking: Forums tags: Foundation, CFNetwork URL Loading System documentation — NSURLSession, or URLSession in Swift, is the recommended API for HTTP[S] on Apple platforms. Moving to Fewer, Larger Transfers forums post Testing Background Session Code forums post Network framework: Forums tag: Network Network framework documentation — Network framework is the recommended API for TCP, UDP, and QUIC on Apple platforms. Building a custom peer-to-peer protocol sample code (aka TicTacToe) Implementing netcat with Network Framework sample code (aka nwcat) Configuring a Wi-Fi accessory to join a network sample code Moving from Multipeer Connectivity to Network Framework forums post NWEndpoint History and Advice forums post Network Extension (including Wi-Fi on iOS): See Network Extension Resources Wi-Fi Fundamentals TN3111 iOS Wi-Fi API overview Wi-Fi Aware framework documentation Wi-Fi on macOS: Forums tag: Core WLAN Core WLAN framework documentation Wi-Fi Fundamentals Secure networking: Forums tags: Security Apple Platform Security support document Preventing Insecure Network Connections documentation — This is all about App Transport Security (ATS). WWDC 2017 Session 701 Your Apps and Evolving Network Security Standards [1] — This is generally interesting, but the section starting at 17:40 is, AFAIK, the best information from Apple about how certificate revocation works on modern systems. Available trusted root certificates for Apple operating systems support article Requirements for trusted certificates in iOS 13 and macOS 10.15 support article About upcoming limits on trusted certificates support article Apple’s Certificate Transparency policy support article What’s new for enterprise in iOS 18 support article — This discusses new key usage requirements. Technote 2232 HTTPS Server Trust Evaluation Technote 2326 Creating Certificates for TLS Testing QA1948 HTTPS and Test Servers Miscellaneous: More network-related forums tags: 5G, QUIC, Bonjour On FTP forums post Using the Multicast Networking Additional Capability forums post Investigating Network Latency Problems forums post WirelessInsights framework documentation iOS Network Signal Strength forums post Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com" [1] This video is no longer available from Apple, but the URL should help you locate other sources of this info.

Hi All, I am trying to write an NWProtocolFramerImplementation that will run after Websockets. I would like to achieve two goals with this Handle the application-layer authentication handshake in-protocol so my external application code can ignore it Automatically send pings periodically so my application can ignore keepalive I am running into trouble because the NWProtocolWebsocket protocol parses websocket metadata into NWMessage's and I don't see how to handle this at the NWProtocolFramerImplementation level Here's what I have (see comments for questions) class CoolProtocol: NWProtocolFramerImplementation { static let label = "Cool" private var tempStatusCode: Int? required init(framer: NWProtocolFramer.Instance) {} static let definition = NWProtocolFramer.Definition(implementation: CoolProtocol.self) func start(framer: NWProtocolFramer.Instance) -> NWProtocolFramer.StartResult { return .willMarkReady } func wakeup(framer: NWProtocolFramer.Instance) { } func stop(framer: NWProtocolFramer.Instance) -> Bool { return true } func cleanup(framer: NWProtocolFramer.Instance) { } func handleOutput(framer: NWProtocolFramer.Instance, message: NWProtocolFramer.Message, messageLength: Int, isComplete: Bool) { // How to write a "Message" onto the next protocol handler. I don't want to just write plain data. // How to tell the websocket protocol framer that it's a ping/pong/text/binary... } func handleInput(framer: NWProtocolFramer.Instance) -> Int { // How to handle getting the input from websockets in a message format? I don't want to just get "Data" I would like to know if that data is // a ping, pong, text, binary, ... } } If I implementing this protocol at the application layer, here's how I would send websocket messages class Client { ... func send(string: String) async throws { guard let data = string.data(using: .utf8) else { return } let metadata = NWProtocolWebSocket.Metadata(opcode: .text) let context = NWConnection.ContentContext( identifier: "textContext", metadata: [metadata] ) self.connection.send( content: data, contentContext: context, isComplete: true, completion: .contentProcessed({ [weak self] error in ... }) ) } } You see at the application layer I have access to this context object and can access NWProtocolMetadata on the input and output side, but in NWProtocolFramer.Instance I only see final func writeOutput(data: Data) which doesn't seem to include context anywhere. Is this possible? If not how would you recommend I handle this? I know I could re-write the entire Websocket protocol framer, but it feels like I shouldn't have to if framers are supposed to be able to stack.

We recently notified from Apple that our Hotspot helper is delaying device to switch Wifi Networks. To handle this issue better, we need to refactor our code a bit handle the scenario gracefully and while reading this documentation https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/Hotspot_Network_Subsystem_Guide/Contents/AuthStateMachine.html#//apple_ref/doc/uid/TP40016639-CH2-SW1 Some questions came up while responding back to evaluate and filterscanlist command. Here are our questions What is the lifecycle of exclude_list? Does it get cleared every time Authentication State Machine goes into Inactive State? What happens if we send commandNotRecognized/unsupportedNetwork/temporaryFailure after evaluate command? Does our app get an evaluate command next time when device joins the same network? What is the actual time for the app to respond to network change evaluate command? Is 45 seconds the timeout limit for app to evaluate and respond? After responding to the evaluate command, how quickly is it terminated from running in the background?

I need to run multiple, slightly different copies of a modeling tool, which all need access to a model repository on a different machine. Security Settings -> Network tends to pick one modeling tool (and unfortunately the wrong one) for permission, but the dialog offers no way to add the other copies manually. Where can I configure the permission on low level. [macOS Sequoia 15.6.1]

I have granted local network permissions, but sometimes I get a second confirmation popup, what is the timing of the secondary popup?

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 code-level support request 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. 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 2025-11-11 Removed the discussion of TSI assets because those are no longer a thing. 2025-09-12 Adopted the code-level support request terminology. Made other minor editorial changes. 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.

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?

When I use NSURLSessionTaskTransactionMetrics property domainLookupStartDate and domainLookupEndDate to calculate the duration of DNS, sometimes I get 4294893875545978 or -4294893875545978 return method like this [NSNumber numberWithLongLong:[taskMetrics.domainLookupEndDate timeIntervalSinceDate:taskMetrics.domainLookupStartDate?]*1000000000] The hexadecimal value of 4294893875545978 is 0xF3F3F3F3F3F3A. Is 4294893875545978 a special value？

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!

Apology for repost. I needed to fix the tags for original thread. https://developer.apple.com/forums/thread/777159 On iOS 18.3, I noted that partition "HTTPCookiePropertyKey: StoragePartition" is not observed to be set for cookies returned from the wkwebview cookie store. Now on 18.4 beta 4 we are now seeing those same cookies are populated with a partition property. Is there documentation for this change? Is it intended to be suddenly populated in 18.4? Now that partition property is set, HTTPCookieStorage.shared.cookies(for: serverUri) doesn't seem to return the expected cookies correctly. For context, we are using the cookies extracted from wkwebview, setting them in HTTPCookieStorage.shared and using URLSession to make network calls outside the webivew. Works fine once I forcefully set partition on the cookie to nil. More details on what the cookie looks like here: https://feedbackassistant.apple.com/feedback/16906526 Hopefully this is on your radar?

Hi, I am making a AI-Powered app that makes api requests to the openai API. However, for security, I set up a vercel backend that handles the API calls securely, while my frontend makes a call to my vercel-hosted https endpoint. Interestingly, whenever I try to make that call on my device, an iPhone, I get this error: Task <91AE4DE0-2845-4348-89B4-D3DD1CF51B65>.<10> finished with error [-1003] Error Domain=NSURLErrorDomain Code=-1003 "A server with the specified hostname could not be found." UserInfo={_kCFStreamErrorCodeKey=-72000, NSUnderlyingError=0x1435783f0 {Error Domain=kCFErrorDomainCFNetwork Code=-1003 "(null)" UserInfo={_kCFStreamErrorDomainKey=10, _kCFStreamErrorCodeKey=-72000, _NSURLErrorNWResolutionReportKey=Resolved 0 endpoints in 3ms using unknown from query, _NSURLErrorNWPathKey=satisfied (Path is satisfied), interface: pdp_ip0[lte], ipv4, ipv6, dns, expensive, uses cell}}, _NSURLErrorFailingURLSessionTaskErrorKey=LocalDataTask <91AE4DE0-2845-4348-89B4-D3DD1CF51B65>.<10>, _NSURLErrorRelatedURLSessionTaskErrorKey=( "LocalDataTask <91AE4DE0-2845-4348-89B4-D3DD1CF51B65>.<10>" ), NSLocalizedDescription=A server with the specified hostname could not be found., NSErrorFailingURLStringKey=https://[my endpoint], NSErrorFailingURLKey=https://[my endpoint], _kCFStreamErrorDomainKey=10} I'm completely stuck because when I directly make https requests to other api's like openai's endpoint, without the proxy, it finds the server completely fine. Running my endpoint on terminal with curl also works as intended, as I see api key usages. But for some reason, on my project, it does not work. I've looked through almost every single post I could find online, but a lot all of the solutions are outdated and unhelpful. I'm willing to schedule a call, meeting, whatever to resolve this issue and get help more in depth as well.

Hi Team, I have a Network Extension application and UI frontend for it. The UI frontend talks to the Network Extension using XPC, as provided by NEMachServiceName. On M2 machine, The application and XPC connection works fine on clean installation. But, when the application is upgraded, the XPC connection keeps failing. Upgrade steps: PreInstall script kills the running processes, both UI and Network Extension Let installation continue PostInstall script to launch the application after installation complete. Following code is successful to the point of resume from UI application NSXPCInterface *exportedInterface = [NSXPCInterface interfaceWithProtocol:@protocol(IPCUIObject)]; newConnection.exportedInterface = exportedInterface; newConnection.exportedObject = delegate; NSXPCInterface *remoteObjectInterface = [NSXPCInterface interfaceWithProtocol:@protocol(IPCExtObject)]; newConnection.remoteObjectInterface = remoteObjectInterface; self.currentConnection = newConnection; [newConnection resume]; But it fails to get the object id<IPCExtObject> providerProxy = [self.currentConnection remoteObjectProxyWithErrorHandler:^(NSError *registerError) { }]; Please note, this only fails for M2. For M1, this exact code is running fine. Additionally, if I uninstall the application by dropping it in Trash and then installing the newer version, then too, the application works fine.

For important background information, read Extra-ordinary Networking before reading this. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com" Network Interface APIs Most developers don’t need to interact directly with network interfaces. If you do, read this post for a summary of the APIs available to you. Before you read this, read Network Interface Concepts. Interface List The standard way to get a list of interfaces and their addresses is getifaddrs. To learn more about this API, see its man page. A network interface has four fundamental attributes: A set of flags — These are packed into a CUnsignedInt. The flags bits are declared in <net/if.h>, starting with IFF_UP. An interface type — See Network Interface Type, below. An interface index — Valid indexes are greater than 0. A BSD interface name. For example, an Ethernet interface might be called en0. The interface name is shared between multiple network interfaces running over a given hardware interface. For example, IPv4 and IPv6 running over that Ethernet interface will both have the name en0. WARNING BSD interface names are not considered API. There’s no guarantee, for example, that an iPhone’s Wi-Fi interface is en0. You can map between the last two using if_indextoname and if_nametoindex. See the if_indextoname man page for details. An interface may also have address information. If present, this always includes the interface address (ifa_addr) and the network mask (ifa_netmask). In addition: Broadcast-capable interfaces (IFF_BROADCAST) have a broadcast address (ifa_broadaddr, which is an alias for ifa_dstaddr). Point-to-point interfaces (IFF_POINTOPOINT) have a destination address (ifa_dstaddr). Calling getifaddrs from Swift is a bit tricky. For an example of this, see QSocket: Interfaces. IP Address List Once you have getifaddrs working, it’s relatively easy to manipulate the results to build a list of just IP addresses, a list of IP addresses for each interface, and so on. QSocket: Interfaces has some Swift snippets that show this. Interface List Updates The interface list can change over time. Hardware interfaces can be added and removed, network interfaces come up and go down, and their addresses can change. It’s best to avoid caching information from getifaddrs. If thats unavoidable, use the kNotifySCNetworkChange Darwin notification to update your cache. For information about registering for Darwin notifications, see the notify man page (in section 3). This notification just tells you that something has changed. It’s up to you to fetch the new interface list and adjust your cache accordingly. You’ll find that this notification is sometimes posted numerous times in rapid succession. To avoid unnecessary thrashing, debounce it. While the Darwin notification API is easy to call from Swift, Swift does not import kNotifySCNetworkChange. To fix that, define that value yourself, calling a C function to get the value: var kNotifySCNetworkChange: UnsafePointer<CChar> { networkChangeNotifyKey() } Here’s what that C function looks like: extern const char * networkChangeNotifyKey(void) { return kNotifySCNetworkChange; } Network Interface Type There are two ways to think about a network interface’s type. Historically there were a wide variety of weird and wonderful types of network interfaces. The following code gets this legacy value for a specific BSD interface name: func legacyTypeForInterfaceNamed(_ name: String) -> UInt8? { var addrList: UnsafeMutablePointer<ifaddrs>? = nil let err = getifaddrs(&addrList) // In theory we could check `errno` here but, honestly, what are gonna // do with that info? guard err >= 0, let first = addrList else { return nil } defer { freeifaddrs(addrList) } return sequence(first: first, next: { $0.pointee.ifa_next }) .compactMap { addr in guard let nameC = addr.pointee.ifa_name, name == String(cString: nameC), let sa = addr.pointee.ifa_addr, sa.pointee.sa_family == AF_LINK, let data = addr.pointee.ifa_data else { return nil } return data.assumingMemoryBound(to: if_data.self).pointee.ifi_type } .first } The values are defined in <net/if_types.h>, starting with IFT_OTHER. However, this value is rarely useful because many interfaces ‘look like’ Ethernet and thus have a type of IFT_ETHER. Network framework has the concept of an interface’s functional type. This is an indication of how the interface fits into the system. There are two ways to get an interface’s functional type: If you’re using Network framework and have an NWInterface value, get the type property. If not, call ioctl with a SIOCGIFFUNCTIONALTYPE request. The return values are defined in <net/if.h>, starting with IFRTYPE_FUNCTIONAL_UNKNOWN. Swift does not import SIOCGIFFUNCTIONALTYPE, so it’s best to write this code in a C: extern uint32_t functionalTypeForInterfaceNamed(const char * name) { int fd = socket(AF_INET, SOCK_DGRAM, 0); if (fd < 0) { return IFRTYPE_FUNCTIONAL_UNKNOWN; } struct ifreq ifr = {}; strlcpy(ifr.ifr_name, name, sizeof(ifr.ifr_name)); bool success = ioctl(fd, SIOCGIFFUNCTIONALTYPE, &ifr) >= 0; int junk = close(fd); assert(junk == 0); if ( ! success ) { return IFRTYPE_FUNCTIONAL_UNKNOWN; } return ifr.ifr_ifru.ifru_functional_type; } Finally, TN3158 Resolving Xcode 15 device connection issues documents the SIOCGIFDIRECTLINK flag as a specific way to identify the network interfaces uses by Xcode for device connection traffic. Revision History 2025-12-10 Added info about SIOCGIFDIRECTLINK. 2023-07-19 First posted.

I’m developing an app designed for hospital environments, where public internet access may not be available. The app includes two components: the main app and a Local Connectivity Extension. Both rely on persistent TCP socket connections to communicate with a local server. We’re observing a recurring issue where the extension’s socket becomes unresponsive every 1–3 hours, but only when the device is on the lock screen, even if the main app remains in the foreground. When the screen is not locked, the connection is stable and no disconnections occur. ❗ Issue Details: • What’s going on: The extension sends a keep-alive ping packet every second, and the server replies with a pong and a system time packet. • The bug: The server stops receiving keep alive packets from the extension.  • On the server, we detect about 30 second gap on the server, a gap that shows no packets were received by the extension. This was confirmed via server logs and Wireshark).  • On the extension, from our logs there was no gap in sending packets. From it’s perspective, all packets were sent with no error.  • Because no packet are being received by the server, no packets will be sent to the extension. Eventually the server closes the connection due to keep-alive timeout.  • FYI we log when the NEAppPushProvider subclass sleeps and it did NOT go to sleep while we were debugging. 🧾 Example Logs: Extension log: 2025-03-24 18:34:48.808 sendKeepAliveRequest() 2025-03-24 18:34:49.717 sendKeepAliveRequest() 2025-03-24 18:34:50.692 sendKeepAliveRequest() ... // continuous sending of the ping packet to the server, no problems here 2025-03-24 18:35:55.063 sendKeepAliveRequest() 2025-03-24 18:35:55.063 keepAliveTimer IS TIME OUT... in CoreService. // this is triggered because we did not receive any packets from the server 2025-03-24 18:34:16.298 No keep-alive received for 16 seconds... connection ID=95b3... // this shows that there has been no packets being received by the extension ... 2025-03-24 18:34:30.298 Connection timed out on keep-alive. connection ID=95b3... // eventually closes due to no packets being received 2025-03-24 18:34:30.298 Remote Subsystem Disconnected {name=iPhone|Replica-Ext|...} ✅ Observations: • The extension process continues running and logging keep-alive attempts. • However, network traffic stops reaching the server, and no inbound packets are received by the extension. • It looks like the socket becomes silently suspended or frozen, without being properly closed or throwing an error. ❓Questions: • Do you know why this might happen within a Local Connectivity Extension, especially under foreground conditions and locked ? • Is there any known system behavior that might cause the socket to be suspended or blocked in this way after running for a few hours? Any insights or recommendations would be greatly appreciated. Thank you!

Transport Layer Security (TLS) is the most important security protocol on the Internet today. Most notably, TLS puts the S into HTTPS, adding security to the otherwise insecure HTTP protocol. IMPORTANT TLS is the successor to the Secure Sockets Layer (SSL) protocol. SSL is no longer considered secure and it’s now rarely used in practice, although many folks still say SSL when they mean TLS. TLS is a complex protocol. Much of that complexity is hidden from app developers but there are places where it’s important to understand specific details of the protocol in order to meet your requirements. This post explains the fundamentals of TLS, concentrating on the issues that most often confuse app developers. Note The focus of this is TLS-PKI, where PKI stands for public key infrastructure. This is the standard TLS as deployed on the wider Internet. There’s another flavour of TLS, TLS-PSK, where PSK stands for pre-shared key. This has a variety of uses, but an Apple platforms we most commonly see it with local traffic, for example, to talk to a Wi-Fi based accessory. For more on how to use TLS, both TLS-PKI and TLS-PSK, in a local context, see TLS For Accessory Developers. Server Certificates For standard TLS to work the server must have a digital identity, that is, the combination of a certificate and the private key matching the public key embedded in that certificate. TLS Crypto Magic™ ensures that: The client gets a copy of the server’s certificate. The client knows that the server holds the private key matching the public key in that certificate. In a typical TLS handshake the server passes the client a list of certificates, where item 0 is the server’s certificate (the leaf certificate), item N is (optionally) the certificate of the certificate authority that ultimately issued that certificate (the root certificate), and items 1 through N-1 are any intermediate certificates required to build a cryptographic chain of trust from 0 to N. Note The cryptographic chain of trust is established by means of digital signatures. Certificate X in the chain is issued by certificate X+1. The owner of certificate X+1 uses their private key to digitally sign certificate X. The client verifies this signature using the public key embedded in certificate X+1. Eventually this chain terminates in a trusted anchor, that is, a certificate that the client trusts by default. Typically this anchor is a self-signed root certificate from a certificate authority. Note Item N is optional for reasons I’ll explain below. Also, the list of intermediate certificates may be empty (in the case where the root certificate directly issued the leaf certificate) but that’s uncommon for servers in the real world. Once the client gets the server’s certificate, it evaluates trust on that certificate to confirm that it’s talking to the right server. There are three levels of trust evaluation here: Basic X.509 trust evaluation checks that there’s a cryptographic chain of trust from the leaf through the intermediates to a trusted root certificate. The client has a set of trusted root certificates built in (these are from well-known certificate authorities, or CAs), and a site admin can add more via a configuration profile. This step also checks that none of the certificates have expired, and various other more technical criteria (like the Basic Constraints extension). Note This explains why the server does not have to include the root certificate in the list of certificates it passes to the client; the client has to have the root certificate installed if trust evaluation is to succeed. In addition, TLS trust evaluation (per RFC 2818) checks that the DNS name that you connected to matches the DNS name in the certificate. Specifically, the DNS name must be listed in the Subject Alternative Name extension. Note The Subject Alternative Name extension can also contain IP addresses, although that’s a much less well-trodden path. Also, historically it was common to accept DNS names in the Common Name element of the Subject but that is no longer the case on Apple platforms. App Transport Security (ATS) adds its own security checks. Basic X.509 and TLS trust evaluation are done for all TLS connections. ATS is only done on TLS connections made by URLSession and things layered on top URLSession (like WKWebView). In many situations you can override trust evaluation; for details, see Technote 2232 HTTPS Server Trust Evaluation). Such overrides can either tighten or loosen security. For example: You might tighten security by checking that the server certificate was issued by a specific CA. That way, if someone manages to convince a poorly-managed CA to issue them a certificate for your server, you can detect that and fail. You might loosen security by adding your own CA’s root certificate as a trusted anchor. IMPORTANT If you rely on loosened security you have to disable ATS. If you leave ATS enabled, it requires that the default server trust evaluation succeeds regardless of any customisations you do. Mutual TLS The previous section discusses server trust evaluation, which is required for all standard TLS connections. That process describes how the client decides whether to trust the server. Mutual TLS (mTLS) is the opposite of that, that is, it’s the process by which the server decides whether to trust the client. Note mTLS is commonly called client certificate authentication. I avoid that term because of the ongoing industry-wide confusion between certificates and digital identities. While it’s true that, in mTLS, the server authenticates the client certificate, to set this up on the client you need a digital identity, not a certificate. mTLS authentication is optional. The server must request a certificate from the client and the client may choose to supply one or not (although if the server requests a certificate and the client doesn’t supply one it’s likely that the server will then fail the connection). At the TLS protocol level this works much like it does with the server certificate. For the client to provide this certificate it must apply a digital identity, known as the client identity, to the connection. TLS Crypto Magic™ assures the server that, if it gets a certificate from the client, the client holds the private key associated with that certificate. Where things diverge is in trust evaluation. Trust evaluation of the client certificate is done on the server, and the server uses its own rules to decided whether to trust a specific client certificate. For example: Some servers do basic X.509 trust evaluation and then check that the chain of trust leads to one specific root certificate; that is, a client is trusted if it holds a digital identity whose certificate was issued by a specific CA. Some servers just check the certificate against a list of known trusted client certificates. When the client sends its certificate to the server it actually sends a list of certificates, much as I’ve described above for the server’s certificates. In many cases the client only needs to send item 0, that is, its leaf certificate. That’s because: The server already has the intermediate certificates required to build a chain of trust from that leaf to its root. There’s no point sending the root, as I discussed above in the context of server trust evaluation. However, there are no hard and fast rules here; the server does its client trust evaluation using its own internal logic, and it’s possible that this logic might require the client to present intermediates, or indeed present the root certificate even though it’s typically redundant. If you have problems with this, you’ll have to ask the folks running the server to explain its requirements. Note If you need to send additional certificates to the server, pass them to the certificates parameter of the method you use to create your URLCredential (typically init(identity:certificates:persistence:)). One thing that bears repeating is that trust evaluation of the client certificate is done on the server, not the client. The client doesn’t care whether the client certificate is trusted or not. Rather, it simply passes that certificate the server and it’s up to the server to make that decision. When a server requests a certificate from the client, it may supply a list of acceptable certificate authorities [1]. Safari uses this to filter the list of client identities it presents to the user. If you are building an HTTPS server and find that Safari doesn’t show the expected client identity, make sure you have this configured correctly. If you’re building an iOS app and want to implement a filter like Safari’s, get this list using: The distinguishedNames property, if you’re using URLSession The sec_protocol_metadata_access_distinguished_names routine, if you’re using Network framework [1] See the certificate_authorities field in Section 7.4.4 of RFC 5246, and equivalent features in other TLS versions. Self-Signed Certificates Self-signed certificates are an ongoing source of problems with TLS. There’s only one unequivocally correct place to use a self-signed certificate: the trusted anchor provided by a certificate authority. One place where a self-signed certificate might make sense is in a local environment, that is, securing a connection between peers without any centralised infrastructure. However, depending on the specific circumstances there may be a better option. TLS For Accessory Developers discusses this topic in detail. Finally, it’s common for folks to use self-signed certificates for testing. I’m not a fan of that approach. Rather, I recommend the approach described in QA1948 HTTPS and Test Servers. For advice on how to set that up using just your Mac, see TN2326 Creating Certificates for TLS Testing. TLS Standards RFC 6101 The Secure Sockets Layer (SSL) Protocol Version 3.0 (historic) RFC 2246 The TLS Protocol Version 1.0 RFC 4346 The Transport Layer Security (TLS) Protocol Version 1.1 RFC 5246 The Transport Layer Security (TLS) Protocol Version 1.2 RFC 8446 The Transport Layer Security (TLS) Protocol Version 1.3 RFC 4347 Datagram Transport Layer Security RFC 6347 Datagram Transport Layer Security Version 1.2 RFC 9147 The Datagram Transport Layer Security (DTLS) Protocol Version 1.3 Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com" Revision History: 2025-11-21 Clearly defined the terms TLS-PKI and TLS-PSK. 2024-03-19 Adopted the term mutual TLS in preference to client certificate authentication throughout, because the latter feeds into the ongoing certificate versus digital identity confusion. Defined the term client identity. Added the Self-Signed Certificates section. Made other minor editorial changes. 2023-02-28 Added an explanation mTLS acceptable certificate authorities. 2022-12-02 Added links to the DTLS RFCs. 2022-08-24 Added links to the TLS RFCs. Made other minor editorial changes. 2022-06-03 Added a link to TLS For Accessory Developers. 2021-02-26 Fixed the formatting. Clarified that ATS only applies to URLSession. Minor editorial changes. 2020-04-17 Updated the discussion of Subject Alternative Name to account for changes in the 2019 OS releases. Minor editorial updates. 2018-10-29 Minor editorial updates. 2016-11-11 First posted.

Hello, I’ve run into some strange behavior with the macOS System Extension using a Packet Tunnel. The issue showed up after the device went to sleep while the VPN was running. When I woke the computer, the VPN tried to reconnect but never succeeded — it just stayed stuck in the “connecting” state. I was able to turn the VPN off, but every attempt to turn it back on failed and got stuck at “connecting” again. Even removing the VPN configuration from Settings didn’t help. The only thing that worked was disabling the system extension completely. While checking the logs, I noticed thousands of identical log messages appearing within just a few seconds: nesessionmanager(562) deny(1) system-fsctl (_IO "h" 47) 17:11:52.481498+0200 NESMVPNSession[Primary Tunnel:Secure DNS: got On Demand start message from pid 5454 com.apple.networkextension 17:11:52.481568+0200 NESMVPNSession[Primary Tunnel:Secure DNS: got On Demand start message from pid 5454 com.apple.networkextension 17:11:52.481580+0200 NESMVPNSession[Primary Tunnel:Secure DNS: got On Demand start message from pid 5454 com.apple.networkextension 17:11:52.481587+0200 NESMVPNSession[Primary Tunnel:Secure DNS: got On Demand start message from pid 5454 com.apple.networkextension 17:11:52.481646+0200 NESMVPNSession[Primary Tunnel:Secure DNS: got On Demand start message from pid 5446 com.apple.networkextension 17:11:52.481664+0200 NESMVPNSession[Primary Tunnel:Secure DNS: got On Demand start message from pid 5446 com.apple.networkextension 17:11:52.481671+0200 NESMVPNSession[Primary Tunnel:Secure DNS: got On Demand start message from pid 5446 com.apple.networkextension 17:11:52.481676+0200 NESMVPNSession[Primary Tunnel:Secure DNS: got On Demand start message from pid 5446 com.apple.networkextension 17:11:52.481682+0200 NESMVPNSession[Primary Tunnel:Secure DNS: got On Demand start message from pid 5446 com.apple.networkextension 17:11:52.481687+0200 NESMVPNSession[Primary Tunnel:Secure DNS: got On Demand start message from pid 5446 com.apple.networkextension After the burst of these repeated messages, I started seeing logs like the following: 17:11:52.481759+0200 NESMVPNSession[Primary Tunnel:Secure DNS: Received a start command from Spotify Helper[69038] com.apple.networkextension 17:11:52.481790+0200 NESMVPNSession[Primary Tunnel:Secure DNS: Skip a start command from Spotify Helper[69038]: session in state connecting com.apple.networkextension 17:11:52.481949+0200 NESMVPNSession[Primary Tunnel:Secure DNS: Received a start command from Spotify Helper[69038] com.apple.networkextension 17:11:52.481966+0200 NESMVPNSession[Primary Tunnel:Secure DNS: Skip a start command from Spotify Helper[69038]: session in state connecting com.apple.networkextension 17:11:52.481986+0200 NESMVPNSession[Primary Tunnel:Secure DNS: Received a start command from Spotify Helper[69038] com.apple.networkextension 17:11:52.481992+0200 NESMVPNSession[Primary Tunnel:Secure DNS: Skip a start command from Spotify Helper[69038]: session in state connecting com.apple.networkextension 17:11:52.482003+0200 NESMVPNSession[Primary Tunnel:Secure DNS: Received a start command from Spotify Helper[69038] com.apple.networkextension 17:11:52.482011+0200 NESMVPNSession[Primary Tunnel:Secure DNS: Skip a start command from Spotify Helper[69038]: session in state connecting com.apple.networkextension 17:11:52.482022+0200 NESMVPNSession[Primary Tunnel:Secure DNS: Received a start command from Spotify Helper[69038] com.apple.networkextension 17:11:52.482028+0200 NESMVPNSession[Primary Tunnel:Secure DNS: Skip a start command from Spotify Helper[69038]: session in state connecting com.apple.networkextension 17:11:52.482039+0200 NESMVPNSession[Primary Tunnel:Secure DNS: Received a start command from Spotify Helper[69038] com.apple.networkextension 17:11:52.482049+0200 NESMVPNSession[Primary Tunnel:Secure DNS: Skip a start command from Spotify Helper[69038]: session in state connecting com.apple.networkextension 17:11:52.482060+0200 NESMVPNSession[Primary Tunnel:Secure DNS: Received a start command from Slack Helper[84828] com.apple.networkextension 17:11:52.482069+0200 NESMVPNSession[Primary Tunnel:Secure DNS: Skip a start command from Slack Helper[84828]: session in state connecting com.apple.networkextension 17:11:52.482079+0200 NESMVPNSession[Primary Tunnel:Secure DNS: Received a start command from sharingd[764] com.apple.networkextension 17:11:52.482086+0200 NESMVPNSession[Primary Tunnel:Secure DNS: Skip a start command from sharingd[764]: session in state connecting com.apple.networkextension It is clear that the connection is in a loop of submitting request to start and then failing. This problem occured only after sleep on macOS 26.0 and 15.6. This issue only occured after the system woke up from sleep. macOS 15.6 and 26.0. Is this a known problem, and how should I go about troubleshooting or resolving it?

hello I am testing the use of network extension. When we use dnsproxy to proxy DNS requests, we will send you a message that the udp pcbcount of your system continues to increase. For example for ((i=1; i<=99999; i++));do echo "Attempt $i:" dig google.com done when the dig command is used continuously, the dig command will show the following errors when pcbcount reaches a certain number. isc_socket_bind: address not available Can you help us determine what the problem might be? thank you

I develop a Network Extension with NEFilterDataProvider and want to understand how to stop or disable it on exit of the base app without deactivating NE from OS and leave ability to start it again without requiring a password from the user. It starts normally, but when I try to disable it: NEFilterManager.sharedManager.enabled = NO; [NEFilterManager.sharedManager saveToPreferencesWithCompletionHandler:^(NSError * _Nullable error) { // never called }]; the completion handler has never called. But stopFilterWithReason inside the NE code called by the framework where I only replay with required completionHandler();. Then NE process keeps alive. I also tried to call remove, which should disable NE: [NEFilterManager.sharedManager removeFromPreferencesWithCompletionHandler:^(NSError * _Nullable error) { // never called }]; with same result - I freeze forever on waiting completion handler. So what is the correct way to disable NE without explicit deactivation it by [OSSystemExtensionRequest deactivationRequestForExtension:...]?

I'm trying to use ThreadNetwork API to manage TheradNetworks on device (following this documentation: https://developer.apple.com/documentation/threadnetwork/), but while some functions on THClient work (such as getPreferedNetwork), most don't (storeCredentials, retrieveAllCredentials). When calling these functions I get the following warning/error: Client: -[THClient getConnectionEntitlementValidity]_block_invoke - Error: -[THClient storeCredentialsForBorderAgent:activeOperationalDataSet:completion:]_block_invoke:701: - Error: Error Domain=NSCocoaErrorDomain Code=4099 "The connection to service with pid 414 named com.apple.ThreadNetwork.xpc was invalidated from this process." UserInfo={NSDebugDescription=The connection to service with pid 414 named com.apple.ThreadNetwork.xpc was invalidated from this process.} Error Domain=NSCocoaErrorDomain Code=4099 "The connection to service with pid 414 named com.apple.ThreadNetwork.xpc was invalidated from this process." UserInfo={NSDebugDescription=The connection to service with pid 414 named com.apple.ThreadNetwork.xpc was invalidated from this process.} Failed to store Thread credentials: Couldn’t communicate with a helper application. STEPS TO REPRODUCE Create new project Add Thread Network capability via Xcode UI (com.apple.developer.networking.manage-thread-network-credentials) Trigger storeCredentials let extendedMacData = "9483C451DC3E".hexadecimal let tlvHex = "0e080000000000010000000300001035060004001fffe002083c66f0dc9ef53f1c0708fdb360c72874da9905104094dce45388fd3d3426e992cbf0697b030d474c2d5332302d6e65773030310102250b04106c9f919a4da9b213764fc83f849381080c0402a0f7f8".hexadecimal // Initialize the THClient let thClient = THClient() // Store the credentials await thClient.storeCredentials(forBorderAgent: extendedMacData!, activeOperationalDataSet: tlvHex!) { error in if let error = error { print(error) print("Failed to store Thread credentials: \(error.localizedDescription)") } else { print("Successfully stored Thread credentials") } } NOTES: I tried with first calling getPreferedNetwork to initiate network permission dialog Tried adding meshcop to bojur services Tried with different release and debug build configurations

Hi, when I perform an overlay installation via a PKG on macOS for an application containing the NEFilterDataProvider functionality, there is a chance that the entire system network becomes unreachable. Disabling the corresponding Content Filter in "System Settings > Network > Filters" immediately restores network connectivity. This issue does not occur every time, with a frequency of approximately 1 in 20 installation attempts.  The following details may help identify the problem: The Filter.app containing the NEFilterDataProvider resides within the main app's Resources directory, e.g., /Applications/Main.app/Contents/Resources/Filter.app Main.app is installed via a PKG; the issue typically occurs during an overlay installation of Main.app. The NEFilterDataProvider operates as a System Extension. The func handleNewFlow(_ flow: NEFilterFlow) -> NEFilterNewFlowVerdict {} returns .allow. Wireshark packet captures show TCP packets but no UDP packets; TCP handshakes cannot complete. Disabling the corresponding content filter in "System Settings > Network > Filters" restores the network; re-enabling it breaks connectivity again. After waiting for a period, approximately 30-60 minutes, network connectivity can recover automatically. What causes this and how can it be fixed? Any workarounds?

Dear Apple： We found that after mirroring an iPhone and a Mac, calling the NEHotspotConfigurationManager applyConfiguration interface on the iPhone fails to connect to Wi-Fi. Are there any restrictions on using this interface in mirror mode?