iOS 4.1: Undocumented VPN API, used by Cisco AnyConnect

A few days ago, Cisco AnyConnect was admitted to the App Store. This was mentioned by a few blogs, but they didn’t seem to notice the relevance of it. AnyConnect is an enterprise SSL VPN technology by Cisco, so this may not seem relevant to all that many people at first sight.
However, in order to implement a VPN client to provide VPN connectivity for other apps, you need to hook into the operating system’s network stack. On the iOS App Store, everybody knows that Apple is rather strict on what a developer can do — hooking into the OS kernel and providing network functionality to other apps isn’t something they provide APIs for (and therefore don’t allow).

Wondering how Cisco got around these App Store limitations, I took a closer look at the AnyConnect app. Upon first starting it, it asks whether you want to let it “extend… the Virtual Private Network (VPN) capabilities of your device”.

Cisco AnyConnect Secure Mobility Client extends the Virtual Private Network (VPN) capabilities of your device. Do you want to enable this software? Don’t Allow / OK

After entering a VPN server name etc., I switched over to the Settings app and noticed that the newly created AnyConnect VPN showed up as a system-wide VPN (though if you try to edit it from there, it’ll just say that you should use the AnyConnect app instead).

To configure the settings for ….., use the app provided by Cisco.

Odd, how would an app be able to do any of this if it’s not allowed to get involved with iOS deeper than the App Store guidelines would allow?

Moving on and digging deeper into the .ipa bundle:

The Payload contains AnyConnectDataAgent.vpnplugin, in addition to the AnyConnect.app:

AnyConnectDataAgent.vpnplugin

AnyConnect.app‘s Entitlements.plist contains an entitlement named com.apple.networking.vpn.configuration:

com.apple.networking.vpn.configuration

Neither vpnplugin bundles nor the com.apple.networking.vpn.configuration entitlement are documented anywhere (at least not in a way that can be found through Google). Since this appears to be a special iOS API created by Apple specifically for Cisco, the question is whether it’s also open to other developers. The only other app I’ve found that uses it is Juniper Junos Pulse, which was posted a few weeks before the AnyConnect app. Since both Junos Pulse and AnyConnect have in common that they require iOS 4.1, I think it’s safe to assume that 4.1 introduced the API they use.
Personally, I’d be interested to see an OpenVPN client for the iPhone. I’m not sure whether that will ever happen though if this VPN API only exits semi-officially, especially since OpenVPN is not backed by a big company like Cisco or Juniper.

Update 2011: The German computer magazine c’t wrote about the API, but couldn’t make much sense of it either.

Update 2012: The current list of apps using this API consists of: Juniper Junos Pulse (released September 2010, requires iOS 4.1), Cisco AnyConnect (released September 2010, requires iOS 4.1), F5 BIG-IP (released December 2010, requires iOS 4.2), SonicWall Mobile Connect (released December 2011, requires iOS 4.2), Aruba VIA (released December 2011, requires iOS 4.3) and CheckPoint Mobile VPN (released March 2012, requires iOS 5.0).

Update 2012: Googling for the VPN entitlement now not only finds my blog post, but also configd source code at Apple: first in OS X 10.7 sources and later in OS X 10.8 sources (but not in OS X 10.6, which iOS 4 was based on). In the older version, inside an ifdef checking for iPhone OS, a constant named kSCVPNFilterEntitlementName is declared containing that entitlement, but the constant never gets used. In OS X 10.8, it is no longer ifdeffed to the iPhone OS and actually gets used for allowing limited access to the global preferences.plist.

Update 2012: Playing around with AnyConnect again, I noticed that it now uses a generic utun network interface, which is similar to a Linux-style layer 3 tun interface. utun is used for example by Mac OS X’s Back to my Mac feature: the kernel implementation in Mac OS X 10.8.2 can be found in the XNU source at bsd/net/if_utun.c. Some details can be found in Levin, Jonathan. Mac OS X and iOS Internals: To the Apple’s Core. Chapter 17, Layer II, Case Study: utun. Wiley, 2012.

