diff options
Diffstat (limited to 'app/openvpn/doc')
| -rw-r--r-- | app/openvpn/doc/android.txt | 76 | ||||
| -rw-r--r-- | app/openvpn/doc/doxygen/openvpn.doxyfile | 2 | ||||
| -rw-r--r-- | app/openvpn/doc/openvpn.8 | 326 |
3 files changed, 354 insertions, 50 deletions
diff --git a/app/openvpn/doc/android.txt b/app/openvpn/doc/android.txt new file mode 100644 index 00000000..871e3997 --- /dev/null +++ b/app/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. diff --git a/app/openvpn/doc/doxygen/openvpn.doxyfile b/app/openvpn/doc/doxygen/openvpn.doxyfile index 5d87172c..cf26c42a 100644 --- a/app/openvpn/doc/doxygen/openvpn.doxyfile +++ b/app/openvpn/doc/doxygen/openvpn.doxyfile @@ -235,7 +235,7 @@ EXPAND_ONLY_PREDEF = NO SEARCH_INCLUDES = YES INCLUDE_PATH = INCLUDE_FILE_PATTERNS = -PREDEFINED = WIN32 NTLM USE_LZO ENABLE_FRAGMENT P2MP P2MP_SERVER USE_CRYPTO USE_SSL ENABLE_PLUGIN ENABLE_MANAGEMENT ENABLE_OCC HAVE_GETTIMEOFDAY +PREDEFINED = WIN32 NTLM USE_LZO ENABLE_FRAGMENT P2MP P2MP_SERVER ENABLE_CRYPTO ENABLE_CRYPTO_OPENSSL ENABLE_SSL ENABLE_PLUGIN ENABLE_MANAGEMENT ENABLE_OCC HAVE_GETTIMEOFDAY EXPAND_AS_DEFINED = SKIP_FUNCTION_MACROS = YES #--------------------------------------------------------------------------- diff --git a/app/openvpn/doc/openvpn.8 b/app/openvpn/doc/openvpn.8 index d66bd665..34894e5a 100644 --- a/app/openvpn/doc/openvpn.8 +++ b/app/openvpn/doc/openvpn.8 @@ -221,6 +221,9 @@ options. indicates the protocol to use when connecting with the remote, and may be "tcp" or "udp". +For forcing IPv4 or IPv6 connection suffix tcp or udp +with 4/6 like udp4/udp6/tcp4/tcp6. + The client will move on to the next host in the list, in the event of connection failure. Note that at any given time, the OpenVPN client @@ -271,7 +274,7 @@ failover capability. .\"********************************************************* .TP .B \-\-remote-random-hostname -Add a random string (6 characters) to first DNS label of hostname to prevent +Prepend a random string (6 bytes, 12 hex characters) to hostname to prevent DNS caching. For example, "foo.bar.gov" would be modified to "<random-chars>.foo.bar.gov". .\"********************************************************* @@ -346,20 +349,27 @@ block: .B connect-retry, .B connect-retry-max, .B connect-timeout, +.B explicit-exit-notify, .B float, +.B fragment, .B http-proxy, .B http-proxy-option, .B http-proxy-retry, .B http-proxy-timeout, +.B link-mtu, .B local, .B lport, +.B mssfix, +.B mtu-disc, .B nobind, .B port, .B proto, .B remote, .B rport, -.B socks-proxy, and -.B socks-proxy-retry. +.B socks-proxy, +.B socks-proxy-retry, +.B tun-mtu and +.B tun-mtu-extra. A defaulting mechanism exists for specifying options to apply to all @@ -471,13 +481,13 @@ seconds (default=10). .TP .B \-\-connect-retry-max n .B n -specifies the number of times all -.B \-\-remote -respectively +specifies the number of times all +.B \-\-remote +respectively .B <connection> -statements are tried. Specifiying +statements are tried. Specifiying .B n -as one would try each entry exactly once. A sucessful connection +as one would try each entry exactly once. A sucessful connection resets the counter. (default=umlimited). .\"********************************************************* .TP @@ -544,14 +554,24 @@ Set HTTP version number to .B AGENT user-agent \-\- Set HTTP "User-Agent" string to .B user-agent. + +.B CUSTOM\-HEADER name content \-\- +Adds the custom Header with +.B name +as name and +.B content +as the content of the custom HTTP header. .\"********************************************************* .TP -.B \-\-socks-proxy server [port] +.B \-\-socks-proxy server [port] [authfile] Connect to remote host through a Socks5 proxy at address .B server and port .B port (default=1080). +.B authfile +(optional) is a file containing a username and password on 2 lines, or +"stdin" to prompt from console. .\"********************************************************* .TP .B \-\-socks-proxy-retry @@ -664,7 +684,7 @@ TCP/UDP port number or name for bind. TCP/UDP port number or name for remote. .\"********************************************************* .TP -.B \-\-bind +.B \-\-bind [ipv6only] Bind to local address and port. This is the default unless any of .B \-\-proto tcp-client , @@ -672,6 +692,12 @@ Bind to local address and port. This is the default unless any of or .B \-\-socks-proxy are used. + +If the +.B ipv6only +keyword is present OpenVPN will bind only to IPv6 (as oposed +to IPv6 and IPv4) when a IPv6 socket is opened. + .\"********************************************************* .TP .B \-\-nobind @@ -797,6 +823,17 @@ also specify or .B \-\-dev-type tap. +Under Mac OS X this option can be used to specify the default tun +implementation. Using +.B \-\-dev\-node utun +forces usage of the native Darwin tun kernel support. Use +.B \-\-dev\-node utunN +to select a specific utun instance. To force using the tun.kext (/dev/tunX) use +.B \-\-dev\-node tun\fR. +When not specifying a +.B \-\-dev\-node +option openvpn will first try to open utun, and fall back to tun.kext. + On Windows systems, select the TAP-Win32 adapter which is named .B node @@ -1872,6 +1909,18 @@ reasons for having OpenVPN fail if it detects problems in a config file. Having said that, there are valid reasons for wanting new software features to gracefully degrade when encountered by older software versions. + +It is also possible to tag a single directive so as not to trigger +a fatal error if the directive isn't recognized. To do this, +prepend the following before the directive: +.B setenv opt + +Versions prior to OpenVPN 2.3.3 will always ignore options set with the +.B setenv opt +directive. + +See also +.B \-\-ignore-unknown-option .\"********************************************************* .TP .B \-\-setenv-safe name value @@ -1885,6 +1934,25 @@ is a safety precaution to prevent a LD_PRELOAD style attack from a malicious or compromised server. .\"********************************************************* .TP +.B \-\-ignore-unknown-option opt1 opt2 opt3 ... optN +When one of options +.B opt1 ... optN +is encountered in the configuration file the configuration +file parsing does not fail if this OpenVPN version does not +support the option. Multiple +.B \-\-ignore-unknown-option +options can be given to support a larger number of options to ignore. + +This option should be used with caution, as there are good security +reasons for having OpenVPN fail if it detects problems in a +config file. Having said that, there are valid reasons for wanting +new software features to gracefully degrade when encountered by +older software versions. + +.B \-\-ignore-unknown-option +is available since OpenVPN 2.3.3. +.\"********************************************************* +.TP .B \-\-script-security level This directive offers policy-level control over OpenVPN's usage of external programs and scripts. Lower @@ -2029,6 +2097,16 @@ In many cases, the parameter can point to an empty directory, however complications can result when scripts or restarts are executed after the chroot operation. + +Note: if OpenVPN is built using the PolarSSL SSL +library, +.B \-\-chroot +will only work if a /dev/urandom device node is available +inside the chroot directory +.B dir. +This is due to the way PolarSSL works (it wants to open +/dev/urandom every time randomness is needed, not just once +at startup) and nothing OpenVPN can influence. .\"********************************************************* .TP .B \-\-setcon context @@ -2205,6 +2283,12 @@ otherwise would be prepended. In particular, this applies to log messages sent to stdout. .\"********************************************************* .TP +.B \-\-machine-readable-output +Always write timestamps and message flags to log messages, even when they +otherwise would not be prefixed. In particular, this applies to +log messages sent to stdout. +.\"********************************************************* +.TP .B \-\-writepid file Write OpenVPN's main process ID to .B file. @@ -2259,18 +2343,23 @@ is NOT specified. .\"********************************************************* .TP .B \-\-multihome -Configure a multi-homed UDP server. This option can be used when -OpenVPN has been configured to listen on all interfaces, and will -attempt to bind client sessions to the interface on which packets -are being received, so that outgoing packets will be sent out -of the same interface. Note that this option is only relevant for -UDP servers and currently is only implemented on Linux. - -Note: clients connecting to a -.B \-\-multihome -server should always use the -.B \-\-nobind -option. +Configure a multi-homed UDP server. This option needs to be used when +a server has more than one IP address (e.g. multiple interfaces, or +secondary IP addresses), and is not using +.B \-\-local +to force binding to one specific address only. This option will +add some extra lookups to the packet path to ensure that the UDP reply +packets are always sent from the address that the client is +talking to. This is not supported on all platforms, and it adds more +processing, so it's not enabled by default. + +Note: this option is only relevant for UDP servers. + +Note 2: if you do an IPv6+IPv4 dual-stack bind on a Linux machine with +multiple IPv4 address, connections to IPv4 addresses will not work +right on kernels before 3.15, due to missing kernel support for the +IPv4-mapped case (some distributions have ported this to earlier kernel +versions, though). .\"********************************************************* .TP .B \-\-echo [parms...] @@ -2344,12 +2433,34 @@ consecutive messages in the same category. This is useful to limit repetitive logging of similar message types. .\"********************************************************* .TP +.B \-\-compress [algorithm] +Enable a compression algorithm. + +The +.B algorithm +parameter may be "snappy", "lzo", "lz4", or empty. Snappy, LZO and LZ4 +are different compression algorithms, with Snappy generally +offering the best performance while LZ4 is faster with less CPU usage. +For backwards compatibility with OpenVPN versions before 2.4, use "lzo" +(which is identical to the older option "\-\-comp-lzo yes"). + +If the +.B algorithm +parameter is empty, compression will be turned off, but the packet +framing for compression will still be enabled, allowing a different +setting to be pushed later. +.\"********************************************************* +.TP .B \-\-comp-lzo [mode] -Use fast LZO compression \-\- may add up to 1 byte per +Use LZO compression \-\- may add up to 1 byte per packet for incompressible data. .B mode may be "yes", "no", or "adaptive" (default). +This option is deprecated in favor of the newer +.B --compress +option. + In a server mode setup, it is possible to selectively turn compression on or off for individual clients. @@ -2479,6 +2590,7 @@ Allow management interface to override .B \-\-remote directives (client-only). .\"********************************************************* +.TP .B \-\-management-external-key Allows usage for external private key file instead of .B \-\-key @@ -3423,7 +3535,7 @@ the authenticated username as the common name, rather than the common name from the client cert. .\"********************************************************* .TP -.B \-\-compat\-names [no\-remapping] +.B \-\-compat\-names [no\-remapping] (DEPRECATED) Until OpenVPN v2.3 the format of the X.509 Subject fields was formatted like this: .IP @@ -3454,25 +3566,42 @@ characters in the usernames, X.509 Subject fields and Common Name variables and it complies to the RFC 2253, UTF\-8 String Representation of Distinguished Names. -As a backwards compatibility for the removed \-\-no\-name\-remapping feature in -older OpenVPN versions, the +The .B no\-remapping mode flag can be used with the .B \-\-compat\-names -option. -When this mode flag is used, the Common Name, Subject, and username strings are -allowed to include any printable character including space, but excluding -control characters such as tab, newline, and carriage-return. It ensures -compatibility with the -.B \-\-no\-name\-remapping -option of OpenVPN versions before v2.3. +option to be compatible with the now deprecated \-\-no\-name\-remapping option. +It is only available at the server. When this mode flag is used, the Common Name, +Subject, and username strings are allowed to include any printable character +including space, but excluding control characters such as tab, newline, and +carriage-return. no-remapping is only available on the server side. .B Please note: -This option will not be around for a long time. It is only implemented +This option is immediately deprecated. It is only implemented to make the transition to the new formatting less intrusive. It will be -removed either in OpenVPN v2.4 or v2.5. So please make sure you start -the process to support the new formatting as soon as possible. +removed either in OpenVPN v2.4 or v2.5. So please make sure you use the +.B \-\-verify-x509-name +option instead of +.B \-\-tls-remote +as soon as possible and update your scripts where necessary. +.\"********************************************************* +.TP +.B \-\-no\-name\-remapping (DEPRECATED) +The +.B \-\-no\-name\-remapping +option is an alias for +.B \-\-compat\-names\ no\-remapping. +It ensures compatibility with server configurations using the +.B \-\-no\-name\-remapping +option. + +.B Please note: +This option is now deprecated. It will be removed either in OpenVPN v2.4 +or v2.5. So please make sure you support the new X.509 name formatting +described with the +.B \-\-compat\-names +option as soon as possible. .\"********************************************************* .TP .B \-\-port-share host port [dir] @@ -4122,6 +4251,13 @@ included with the OpenVPN distribution. Diffie Hellman parameters may be considered public. .\"********************************************************* .TP +.B \-\-ecdh-curve name +Specify the curve to use for elliptic curve Diffie Hellman. Available +curves can be listed with +.B \-\-show-curves +. The specified curve will only be used for ECDH TLS-ciphers. +.\"********************************************************* +.TP .B \-\-cert file Local peer's signed certificate in .pem format \-\- must be signed by a certificate authority whose certificate is in @@ -4189,6 +4325,15 @@ when you built your peer's certificate (see above). .\"********************************************************* .TP +.B \-\-tls-version-min version ['or-highest'] +Sets the minimum +TLS version we will accept from the peer (default is "1.0"). +Examples for version +include "1.0", "1.1", or "1.2". If 'or-highest' is specified +and version is not recognized, we will only accept the highest TLS +version supported by the local SSL implementation. +.\"********************************************************* +.TP .B \-\-pkcs12 file Specify a PKCS #12 file containing local private key, local certificate, and root CA certificate. @@ -4649,11 +4794,11 @@ is available via the peer_cert environment variable. Field in x509 certificate subject to be used as username (default=CN). .B Fieldname will be uppercased before matching. When this option is used, the ---tls-remote option will match against the chosen fieldname instead -of the CN. +.B \-\-verify-x509-username +option will match against the chosen fieldname instead of the CN. .\"********************************************************* .TP -.B \-\-tls-remote name +.B \-\-tls-remote name (DEPRECATED) Accept connections only from a host with X509 name or common name equal to .B name. @@ -4685,6 +4830,59 @@ option to verify the remote host, because works in a .B \-\-chroot environment too. + +.B Please also note: +This option is now deprecated. It will be removed either in OpenVPN v2.4 +or v2.5. So please make sure you support the new X.509 name formatting +described with the +.B \-\-compat-names +option as soon as possible by updating your configurations to use +.B \-\-verify-x509-name +instead. +.\"********************************************************* +.TP +.B \-\-verify-x509-name name type +Accept connections only if a host's X.509 name is equal to +.B name. +The remote host must also pass all other tests of verification. + +Which X.509 name is compared to +.B name +depends on the setting of type. +.B type +can be "subject" to match the complete subject DN (default), +"name" to match a subject RDN or "name-prefix" to match a subject RDN prefix. +Which RDN is verified as name depends on the +.B \-\-x509-username-field +option. But it defaults to the common name (CN), e.g. a certificate with a +subject DN "C=KG, ST=NA, L=Bishkek, CN=Server-1" would be matched by: + +.B \-\-verify-x509-name 'C=KG, ST=NA, L=Bishkek, CN=Server-1' +and +.B \-\-verify-x509-name Server-1 name +or you could use +.B \-\-verify-x509-name Server- name-prefix +if you want a client to only accept connections to "Server-1", "Server-2", etc. + +.B \-\-verify-x509-name +is a useful replacement for the +.B \-\-tls-verify +option to verify the remote host, because +.B \-\-verify-x509-name +works in a +.B \-\-chroot +environment without any dependencies. + +Using a name prefix is a useful alternative to managing +a CRL (Certificate Revocation List) on the client, since it allows the client +to refuse all certificates except for those associated +with designated servers. + +.B NOTE: +Test against a name prefix only when you are using OpenVPN with +a custom CA certificate that is under your control. +Never use this option with type "name-prefix" when your client certificates +are signed by a third party, such as a commercial web CA. .\"********************************************************* .TP .B \-\-x509-track attribute @@ -4722,7 +4920,7 @@ a man-in-the-middle attack where an authorized client attempts to connect to another client by impersonating the server. The attack is easily prevented by having clients verify the server certificate using any one of -.B \-\-ns-cert-type, \-\-tls-remote, +.B \-\-ns-cert-type, \-\-verify-x509-name, or .B \-\-tls-verify. .\"********************************************************* @@ -4780,7 +4978,7 @@ a man-in-the-middle attack where an authorized client attempts to connect to another client by impersonating the server. The attack is easily prevented by having clients verify the server certificate using any one of -.B \-\-remote-cert-tls, \-\-tls-remote, +.B \-\-remote-cert-tls, \-\-verify-x509-name, or .B \-\-tls-verify. .\"********************************************************* @@ -4841,6 +5039,13 @@ lowest. Show currently available hardware-based crypto acceleration engines supported by the OpenSSL library. .\"********************************************************* +.TP +.B \-\-show-curves +(Standalone) +Show all available elliptic curves to use with the +.B \-\-ecdh-curve +option. +.\"********************************************************* .SS Generate a random key: Used only for non-TLS static key encryption mode. .\"********************************************************* @@ -5267,9 +5472,11 @@ option can be used BEFORE this option to produce debugging information. .SS IPv6 Related Options .\"********************************************************* The following options exist to support IPv6 tunneling in peer-to-peer -and client-server mode. As of now, this is just very basic -documentation of the IPv6-related options. More documentation can be -found on http://www.greenie.net/ipv6/openvpn.html. +and client-server mode. All options are modeled after their IPv4 +counterparts, so more detailed explanations given there apply here +as well (except for +.B \-\-topology +, which has no effect on IPv6). .TP .B --ifconfig-ipv6 ipv6addr/bits ipv6remote configure IPv6 address @@ -5280,7 +5487,11 @@ if no gateway is specified. .TP .B --route-ipv6 ipv6addr/bits [gateway] [metric] setup IPv6 routing in the system to send the specified IPv6 network -into OpenVPN's ``tun'' device +into OpenVPN's ``tun''. The gateway parameter is only used for +IPv6 routes across ``tap'' devices, and if missing, the ``ipv6remote'' +field from +.B --ifconfig-ipv6 +is used. .TP .B --server-ipv6 ipv6addr/bits convenience-function to enable a number of IPv6 related options at @@ -5296,7 +5507,8 @@ pool starts at .B ipv6addr and increments by +1 for every new client (linear mode). The .B /bits -setting controls the size of the pool. +setting controls the size of the pool. Due to implementation details, +the pool size must be between /64 and /112. .TP .B --ifconfig-ipv6-push ipv6addr/bits ipv6remote for ccd/ per-client static IPv6 interface configuration, see @@ -5863,6 +6075,16 @@ Set prior to execution of the script. .\"********************************************************* .TP +.B tls_digest_{n} +Contains the certificate SHA1 fingerprint/digest hash value, +where +.B n +is the verification level. Only set for TLS connections. Set prior +to execution of +.B \-\-tls-verify +script. +.\"********************************************************* +.TP .B tls_id_{n} A series of certificate fields from the remote peer, where @@ -5880,14 +6102,20 @@ where is the verification level. Only set for TLS connections. Set prior to execution of .B \-\-tls-verify -script. This is in the form of a hex string like "37AB46E0", which is -suitable for doing serial-based OCSP queries (with OpenSSL, you have -to prepend "0x" to the string). If something goes wrong while reading +script. This is in the form of a decimal string like "933971680", which is +suitable for doing serial-based OCSP queries (with OpenSSL, do not +prepend "0x" to the string) If something goes wrong while reading the value from the certificate it will be an empty string, so your code should check that. See the contrib/OCSP_check/OCSP_check.sh script for an example. .\"********************************************************* .TP +.B tls_serial_hex_{n} +Like +.B tls_serial_{n}\fR, +but in hex form (e.g. "12:34:56:78:9A"). +.\"********************************************************* +.TP .B tun_mtu The MTU of the TUN/TAP device. Set prior to |