Adopting iOS 9 network extension points #124

clowwindy opened this Issue Jun 9, 2015 · 532 comments


None yet

Network extension points:
Use the Packet Tunnel Provider extension point to implement the client side of a custom VPN tunneling protocol.
Use the App Proxy Provider extension point to implement the client side of a custom transparent network proxy protocol.
Use the Filter Data Provider and the Filter Control Provider extension points to implement dynamic, on-device network content filtering.
Each of the network extension points requires special permission from Apple.

conradev commented Jun 9, 2015

Each of the network extension points requires special permission from Apple :(


Now that Apple allows anyone to run the code on their own devices, we don't have to publish the app on the App Store.

No, it still requires some entitlements to run on the devices.

conradev commented Jun 9, 2015

Totally, but - the API documentation is hard to piece together and there is no template in Xcode for the extension point. Gonna have to do some reverse engineering.


There's no documentation at all at the moment. The headers of NetworkExtension.framework are public, so we can figure out how to implement the proxy.

I guess we need to subclass NEAppProxyProvider to handle both NEAppProxyTCPFlow and NEAppProxyUDPFlow. And somehow activate the proxy.

Or we can subclass NEPacketTunnelProvider to create a VPN tunnel that handles NEPacketTunnelFlow.


Totally. We need to find the extension point identifier, too. Cisco and OpenVPN need to update their apps...


I guess it works just like an app that controls IPSec VPN settings. Before calling manager.connection.startVPNTunnelAndReturnError, we should register our own protocol with

[NETunnelProviderManager loadAllFromPreferencesWithCompletionHandler:(void (^)(NSArray<NETunnelProviderManager *> * __nullable managers, NSError * __nullable error))completionHandler]

I'll give it a try when I have time.


I'm going to wait for the single WWDC session before diving in


NEAppProxyProvider is actually per-app exclusive. Good news is we can use NEPacketTunnelProvider to create global VPN services.

I'm writing to Apple to see if we can get permission for the API.


Have you made any progress on packet tunnel?


Still no reply from Apple.


I'm writing to Apple to see if we can get permission for the API.

So does this mean only those who have grant permissions from Apple can develop global proxy apps?


I'm afraid yes.


I'm afraid yes.

Sad but reasonable. Good luck with SS. 🙏


The NEAppProxyProvider API only require a MDM deployed app. That can be "simulated" as described in the video.


There're actually templates for Xcode. You need to install them from


But I have not found the way of how to activate a vpn. As there's no shared instance for NETunnelProviderManager I think we need to create a new one.

[NETunnelProviderManager loadAllFromPreferencesWithCompletionHandler:^(NSArray<NETunnelProviderManager *> * __nullable managers, NSError * __nullable error) {

        if (managers.count <= 0){
            NETunnelProviderProtocol *protocol = [[NETunnelProviderProtocol alloc] init];
            protocol.providerConfiguration = @{ @"some parameter" : @"some value" };
            protocol.providerBundleIdentifier = @"com.example.vpn.vpntunnel";

            NETunnelProviderManager *manager = [[NETunnelProviderManager alloc] init];
            [manager setProtocol:protocol];
            [manager setLocalizedDescription:@"My VPN"];
            [manager setOnDemandEnabled:NO];
            [manager setEnabled:YES];

            [manager loadFromPreferencesWithCompletionHandler:^(NSError * __nullable error) {
                NSLog(@"%@", error);

On the line NETunnelProviderManager *manager = [[NETunnelProviderManager alloc] init];, the following message appears in the console app:

6/27/15 5:31:13.845 PM VPNOSX[1403]: Application does not have the required entitlements.

It doesn't say which entitlements and there's no any documentation about it.
I want to try this api on MAC OS 10.11. I understand the reason why I need to ask apple for some permission to publish the app with this api to app store, but I can't believe that I have to ask them for permission to run this api on my development machine.
Sorry, that's a little bit off topic, but that is the only thread that I found in the internet so far.


Yes. You need to send an email to Apple to get the entitlements. And I'm waiting for their reply.

manjonn commented Jul 8, 2015

Any luck on this yet? I am looking at NEAppProxyProvider for a project for a client. I think I do understand some things, but can't be sure till I can run it on the device.

let newManager = NETunnelProviderManager()

You'll get a warning complaining about missing entitlements when you execute this line of code.


In it says:

The NEProvider family of APIs require the following entitlement:
The and the provider extensions will not run if they are not code signed with this entitlement.
You can request this entitlement by sending an email to

If you try to compile the app with this entitlement, your app will be killed by taskgated daemon. If you like to move from /System/Library/LaunchDaemons with root permission, you will get a nice response:

sudo mv ~
mv: rename to /Users/alex/ Operation not permitted

means that you are not admin now, you are nothing and you are in sandbox:

7/9/15 12:37:27.138 PM sandboxd[113]: ([3711]) mv(3711) System Policy: deny file-write-unlink /System/Library/LaunchDaemons/

We just received the entitlements.


Got the entitlements, too.


Did you apply as an individual or as a company?

I didn't dare filling the form because it seemed like you had to apply as a company.


I applied as an open source organization. I explained a bit about this project in the Company name and address field.

@Contexter Contexter referenced this issue in audiokit/AudioKit Jul 13, 2015

Add OSC instrument communication #199



Now I can get a virtual tun device running and route packets through UDP. While I find it a little hard to debug as I can't attach to the extension.

@clowwindy clowwindy self-assigned this Jul 18, 2015

Now I have ShadowVPN fully working on an iPad. The next step is to add UI, etc.


Jul 19 12:17:56 new-iPad ShadowVPN(NetworkExtension)[1242] : MDM must be used to create NEAppProxyProvider configurations

Looks like NEAppProxyProviderManager isn't for us. Thus to implement Shadowsocks for iOS, we need convert it to a VPN. Maybe we have to port tun2socks to iOS.

madeye commented Jul 19, 2015

@linusyang has a working port of tun2socks on iOS. Maybe he can help.



In some old version of Shadowsocks-iOS, I had polipo's main function renamed and called from a background thread. We can do the same to tun2socks and turn it into libtun2socks. Instead of letting tun2socks create the tun device, we'll create and pass the tun fd to its main function.

Since the VPN extension is a hard place for debugging, we may debug libtun2socks on OS X where it's possible to create a tun fd in a normal process. Then the only thing left is to change the project target.

I think I'll begin working on this in mid August after I'm done with ShadowVPN and ChinaDNS (we have to do some DNS hijacking since it's not possible to listen on port 53). According to records iOS 9 will be released around Sep 18.

If you're interested in porting the library, I've created a repo for it.


@clowwindy I did some work on this a year ago but I don't really remember how far I got because I eventually hit a wall.

Not sure if any of that is useful anymore.


I'm happy to help in any capacity that I can. I want to get Tor working on iOS, which will require the same NEPacketTunnelProvider -> SOCKS bridge.

Correct me if I am wrong, but the parts we need are:

  • Something to parse/create the IPv4/6 headers of incoming/outgoing packets.
  • A SOCKS4/5 client

These pieces on their own don't sound awful to implement while looking at existing implementations – or am I misunderstanding the complexity?


@conradev Awesome work! I have been reaching out to other people who have expressed interest in collaborating on an iOS 9 Tor implementation and I'm glad to see you've already made some progress. Sent you an email. :)


@conradev @chrisballinger
Good to see we can join forces on the tun to socks bridge!


@linusyang I've added you to the team. You can push directly to the repo.


@clowwindy Thanks!


@clowwindy @linusyang @conradev @chrisballinger any one having a sample code for NetworkExtension to scan the wifi list? I guess NEHotspotHelper will be used, but i dont know how to implement


Do application that uses Extension Framework can run in background or should i do something specific to run my application in background?How do I run my custom VPN application in background?

manjonn commented Jul 29, 2015

I working on getting NEAppProxyProvider working. Not much luck so far. I think it the Proxy has to be configured either through the code or through an MDM config profile. Don't know which one. Is anybody working on this? Would like to compare notes.


Using the extension Framework I can get it working on the idp_ip0 but if I start with en0 it gives an error 49. However if I switch from idp_ip0 -> en0 it works. Any one else see this problem?@clowwindy

conradev commented Aug 1, 2015

@clowwindy, @linusyang, would love your thoughts on this document.

Trying to actually figure out how to implement this library. I don't have the entitlements yet, so it's all I can do while I wait.

tredds commented Aug 10, 2015

Hei, have you been able to run the sample code? I'm getting "Error Domain=NEConfigurationErrorDomain Code=11 "IPC failed" UserInfo={NSLocalizedDescription=IPC failed}" when trying to use NEFilterManager. I created provisioning profiles for each extension + the main app. I expect this to be a signing problem, but I just can't see it. Thanks


Update: ShadowVPN-iOS is now fully functional.

I've created UI, added CHNRoutes and ChinaDNS. You can also see how to deal with network status change (Wi-Fi/4G). You can try to compile and run it if you have the entitlements from Apple.

The bad news is, I found that UDP traffic often gets blocked very quickly (~10 minutes) in 4G network in China. After toggling Airplane mode twice to get a new 4G IP, the server received data again. But after a while it got blocked again.

So I'm coming back to working on Shadowsocks again. It seems that we can't get the file descriptor from NEPacketTunnelProvider API. As @conradev proposed, we can pass the data directly from and to PacketPassInterface and PacketRecvInterface and let tun2socks reassemble the TCP flow. For UDP, I think it's really easy to write our own forwarder rather that using tun2socks.


@tredds are you running it on device? I was getting this error when was trying to run it in ios simulator.

tredds commented Aug 11, 2015

@angelovAlex Indeed I was running on simulator. I'll give it a try on device.

ionull commented Aug 11, 2015

@clowwindy on China Mobile or China Unicom 4G network?


@ionull China Unicom


@conradev @linusyang
tun2socks is based on lwIP, which is a pure C, full stack TCP/IP protocol implementation.

We can just build our own Socks adapter from lwIP and GCD, without tun2socks's event loop.


@clowwindy @linusyang @conradev

Are you saying rewrite tun2socks from scratch, or just rip out portions of it for a partial rewrite? Either way we will also be working on this problem for our iOS 9 Tor VPN effort, and would love to work together where possible.

tredds commented Aug 12, 2015

@angelovAlex It worked. Thanks man!


Actually tun2socks didn't do much work. It's lwip that's doing the magic.
So I'm thinking about writing a tun2shadowsocks directly based on lwip and GCD, it would not only be easier but save a lot of sockets and RAM. (We can save 66.7% file descriptors).

BTW: As I tested to find out, the max open files limit is around 2549 in a PacketTunnelProvider extension.


@clowwindy Awesome! Any chance of using BSD, MIT, or MPL 2.0 for that so we can ship it with the Tor VPN? ;)


Oh, I meant I would build Shadowsocks directly on lwip. It will be an adapter from a tun device to a Shadowsocks protocol client, without implementing Socks5 protocol.

It turns out that lwip's API is very easy to use. tun2socks.c has demonstrated how to create a tcp listener on a virtual interface and how to operate on connections, etc. Apart from code that reads the command line arguments, it's only a few hundreds lines. We can just fit these code in Shadowsocks or Tor's event loop and bridge them together.

I'll update when I've made any progress.


@clowwindy Ah ok, that's great news. Thank you for all of your amazing work on shadowsocks!


Installed Xcode 7 beta 4 in Yosomite, not getting NetworkExtension template in XCODE. /System/Library/Frameworks/NetworkExtension.framework/Versions/A/Resources/NEProviderTargetTemplates.pkg is not present in my system too!


I believe you guys will make great stuff with Network Extensions.


hankbao commented Aug 22, 2015

Thanks so much for providing such great software.


I hope one day I'll live in a country where I have freedom to write any code I like without fearing.

ytf4425 commented Aug 22, 2015

Love you


Thank you


Thank you

mthli commented Aug 22, 2015

Thanks again.


Thank you


take care

aisuika commented Aug 22, 2015

Thank you


Thank you and take care.


What do you mean you have no choice? Which law forbid you from writing software?


@AnthraX1 the network safety law.

jswxdzc commented Aug 22, 2015

Thank you.

XL2014 commented Aug 22, 2015

Thank You.


I hope one day I'll live in a country where I have freedom to write any code I like without fearing.

Thank you.

Lest We Forget.


thank you

pinyin commented Aug 22, 2015

Thank you.


Thank you.

billzbc commented Aug 22, 2015

Thank you. 保重

hilen commented Aug 22, 2015

Love you


thank you


Thank you!


Thank you!


Thank you.

jiyee commented Aug 22, 2015

Thank you.


Thank you and take care.

qinix commented Aug 22, 2015

Thank you.


Good luck @clowwindy :(

gzmask commented Aug 22, 2015



Let us know if we can do anything for you, @clowwindy


Long long live shadowsocks
Thanks, and good luck


take care of yourself


Thank you.


Thank you.


take care

Fleurer commented Aug 22, 2015

thank you


thank you

On Aug 22, 2015, at 11:17, clowwindy wrote:

Two days ago the police came to me and wanted me to stop working on this. Today they asked me to delete all the code from GitHub. I have no choice but to obey.

I hope one day I'll live in a country where I have freedom to write any code I like without fearing.

I believe you guys will make great stuff with Network Extensions.


Reply to this email directly or view it on GitHub.

fanzeyi commented Aug 22, 2015

Thank you.



XiaoYy commented Aug 27, 2015

Thank you.

cdmask commented Aug 27, 2015

Thank you so much.




Thank you.




Thank you.

mveplus commented Aug 28, 2015

@clowwindy your work showed us that there are better ways to defeat the wall!
Ways that even they fear from!
Thank you for your genuine work and take care about your family! Hope to meet you...
Let us know if we can help you anyhow?

Esccc commented Aug 29, 2015

Thanks brave Mea.Your wisdom ∞ Our freedom.


Thank you!

eptru commented Aug 30, 2015

Thank you sir.

ghost commented Aug 30, 2015



thank you!




Good job!


Thank you.

zeyangl commented Sep 1, 2015

Best of luck.


Good luck

zeonsgtr commented Sep 2, 2015

Thank you!


Thanks for your great work

xuxanwan commented Sep 2, 2015

Thank you!

ycwalker commented Sep 3, 2015

Thank you for your efforts !



jun283 commented Sep 4, 2015



Think you!


Think you!

bingxian commented Sep 6, 2015


yxonic commented Sep 6, 2015

为没有代码的repo加星,这是唯一一个。They beat you just because they can't beat your code.


Thank you!

raintean commented Sep 7, 2015



I want to know how to get the entitlements


@RobertYan Thank you!


@RobertYan There is also a question I want to ask, in the message which I want to provide information to Apple.

porea commented Sep 8, 2015

Thank you!


Thank you ! 你的项目是free的一小步 却是网络free的一大步


Thank you! You will be remembered in the history.

simingli commented Sep 9, 2015

Thank you.

hkbase commented Sep 10, 2015

thank you ,love you

ihmv commented Sep 10, 2015

Thank you ! 你很了不起!


作为一个新手菜鸟能说的只有thank you了,愿面神保佑你


Hearts and minds are with you! Keep Coding the Dream! :)

jiang42 commented Sep 11, 2015

Thank you.

Good luck.

Freedom will never die.


@clowwindy , thank you!

Moseszi commented Sep 14, 2015

Thank you.


Thank you.

zhlifly commented Sep 18, 2015

Thank you and good luck!

e10101 commented Sep 19, 2015

Thank you from Hebei, China.

xingbo commented Sep 19, 2015

thanks and may force be with you




Thank you from Germany. Your efforts have been great help and will soon be part of an awesome product for millions to use. Good luck in your future and take care.

z563721 commented Sep 25, 2015


Nyr commented Sep 26, 2015

@CzokNorris are you working on something? I'm very interested and maybe can help.


thank you



wan-qy commented Oct 4, 2015 edited

thank you
I'll never forget you.
And I hope I can BREAK THE FIREWALL one day.

I'll try my best to break the GFW, I promise.

I hope one day I'll live in a country where I have freedom to write any code I like without fearing.

I'm sure we will fear but we can't stop, we must keep moving forward because if we stop coding, we will lose all hope.

I believe you guys will make great stuff with Network Extensions.

I believe , too.

wan-qy commented Oct 4, 2015

anyway,thank you.


Thank you so much.


Thank you!




Thank you.


thank you very much




Thank you.

kkHAIKE commented Nov 23, 2015

Thank you everyone

arange commented Nov 30, 2015

Thank you for all of your efforts.


Thank you and take care.

bennetcq commented Dec 3, 2015

only register here to say : thank you !

nospy commented Dec 5, 2015

Thank you!

z-jason commented Dec 6, 2015

I know it is a bit late. Just heard the news. Thank you.


Could anybody tell me where I can find Shadowssocks OS X client source code and iOS 9 client source code? I want to continue the development.


@cielpy I guess this the deprecated iOS 8 version. It didn't work anymore. I also want the OS X client code

cielpy commented Dec 11, 2015

OS X client code is in this folder
and there is no iOS9 version.Before clowwindy ready to work on it,someone stop him.
A few days ago,there is a app named surge can use shadowsocks protocol as a proxy server,and it is not opensource. And with the similar reson,the app's owner remove it from app store.


10月15号给苹果发的申请entitlement文件的邮件,完全配合他的提问,已经把所有问题答复给苹果,时至今日,为什么还不给我entitlement文件?为什么为什么??? !!!! 有木有同学一样的情况一起交流下,


I have send email to request the entitlement on 15Oct,and I reply the questions also, Why , why I can't get the entitlement file until now? who can help me? thanks in advance, .


刚发现这个问题貌似不止我一个人遇见了,坑死人的苹果,临时决定新建QQ群 477571322 ,遇到同样问题的感兴趣的小伙伴快快加入吧 -=-

ghost commented Dec 24, 2015

thank you so much



2015-12-24 10:18 GMT+08:00 Huang Json

thank you so much

Reply to this email directly or view it on GitHub
#124 (comment)

byszhao commented Jan 15, 2016

Thank you


Thanks a lot


Can i read SSID and BSSID of any wifi (being scanned by my device) using NSHotspotHelper?

zxbiao commented Jan 22, 2016



You are a hero in china.Thanks a lot.
We will never forget your great work.
Take care of yourself.🙂


Is too late for me to know you and your contribution.Just a little sadness . Take care bro

ajjing commented Feb 19, 2016

Thank you!and take wishes~

simdm commented Mar 1, 2016

good luck! thanks

zaypen commented Mar 1, 2016

Great job! Thanks a loooooooooooooot

hieixu commented Mar 16, 2016

Thank you!

lisces commented Mar 24, 2016

The GFW will falling.


Thank u!






谢谢. 那几年多亏有了你. 没有你我就用不了google scholar, 没有google scholar我也不会申请上心仪的学校.
后来出了国一直记得这个代理, 我还到处给国内朋友打广告, 直到你被请去喝茶..


Thank you, and take care.

jianpx commented Aug 11, 2016

Thanks , and good luck!

jianpx commented Aug 12, 2016

Can Network Extension support to implement OpenVPN protocol ?


I have the same question like jianpx.

Liwink commented Oct 8, 2016

Thank you.

t3chno commented Oct 28, 2016

Hello Guys, I need a help for blocking unwanted url. I have a job from one school and they want to give iPad to their students but they want to block few urls. I already started project but I have few problems so I want to pay to who helps me with this...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment