From: Arne Schwabe Date: Sun, 11 Sep 2022 14:48:34 +0000 (+0200) Subject: Update android.txt to reflect more recent changes. X-Git-Tag: v2.6_beta1~75 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7b42a0ebc968d178faa1083dd42a0c170d4dfe74;p=thirdparty%2Fopenvpn.git Update android.txt to reflect more recent changes. Signed-off-by: Arne Schwabe Acked-by: Gert Doering Message-Id: <20220911144834.2220049-1-arne@rfc2549.org> URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg25165.html Signed-off-by: Gert Doering --- diff --git a/doc/android.txt b/doc/android.txt index e287be0a8..394baf441 100644 --- a/doc/android.txt +++ b/doc/android.txt @@ -1,4 +1,6 @@ -This file documents the support in OpenVPN for Android 4.0 and up. +This file documents the support in OpenVPN for Android using the +VPNService API (https://developer.android.com/reference/android/net/VpnService) +that has been introduced in Android 4.0 (API 14). This support is primarily used in the "OpenVPN for Android" app (https://github.com/schwabe/ics-openvpn). For building see the developer @@ -8,26 +10,26 @@ 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: +Unlike on other platforms, the tun device is openend by UI instead of +OpenVPN itself. The VpnService 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. +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 +interface. However, Android 13 adds support for exclusion routes that +serve the same purpose. The Android VPNService API has the concept +of protecting a socket from being routed over an 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 +To use OpenVPN with the VPNService API OpenVPN must be built 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 @@ -58,18 +60,16 @@ The GUI will then respond with a "needok 'command' ok' or "needok PERSIST_TUN_ACTION -In Android 4.4-4.4.2 a bug exists that does not allow to open a new tun fd -while a tun fd is still open. When OpenVPN wants to open an fd it will do -this query. The UI should compare the last configuration of -the tun device with the current tun configuration and reply with either (or -always respond with OPEN_AFTER_BEFORE/OPEN_BEFORE_CLOSE) +When OpenVPN wants to open an fd it will do this query via management. +The UI should compare the last configuration of the tun device with the current +tun configuration and reply with either NOACTION (or always respond with +OPEN_BEFORE_CLOSE). - NOACTION: Keep using the old fd -- OPEN_AFTER_CLOSE: First close the old fd and then open a new to workaround the bug - OPEN_BEFORE_CLOSE: the normal behaviour when the VPN configuration changed For example the UI could respond with -needok 'PERSIST_TUN_ACTION' OPEN_AFTER_CLOSE +needok 'PERSIST_TUN_ACTION' OPEN_BEFORE_CLOSE 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 @@ -80,7 +80,7 @@ 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 +configuration. The UI will then 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. @@ -95,7 +95,7 @@ To better support handover between networks, a the management command network-change [samenetwork] -is used on the Android platform. It tells OpenVPN to do the necessary -action when the network changes. Currently this is just calling +is used on the Android platform. It tells OpenVPN to do the necessary +action when the network changes. Currently this is just calling the protect callback when using peer-id regardless of the samenetwork. Without peer-id OpenVPN will generate USR1 when samenetwork is not set.