I have received several more reports of unsuccessful attempts to get access to the VPN API. Apparently despite now offering a generic utun interface, Apple continues to be very strict about it. And to date, there still isn’t an OpenVPN client for iOS.

Update 2013: OpenVPN Connect was released today. It supports tun-style OpenVPN connections. Hooray, finally we can use OpenVPN on iOS! Apparently it can even be managed using the “Custom SSL” option in iPhone Configuration Utility.

12 Responses to “iOS 4.1: Undocumented VPN API, used by Cisco AnyConnect”

  1. Thomas says:

    Hei, have you ever dug a little bit deeper into that VPN stuff? I’m wondering how I can start/stop a VPN connection from inside of my app. I think there must be some private API somewhere that does that.

  2. Andul says:

    Hej there,

    nice article! I would like to ask you to comment on this one, as my knowledge in this area is not that deep:

    https://discussions.apple.com/message/16371125#16371125

    Hope OpenVPN will officially come to iOS soon!

  3. @Andul: I am not sure whether this is a generic interface (i.e. similar to tun/tap virtual interfaces), or requires specific kernel support for each custom VPN app.
    As Apple has not (publicly) documented the VPN API, and I have yet to find a single situation in which the “Custom SSL” option described in that forum post actually does anything, I unfortunately do not have any further information on whether an OpenVPN client for iOS would be possible.

  4. I believe the custom SSL option in the configuration profile exists so that you can create profiles for a custom VPN using the undocumented API. So for instance, if you create a profile for Cisco AnyConnect, you select Custom SSL and use “com.cisco.anyconnect” as identifier. You can then add some key/value custom parameters that are interpreted by the app itself.

  5. @Giovanni: Cisco AnyConnect, Juniper SSL and F5 SSL can be selected in the IPCU. As these are the only apps currently available that use the VPN API, Custom SSL seems somewhat useless at this time. Perhaps Apple originally intended to open up the API to more 3rd parties.

  6. Victor Ronin says:

    Hi Mike,

    Do you have any idea whether Apple has some special program to which a person (or company) can enroll to get the access to the documentation of VPN API?

  7. I assume Apple has a way to give you access to this non-public API (probably not through the regular developer support channel though). Since to date there are only five apps utilizing it, I don’t think they have anything that you can simply sign up for (like the iOS Developer program or the Made for iPhone program). They might not even have a polished API documentation and you might need to pay one of their engineers to help you interface with the API.

    It’s certainly still nothing they want the average developer doing. They seem to be aiming the API at large networking equipment manufacturers. I have been waiting for someone to create OpenVPN client using this API for two full years now…

  8. Sharon says:

    Is it possible to use this api to create “In-house” application (which used in an enterprise and is not uploaded to AppStore) to implement OpenVPN client or to control existing VPN connections?

  9. Victor Ronin says:

    2Sharon:

    You won’t be able to create “in-house” app to have a system wide OpenVPN client. The issue is that you need entitlement to write a system wide VPN. As I know Apple has some list of people who are interested and they invite some of these people (on their discretion). You may try to contact Apple through Developer Program to get on this list.

    On other hand, nothing stops you from implementing application with OpenVPN capabilities. I mean, all connection within this application will go through OpenVPN module, which will establish connection to OpenVPN server. However, this will be only on application basis (you won’t be able to use this functionality to channel any 3rd party traffic).

    Regarding controlling existing VPN connections. Can you please contact me to discuss this? My email is victor dot ronin at gmail dot com.

  10. [...] all major platforms. I know many of my blog readers have been waiting for this: my article on the iOS VPN API is one of the most popular articles on my [...]

  11. jackynoise says:

    i see one software ibluver has use utun to enject data, but they need jailbreak the iphone.

    but seems now they use ppp0 to enject data, i dont know why.

Leave a Reply