From 0393ba6656ce6cf679a2c4663275b3ed0f1a34b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Parm=C3=A9nides=20GV?= Date: Thu, 31 Jul 2014 12:09:49 +0200 Subject: Updated ics-openvpn to rev 859 + no 2nd notification. --- ics-openvpn-stripped/main/openvpn/doc/android.txt | 76 +++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 ics-openvpn-stripped/main/openvpn/doc/android.txt (limited to 'ics-openvpn-stripped/main/openvpn/doc/android.txt') diff --git a/ics-openvpn-stripped/main/openvpn/doc/android.txt b/ics-openvpn-stripped/main/openvpn/doc/android.txt new file mode 100644 index 00000000..871e3997 --- /dev/null +++ b/ics-openvpn-stripped/main/openvpn/doc/android.txt @@ -0,0 +1,76 @@ +This file documents the support in OpenVPN for Android 4.0 and up. + +This support is primarily used in the "OpenVPN for Android" app +(http://code.google.com/p/ics-openvpn/). For building see the developer +README: http://code.google.com/p/ics-openvpn/source/browse/README.txt. + +Android provides the VPNService API +(http://developer.android.com/reference/android/net/VpnService.html) +which allows establishing VPN connections without rooting the device. + +Since all the interfaces are are Android specific the calls to this +interface are made from the UI instead of OpenVPN directly. The API +needs the following parameters: + +- IP and netmask of tun interface +- Networks that should be routed to the tun interface +- DNS Servers and DNS Domain +- MTU + +All IPs/Routes are in CIDR style. Non CIDR routes are not supported. +Notable is the lack of support for setting routes to other interfaces +usually used to avoid the server connection going over the tun +interface. The Android VPNService API has the concept of protecting +a socket from being routed over a interface. Calling protect (fd) +will internally bind the socket to the interface used for the +external connection (usually WiFi or mobile data). + +To use OpenVPN with the VPNService API OpenVPN must be build with +the TARGET_ANDROID compile option. Also the UI must use a UNIX +domain socket to connect to OpenVPN. When compiled as TARGET_ANDROID +OpenVPN will use management callbacks instead of executing traditional +ifconfig/route commands use the need-ok callback mechanism which +will ask + +> NEED-OK command + +where command can be: + +IFCONFIG6 IPv6/netmask +IFCONFIG local remoteOrNetmask MTU topology + +To tell the UI which IPs addresses OpenVPN expects on the interface. +Topology is one of "net30","p2p","subnet" or "undef". + +ROUTE6 network/netmask +ROUTE network netmask + +To tell the UI which routes should be set on the tun interface. + +DNSSERVER serverip +DNSDOMAIN searchdomain + +To set the DNS server and search domain. + +The GUI will then respond with a "needok 'command' ok' or "needok +'command' cancel', e.g. "needok 'IFCONFIG' ok". + +To protect a socket the OpenVPN will send a PROTECTFD to the UI. +When sending the PROTECTFD command command to the UI it will send +the fd of the socket as ancillary message over the UNIX socket. +The UI will then call protect(fd) on the received socket protecting +it from being routed over the VPN. + +When opening a tun device the OpenVPN process will first send all +route, ifconfig and DNS related configuration to the UI and after +that calls the OPENTUN command to receive a tun fd with the requested +configuration. The UI will than use the collected information to +call the VPNService's establish() method to receive a fd which in +turn is send to the OpenVPN process as ancillary message to the +"needok 'OPENTUN' ok' response. + +The OpenVPN for Android UI extensively uses other features that +are not specific to Android but are rarely used on other platform. +For example using SIGUSR1 and management-hold to restart, pause, +continue the VPN on network changes or the external key management +--management-external-key option and inline files. -- cgit v1.2.3