diff --git a/Changes.md b/Changes.md new file mode 100644 index 0000000..2684251 --- /dev/null +++ b/Changes.md @@ -0,0 +1,1457 @@ +# Overview of changes in 2.8 + +## User-visible Changes + +* **Parsing Distinguished Names in certificates** + + (OpenSSL backend:) OpenVPN now rejects certificates that have a null-byte + inside any of the field values of their subject. To avoid ambiguity in the + parsed subject, OpenVPN escapes the following characters by prefixing them with + a backslash: + + * " " (space) at the start or end of a field, + * "#" at the start of a field, + * ",", "+", """, "\", "<", ">" and ";" anywhere. + + As a result, if you use the option `--verify-x509-name `, + you need to prefix these characters with a backslash in your configuration. + The subject passed to a `--tls-verify` script is escaped in the same way and + you may need to adjust your script. + + (Mbed TLS backend:) The behavior has not changed. Subjects with null-bytes were + already rejected (assuming OpenVPN was built with Mbed TLS 3.5 or later) and + the characters mentioned above were already escaped. However, the behavior of + Mbed TLS is slightly different from OpenSSL in that it also escapes "=". + +# Overview of changes in 2.7 + +## New features + +* **Multi-socket support for servers** + + OpenVPN servers now can listen on multiple sockets at the same time. Multiple + `--local` statements in the configuration can be used to configure this. This + way the same server can e.g. listen for UDP and TCP connections at the same + time, or listen on multiple addresses and/or ports. + +* **Client implementations for DNS options sent by server for Linux/BSD/macOS** + + Linux, BSD and macOS versions of OpenVPN now ship with a per-platform default + `--dns-updown` script that implements proper handling of DNS configuration sent + by the server. The scripts should work on systems that use `systemd` or + `resolveconf` to manage the DNS setup, as well as raw `/etc/resolv.conf` files. + However, the exact features supported will depend on the configuration method. + On Linux and MacOS this should usually make split-DNS configurations supported + out-of-the-box now. + + Note that this new script will not be used by default if a `--up` script is + already in use to reduce problems with backwards compatibility. + + See documentation for `--dns-updown` and `--dns` for more details. + +* **New client implementation for DNS options sent by server for Windows** + + The Windows client now uses NRPT (Name Resolution Policy Table) to handle DNS + configurations. This adds support for split-DNS and DNSSEC and improves the + compatbility with local DNS resolvers. Requires the interactive service. + +* **On Windows the `block-local` flag is now enforced with WFP filters.** + + The `block-local` flag to `--redirect-gateway` and `--redirect-private` is now + also enforced via the Windows Firewall, making sure packets can't be sent to the + local network. This provides stronger protection against TunnelCrack-style + attacks. + +* **Windows network adapters are now generated on demand** + + This means that on systems that run multiple OpenVPN connections at the same + time the users don't need to manually create enough network adapters anymore (in + addition to the ones created by the installer). + +* **Windows automatic service now runs as an unpriviledged user** + + All tasks that need privileges are now delegated to the interactive service. + **NOTE** this has the risk of breaking existing setups if the Windows + certificate store is used (cryptoapi), and the certificates are not readable for + `NT SERVICE\OpenVPNService`. + +* **Support for new version of Linux DCO module** + + The OpenVPN DCO module has been merged into the Linux kernel as of 6.16. This + required some API changes and OpenVPN 2.7 only supports the new API. The new + module is called `ovpn`. Out-of-tree builds for older kernels are available from + . Please see the release + announcements for further information. + +* **Support for server mode in win-dco driver** + + On Windows the win-dco driver can now be used in server setups. + +* **Support for TLS client floating in DCO implementations** + + The kernel modules will detect clients floating to a new IP address and notify + userland so both data packets (kernel) and TLS packets (sent by userland) can + reach the new client IP. (Actual support depends on recent-enough kernel + implementation) + +* **Enforcement of AES-GCM usage limit** + + OpenVPN will now enforce the usage limits on AES-GCM with the same + confidentiality margin as TLS 1.3 does. This mean that renegotiation will be + triggered after roughly 2^28 to 2^31 packets depending of the packet size. More + details about usage limit of AES-GCM can be found here: + + + +* **Epoch data keys and packet format** + + This introduces the epoch data format for AEAD data channel ciphers in TLS mode + ciphers. This new data format has a number of improvements over the standard + "DATA_V2" format. + + - AEAD tag at the end of packet which is more hardware implementation friendly + - Automatic key switchover when cipher usage limits are hit, similar to the + epoch data keys in (D)TLS 1.3 + - 64 bit instead of 32 bit packet ids to allow the data channel to be ready for + 10 GBit/s without having frequent renegotiation + - IV constructed with XOR instead of concatenation to not have (parts) of the + real IV on the wire + +* **Support for Epoch data channel on Windows, using the win-dco driver (2.8.0+)** + +* **Default ciphers in `--data-ciphers`** + + Ciphers in `--data-ciphers` can contain the string DEFAULT that is replaced by + the default ciphers used by OpenVPN, making it easier to add an allowed cipher + without having to spell out the default ciphers. + +* **TLS alerts** + + OpenVPN 2.7 will send out TLS alerts to peers informing them if the TLS session + shuts down or when the TLS implementation informs the peer about an error in the + TLS session (e.g. mismatching TLS versions). This improves the user experience + as the client shows an error instead of running into a timeout when the server + just stops responding completely. + +* **Support for tun/tap via unix domain socket and lwipovpn support** + + To allow better testing and emulating a full client with a full network stack + OpenVPN now allows a program executed to provide a tun/tap device instead of + opening a device. + + The co-developed lwipovpn program based on lwIP stack allows to simulate full IP + stack. An OpenVPN client using `--dev-node unix:/path/to/lwipovpn` can emulate a + full client that can be pinged, can serve a website and more without requiring + any elevated permission. This can make testing OpenVPN much easier. + + For more details see [lwipovpn on Github](https://github.com/OpenVPN/lwipovpn). + +* **Allow overriding username with `--override-username`** + + This is intended to allow using `--auth-gen-token` in scenarios where the + clients use certificates and multi-factor authentication. This will also + generate a `push "auth-token-user newusername"` directive in push replies. + +* **`--port-share` now properly supports IPv6** + + Issues with logging of IPv6 addresses were fixed. The feature now allows IPv6 + connections towards the proxy receiver. + +* **Support for Haiku OS** + +* **TLS1.3 support with mbedTLS (requires mbedTLS >= 3.6.4)** + +* **PUSH_UPDATE client support** + + It is now possible to update parts of the client-side configuration (IP address, + routes, MTU, DNS) by sending a new server-to-client control message, + `PUSH_UPDATE,`. See also: + + + NOTE: PUSH_UPDATE client support is currently disabled if DCO is active (on all + platforms). + +* **PUSH_UPDATE server support (minimal)** + + New management interface commands `push-update-broad` and `push-update-cid` to + send PUSH_UPDATE option updates to all clients ("there is a new DNS server") or + only a specific client ID ("privileges have changed, here's a new IP address"). + + See doc/management-notes.txt + + NOTE: PUSH_UPDATE server support is currently disabled if DCO is active + (on all platforms). + +* **Support for user-defined routing tables on Linux** + + See the `--route-table` option in the manpage + +* **PQE support for WolfSSL** + +* **New environment variables for gateway redirection** + + Two new environment variables have been introduced to communicate desired + default gateway redirection to plugins like Network Manager, + `route_redirect_gateway_ipv4` and `route_redirect_gateway_ipv6`. See the + "Environmental Variables" section in the man page + +* **Improved logging of service events/errors to event log on Windows.** + +* **Improved "Recursive Routing" check** + + The check is now more granular, and will only drop + packets-in-tunnel if destination IP, protocol and port matches with those needed + to reach the VPN server. With that change, you can now use policies that direct + "everything that is not OpenVPN" into the tunnel, and have IP packets to the VPN + server address arrive as expected (no such policies are currently installed by + OpenVPN) (GH: OpenVPN/openvpn#669). + +* **COPYING: license details only relevant to our Windows installers have +been updated and moved to the openvpn-build repo** + +* **Improved BYTECOUNT support** + + More strictly adhere to timing interval requested, correctly support client and + server counters with Linux and Windows DCO offloading. + +* **Improve compatibility with OpenSSL 3.6.0 (do not fail t_lpback selftest)** + +* **New option `--tls-crypt-v2-max-age n` to check tls-crypt-v2 timestamps** + + When a client is older than n days or has no timestamp, the server will reject + it. + +* **mbedTLS 4 support has been added.** + + Note that with mbedTLS 4 algorithms need to be translated to mbedTLS 4 internal + IDs by OpenVPN, and some names might be missing. + +## Deprecated features + +* **`secret` support has been removed (by default).** + + static key mode (non-TLS) is no longer considered "good and secure enough" for + today's requirements. Use TLS mode instead. If deploying a PKI CA is considered + "too complicated", using `--peer-fingerprint` makes TLS mode about as easy as + using `--secret`. + + This mode can still be enabled by using + `--allow-deprecated-insecure-static-crypto` but will be removed in OpenVPN 2.8. + +* **Support for wintun Windows driver has been removed.** + + OpenVPN 2.6 added support for the new dco-win driver, so it supported three + different device drivers: dco-win, wintun, and tap-windows6. OpenVPN 2.7 now + drops the support for wintun driver. By default all modern configs should be + supported by dco-win driver. In all other cases OpenVPN will fall back + automatically to tap-windows6 driver. + +* **NTLMv1 authentication support for HTTP proxies has been removed.** + + This is considered an insecure method of authentication that uses obsolete + crypto algorithms. NTLMv2 support is still available, but will be removed in a + future release. When configured to authenticate with NTLMv1 (`ntlm` keyword in + `--http-proxy`) OpenVPN will try NTLMv2 instead. + +* **`persist-key` option has been enabled by default.** + + All the keys will be kept in memory across restart. + +* **OpenSSL 1.0.2 support has been removed.** + + Support for building with OpenSSL 1.0.2 has been removed. The minimum supported + OpenSSL version is now 1.1.0. + +* **mbedTLS 2.x support has been removed** + + Support for building with mbedTLS 2.x has been removed (it is out of support + since March 2025, and the necessary compatibility code is making maintenance and + support for mbedTLS 4.x hard). The minimum supported mbedTLS version is now + 3.2.1. + +* **Compression on send has been removed.** + + OpenVPN 2.7 will never compress data before sending. Decompression of received + data is still supported. `--allow-compression yes` is now an alias for + `--allow-compression asym`. + +* **`--memstats` feature removed** + + The `--memstats` option was largely undocumented and there is no known user of + this feature. This feature provided very limited statistics (number of users, + link bytes read/written) and we do not except any usage because of this. + +* **Warning when using `--push` without `--mode server`** + + Using `--push` in a mode that is not `--mode server` will now print a + clear warning that this is an unsupported operation and might cause negotiation + failures. + +* **Warning for `--reneg-bytes` and `--reneg-packets` in DCO mode** + + `--reneg-bytes` and `--reneg-packets` do not work in DCO mode, and will + now print an appropriate warning. + +* **On-connect resolving of `--remote` in `--tcp-server` mode removed** + + On-connect resolving of `--remote` addresses in `--tcp-server` mode + was not working since 2.4, so the code was completely removed. + +## User-visible Changes + +- Default for `--topology` changed to `subnet` for `--mode server`. Previous + releases always used `net30` as default. This only affects configs with + `--mode server` or `--server` (the latter implies the former), and + `--dev tun`, and only if IPv4 is enabled. Note that this changes the semantics + of `--ifconfig`, so if you have manual settings for that in your config but + not set `--topology` your config might fail to parse with the new version. + Just adding `--topology net30` to the config should fix the problem. By + default `--topology` is pushed from server to client. +- `--x509-username-field` will no longer automatically convert fieldnames to + uppercase. This was deprecated since OpenVPN 2.4, and has now been removed. +- `--dh none` is now the default if `--dh` is not specified. Modern TLS + implementations will prefer ECDH and other more modern algorithms anyway. And + finite field Diffie Hellman is in the proces of being deprecated (see + draft-ietf-tls-deprecate-obsolete-kex) +- `--lport 0` does not imply `--bind` anymore. +- `--redirect-gateway` now works correctly if the VPN remote is not reachable by + the default gateway. +- `--show-gateway` now supports querying the gateway for IPv4 addresses. +- `--static-challenge` option now has a third parameter `format` that can change + how password and challenge response should be combined. +- `--key` and `--cert` now accept URIs implemented in OpenSSL 3 as well as + optional OpenSSL 3 providers loaded using `--providers` option. +- `--cryptoapicert` now supports issuer name as well as Windows CA template name + or OID as selector string. +- TLS handshake debugging information contains much more details now when using + recent versions of OpenSSL. +- The `IV_PLAT_VER` variable sent by Windows clients now contains the full + Windows build version to make it possible to determine the Windows 10 or + Windows 11 version used. +- The `--windows-driver` option to select between various windows drivers will + no longer do anything - it's kept so existing configs will not become invalid, + but it is ignored with a warning. The default is now `ovpn-dco` if all options + used are compatible with DCO, with a fallback to `tap-windows6`. To force TAP + (for example because a server pushes DCO incompatible options), use the + `--disable-dco` option. +- Apply more checks to incoming TLS handshake packets before creating new + state - namely, verify message ID / acked ID for "valid range for an initial + packet". This fixes a problem with clients that float very early but send + control channel packet from the pre-float IP (Github: OpenVPN/openvpn#704). +- Use of `--dh dh2048.pem` in all sample configs has been replaced with + `--dh none`. The `dh2048.pem` file has been removed. +- The startup delay in `t_client.sh` has been reduced from 3s to 1s, making a + noticeable difference for setups with many tests. +- Changed from using `uncrustify` for code formatting and pre-commit checks to + `clang-format`. This reformatted quite a bit of code, and requires that + regular committers change their pre-commit checks accordingly. +- On Linux, on interfaces where applicable, OpenVPN explicitly configures the + broadcast address again. This was dropped for 2.6.0 "because computers are + smart and can do it themselves", but the kernel netlink interface isn't, and + will install "0.0.0.0". This does not normally matter, but for broadcast-based + applications that get the address to use from "ifconfig", this change repairs + functionality (this has been backported to 2.6.15, but is not in earlier 2.6 + versions). +- `max-routes-per-client 0` used to be silently upgraded to `1`. This now + produces an error. +- `ifconfig` and `ifconfig-ipv6` values are now stored in pre-connect options + cache, and will be restored to pre-connect values on reconnects if the server + stops pushing the respective option. +- `tapctl.exe` helper binary on Windows has been reworked to improve help texts + (making clear that it can not only do TAP-Adapters but Win-DCO as well), add + printing of the hwid to all adapter outputs, and change the default adapter + type created to `ovpn-dco`. +- The default for `multihome` egress interface handling has changed. 2.7.0 will + default to ipi_ifindex=0, that is, leave the decision to the routing/policy + setup of the operating system. The pre-2.7 behaviour (force egress = ingress + interface) can be achieved with the new `--multihome same-interface` + sub-option. +- Windows `openvpn.exe` binary manifest now sets code page UTF8 - which has no + direct effect on OpenVPN itself, but this repairs OpenSSL file loading for + key/cert files with non-ASCII characters in their file names (GH: + OpenVPN/openvpn#920). +- The `test-crypto` option no longer requires a `--secret` argument and will + automatically generate a random key. +- The configure-time option `--enable-x509-alt-username` is no longer + conditional, and always-on (GH: OpenVPN/openvpn#917). + +## Deprecated features + +* **`--opt-verify` feature removed** + + This option was already deprecated and it is now being converted to a no-op. + Using this option will only print a warning. + +# Overview of changes in 2.6 + +## Project changes + +We want to deprecate our old Trac bug tracking system. Please report any issues +with this release in GitHub instead: + +## New features + +* **Support unlimited number of connection entries and remote entries** + +* **New management commands to enumerate and list remote entries** + + Use `remote-entry-count` and `remote-entry-get` commands from the management + interface to get the number of remote entries and the entries themselves. + +* **Keying Material Exporters (RFC 5705) based key generation** + + As part of the cipher negotiation OpenVPN will automatically prefer the RFC5705 + based key material generation to the current custom OpenVPN PRF. This feature + requires OpenSSL or mbed TLS 2.18+. + +* **Compatibility with OpenSSL in FIPS mode** + + OpenVPN will now work with OpenSSL in FIPS mode. Note, no effort has been made + to check or implement all the requirements/recommendation of FIPS 140-2. This + just allows OpenVPN to be run on a system that be configured OpenSSL in FIPS + mode. + +* **`mlock` now checks available memlock-able memory** + + `mlock` will now check if enough memlock-able memory has been reserved, + and if less than 100MB RAM are available, use setrlimit() to upgrade the limit. + See Trac #1390. Not available on OpenSolaris. + +* **Certificate pinning/verify peer fingerprint** + + The `--peer-fingerprint` option has been introduced to give users an easy to use + alternative to the `tls-verify` for matching the fingerprint of the peer. The + option takes use a number of allowed SHA256 certificate fingerprints. + + See the man page section "Small OpenVPN setup with peer-fingerprint" for a + tutorial on how to use this feature. This is also available online under + + +* **TLS mode with self-signed certificates** + + When `--peer-fingerprint` is used, the `--ca` and `--capath` option become + optional. This allows for small OpenVPN setups without setting up a PKI with + Easy-RSA or similar software. + +* **Deferred auth support for scripts** + + The `--auth-user-pass-verify` script supports now deferred authentication. + +* **Pending auth support for plugins and scripts** + + Both auth plugin and script can now signal pending authentication to the client + when using deferred authentication. The new `client-crresponse` script option + and `OPENVPN_PLUGIN_CLIENT_CRRESPONSE` plugin function can be used to parse a + client response to a `CR_TEXT` two factor challenge. + + See `sample/sample-scripts/totpauth.py` for an example. + +* **Compatibility mode (`--compat-mode`)** + + The modernisation of defaults can impact the compatibility of OpenVPN 2.6.0 with + older peers. The options `--compat-mode` allows UIs to provide users with an + easy way to still connect to older servers. + +* **OpenSSL 3.0 support** + + OpenSSL 3.0 has been added. Most of OpenSSL 3.0 changes are not user visible but + improve general compatibility with OpenSSL 3.0. `--tls-cert-profile insecure` + has been added to allow selecting the lowest OpenSSL security level (not + recommended, use only if you must). OpenSSL 3.0 no longer supports the Blowfish + (and other deprecated) algorithm by default and the new option `--providers` + allows loading the legacy provider to renable these algorithms. + +* **Optional ciphers in `--data-ciphers`** + + Ciphers in `--data-ciphers` can now be prefixed with a `?` to mark those as + optional and only use them if the SSL library supports them. + +* **Improved `--mssfix` and `--fragment` calculation** + + The `--mssfix` and `--fragment` options now allow an optional `mtu` parameter to + specify that different overhead for IPv4/IPv6 should taken into account and the + resulting size is specified as the total size of the VPN packets including IP + and UDP headers. + +* **Cookie based handshake for UDP server** + + Instead of allocating a connection for each client on the initial packet OpenVPN + server will now use an HMAC based cookie as its session id. This way the server + can verify it on completing the handshake without keeping state. This eliminates + the amplification and resource exhaustion attacks. For tls-crypt-v2 clients, + this requires OpenVPN 2.6 clients or later because the client needs to resend + its client key on completing the hand shake. The tls-crypt-v2 option allows + controlling if older clients are accepted. + + By default the rate of initial packet responses is limited to 100 per 10s + interval to avoid OpenVPN servers being abused in reflection attacks (see + `--connect-freq-initial`). + +* **Data channel offloading with ovpn-dco** + + 2.6.0+ implements support for data-channel offloading where the data packets are + directly processed and forwarded in kernel space thanks to the ovpn-dco kernel + module. The userspace openvpn program acts purely as a control plane + application. Note that DCO will use DATA\_V2 packets in P2P mode, therefore, this + implies that peers must be running 2.6.0+ in order to have P2P-NCP which brings + DATA\_V2 packet support. + +* **Session timeout** + + It is now possible to terminate a session (or all) after a specified amount of + seconds has passed session commencement. This behaviour can be configured using + `--session-timeout`. This option can be configured on the server, on the client + or can also be pushed. + +* **Inline auth username and password** + + Username and password can now be specified inline in the configuration file + within the `` tags. If the password is + missing OpenVPN will prompt for input via stdin. This applies to inline'd + http-proxy-user-pass too. + +* **Tun MTU can be pushed** + + The client can now also dynamically configure its MTU and the server will try to + push the client MTU when the client supports it. The directive `--tun-mtu-max` + has been introduced to increase the maximum pushable MTU size (defaults to + 1600). + +* **Dynamic TLS Crypt** + + When both peers are OpenVPN 2.6.1+, OpenVPN will dynamically create a tls-crypt + key that is used for renegotiation. This ensure that only the previously + authenticated peer can do trigger renegotiation and complete renegotiations. + +* **Improved control channel packet size control (`max-packet-size`)** + + The size of control channel is no longer tied to `--link-mtu`/`--tun-mtu` and + can be set using `--max-packet-size`. Sending large control channel frames is + also optimised by allowing 6 outstanding packets instead of just 4. + `max-packet-size` will also set `mssfix` to try to limit data-channel packets as + well. + +## Deprecated features + +* **`inetd` has been removed** + + This was a very limited and not-well-tested way to run OpenVPN, on TCP and TAP + mode only. + +* **`verify-hash` has been deprecated** + + This option has very limited usefulness and should be replaced by either a + better `--ca` configuration or with a `--tls-verify` script. + +* **`secret` has been deprecated** + + Static key mode (non-TLS) is no longer considered "good and secure enough" for + today's requirements. Use TLS mode instead. If deploying a PKI CA is considered + "too complicated", using `--peer-fingerprint` makes TLS mode about as easy as + using `--secret`. + +* **`ncp-disable` has been removed** + + This option mainly served a role as debug option when NCP was first introduced. + It should now no longer be necessary. + +* **TLS 1.0 and 1.1 are deprecated** + + `tls-version-min` is set to 1.2 by default. OpenVPN 2.6.0 defaults to a minimum + TLS version of 1.2 as TLS 1.0 and 1.1 should be generally avoided. Note that + OpenVPN versions older than 2.3.7 use TLS 1.0 only. + +* **`--cipher` argument is no longer appended to `--data-ciphers` by default** + + Data cipher negotiation has been introduced in 2.4.0 and been + significantly improved in 2.5.0. The implicit fallback to the cipher specified + in `--cipher` has been removed. Effectively, `--cipher` is a no-op in TLS mode + now, and will only have an effect in pre-shared-key mode (`--secret`). From now + on `--cipher` should not be used in new configurations for TLS mode. Should + backwards compatibility with older OpenVPN peers be required, please see the + `--compat-mode` instead. + +* **`--prng` has beeen removed** + + OpenVPN used to implement its own PRNG based on a hash. However implementing a + PRNG is better left to a crypto library. So we use the PRNG mbed TLS or OpenSSL + now. + +* **`--keysize` has been removed** + + The `--keysize` option was only useful to change the key length when using the + BF, CAST6 or RC2 ciphers. For all other ciphers the key size is fixed with the + chosen cipher. As OpenVPN v2.6 no longer supports any of these variable length + ciphers, this option was removed as well to avoid confusion. + +* **Compression no longer enabled by default** + + Unless an explicit compression option is specified in the configuration, + `--allow-compression` defaults to `no` in OpeNVPN 2.6.0. By default, OpenVPN 2.5 + still allowed a server to enable compression by pushing compression related + options. + +* **PF (Packet Filtering) support has been removed** + + The built-in PF functionality has been removed from the code base. This feature + wasn't really easy to use and was long unmaintained. This implies that also + `--management-client-pf` and any other compile time or run time related option + do not exist any longer. + +* **Option conflict checking is being deprecated and phased out** + + The static option checking (OCC) is no longer useful in typical setups that + negotiate most connection parameters. The `--opt-verify` and `--occ-disable` + options are deprecated, and the configure option `--enable-strict-options` has + been removed. Logging of mismatched options has been moved to debug logging + (verb 7). + +## User-visible Changes + +- CHACHA20-POLY1305 is included in the default of `--data-ciphers` when + available. +- Option `--prng` is ignored as we rely on the SSL library random number + generator. +- Option `--nobind` is default when `--client` or `--pull` is used in the + configuration +- `link_mtu` parameter is removed from environment or replaced with 0 when + scripts are called with parameters. This parameter is unreliable and no longer + internally calculated. +- control channel packet maximum size is no longer influenced by + `--link-mtu`/`--tun-mtu` and must be set by `--max-packet-size` now. The + default is 1250 for the control channel size. +- In point-to-point OpenVPN setups (no `--server`), using `--explict-exit-notiy` + on one end would terminate the other side at session end. This is considered a + no longer useful default and has been changed to "restart on reception of + explicit-exit-notify message". If the old behaviour is still desired, + `--remap-usr1 SIGTERM` can be used. +- FreeBSD tun interfaces with `--topology subnet` are now put into real subnet + mode (IFF_BROADCAST instead of IFF_POINTOPOINT) - this might upset software + that enumerates interfaces, looking for "broadcast capable?" and expecting + certain results. Normal uses should not see any difference. +- The default configurations will no longer allow connections to OpenVPN 2.3.x + peer or earlier, use the new `--compat-mode` option if you need compatibility + with older versions. See the manual page on the `--compat-mode` for details. +- The `client-pending-auth` management command now requires also the key id. The + management version has been changed to 5 to indicate this change. +- (OpenVPN 2.6.2) A client will now refuse a connection if pushed compression + settings will contradict the setting of allow-compression as this almost + always results in a non-working connection. +- The "kill" by addr management command now requires also the protocol as string + e.g. "udp", "tcp". + +## Common errors with OpenSSL 3.0 and OpenVPN 2.6 + +Both OpenVPN 2.6 and OpenSSL 3.0 tighten the security considerable, so some +configuration will no longer work. This section will cover the most common +causes and error message we have seen and explain their reason and temporary +workarounds. You should fix the underlying problems as soon as possible since +these workaround are not secure and will eventually stop working in a future +update. + +- weak SHA1 or MD5 signature on certificates + + This will happen on either loading of certificates or on connection to a + server: + + OpenSSL: error:0A00018E:SSL routines::ca md too weak + Cannot load certificate file cert.crt + Exiting due to fatal error + + OpenSSL 3.0 no longer allows weak signatures on certificates. You can + downgrade your security to allow them by using `--tls-cert-profile insecure` + but should replace/regenerate these certificates as soon as possible. + +- 1024 bit RSA certificates, 1024 bit DH parameters, other weak keys + + This happens if you use private keys or other cryptographic material that does + not meet today's cryptographic standards anymore. Messages are similar to: + + OpenSSL: error:0A00018F:SSL routines::ee key too small + OpenSSL: error:1408518A:SSL routines:ssl3_ctx_ctrl:dh key too small + + DH parameters (`--dh`) can be regenerated with `openssl dhparam 2048`. For + other cryptographic keys, these keys and certificates need to be regenerated. + TLS Security level can be temporarily lowered with `--tls-cert-profile legacy` + or even `--tls-cert-profile insecure`. + +- Connecting to a OpenVPN 2.3.x server or allowing OpenVPN 2.3.x or earlier + clients + + This will normally result in messages like: + + OPTIONS ERROR: failed to negotiate cipher with server. Add the server's cipher ('AES-128-CBC') to --data-ciphers (currently 'AES-256-GCM:AES-128-GCM:CHACHA20-POLY1305') if you want to connect to this server. + + or + + client/127.0.0.1:49954 SENT CONTROL [client]: 'AUTH_FAILED,Data channel cipher negotiation failed (no shared cipher)' (status=1) + + You can manually add the missing cipher to the `--data-ciphers`. The standard + ciphers should be included as well, e.g. + `--data-ciphers AES-256-GCM:AES-128-GCM:?Chacha20-Poly1305:?AES-128-CBC`. You + can also use the `--compat-mode` option. Note that these message may also + indicate other cipher configuration problems. See the data channel cipher + negotiation manual section for more details. (Available online under + ) + +- Use of a legacy or deprecated cipher (e.g. 64bit block ciphers) + + OpenSSL 3.0 no longer supports a number of insecure and outdated ciphers in + its default configuration. Some of these ciphers are known to be vulnerable + (SWEET32 attack). + + This will typically manifest itself in messages like: + + OpenSSL: error:0308010C:digital envelope routines::unsupported + Cipher algorithm 'BF-CBC' not found + Unsupported cipher in --data-ciphers: BF-CBC + + If your OpenSSL distribution comes with the legacy provider (see also + `man OSSL_PROVIDER-legacy`), you can load it with + `--providers legacy default`. This will re-enable the old algorithms. + +- OpenVPN version not supporting TLS 1.2 or later + + The default in OpenVPN 2.6 and also in many distributions is now TLS 1.2 or + later. Connecting to a peer that does not support this will results in + messages like: + + TLS error: Unsupported protocol. + + This typically indicates that client and server have no common TLS version + enabled. This can be caused by mismatched tls-version-min and tls-version-max + options on client and server. If your OpenVPN client is between v2.3.6 and + v2.3.2 try adding `tls-version-min 1.0` to the client configuration to use + TLS 1.0+ instead of TLS 1.0 only. + + OpenSSL: error:0A000102:SSL routines::unsupported protocol + + This can be an OpenVPN 2.3.6 or earlier version. `compat-version 2.3.0` will + enable TLS 1.0 support if supported by the OpenSSL distribution. Note that on + some Linux distributions enabling TLS 1.1 or 1.0 is not possible. + +# Overview of changes in 2.5 + +## New features + +* **Client-specific tls-crypt keys (`--tls-crypt-v2`)** + + `tls-crypt-v2` adds the ability to supply each client with a unique tls-crypt + key. This allows large organisations and VPN providers to profit from the same + DoS and TLS stack protection that small deployments can already achieve using + `tls-auth` or `tls-crypt`. + +* **ChaCha20-Poly1305 cipher support** + + Added support for using the ChaCha20-Poly1305 cipher in the OpenVPN data + channel. + +* **Improved Data channel cipher negotiation** + + The option `ncp-ciphers` has been renamed to `data-ciphers`. The old name is + still accepted. The change in name signals that `data-ciphers` is the preferred + way to configure data channel ciphers and the data prefix is chosen to avoid the + ambiguity that exists with `--cipher` for the data cipher and `tls-cipher` for + the TLS ciphers. + + OpenVPN clients will now signal all supported ciphers from the `data-ciphers` + option to the server via `IV_CIPHERS`. OpenVPN servers will select the first + common cipher from the `data-ciphers` list instead of blindly pushing the first + cipher of the list. This allows to use a configuration like + `data-ciphers ChaCha20-Poly1305:AES-256-GCM` on the server that prefers + ChaCha20-Poly1305 but uses it only if the client supports it. + + See the data channel negotiation section in the manual for more details. + +* **Removal of BF-CBC support in default configuration:** + + By default OpenVPN 2.5 will only accept AES-256-GCM and AES-128-GCM as data + ciphers. OpenVPN 2.4 allows AES-256-GCM,AES-128-GCM and BF-CBC when no --cipher + and --ncp-ciphers options are present. Accepting BF-CBC can be enabled by adding + + > data-ciphers AES-256-GCM:AES-128-GCM:BF-CBC + + and when you need to support very old peers also + + > data-ciphers-fallback BF-CBC + + To offer backwards compatibility with older configs an *explicit* + + > cipher BF-CBC + + in the configuration will be automatically translated into adding BF-CBC to the + data-ciphers option and setting data-ciphers-fallback to BF-CBC (as in the + example commands above). We strongly recommend to switching away from BF-CBC to + a more secure cipher. + +* **Asynchronous (deferred) authentication support for auth-pam plugin.** + + See src/plugins/auth-pam/README.auth-pam for details. + +* **Deferred client-connect** + + The `--client-connect` option and the connect plugin API allow + asynchronous/deferred return of the configuration file in the same way as the + auth-plugin. + +* **Faster connection setup** + + A client will signal in the `IV_PROTO` variable that it is in pull mode. This + allows the server to push the configuration options to the client without + waiting for a `PULL_REQUEST` message. The feature is automatically enabled if + both client and server support it and significantly reduces the connection setup + time by avoiding one extra packet round-trip and 1s of internal event delays. + +* **Netlink support** + + On Linux, if configured without `--enable-iproute2`, configuring IP addresses + and adding/removing routes is now done via the netlink(3) kernel interface. This + is much faster than calling `ifconfig` or `route` and also enables OpenVPN to + run with less privileges. + + If configured with --enable-iproute2, the `ip` command is used (as in 2.4). + Support for `ifconfig` and `route` is gone. + +* **Wintun support** + + On Windows, OpenVPN can now use `wintun` devices. They are faster than the + traditional `tap9` tun/tap devices, but do not provide `--dev tap` mode - so the + official installers contain both. To use a wintun device, add + `--windows-driver wintun` to your config (and use of the interactive service is + required as wintun needs SYSTEM privileges to enable access). + +* **IPv6-only operation** + + It is now possible to have only IPv6 addresses inside the VPN tunnel, and + IPv6-only address pools (2.4 always required IPv4 config/pools and IPv6 was the + "optional extra"). + +* **Improved Windows 10 detection** + + Correctly log OS on Windows 10 now. + +* **Linux VRF support** + + Using the new `--bind-dev` option, the OpenVPN outside socket can now be put + into a Linux VRF. See the "Virtual Routing and Forwarding" documentation in the + man page. + +* **TLS 1.3 support** + + TLS 1.3 support has been added to OpenVPN. Currently, this requires OpenSSL + 1.1.1+. The options `--tls-ciphersuites` and `--tls-groups` have been added to + fine tune TLS protocol options. Most of the improvements were also backported to + OpenVPN 2.4 as part of the maintainance releases. + +* **Support setting DHCP search domain** + + A new option `--dhcp-option DOMAIN-SEARCH my.example.com` has been defined, and + Windows support for it is implemented (tun/tap only, no wintun support yet). + Other platforms need to support this via `--up` script (Linux) or GUI + (OSX/Tunnelblick). + +* **per-client changing of `--data-ciphers` or `data-ciphers-fallback`** + + Via client-connect script/dir (NOTE: this only changes preference of ciphers + for NCP, but can not override what the client announces as "willing to accept"). + +* **Handle setting of tun/tap interface MTU on Windows** + + If IPv6 is in use, MTU must be >= 1280 (Windows enforces IETF requirements) + +* **Add support for OpenSSL engines to access private key material (like TPM).** + +* **HMAC based auth-token support** + + The `--auth-gen-token` support has been improved and now generates HMAC based + user token. If the optional `--auth-gen-token-secret` option is used clients + will be able to seamlessly reconnect to a different server using the same secret + file or to the same server after a server restart. + +* **Improved support for pending authentication** + + The protocol has been enhanced to be able to signal that the authentication + should use a secondary authentication via web (like SAML) or a two factor + authentication without disconnecting the OpenVPN session with AUTH_FAILED. The + session will instead be stay in a authenticated state and wait for the second + factor authentication to complete. + + This feature currently requires usage of the managent interface on both client + and server side. See the `management-notes.txt` `client-pending-auth` and + `cr-response` commands for more details. + +* **VLAN support** + + OpenVPN servers in TAP mode can now use 802.1q tagged VLANs on the TAP interface + to separate clients into different groups that can then be handled differently + (different subnets / DHCP, firewall zones, ...) further down the network. See + the new options `--vlan-tagging`, `--vlan-accept`, `--vlan-pvid`. + + 802.1q tagging on the client side TAP interface is not handled today (= tags are + just forwarded transparently to the server). + +* **Support building of .msi installers for Windows** + +* **Allow unicode search string in `--cryptoapicert` option (Windows)** + +* **Support IPv4 configs with /31 netmasks now** + + (By no longer trying to configure `broadcast x.x.x.x` in ifconfig calls, /31 + support "just works") + +* **New option `--block-ipv6` to reject all IPv6 packets (ICMPv6)** + + This is useful if the VPN service has no IPv6, but the clients might have (LAN), + to avoid client connections to IPv6-enabled servers leaking "around" the + IPv4-only VPN. + +* **`--ifconfig-ipv6` and `--ifconfig-ipv6-push` accept hostnames** + + `--ifconfig-ipv6` and `--ifconfig-ipv6-push` will now accept hostnames and do + a DNS lookup to get the IPv6 address to use. + +## Deprecated features + +For an up-to-date list of all deprecated options, see this wiki page: + + +- `ncp-disable` has been deprecated. + + With the improved and matured data channel cipher negotiation, the use of + `ncp-disable` should not be necessary anymore. + +- `inetd` has been deprecated. + + This is a very limited and not-well-tested way to + run OpenVPN, on TCP and TAP mode only, which complicates the code quite a bit + for little gain. To be removed in OpenVPN 2.6 (unless users protest). + +- `no-iv` has been removed. + + This option was made into a NOOP option with OpenVPN + 2.4. This has now been completely removed. + +- `--client-cert-not-required` has been removed + + This option will now cause server configurations to not start. + Use `--verify-client-cert none` instead. + +- `--ifconfig-pool-linear` has been removed. + + This option is removed. Use `--topology p2p` or `--topology subnet` instead. + +- `--compress xxx` is considered risky and is warned against, see below. + +- `--key-method 1` has been removed + +## User-visible Changes + +- If multiple connect handlers are used (client-connect, ccd, connect plugin) + and one of the handler succeeds but a subsequent fails, the + client-disconnect-script is now called immediately. Previously it was called, + when the VPN session was terminated. +- Support for building with OpenSSL 1.0.1 has been removed. The minimum + supported OpenSSL version is now 1.0.2. +- The GET_CONFIG management state is omitted if the server pushes the client + configuration almost immediately as result of the faster connection setup + feature. +- `--compress` is nowadays considered risky, because attacks exist leveraging + compression-inside-crypto to reveal plaintext (VORACLE). So by default, + `--compress xxx` will now accept incoming compressed packets (for + compatibility with peers that have not been upgraded yet), but will not use + compression outgoing packets. This can be controlled with the new option + `--allow-compression yes|no|asym`. +- Stop changing `--txlen` aways from OS defaults unless explicitly specified in + config file. OS defaults nowadays are actually larger then what we used to + configure, so our defaults sometimes caused packet drops = bad performance. +- remove `--writepid` pid file on exit now +- plugin-auth-pam now logs via OpenVPN logging method, no longer to stderr (this + means you'll have log messages in syslog or openvpn log file now) +- use ISO 8601 time format for file based logging now (YYYY-MM-DD hh:mm:dd) + (syslog is not affected, nor is `--machine-readable-output`) +- `--clr-verify` now loads all CRLs if more than one CRL is in the same file + (OpenSSL backend only, mbedTLS always did that) +- when `--auth-user-pass file` has no password, and the management interface is + active, query management interface (instead of trying console query, which + does not work on windows) +- skip expired certificates in Windows certificate store (`--cryptoapicert`) +- `--socks-proxy` + `--proto udp*` will now allways use IPv4, even if IPv6 is + requested and available. Our SOCKS code does not handle IPv6+UDP, and before + that change it would just fail in non-obvious ways. +- TCP listen() backlog queue is now set to 32 - this helps TCP servers that + receive lots of "invalid" connects by TCP port scanners +- do no longer print OCC warnings ("option mismatch") about `key-method`, + `keydir`, `tls-auth` and `cipher` - these are either gone now, or negotiated, + and the warnings do not serve a useful purpose. +- `dhcp-option DNS` and `dhcp-option DNS6` are now treated identically (= both + accept an IPv4 or IPv6 address for the nameserver) + +## Maintainer-visible changes + +- the man page is now in maintained in .rst format, so building the openvpn.8 + manpage from a git checkout now requires python-docutils (if this is missing, + the manpage will not be built - which is not considered an error generally, + but for package builders or `make distcheck` it is). Release tarballs contain + the openvpn.8 file, so unless some .rst is changed, doc-utils are not needed + for building. +- OCC support can no longer be disabled +- AEAD support is now required in the crypto library +- `--disable-server` has been removed from configure (so it is no longer + possible to build a client-/p2p-only OpenVPN binary) - the saving in code size + no longer outweighs the extra maintenance effort. +- `--enable-iproute2` will disable netlink(3) support, so maybe remove that from + package building configs (see above) +- support building with MSVC 2019 +- cmocka based unit tests are now only run if cmocka is installed externally + (2.4 used to ship a local git submodule which was painful to maintain) +- `--disable-crypto` configure option has been removed. OpenVPN is now always + built with crypto support, which makes the code much easier to maintain. This + does not affect `--cipher none` to do a tunnel without encryption. +- `--disable-multi` configure option has been removed + +# Overview of changes in 2.4 + +## New features + +* **Seamless client IP/port floating** + + Added new packet format P_DATA_V2, which includes peer-id. If both the server + and client support it, the client sends all data packets in the new format. When + a data packet arrives, the server identifies peer by peer-id. If peer's ip/port + has changed, server assumes that client has floated, verifies HMAC and updates + ip/port in internal structs. This allows the connection to be immediately + restored, instead of requiring a TLS handshake before the server accepts packets + from the new client ip/port. + +* **Data channel cipher negotiation** + + Data channel ciphers (`--cipher`) are now by default negotiated. If a client + advertises support for Negotiable Crypto Parameters (NCP), the server will + choose a cipher (by default AES-256-GCM) for the data channel, and tell the + client to use that cipher. Data channel cipher negotiation can be controlled + using `--ncp-ciphers` and `--ncp-disable`. + + A more limited version also works in client-to-server and server-to-client + scenarios where one of the end points uses a v2.4 client or server and the other + side uses an older version. In such scenarios the v2.4 side will change to the + `--cipher` set by the remote side, if permitted by by `--ncp-ciphers`. For + example, a v2.4 client with `--cipher BF-CBC` and + `ncp-ciphers AES-256-GCM:AES-256-CBC` can connect to both a v2.3 server with + `cipher BF-CBC` as well as a server with `cipher AES-256-CBC` in its config. The + other way around, a v2.3 client with either `cipher BF-CBC` or + `cipher AES-256-CBC` can connect to a v2.4 server with e.g. `cipher BF-CBC` and + `ncp-ciphers AES-256-GCM:AES-256-CBC` in its config. For this to work it + requires that OpenVPN was built without disabling OCC support. + +* **AEAD (GCM) data channel cipher support** + + The data channel now supports AEAD ciphers (currently only GCM). The AEAD packet + format has a smaller crypto overhead than the CBC packet format, (e.g. 20 bytes + per packet for AES-128-GCM instead of 36 bytes per packet for AES-128-CBC + + HMAC-SHA1). + +* **ECDH key exchange** + + The TLS control channel now supports for elliptic curve diffie-hellmann key + exchange (ECDH). + +* **Improved Certificate Revocation List (CRL) processing** + + CRLs are now handled by the crypto library (OpenSSL or mbed TLS), instead of + inside OpenVPN itself. The crypto library implementations are more strict than + the OpenVPN implementation was. This might reject peer certificates that would + previously be accepted. If this occurs, OpenVPN will log the crypto library's + error description. + +* **Dualstack round-robin DNS client connect** + + Instead of only using the first address of each `--remote` OpenVPN will now try + all addresses (IPv6 and IPv4) of a `--remote` entry. + +* **Support for providing IPv6 DNS servers** + + A new DHCP sub-option `DNS6` is added alongside with the already existing `DNS` + sub-option. This is used to provide DNS resolvers available over IPv6. This may + be pushed to clients where `--up` scripts and `--plugin` can act upon it through + the `foreign_option_` environment variables. + + Support for the Windows client picking up this new sub-option is added, however + IPv6 DNS resolvers need to be configured via `netsh` which requires + administrator privileges unless the new interactive services on Windows is being + used. If the interactive service is used, this service will execute `netsh` in + the background with the proper privileges. + +* **New improved Windows Background service** + + The new OpenVPNService is based on openvpnserv2, a complete rewrite of the + OpenVPN service wrapper. It is intended for launching OpenVPN instances that + should be up at all times, instead of being manually launched by a user. + OpenVPNService is able to restart individual OpenVPN processes if they crash, + and it also works properly on recent Windows versions. OpenVPNServiceLegacy + tends to work poorly, if at all, on newer Windows versions (8+) and its use is + not recommended. + +* **New interactive Windows service** + + The installer starts OpenVPNServiceInteractive automatically and configures it + to start at system startup. + + The interactive Windows service allows unprivileged users to start OpenVPN + connections in the global config directory (usually C:\Program + Files\OpenVPN\config) using OpenVPN GUI without any extra configuration. + + Users who belong to the built-in Administrator group or to the local "OpenVPN + Administrator" group can also store configuration files under + %USERPROFILE%\OpenVPN\config for use with the interactive service. + +* **redirect-gateway ipv6** + + OpenVPN has now feature parity between IPv4 and IPv6 for redirect gateway + including the handling of overlapping IPv6 routes with IPv6 remote VPN server + address. + +* **LZ4 Compression and pushable compression** + + Additionally to LZO compression OpenVPN now also supports LZ4 compression. + Compression options are now pushable from the server. + +* **Filter pulled options client-side: pull-filter** + + New option to explicitly allow or reject options pushed by the server. May be + used multiple times and is applied in the order specified. + +* **Per-client remove push options: push-remove** + + New option to remove options on a per-client basis from the "push" list (more + fine-grained than `--push-reset`). + +* **Http proxy password inside config file** + + Http proxy passwords can be specified with the inline file option + `` .. `` + +* **Windows version detection** + + Windows version is detected, logged and possibly signalled to server + (`IV_PLAT_VER=` if `--push-peer-info` is set on client). + +* **Authentication tokens** + + In situations where it is not suitable to save user passwords on the client, + OpenVPN has support for pushing a --auth-token since v2.3. This option is pushed + from the server to the client with a token value to be used instead of the users + password. For this to work, the authentication plug-in would need to implement + this support as well. In OpenVPN 2.4 --auth-gen-token is introduced, which will + allow the OpenVPN server to generate a random token and push it to the client + without any changes to the authentication modules. When the clients need to + re-authenticate the OpenVPN server will do the authentication internally, + instead of sending the re-authentication request to the authentication module . + This feature is especially useful in configurations which use One Time Password + (OTP) authentication schemes, as this allows the tunnel keys to be renegotiated + regularly without any need to supply new OTP codes. + +* **keying-material-exporter** + + Keying Material Exporter [RFC-5705] allow additional keying material to be + derived from existing TLS channel. + +* **Android platform support** + + Support for running on Android using Android's VPNService API has been added. + See doc/android.txt for more details. This support is primarily used in the + OpenVPN for Android app () + +* **AIX platform support** + + AIX platform support has been added. The support only includes tap devices since + AIX does not provide tun interface. + +* **Control channel encryption (`--tls-crypt`)** + + Use a pre-shared static key (like the `--tls-auth` key) to encrypt control + channel packets. Provides more privacy, some obfuscation and poor-man's + post-quantum security. + +* **Asynchronous push reply** + + Plug-ins providing support for deferred authentication can benefit from a more + responsive authentication where the server sends PUSH\_REPLY immediately once the + authentication result is ready, instead of waiting for the client to to send + PUSH\_REQUEST once more. This requires OpenVPN to be built with + `./configure --enable-async-push`. This is a compile-time only switch. + +## Deprecated features + +For an up-to-date list of all deprecated options, see this wiki page: + + +- `--key-method 1` is deprecated in OpenVPN 2.4 and will be removed in v2.5. + Migrate away from `--key-method 1` as soon as possible. The recommended + approach is to remove the `--key-method` option from the configuration files, + OpenVPN will then use `--key-method 2` by default. Note that this requires + changing the option in both the client and server side configs. +- `--tls-remote` is removed in OpenVPN 2.4, as indicated in the v2.3 man-pages. + Similar functionality is provided via `--verify-x509-name`, which does the + same job in a better way. +- `--compat-names` and `--no-name-remapping` were deprecated in OpenVPN 2.3 and + will be removed in v2.5. All scripts and plug-ins depending on the old + non-standard X.509 subject formatting must be updated to the standardized + formatting. See the man page for more information. +- `--no-iv` is deprecated in OpenVPN 2.4 and will be removed in v2.5. +- `--keysize` is deprecated in OpenVPN 2.4 and will be removed in v2.6 together + with the support of ciphers with cipher block size less than 128-bits. +- `--comp-lzo` is deprecated in OpenVPN 2.4. Use `--compress` instead. +- `--ifconfig-pool-linear` has been deprecated since OpenVPN 2.1 and will be + removed in v2.5. Use `--topology p2p` instead. +- `--client-cert-not-required` is deprecated in OpenVPN 2.4 and will be removed + in v2.5. Use `--verify-client-cert none` for a functional equivalent. +- `--ns-cert-type` is deprecated in OpenVPN 2.3.18 and v2.4. It will be removed + in v2.5. Use the far better `--remote-cert-tls` option which replaces this + feature. + +## User-visible Changes + +- When using ciphers with cipher blocks less than 128-bits, OpenVPN will + complain loudly if the configuration uses ciphers considered weak, such as the + SWEET32 attack vector. In such scenarios, OpenVPN will by default renegotiate + for each 64MB of transported data (`--reneg-bytes`). This renegotiation can be + disabled, but is HIGHLY DISCOURAGED. + +- For certificate DNs with duplicate fields, e.g. "OU=one,OU=two", both fields + are now exported to the environment, where each second and later occurrence of + a field get `_$N` appended to it's field name, starting at N=1. For the + example above, that would result in e.g. `X509_0_OU=one`, `X509_0_OU_1=two`. Note + that this breaks setups that rely on the fact that OpenVPN would previously + (incorrectly) only export the last occurrence of a field. + +- `proto udp` and `proto tcp` now use both IPv4 and IPv6. The new options + `proto udp4` and `proto tcp4` use IPv4 only. + +- `--sndbuf` and `--recvbuf` default now to OS defaults instead of 64k + +- OpenVPN exits with an error if an option has extra parameters; previously they + were silently ignored + +- `--tls-auth` always requires OpenVPN static key files and will no longer work + with free form files + +- `--proto udp6/tcp6` in server mode will now try to always listen to both IPv4 + and IPv6 on platforms that allow it. Use `--bind ipv6only` to explicitly + listen only on IPv6. + +- Removed `--enable-password-save` from configure. This option is now always + enabled. + +- Stricter default TLS cipher list (override with `--tls-cipher`), that now also + disables: + + - Non-ephemeral key exchange using static (EC)DH keys + - DSS private keys + +- mbed TLS builds: changed the `tls_digest_N` values exported to the script + environment to be equal to the ones exported by OpenSSL builds, namely the + certificate fingerprint (was the hash of the 'to be signed' data). + +- mbed TLS builds: minimum RSA key size is now 2048 bits. Shorter keys will not + be accepted, both local and from the peer. + +- `--connect-timeout` now specifies the timeout until the first TLS packet is + received (identical to `--server-poll-timeout`) and this timeout now includes + the removed socks proxy timeout and http proxy timeout. + + In `--static` mode `connect-timeout` specifies the timeout for TCP and proxy + connection establishment + +- `--connect-retry-max` now specifies the maximum number of unsuccessful + attempts of each remote/connection entry before exiting. + +- `--http-proxy-timeout` and the static non-changeable socks timeout (5s) have + been folded into a "unified" `--connect-timeout` which covers all steps needed + to connect to the server, up to the start of the TLS exchange. The default + value has been raised to 120s, to handle slow http/socks proxies graciously. + The old "fail TCP fast" behaviour can be achieved by adding + "`--connect-timeout 10`" to the client config. + +- `--http-proxy-retry` and `--sock-proxy-retry` have been removed. Proxy + connections will now behave like regular connection entries and generate a + USR1 on failure. + +- `--connect-retry` gets an optional second argument that specifies the maximum + time in seconds to wait between reconnection attempts when an exponential + backoff is triggered due to repeated retries. Default = 300 seconds. + +- Data channel cipher negotiation (see New features section) can override + ciphers configured in the config file. Use `--ncp-disable` if you do not want + this behavior. + +- All tun devices on all platforms are always considered to be IPv6 capable. The + `--tun-ipv6` option is ignored (behaves like it is always on). + +- On the client side recursively routed packets, which have the same destination + as the VPN server, are dropped. This can be disabled with + --allow-recursive-routing option. + +- On Windows, when the `--register-dns` option is set, OpenVPN no longer + restarts the `dnscache` service - this had unwanted side effects, and seems to + be no longer necessary with currently supported Windows versions. + +- If no flags are given, and the interactive Windows service is used, "def1" is + implicitly set (because "delete and later reinstall the existing default + route" does not work well here). If not using the service, the old behaviour + is kept. + +- OpenVPN now reloads a CRL only if the modication time or file size has + changed, instead of for each new connection. This reduces the connection setup + time, in particular when using large CRLs. + +- OpenVPN now ships with more up-to-date systemd unit files which take advantage + of the improved service management as well as some hardening steps. The + configuration files are picked up from the /etc/openvpn/server/ and + /etc/openvpn/client/ directories (depending on unit file). This also avoids + these new unit files and how they work to collide with older pre-existing unit + files. + +- Using `--no-iv` (which is generally not a recommended setup) will require + explicitly disabling NCP with `--disable-ncp`. This is intentional because NCP + will by default use AES-GCM, which requires an IV - so we want users of that + option to consciously reconsider. + +## Maintainer-visible changes + +- OpenVPN no longer supports building with crypto support, but without TLS + support. As a consequence, `OPENSSL_CRYPTO_{CFLAGS,LIBS}` and + `OPENSSL_SSL_{CFLAGS,LIBS}` have been merged into `OPENSSL_{CFLAGS,LIBS}`. + This is particularly relevant for maintainers who build their own OpenSSL + library, e.g. when cross-compiling. +- Linux distributions using systemd is highly encouraged to ship these new unit + files instead of older ones, to provide a unified behaviour across systemd + based Linux distributions. +- With OpenVPN 2.4, the project has moved over to depend on and actively use the + official C99 standard (-std=c99). This may fail on some older compiler/libc + header combinations. In most of these situations it is recommended to use + -std=gnu99 in CFLAGS. This is known to be needed when doing i386/i686 builds + on RHEL5. + +# Version 2.4.5 + +## New features + +- The new option `--tls-cert-profile` can be used to restrict the set of allowed + crypto algorithms in TLS certificates in mbed TLS builds. The default profile + is 'legacy' for now, which allows SHA1+, RSA-1024+ and any elliptic curve + certificates. The default will be changed to the 'preferred' profile in the + future, which requires SHA2+, RSA-2048+ and any curve. + +# Version 2.4.3 + +## New features + +- Support building with OpenSSL 1.1 now (in addition to older versions) +- On Win10, set low interface metric for TAP adapter when block-outside-dns is + in use, to make Windows prefer the TAP adapter for DNS queries (avoiding large + delays) + +## Security + +- CVE-2017-7522: Fix `--x509-track` post-authentication remote DoS A client + could crash a v2.4+ mbedtls server, if that server uses the `--x509-track` + option and the client has a correct, signed and unrevoked certificate that + contains an embedded NUL in the certificate subject. Discovered and reported + to the OpenVPN security team by Guido Vranken. +- CVE-2017-7521: Fix post-authentication remote-triggerable memory leaks A + client could cause a server to leak a few bytes each time it connects to the + server. That can eventually cause the server to run out of memory, and thereby + causing the server process to terminate. Discovered and reported to the + OpenVPN security team by Guido Vranken. (OpenSSL builds only.) +- CVE-2017-7521: Fix a potential post-authentication remote code execution + attack on servers that use the `--x509-username-field` option with an X.509 + extension field (option argument prefixed with `ext:`). A client that can + cause a server to run out-of-memory (see above) might be able to cause the + server to double free, which in turn might lead to remote code execution. + Discovered and reported to the OpenVPN security team by Guido Vranken. + (OpenSSL builds only.) +- CVE-2017-7520: Pre-authentication remote crash/information disclosure for + clients. If clients use a HTTP proxy with NTLM authentication (i.e. + `--http-proxy [|'auto'|'auto-nct'] ntlm2`), a + man-in-the-middle attacker between the client and the proxy can cause the + client to crash or disclose at most 96 bytes of stack memory. The disclosed + stack memory is likely to contain the proxy password. If the proxy password is + not reused, this is unlikely to compromise the security of the OpenVPN tunnel + itself. Clients who do not use the `--http-proxy` option with ntlm2 + authentication are not affected. +- CVE-2017-7508: Fix remotely-triggerable ASSERT() on malformed IPv6 packet. + This can be used to remotely shutdown an openvpn server or client, if IPv6 and + `--mssfix` are enabled and the IPv6 networks used inside the VPN are known. +- Fix null-pointer dereference when talking to a malicious http proxy that + returns a malformed `Proxy-Authenticate:` headers for digest auth. +- Fix overflow check for long `--tls-cipher` option +- Windows: Pass correct buffer size to `GetModuleFileNameW()` (OSTIF/Quarkslabs + audit, finding 5.6) + +## User-visible Changes + +- `--verify-hash` can now take an optional flag which changes the hashing + algorithm. It can be either SHA1 or SHA256. The default if not provided is + SHA1 to preserve backwards compatibility with existing configurations. +- Restrict the supported `--x509-username-field` extension fields to + subjectAltName and issuerAltName. Other extensions probably didn't work + anyway, and would cause OpenVPN to crash when a client connects. + +## Bugfixes + +- Fix fingerprint calculation in mbed TLS builds. This means that mbed TLS users + of OpenVPN 2.4.0, v2.4.1 and v2.4.2 that rely on the values of the + `tls_digest_*` env vars, or that use `--verify-hash` will have to change the + fingerprint values they check against. The security impact of the incorrect + calculation is very minimal; the last few bytes (max 4, typically 4) are not + verified by the fingerprint. We expect no real-world impact, + because users that used this feature before will notice that it has suddenly + stopped working, and users that didn't will notice that connection setup fails + if they specify correct fingerprints. + +- Fix edge case with NCP when the server sends an empty PUSH_REPLY message back, + and the client would not initialize it's data channel crypto layer properly + (trac #903) + +- Fix SIGSEGV on unaligned buffer access on OpenBSD/Sparc64 + +- Fix TCP_NODELAY on OpenBSD + +- Remove erroneous limitation on max number of args for `--plugin` + +- Fix NCP behaviour on TLS reconnect (Server would not send a proper "cipher + ..." message back to the client, leading to client and server using different + ciphers) (trac #887) + +# Version 2.4.2 + +## Bugfixes + +- Fix memory leak introduced in OpenVPN 2.4.1: if `--remote-cert-tls` is used, + we leaked some memory on each TLS (re)negotiation. + +## Security + +- Fix a pre-authentication denial-of-service attack on both clients and servers. + By sending a too-large control packet, OpenVPN 2.4.0 or v2.4.1 can be forced + to hit an ASSERT() and stop the process. If `--tls-auth` or `--tls-crypt` is + used, only attackers that have the `--tls-auth` or `--tls-crypt` key can mount + an attack. (OSTIF/Quarkslab audit finding 5.1, CVE-2017-7478) +- Fix an authenticated remote DoS vulnerability that could be triggered by + causing a packet id roll over. An attack is rather inefficient; a peer would + need to get us to send at least about 196 GB of data. (OSTIF/Quarkslab audit + finding 5.2, CVE-2017-7479) + +# Version 2.4.1 + +- `--remote-cert-ku` now only requires the certificate to have at least the bits + set of one of the values in the supplied list, instead of requiring an exact + match to one of the values in the list. +- `--remote-cert-tls` now only requires that a keyUsage is present in the + certificate, and leaves the verification of the value up to the crypto + library, which has more information (i.e. the key exchange method in use) to + verify that the keyUsage is correct. +- `--ns-cert-type` is deprecated. Use `--remote-cert-tls` instead. The + nsCertType x509 extension is very old, and barely used. `--remote-cert-tls` + uses the far more common keyUsage and extendedKeyUsage extension instead. Make + sure your certificates carry these to be able to use `--remote-cert-tls`. diff --git a/Changes.rst b/Changes.rst deleted file mode 100644 index fe81909..0000000 --- a/Changes.rst +++ /dev/null @@ -1,1480 +0,0 @@ -Overview of changes in 2.8 -========================== -User-visible Changes --------------------- -Parsing Distinguished Names in certificates - (OpenSSL backend:) OpenVPN now rejects certificates that have a null-byte - inside any of the field values of their subject. To avoid ambiguity in the - parsed subject, OpenVPN escapes the following characters by prefixing them with - a backslash: - * " " (space) at the start or end of a field, - * "#" at the start of a field, - * ",", "+", """, "\", "<", ">" and ";" anywhere. - - As a result, if you use the option ``--verify-x509-name ``, - you need to prefix these characters with a backslash in your configuration. - The subject passed to a ``--tls-verify`` script is escaped in the same way and - you may need to adjust your script. - - (Mbed TLS backend:) The behavior has not changed. Subjects with null-bytes were - already rejected (assuming OpenVPN was built with Mbed TLS 3.5 or later) and - the characters mentioned above were already escaped. However, the behavior of - Mbed TLS is slightly different from OpenSSL in that it also escapes "=". - - -Overview of changes in 2.7 -========================== -New features ------------- -Multi-socket support for servers - OpenVPN servers now can listen on multiple sockets at the same time. - Multiple ``--local`` statements in the configuration can be used to - configure this. This way the same server can e.g. listen for UDP - and TCP connections at the same time, or listen on multiple addresses - and/or ports. - -Client implementations for DNS options sent by server for Linux/BSD/macOS - Linux, BSD and macOS versions of OpenVPN now ship with a per-platform - default ``--dns-updown`` script that implements proper handling of - DNS configuration sent by the server. The scripts should work on - systems that use ``systemd`` or ``resolveconf`` to manage the DNS - setup, as well as raw ``/etc/resolv.conf`` files. However, the exact - features supported will depend on the configuration method. - On Linux and MacOS this should usually make split-DNS configurations - supported out-of-the-box now. - - Note that this new script will not be used by default if a ``--up`` - script is already in use to reduce problems with - backwards compatibility. - - See documentation for ``--dns-updown`` and ``--dns`` for more details. - -New client implementation for DNS options sent by server for Windows - The Windows client now uses NRPT (Name Resolution Policy Table) to - handle DNS configurations. This adds support for split-DNS and DNSSEC - and improves the compatbility with local DNS resolvers. Requires the - interactive service. - -On Windows the ``block-local`` flag is now enforced with WFP filters. - The ``block-local`` flag to ``--redirect-gateway`` and - ``--redirect-private`` is now also enforced via the Windows Firewall, - making sure packets can't be sent to the local network. - This provides stronger protection against TunnelCrack-style attacks. - -Windows network adapters are now generated on demand - This means that on systems that run multiple OpenVPN connections at - the same time the users don't need to manually create enough network - adapters anymore (in addition to the ones created by the installer). - -Windows automatic service now runs as an unpriviledged user - All tasks that need privileges are now delegated to the interactive - service. - **NOTE** this has the risk of breaking existing setups if the - Windows certificate store is used (cryptoapi), and the certificates - are not readable for ``NT SERVICE\OpenVPNService``. - -Support for new version of Linux DCO module - The OpenVPN DCO module has been merged into the Linux kernel as of - 6.16. This required some API changes and OpenVPN 2.7 only supports - the new API. The new module is called ``ovpn``. Out-of-tree builds - for older kernels are available from - https://github.com/OpenVPN/ovpn-backports. Please - see the release announcements for further information. - -Support for server mode in win-dco driver - On Windows the win-dco driver can now be used in server setups. - -Support for TLS client floating in DCO implementations - The kernel modules will detect clients floating to a new IP address - and notify userland so both data packets (kernel) and TLS packets - (sent by userland) can reach the new client IP. - (Actual support depends on recent-enough kernel implementation) - -Enforcement of AES-GCM usage limit - OpenVPN will now enforce the usage limits on AES-GCM with the same - confidentiality margin as TLS 1.3 does. This mean that renegotiation will - be triggered after roughly 2^28 to 2^31 packets depending of the packet - size. More details about usage limit of AES-GCM can be found here: - - https://datatracker.ietf.org/doc/draft-irtf-cfrg-aead-limits/ - -Epoch data keys and packet format - This introduces the epoch data format for AEAD data channel - ciphers in TLS mode ciphers. This new data format has a number of - improvements over the standard "DATA_V2" format. - - - AEAD tag at the end of packet which is more hardware implementation - friendly - - Automatic key switchover when cipher usage limits are hit, similar to - the epoch data keys in (D)TLS 1.3 - - 64 bit instead of 32 bit packet ids to allow the data channel to be - ready for 10 GBit/s without having frequent renegotiation - - IV constructed with XOR instead of concatenation to not have (parts) of - the real IV on the wire - -Support for Epoch data channel on Windows, using the win-dco driver (2.8.0+) - -Default ciphers in ``--data-ciphers`` - Ciphers in ``--data-ciphers`` can contain the string DEFAULT that is - replaced by the default ciphers used by OpenVPN, making it easier to - add an allowed cipher without having to spell out the default ciphers. - -TLS alerts - OpenVPN 2.7 will send out TLS alerts to peers informing them if the TLS - session shuts down or when the TLS implementation informs the peer about - an error in the TLS session (e.g. mismatching TLS versions). This improves - the user experience as the client shows an error instead of running into - a timeout when the server just stops responding completely. - -Support for tun/tap via unix domain socket and lwipovpn support - To allow better testing and emulating a full client with a full - network stack OpenVPN now allows a program executed to provide - a tun/tap device instead of opening a device. - - The co-developed lwipovpn program based on lwIP stack allows to - simulate full IP stack. An OpenVPN client using - ``--dev-node unix:/path/to/lwipovpn`` can emulate a full client that - can be pinged, can serve a website and more without requiring any - elevated permission. This can make testing OpenVPN much easier. - - For more details see - `lwipovpn on Github `_. - -Allow overriding username with ``--override-username`` - This is intended to allow using ``--auth-gen-token`` in scenarios where the - clients use certificates and multi-factor authentication. This will - also generate a ``push "auth-token-user newusername"`` directive in - push replies. - -``--port-share`` now properly supports IPv6 - Issues with logging of IPv6 addresses were fixed. The feature now allows - IPv6 connections towards the proxy receiver. - -Support for Haiku OS - -TLS1.3 support with mbedTLS (requires mbedTLS >= 3.6.4) - -PUSH_UPDATE client support - It is now possible to update parts of the client-side configuration - (IP address, routes, MTU, DNS) by sending a new server-to-client - control message, ``PUSH_UPDATE,``. - See also: https://openvpn.github.io/openvpn-rfc/openvpn-wire-protocol.html - NOTE: PUSH_UPDATE client support is currently disabled if DCO - is active (on all platforms). - -PUSH_UPDATE server support (minimal) - New management interface commands ``push-update-broad`` and - ``push-update-cid`` to send PUSH_UPDATE option updates to all - clients ("there is a new DNS server") or only a specific client ID - ("privileges have changed, here's a new IP address"). See - doc/management-notes.txt - NOTE: PUSH_UPDATE server support is currently disabled if DCO - is active (on all platforms). - -Support for user-defined routing tables on Linux - See the ``--route-table`` option in the manpage - -PQE support for WolfSSL - -Two new environment variables have been introduced to communicate desired - default gateway redirection to plugins like Network Manager, - ``route_redirect_gateway_ipv4`` and ``route_redirect_gateway_ipv6``. - See the "Environmental Variables" section in the man page - -Improved logging of service events/errors to event log on Windows. - -"Recursive Routing" check is now more granular, and will only drop - packets-in-tunnel if destination IP, protocol and port matches with - those needed to reach the VPN server. With that change, you can now - use policies that direct "everything that is not OpenVPN" into the - tunnel, and have IP packets to the VPN server address arrive as - expected (no such policies are currently installed by OpenVPN) - (GH: OpenVPN/openvpn#669). - -COPYING: license details only relevant to our Windows installers have - been updated and moved to the openvpn-build repo - -Improved BYTECOUNT support - more strictly adhere to timing interval - requested, correctly support client and server counters with Linux and - Windows DCO offloading. - -Improve compatibility with OpenSSL 3.6.0 (do not fail t_lpback selftest) - -New option ``--tls-crypt-v2-max-age n`` to check tls-crypt-v2 timestamps - (When a client is older than n days or has no timestamp, the server - will reject it) - -mbedTLS 4 support has been added. - Note that with mbedTLS 4 algorithms need to be translated to - mbedTLS 4 internal IDs by OpenVPN, and some names might be - missing. - - -Deprecated features -------------------- -``secret`` support has been removed (by default). - static key mode (non-TLS) is no longer considered "good and secure enough" - for today's requirements. Use TLS mode instead. If deploying a PKI CA - is considered "too complicated", using ``--peer-fingerprint`` makes - TLS mode about as easy as using ``--secret``. - - This mode can still be enabled by using - ``--allow-deprecated-insecure-static-crypto`` but will be removed in - OpenVPN 2.8. - -Support for wintun Windows driver has been removed. - OpenVPN 2.6 added support for the new dco-win driver, so it supported - three different device drivers: dco-win, wintun, and tap-windows6. - OpenVPN 2.7 now drops the support for wintun driver. By default - all modern configs should be supported by dco-win driver. In all - other cases OpenVPN will fall back automatically to tap-windows6 - driver. - -NTLMv1 authentication support for HTTP proxies has been removed. - This is considered an insecure method of authentication that uses - obsolete crypto algorithms. - NTLMv2 support is still available, but will be removed in a future - release. - When configured to authenticate with NTLMv1 (``ntlm`` keyword in - ``--http-proxy``) OpenVPN will try NTLMv2 instead. - -``persist-key`` option has been enabled by default. - All the keys will be kept in memory across restart. - -OpenSSL 1.0.2 support has been removed. - Support for building with OpenSSL 1.0.2 has been removed. The minimum - supported OpenSSL version is now 1.1.0. - -mbedTLS 2.x support has been removed - Support for building with mbedTLS 2.x has been removed (it is out - of support since March 2025, and the necessary compatibility code - is making maintenance and support for mbedTLS 4.x hard). - The minimum supported mbedTLS version is now 3.2.1. - -Compression on send has been removed. - OpenVPN 2.7 will never compress data before sending. Decompression of - received data is still supported. - ``--allow-compression yes`` is now an alias for - ``--allow-compression asym``. - -``--memstats`` feature removed - The ``--memstats`` option was largely undocumented and there is no known - user of this feature. This feature provided very limited statistics - (number of users, link bytes read/written) and we do not except any - usage because of this. - -Using ``--push`` in a mode that is not ``--mode server`` will now print a - clear warning that this is an unsupported operation and might cause - negotiation failures. - -``--reneg-bytes`` and ``--reneg-packets`` do not work in DCO mode, and will - now print an appropriate warning. - -On-connect resolving of ``--remote`` addresses in ``--tcp-server`` mode - was not working since 2.4, so the code was completely removed. - - -User-visible Changes --------------------- -- Default for ``--topology`` changed to ``subnet`` for ``--mode server``. - Previous releases always used ``net30`` as default. This only affects - configs with ``--mode server`` or ``--server`` (the latter implies the - former), and ``--dev tun``, and only if IPv4 is enabled. - Note that this changes the semantics of ``--ifconfig``, so if you have - manual settings for that in your config but not set ``--topology`` - your config might fail to parse with the new version. Just adding - ``--topology net30`` to the config should fix the problem. - By default ``--topology`` is pushed from server to client. - -- ``--x509-username-field`` will no longer automatically convert fieldnames to - uppercase. This was deprecated since OpenVPN 2.4, and has now been removed. - -- ``--dh none`` is now the default if ``--dh`` is not specified. Modern TLS - implementations will prefer ECDH and other more modern algorithms anyway. - And finite field Diffie Hellman is in the proces of being deprecated - (see draft-ietf-tls-deprecate-obsolete-kex) - -- ``--lport 0`` does not imply ``--bind`` anymore. - -- ``--redirect-gateway`` now works correctly if the VPN remote is not - reachable by the default gateway. - -- ``--show-gateway`` now supports querying the gateway for IPv4 addresses. - -- ``--static-challenge`` option now has a third parameter ``format`` that - can change how password and challenge response should be combined. - -- ``--key`` and ``--cert`` now accept URIs implemented in OpenSSL 3 as well as - optional OpenSSL 3 providers loaded using ``--providers`` option. - -- ``--cryptoapicert`` now supports issuer name as well as Windows CA template - name or OID as selector string. - -- TLS handshake debugging information contains much more details now when - using recent versions of OpenSSL. - -- The ``IV_PLAT_VER`` variable sent by Windows clients now contains the - full Windows build version to make it possible to determine the - Windows 10 or Windows 11 version used. - -- The ``--windows-driver`` option to select between various windows - drivers will no longer do anything - it's kept so existing configs - will not become invalid, but it is ignored with a warning. The default - is now ``ovpn-dco`` if all options used are compatible with DCO, with - a fallback to ``tap-windows6``. To force TAP (for example because a - server pushes DCO incompatible options), use the ``--disable-dco`` - option. - -- Apply more checks to incoming TLS handshake packets before creating - new state - namely, verify message ID / acked ID for "valid range for - an initial packet". This fixes a problem with clients that float - very early but send control channel packet from the pre-float IP - (Github: OpenVPN/openvpn#704). - -- Use of ``--dh dh2048.pem`` in all sample configs has been replaced - with ``--dh none``. The ``dh2048.pem`` file has been removed. - -- The startup delay in ``t_client.sh`` has been reduced from 3s to 1s, - making a noticeable difference for setups with many tests. - -- Changed from using ``uncrustify`` for code formatting and pre-commit checks - to ``clang-format``. This reformatted quite a bit of code, and requires - that regular committers change their pre-commit checks accordingly. - -- On Linux, on interfaces where applicable, OpenVPN explicitly configures - the broadcast address again. This was dropped for 2.6.0 "because - computers are smart and can do it themselves", but the kernel netlink - interface isn't, and will install "0.0.0.0". This does not normally - matter, but for broadcast-based applications that get the address to - use from "ifconfig", this change repairs functionality (this has - been backported to 2.6.15, but is not in earlier 2.6 versions). - -- ``max-routes-per-client 0`` used to be silently upgraded to ``1``. This - now produces an error. - -- ``ifconfig`` and ``ifconfig-ipv6`` values are now stored in pre-connect - options cache, and will be restored to pre-connect values on reconnects - if the server stops pushing the respective option. - -- ``tapctl.exe`` helper binary on Windows has been reworked to improve - help texts (making clear that it can not only do TAP-Adapters but - Win-DCO as well), add printing of the hwid to all adapter outputs, and - change the default adapter type created to ``ovpn-dco``. - -- The default for ``multihome`` egress interface handling has changed. - 2.7.0 will default to ipi_ifindex=0, that is, leave the decision to the - routing/policy setup of the operating system. The pre-2.7 behaviour - (force egress = ingress interface) can be achieved with the new - ``--multihome same-interface`` sub-option. - -- Windows ``openvpn.exe`` binary manifest now sets code page UTF8 - which - has no direct effect on OpenVPN itself, but this repairs OpenSSL file - loading for key/cert files with non-ASCII characters in their file names - (GH: OpenVPN/openvpn#920). - -- The ``test-crypto`` option no longer requires a ``--secret`` argument and - will automatically generate a random key. - -- The configure-time option ``--enable-x509-alt-username`` is no longer - conditional, and always-on (GH: OpenVPN/openvpn#917). - - -Deprecated features -------------------- -``--opt-verify`` feature removed - This option was already deprecated and it is now being converted to a - no-op. Using this option will only print a warning. - - -Overview of changes in 2.6 -========================== - -Project changes ---------------- - -We want to deprecate our old Trac bug tracking system. -Please report any issues with this release in GitHub -instead: https://github.com/OpenVPN/openvpn/issues - -New features ------------- -Support unlimited number of connection entries and remote entries - -New management commands to enumerate and list remote entries - Use ``remote-entry-count`` and ``remote-entry-get`` - commands from the management interface to get the number of - remote entries and the entries themselves. - -Keying Material Exporters (RFC 5705) based key generation - As part of the cipher negotiation OpenVPN will automatically prefer - the RFC5705 based key material generation to the current custom - OpenVPN PRF. This feature requires OpenSSL or mbed TLS 2.18+. - -Compatibility with OpenSSL in FIPS mode - OpenVPN will now work with OpenSSL in FIPS mode. Note, no effort - has been made to check or implement all the - requirements/recommendation of FIPS 140-2. This just allows OpenVPN - to be run on a system that be configured OpenSSL in FIPS mode. - -``mlock`` will now check if enough memlock-able memory has been reserved, - and if less than 100MB RAM are available, use setrlimit() to upgrade - the limit. See Trac #1390. Not available on OpenSolaris. - -Certificate pinning/verify peer fingerprint - The ``--peer-fingerprint`` option has been introduced to give users an - easy to use alternative to the ``tls-verify`` for matching the - fingerprint of the peer. The option takes use a number of allowed - SHA256 certificate fingerprints. - - See the man page section "Small OpenVPN setup with peer-fingerprint" - for a tutorial on how to use this feature. This is also available online - under https://github.com/openvpn/openvpn/blob/master/doc/man-sections/example-fingerprint.rst - -TLS mode with self-signed certificates - When ``--peer-fingerprint`` is used, the ``--ca`` and ``--capath`` option - become optional. This allows for small OpenVPN setups without setting up - a PKI with Easy-RSA or similar software. - -Deferred auth support for scripts - The ``--auth-user-pass-verify`` script supports now deferred authentication. - -Pending auth support for plugins and scripts - Both auth plugin and script can now signal pending authentication to - the client when using deferred authentication. The new ``client-crresponse`` - script option and ``OPENVPN_PLUGIN_CLIENT_CRRESPONSE`` plugin function can - be used to parse a client response to a ``CR_TEXT`` two factor challenge. - - See ``sample/sample-scripts/totpauth.py`` for an example. - -Compatibility mode (``--compat-mode``) - The modernisation of defaults can impact the compatibility of OpenVPN 2.6.0 - with older peers. The options ``--compat-mode`` allows UIs to provide users - with an easy way to still connect to older servers. - -OpenSSL 3.0 support - OpenSSL 3.0 has been added. Most of OpenSSL 3.0 changes are not user visible but - improve general compatibility with OpenSSL 3.0. ``--tls-cert-profile insecure`` - has been added to allow selecting the lowest OpenSSL security level (not - recommended, use only if you must). OpenSSL 3.0 no longer supports the Blowfish - (and other deprecated) algorithm by default and the new option ``--providers`` - allows loading the legacy provider to renable these algorithms. - -Optional ciphers in ``--data-ciphers`` - Ciphers in ``--data-ciphers`` can now be prefixed with a ``?`` to mark - those as optional and only use them if the SSL library supports them. - - -Improved ``--mssfix`` and ``--fragment`` calculation - The ``--mssfix`` and ``--fragment`` options now allow an optional :code:`mtu` - parameter to specify that different overhead for IPv4/IPv6 should taken into - account and the resulting size is specified as the total size of the VPN packets - including IP and UDP headers. - -Cookie based handshake for UDP server - Instead of allocating a connection for each client on the initial packet - OpenVPN server will now use an HMAC based cookie as its session id. This - way the server can verify it on completing the handshake without keeping - state. This eliminates the amplification and resource exhaustion attacks. - For tls-crypt-v2 clients, this requires OpenVPN 2.6 clients or later - because the client needs to resend its client key on completing the hand - shake. The tls-crypt-v2 option allows controlling if older clients are - accepted. - - By default the rate of initial packet responses is limited to 100 per 10s - interval to avoid OpenVPN servers being abused in reflection attacks - (see ``--connect-freq-initial``). - -Data channel offloading with ovpn-dco - 2.6.0+ implements support for data-channel offloading where the data packets - are directly processed and forwarded in kernel space thanks to the ovpn-dco - kernel module. The userspace openvpn program acts purely as a control plane - application. Note that DCO will use DATA_V2 packets in P2P mode, therefore, - this implies that peers must be running 2.6.0+ in order to have P2P-NCP - which brings DATA_V2 packet support. - -Session timeout - It is now possible to terminate a session (or all) after a specified amount - of seconds has passed session commencement. This behaviour can be configured - using ``--session-timeout``. This option can be configured on the server, on - the client or can also be pushed. - -Inline auth username and password - Username and password can now be specified inline in the configuration file - within the tags. If the password is - missing OpenVPN will prompt for input via stdin. This applies to inline'd - http-proxy-user-pass too. - -Tun MTU can be pushed - The client can now also dynamically configure its MTU and the server - will try to push the client MTU when the client supports it. The - directive ``--tun-mtu-max`` has been introduced to increase the maximum - pushable MTU size (defaults to 1600). - -Dynamic TLS Crypt - When both peers are OpenVPN 2.6.1+, OpenVPN will dynamically create - a tls-crypt key that is used for renegotiation. This ensure that only the - previously authenticated peer can do trigger renegotiation and complete - renegotiations. - -Improved control channel packet size control (``max-packet-size``) - The size of control channel is no longer tied to - ``--link-mtu``/``--tun-mtu`` and can be set using ``--max-packet-size``. - Sending large control channel frames is also optimised by allowing 6 - outstanding packets instead of just 4. ``max-packet-size`` will also set - ``mssfix`` to try to limit data-channel packets as well. - -Deprecated features -------------------- -``inetd`` has been removed - This was a very limited and not-well-tested way to run OpenVPN, on TCP - and TAP mode only. - -``verify-hash`` has been deprecated - This option has very limited usefulness and should be replaced by either - a better ``--ca`` configuration or with a ``--tls-verify`` script. - -``secret`` has been deprecated - static key mode (non-TLS) is no longer considered "good and secure enough" - for today's requirements. Use TLS mode instead. If deploying a PKI CA - is considered "too complicated", using ``--peer-fingerprint`` makes - TLS mode about as easy as using ``--secret``. - -``ncp-disable`` has been removed - This option mainly served a role as debug option when NCP was first - introduced. It should now no longer be necessary. - -TLS 1.0 and 1.1 are deprecated - ``tls-version-min`` is set to 1.2 by default. OpenVPN 2.6.0 defaults - to a minimum TLS version of 1.2 as TLS 1.0 and 1.1 should be generally - avoided. Note that OpenVPN versions older than 2.3.7 use TLS 1.0 only. - -``--cipher`` argument is no longer appended to ``--data-ciphers`` - by default. Data cipher negotiation has been introduced in 2.4.0 - and been significantly improved in 2.5.0. The implicit fallback - to the cipher specified in ``--cipher`` has been removed. - Effectively, ``--cipher`` is a no-op in TLS mode now, and will - only have an effect in pre-shared-key mode (``--secret``). - From now on ``--cipher`` should not be used in new configurations - for TLS mode. - Should backwards compatibility with older OpenVPN peers be - required, please see the ``--compat-mode`` instead. - -``--prng`` has beeen removed - OpenVPN used to implement its own PRNG based on a hash. However implementing - a PRNG is better left to a crypto library. So we use the PRNG - mbed TLS or OpenSSL now. - -``--keysize`` has been removed - The ``--keysize`` option was only useful to change the key length when using the - BF, CAST6 or RC2 ciphers. For all other ciphers the key size is fixed with the - chosen cipher. As OpenVPN v2.6 no longer supports any of these variable length - ciphers, this option was removed as well to avoid confusion. - -Compression no longer enabled by default - Unless an explicit compression option is specified in the configuration, - ``--allow-compression`` defaults to ``no`` in OpeNVPN 2.6.0. - By default, OpenVPN 2.5 still allowed a server to enable compression by - pushing compression related options. - -PF (Packet Filtering) support has been removed - The built-in PF functionality has been removed from the code base. This - feature wasn't really easy to use and was long unmaintained. - This implies that also ``--management-client-pf`` and any other compile - time or run time related option do not exist any longer. - -Option conflict checking is being deprecated and phased out - The static option checking (OCC) is no longer useful in typical setups - that negotiate most connection parameters. The ``--opt-verify`` and - ``--occ-disable`` options are deprecated, and the configure option - ``--enable-strict-options`` has been removed. Logging of mismatched - options has been moved to debug logging (verb 7). - -User-visible Changes --------------------- -- CHACHA20-POLY1305 is included in the default of ``--data-ciphers`` when available. -- Option ``--prng`` is ignored as we rely on the SSL library random number generator. -- Option ``--nobind`` is default when ``--client`` or ``--pull`` is used in the configuration -- :code:`link_mtu` parameter is removed from environment or replaced with 0 when scripts are - called with parameters. This parameter is unreliable and no longer internally calculated. - -- control channel packet maximum size is no longer influenced by - ``--link-mtu``/``--tun-mtu`` and must be set by ``--max-packet-size`` now. - The default is 1250 for the control channel size. - -- In point-to-point OpenVPN setups (no ``--server``), using - ``--explict-exit-notiy`` on one end would terminate the other side at - session end. This is considered a no longer useful default and has - been changed to "restart on reception of explicit-exit-notify message". - If the old behaviour is still desired, ``--remap-usr1 SIGTERM`` can be used. - -- FreeBSD tun interfaces with ``--topology subnet`` are now put into real - subnet mode (IFF_BROADCAST instead of IFF_POINTOPOINT) - this might upset - software that enumerates interfaces, looking for "broadcast capable?" and - expecting certain results. Normal uses should not see any difference. - -- The default configurations will no longer allow connections to OpenVPN 2.3.x - peer or earlier, use the new ``--compat-mode`` option if you need - compatibility with older versions. See the manual page on the - ``--compat-mode`` for details. - -- The ``client-pending-auth`` management command now requires also the - key id. The management version has been changed to 5 to indicate this change. - -- (OpenVPN 2.6.2) A client will now refuse a connection if pushed compression - settings will contradict the setting of allow-compression as this almost - always results in a non-working connection. - -- The "kill" by addr management command now requires also the protocol - as string e.g. "udp", "tcp". - -Common errors with OpenSSL 3.0 and OpenVPN 2.6 ----------------------------------------------- -Both OpenVPN 2.6 and OpenSSL 3.0 tighten the security considerable, so some -configuration will no longer work. This section will cover the most common -causes and error message we have seen and explain their reason and temporary -workarounds. You should fix the underlying problems as soon as possible since -these workaround are not secure and will eventually stop working in a future -update. - -- weak SHA1 or MD5 signature on certificates - - This will happen on either loading of certificates or on connection - to a server:: - - OpenSSL: error:0A00018E:SSL routines::ca md too weak - Cannot load certificate file cert.crt - Exiting due to fatal error - - OpenSSL 3.0 no longer allows weak signatures on certificates. You can - downgrade your security to allow them by using ``--tls-cert-profile insecure`` - but should replace/regenerate these certificates as soon as possible. - - -- 1024 bit RSA certificates, 1024 bit DH parameters, other weak keys - - This happens if you use private keys or other cryptographic material that - does not meet today's cryptographic standards anymore. Messages are similar - to:: - - OpenSSL: error:0A00018F:SSL routines::ee key too small - OpenSSL: error:1408518A:SSL routines:ssl3_ctx_ctrl:dh key too small - - DH parameters (``--dh``) can be regenerated with ``openssl dhparam 2048``. - For other cryptographic keys, these keys and certificates need to be - regenerated. TLS Security level can be temporarily lowered with - ``--tls-cert-profile legacy`` or even ``--tls-cert-profile insecure``. - -- Connecting to a OpenVPN 2.3.x server or allowing OpenVPN 2.3.x or earlier - clients - - This will normally result in messages like:: - - OPTIONS ERROR: failed to negotiate cipher with server. Add the server's cipher ('AES-128-CBC') to --data-ciphers (currently 'AES-256-GCM:AES-128-GCM:CHACHA20-POLY1305') if you want to connect to this server. - - or - - client/127.0.0.1:49954 SENT CONTROL [client]: 'AUTH_FAILED,Data channel cipher negotiation failed (no shared cipher)' (status=1) - - You can manually add the missing cipher to the ``--data-ciphers``. The - standard ciphers should be included as well, e.g. - ``--data-ciphers AES-256-GCM:AES-128-GCM:?Chacha20-Poly1305:?AES-128-CBC``. - You can also use the ``--compat-mode`` option. Note that these message may - also indicate other cipher configuration problems. See the data channel - cipher negotiation manual section for more details. (Available online under - https://github.com/OpenVPN/openvpn/blob/master/doc/man-sections/cipher-negotiation.rst) - -- Use of a legacy or deprecated cipher (e.g. 64bit block ciphers) - - OpenSSL 3.0 no longer supports a number of insecure and outdated ciphers in - its default configuration. Some of these ciphers are known to be vulnerable (SWEET32 attack). - - This will typically manifest itself in messages like:: - - OpenSSL: error:0308010C:digital envelope routines::unsupported - Cipher algorithm 'BF-CBC' not found - Unsupported cipher in --data-ciphers: BF-CBC - - If your OpenSSL distribution comes with the legacy provider (see - also ``man OSSL_PROVIDER-legacy``), you can load it with - ``--providers legacy default``. This will re-enable the old algorithms. - -- OpenVPN version not supporting TLS 1.2 or later - - The default in OpenVPN 2.6 and also in many distributions is now TLS 1.2 or - later. Connecting to a peer that does not support this will results in - messages like:: - - TLS error: Unsupported protocol. This typically indicates that client and - server have no common TLS version enabled. This can be caused by mismatched - tls-version-min and tls-version-max options on client and server. If your - OpenVPN client is between v2.3.6 and v2.3.2 try adding tls-version-min 1.0 - to the client configuration to use TLS 1.0+ instead of TLS 1.0 only - OpenSSL: error:0A000102:SSL routines::unsupported protocol - - This can be an OpenVPN 2.3.6 or earlier version. ``compat-version 2.3.0`` will - enable TLS 1.0 support if supported by the OpenSSL distribution. Note that - on some Linux distributions enabling TLS 1.1 or 1.0 is not possible. - - - -Overview of changes in 2.5 -========================== - -New features ------------- -Client-specific tls-crypt keys (``--tls-crypt-v2``) - ``tls-crypt-v2`` adds the ability to supply each client with a unique - tls-crypt key. This allows large organisations and VPN providers to profit - from the same DoS and TLS stack protection that small deployments can - already achieve using ``tls-auth`` or ``tls-crypt``. - -ChaCha20-Poly1305 cipher support - Added support for using the ChaCha20-Poly1305 cipher in the OpenVPN data - channel. - -Improved Data channel cipher negotiation - The option ``ncp-ciphers`` has been renamed to ``data-ciphers``. - The old name is still accepted. The change in name signals that - ``data-ciphers`` is the preferred way to configure data channel - ciphers and the data prefix is chosen to avoid the ambiguity that - exists with ``--cipher`` for the data cipher and ``tls-cipher`` - for the TLS ciphers. - - OpenVPN clients will now signal all supported ciphers from the - ``data-ciphers`` option to the server via ``IV_CIPHERS``. OpenVPN - servers will select the first common cipher from the ``data-ciphers`` - list instead of blindly pushing the first cipher of the list. This - allows to use a configuration like - ``data-ciphers ChaCha20-Poly1305:AES-256-GCM`` on the server that - prefers ChaCha20-Poly1305 but uses it only if the client supports it. - - See the data channel negotiation section in the manual for more details. - -Removal of BF-CBC support in default configuration: - By default OpenVPN 2.5 will only accept AES-256-GCM and AES-128-GCM as - data ciphers. OpenVPN 2.4 allows AES-256-GCM,AES-128-GCM and BF-CBC when - no --cipher and --ncp-ciphers options are present. Accepting BF-CBC can be - enabled by adding - - data-ciphers AES-256-GCM:AES-128-GCM:BF-CBC - - and when you need to support very old peers also - - data-ciphers-fallback BF-CBC - - To offer backwards compatibility with older configs an *explicit* - - cipher BF-CBC - - in the configuration will be automatically translated into adding BF-CBC - to the data-ciphers option and setting data-ciphers-fallback to BF-CBC - (as in the example commands above). We strongly recommend to switching - away from BF-CBC to a more secure cipher. - -Asynchronous (deferred) authentication support for auth-pam plugin. - See src/plugins/auth-pam/README.auth-pam for details. - -Deferred client-connect - The ``--client-connect`` option and the connect plugin API allow - asynchronous/deferred return of the configuration file in the same way - as the auth-plugin. - -Faster connection setup - A client will signal in the ``IV_PROTO`` variable that it is in pull - mode. This allows the server to push the configuration options to - the client without waiting for a ``PULL_REQUEST`` message. The feature - is automatically enabled if both client and server support it and - significantly reduces the connection setup time by avoiding one - extra packet round-trip and 1s of internal event delays. - -Netlink support - On Linux, if configured without ``--enable-iproute2``, configuring IP - addresses and adding/removing routes is now done via the netlink(3) - kernel interface. This is much faster than calling ``ifconfig`` or - ``route`` and also enables OpenVPN to run with less privileges. - - If configured with --enable-iproute2, the ``ip`` command is used - (as in 2.4). Support for ``ifconfig`` and ``route`` is gone. - -Wintun support - On Windows, OpenVPN can now use ``wintun`` devices. They are faster - than the traditional ``tap9`` tun/tap devices, but do not provide - ``--dev tap`` mode - so the official installers contain both. To use - a wintun device, add ``--windows-driver wintun`` to your config - (and use of the interactive service is required as wintun needs - SYSTEM privileges to enable access). - -IPv6-only operation - It is now possible to have only IPv6 addresses inside the VPN tunnel, - and IPv6-only address pools (2.4 always required IPv4 config/pools - and IPv6 was the "optional extra"). - -Improved Windows 10 detection - Correctly log OS on Windows 10 now. - -Linux VRF support - Using the new ``--bind-dev`` option, the OpenVPN outside socket can - now be put into a Linux VRF. See the "Virtual Routing and Forwarding" - documentation in the man page. - -TLS 1.3 support - TLS 1.3 support has been added to OpenVPN. Currently, this requires - OpenSSL 1.1.1+. - The options ``--tls-ciphersuites`` and ``--tls-groups`` have been - added to fine tune TLS protocol options. Most of the improvements - were also backported to OpenVPN 2.4 as part of the maintainance - releases. - -Support setting DHCP search domain - A new option ``--dhcp-option DOMAIN-SEARCH my.example.com`` has been - defined, and Windows support for it is implemented (tun/tap only, no - wintun support yet). Other platforms need to support this via ``--up`` - script (Linux) or GUI (OSX/Tunnelblick). - -per-client changing of ``--data-ciphers`` or ``data-ciphers-fallback`` - from client-connect script/dir (NOTE: this only changes preference of - ciphers for NCP, but can not override what the client announces as - "willing to accept") - -Handle setting of tun/tap interface MTU on Windows - If IPv6 is in use, MTU must be >= 1280 (Windows enforces IETF requirements) - -Add support for OpenSSL engines to access private key material (like TPM). - -HMAC based auth-token support - The ``--auth-gen-token`` support has been improved and now generates HMAC - based user token. If the optional ``--auth-gen-token-secret`` option is - used clients will be able to seamlessly reconnect to a different server - using the same secret file or to the same server after a server restart. - -Improved support for pending authentication - The protocol has been enhanced to be able to signal that - the authentication should use a secondary authentication - via web (like SAML) or a two factor authentication without - disconnecting the OpenVPN session with AUTH_FAILED. The - session will instead be stay in a authenticated state and - wait for the second factor authentication to complete. - - This feature currently requires usage of the managent interface - on both client and server side. See the ``management-notes.txt`` - ``client-pending-auth`` and ``cr-response`` commands for more - details. - -VLAN support - OpenVPN servers in TAP mode can now use 802.1q tagged VLANs - on the TAP interface to separate clients into different groups - that can then be handled differently (different subnets / DHCP, - firewall zones, ...) further down the network. See the new - options ``--vlan-tagging``, ``--vlan-accept``, ``--vlan-pvid``. - - 802.1q tagging on the client side TAP interface is not handled - today (= tags are just forwarded transparently to the server). - -Support building of .msi installers for Windows - -Allow unicode search string in ``--cryptoapicert`` option (Windows) - -Support IPv4 configs with /31 netmasks now - (By no longer trying to configure ``broadcast x.x.x.x`` in - ifconfig calls, /31 support "just works") - -New option ``--block-ipv6`` to reject all IPv6 packets (ICMPv6) - this is useful if the VPN service has no IPv6, but the clients - might have (LAN), to avoid client connections to IPv6-enabled - servers leaking "around" the IPv4-only VPN. - -``--ifconfig-ipv6`` and ``--ifconfig-ipv6-push`` will now accept - hostnames and do a DNS lookup to get the IPv6 address to use - - -Deprecated features -------------------- -For an up-to-date list of all deprecated options, see this wiki page: -https://community.openvpn.net/openvpn/wiki/DeprecatedOptions - -- ``ncp-disable`` has been deprecated - With the improved and matured data channel cipher negotiation, the use - of ``ncp-disable`` should not be necessary anymore. - -- ``inetd`` has been deprecated - This is a very limited and not-well-tested way to run OpenVPN, on TCP - and TAP mode only, which complicates the code quite a bit for little gain. - To be removed in OpenVPN 2.6 (unless users protest). - -- ``no-iv`` has been removed - This option was made into a NOOP option with OpenVPN 2.4. This has now - been completely removed. - -- ``--client-cert-not-required`` has been removed - This option will now cause server configurations to not start. Use - ``--verify-client-cert none`` instead. - -- ``--ifconfig-pool-linear`` has been removed - This option is removed. Use ``--topology p2p`` or ``--topology subnet`` - instead. - -- ``--compress xxx`` is considered risky and is warned against, see below. - -- ``--key-method 1`` has been removed - - -User-visible Changes --------------------- -- If multiple connect handlers are used (client-connect, ccd, connect - plugin) and one of the handler succeeds but a subsequent fails, the - client-disconnect-script is now called immediately. Previously it - was called, when the VPN session was terminated. - -- Support for building with OpenSSL 1.0.1 has been removed. The minimum - supported OpenSSL version is now 1.0.2. - -- The GET_CONFIG management state is omitted if the server pushes - the client configuration almost immediately as result of the - faster connection setup feature. - -- ``--compress`` is nowadays considered risky, because attacks exist - leveraging compression-inside-crypto to reveal plaintext (VORACLE). So - by default, ``--compress xxx`` will now accept incoming compressed - packets (for compatibility with peers that have not been upgraded yet), - but will not use compression outgoing packets. This can be controlled with - the new option ``--allow-compression yes|no|asym``. - -- Stop changing ``--txlen`` aways from OS defaults unless explicitly specified - in config file. OS defaults nowadays are actually larger then what we used - to configure, so our defaults sometimes caused packet drops = bad performance. - -- remove ``--writepid`` pid file on exit now - -- plugin-auth-pam now logs via OpenVPN logging method, no longer to stderr - (this means you'll have log messages in syslog or openvpn log file now) - -- use ISO 8601 time format for file based logging now (YYYY-MM-DD hh:mm:dd) - (syslog is not affected, nor is ``--machine-readable-output``) - -- ``--clr-verify`` now loads all CRLs if more than one CRL is in the same - file (OpenSSL backend only, mbedTLS always did that) - -- when ``--auth-user-pass file`` has no password, and the management interface - is active, query management interface (instead of trying console query, - which does not work on windows) - -- skip expired certificates in Windows certificate store (``--cryptoapicert``) - -- ``--socks-proxy`` + ``--proto udp*`` will now allways use IPv4, even if - IPv6 is requested and available. Our SOCKS code does not handle IPv6+UDP, - and before that change it would just fail in non-obvious ways. - -- TCP listen() backlog queue is now set to 32 - this helps TCP servers that - receive lots of "invalid" connects by TCP port scanners - -- do no longer print OCC warnings ("option mismatch") about ``key-method``, - ``keydir``, ``tls-auth`` and ``cipher`` - these are either gone now, or - negotiated, and the warnings do not serve a useful purpose. - -- ``dhcp-option DNS`` and ``dhcp-option DNS6`` are now treated identically - (= both accept an IPv4 or IPv6 address for the nameserver) - - -Maintainer-visible changes --------------------------- -- the man page is now in maintained in .rst format, so building the openvpn.8 - manpage from a git checkout now requires python-docutils (if this is missing, - the manpage will not be built - which is not considered an error generally, - but for package builders or ``make distcheck`` it is). Release tarballs - contain the openvpn.8 file, so unless some .rst is changed, doc-utils are - not needed for building. - -- OCC support can no longer be disabled - -- AEAD support is now required in the crypto library - -- ``--disable-server`` has been removed from configure (so it is no longer - possible to build a client-/p2p-only OpenVPN binary) - the saving in code - size no longer outweighs the extra maintenance effort. - -- ``--enable-iproute2`` will disable netlink(3) support, so maybe remove - that from package building configs (see above) - -- support building with MSVC 2019 - -- cmocka based unit tests are now only run if cmocka is installed externally - (2.4 used to ship a local git submodule which was painful to maintain) - -- ``--disable-crypto`` configure option has been removed. OpenVPN is now always - built with crypto support, which makes the code much easier to maintain. - This does not affect ``--cipher none`` to do a tunnel without encryption. - -- ``--disable-multi`` configure option has been removed - - - -Overview of changes in 2.4 -========================== - - -New features ------------- -Seamless client IP/port floating - Added new packet format P_DATA_V2, which includes peer-id. If both the - server and client support it, the client sends all data packets in - the new format. When a data packet arrives, the server identifies peer - by peer-id. If peer's ip/port has changed, server assumes that - client has floated, verifies HMAC and updates ip/port in internal structs. - This allows the connection to be immediately restored, instead of requiring - a TLS handshake before the server accepts packets from the new client - ip/port. - -Data channel cipher negotiation - Data channel ciphers (``--cipher``) are now by default negotiated. If a - client advertises support for Negotiable Crypto Parameters (NCP), the - server will choose a cipher (by default AES-256-GCM) for the data channel, - and tell the client to use that cipher. Data channel cipher negotiation - can be controlled using ``--ncp-ciphers`` and ``--ncp-disable``. - - A more limited version also works in client-to-server and server-to-client - scenarios where one of the end points uses a v2.4 client or server and the - other side uses an older version. In such scenarios the v2.4 side will - change to the ``--cipher`` set by the remote side, if permitted by by - ``--ncp-ciphers``. For example, a v2.4 client with ``--cipher BF-CBC`` - and ``ncp-ciphers AES-256-GCM:AES-256-CBC`` can connect to both a v2.3 - server with ``cipher BF-CBC`` as well as a server with - ``cipher AES-256-CBC`` in its config. The other way around, a v2.3 client - with either ``cipher BF-CBC`` or ``cipher AES-256-CBC`` can connect to a - v2.4 server with e.g. ``cipher BF-CBC`` and - ``ncp-ciphers AES-256-GCM:AES-256-CBC`` in its config. For this to work - it requires that OpenVPN was built without disabling OCC support. - -AEAD (GCM) data channel cipher support - The data channel now supports AEAD ciphers (currently only GCM). The AEAD - packet format has a smaller crypto overhead than the CBC packet format, - (e.g. 20 bytes per packet for AES-128-GCM instead of 36 bytes per packet - for AES-128-CBC + HMAC-SHA1). - -ECDH key exchange - The TLS control channel now supports for elliptic curve diffie-hellmann - key exchange (ECDH). - -Improved Certificate Revocation List (CRL) processing - CRLs are now handled by the crypto library (OpenSSL or mbed TLS), instead - of inside OpenVPN itself. The crypto library implementations are more - strict than the OpenVPN implementation was. This might reject peer - certificates that would previously be accepted. If this occurs, OpenVPN - will log the crypto library's error description. - -Dualstack round-robin DNS client connect - Instead of only using the first address of each ``--remote`` OpenVPN - will now try all addresses (IPv6 and IPv4) of a ``--remote`` entry. - -Support for providing IPv6 DNS servers - A new DHCP sub-option ``DNS6`` is added alongside with the already existing - ``DNS`` sub-option. This is used to provide DNS resolvers available over - IPv6. This may be pushed to clients where `` --up`` scripts and ``--plugin`` - can act upon it through the ``foreign_option_`` environment variables. - - Support for the Windows client picking up this new sub-option is added, - however IPv6 DNS resolvers need to be configured via ``netsh`` which requires - administrator privileges unless the new interactive services on Windows is - being used. If the interactive service is used, this service will execute - ``netsh`` in the background with the proper privileges. - -New improved Windows Background service - The new OpenVPNService is based on openvpnserv2, a complete rewrite of the OpenVPN - service wrapper. It is intended for launching OpenVPN instances that should be - up at all times, instead of being manually launched by a user. OpenVPNService is - able to restart individual OpenVPN processes if they crash, and it also works - properly on recent Windows versions. OpenVPNServiceLegacy tends to work poorly, - if at all, on newer Windows versions (8+) and its use is not recommended. - -New interactive Windows service - The installer starts OpenVPNServiceInteractive automatically and configures - it to start at system startup. - - The interactive Windows service allows unprivileged users to start - OpenVPN connections in the global config directory (usually - C:\\Program Files\\OpenVPN\\config) using OpenVPN GUI without any - extra configuration. - - Users who belong to the built-in Administrator group or to the - local "OpenVPN Administrator" group can also store configuration - files under %USERPROFILE%\\OpenVPN\\config for use with the - interactive service. - -redirect-gateway ipv6 - OpenVPN has now feature parity between IPv4 and IPv6 for redirect - gateway including the handling of overlapping IPv6 routes with - IPv6 remote VPN server address. - -LZ4 Compression and pushable compression - Additionally to LZO compression OpenVPN now also supports LZ4 compression. - Compression options are now pushable from the server. - -Filter pulled options client-side: pull-filter - New option to explicitly allow or reject options pushed by the server. - May be used multiple times and is applied in the order specified. - -Per-client remove push options: push-remove - New option to remove options on a per-client basis from the "push" list - (more fine-grained than ``--push-reset``). - -Http proxy password inside config file - Http proxy passwords can be specified with the inline file option - ```` .. ```` - -Windows version detection - Windows version is detected, logged and possibly signalled to server - (IV_PLAT_VER= if ``--push-peer-info`` is set on client). - -Authentication tokens - In situations where it is not suitable to save user passwords on the client, - OpenVPN has support for pushing a --auth-token since v2.3. This option is - pushed from the server to the client with a token value to be used instead - of the users password. For this to work, the authentication plug-in would - need to implement this support as well. In OpenVPN 2.4 --auth-gen-token - is introduced, which will allow the OpenVPN server to generate a random - token and push it to the client without any changes to the authentication - modules. When the clients need to re-authenticate the OpenVPN server will - do the authentication internally, instead of sending the re-authentication - request to the authentication module . This feature is especially - useful in configurations which use One Time Password (OTP) authentication - schemes, as this allows the tunnel keys to be renegotiated regularly without - any need to supply new OTP codes. - -keying-material-exporter - Keying Material Exporter [RFC-5705] allow additional keying material to be - derived from existing TLS channel. - -Android platform support - Support for running on Android using Android's VPNService API has been added. - See doc/android.txt for more details. This support is primarily used in - the OpenVPN for Android app (https://github.com/schwabe/ics-openvpn) - -AIX platform support - AIX platform support has been added. The support only includes tap - devices since AIX does not provide tun interface. - -Control channel encryption (``--tls-crypt``) - Use a pre-shared static key (like the ``--tls-auth`` key) to encrypt control - channel packets. Provides more privacy, some obfuscation and poor-man's - post-quantum security. - -Asynchronous push reply - Plug-ins providing support for deferred authentication can benefit from a more - responsive authentication where the server sends PUSH_REPLY immediately once - the authentication result is ready, instead of waiting for the client to - to send PUSH_REQUEST once more. This requires OpenVPN to be built with - ``./configure --enable-async-push``. This is a compile-time only switch. - - -Deprecated features -------------------- -For an up-to-date list of all deprecated options, see this wiki page: -https://community.openvpn.net/openvpn/wiki/DeprecatedOptions - -- ``--key-method 1`` is deprecated in OpenVPN 2.4 and will be removed in v2.5. - Migrate away from ``--key-method 1`` as soon as possible. The recommended - approach is to remove the ``--key-method`` option from the configuration - files, OpenVPN will then use ``--key-method 2`` by default. Note that this - requires changing the option in both the client and server side configs. - -- ``--tls-remote`` is removed in OpenVPN 2.4, as indicated in the v2.3 - man-pages. Similar functionality is provided via ``--verify-x509-name``, - which does the same job in a better way. - -- ``--compat-names`` and ``--no-name-remapping`` were deprecated in OpenVPN 2.3 - and will be removed in v2.5. All scripts and plug-ins depending on the old - non-standard X.509 subject formatting must be updated to the standardized - formatting. See the man page for more information. - -- ``--no-iv`` is deprecated in OpenVPN 2.4 and will be removed in v2.5. - -- ``--keysize`` is deprecated in OpenVPN 2.4 and will be removed in v2.6 - together with the support of ciphers with cipher block size less than - 128-bits. - -- ``--comp-lzo`` is deprecated in OpenVPN 2.4. Use ``--compress`` instead. - -- ``--ifconfig-pool-linear`` has been deprecated since OpenVPN 2.1 and will be - removed in v2.5. Use ``--topology p2p`` instead. - -- ``--client-cert-not-required`` is deprecated in OpenVPN 2.4 and will be removed - in v2.5. Use ``--verify-client-cert none`` for a functional equivalent. - -- ``--ns-cert-type`` is deprecated in OpenVPN 2.3.18 and v2.4. It will be removed - in v2.5. Use the far better ``--remote-cert-tls`` option which replaces this - feature. - - -User-visible Changes --------------------- -- When using ciphers with cipher blocks less than 128-bits, - OpenVPN will complain loudly if the configuration uses ciphers considered - weak, such as the SWEET32 attack vector. In such scenarios, OpenVPN will by - default renegotiate for each 64MB of transported data (``--reneg-bytes``). - This renegotiation can be disabled, but is HIGHLY DISCOURAGED. - -- For certificate DNs with duplicate fields, e.g. "OU=one,OU=two", both fields - are now exported to the environment, where each second and later occurrence - of a field get _$N appended to it's field name, starting at N=1. For the - example above, that would result in e.g. X509_0_OU=one, X509_0_OU_1=two. - Note that this breaks setups that rely on the fact that OpenVPN would - previously (incorrectly) only export the last occurrence of a field. - -- ``proto udp`` and ``proto tcp`` now use both IPv4 and IPv6. The new - options ``proto udp4`` and ``proto tcp4`` use IPv4 only. - -- ``--sndbuf`` and ``--recvbuf`` default now to OS defaults instead of 64k - -- OpenVPN exits with an error if an option has extra parameters; - previously they were silently ignored - -- ``--tls-auth`` always requires OpenVPN static key files and will no - longer work with free form files - -- ``--proto udp6/tcp6`` in server mode will now try to always listen to - both IPv4 and IPv6 on platforms that allow it. Use ``--bind ipv6only`` - to explicitly listen only on IPv6. - -- Removed ``--enable-password-save`` from configure. This option is now - always enabled. - -- Stricter default TLS cipher list (override with ``--tls-cipher``), that now - also disables: - - * Non-ephemeral key exchange using static (EC)DH keys - * DSS private keys - -- mbed TLS builds: changed the tls_digest_N values exported to the script - environment to be equal to the ones exported by OpenSSL builds, namely - the certificate fingerprint (was the hash of the 'to be signed' data). - -- mbed TLS builds: minimum RSA key size is now 2048 bits. Shorter keys will - not be accepted, both local and from the peer. - -- ``--connect-timeout`` now specifies the timeout until the first TLS packet - is received (identical to ``--server-poll-timeout``) and this timeout now - includes the removed socks proxy timeout and http proxy timeout. - - In ``--static`` mode ``connect-timeout`` specifies the timeout for TCP and - proxy connection establishment - -- ``--connect-retry-max`` now specifies the maximum number of unsuccessful - attempts of each remote/connection entry before exiting. - -- ``--http-proxy-timeout`` and the static non-changeable socks timeout (5s) - have been folded into a "unified" ``--connect-timeout`` which covers all - steps needed to connect to the server, up to the start of the TLS exchange. - The default value has been raised to 120s, to handle slow http/socks - proxies graciously. The old "fail TCP fast" behaviour can be achieved by - adding "``--connect-timeout 10``" to the client config. - -- ``--http-proxy-retry`` and ``--sock-proxy-retry`` have been removed. Proxy connections - will now behave like regular connection entries and generate a USR1 on failure. - -- ``--connect-retry`` gets an optional second argument that specifies the maximum - time in seconds to wait between reconnection attempts when an exponential - backoff is triggered due to repeated retries. Default = 300 seconds. - -- Data channel cipher negotiation (see New features section) can override - ciphers configured in the config file. Use ``--ncp-disable`` if you do not want - this behavior. - -- All tun devices on all platforms are always considered to be IPv6 - capable. The ``--tun-ipv6`` option is ignored (behaves like it is always - on). - -- On the client side recursively routed packets, which have the same destination - as the VPN server, are dropped. This can be disabled with - --allow-recursive-routing option. - -- On Windows, when the ``--register-dns`` option is set, OpenVPN no longer - restarts the ``dnscache`` service - this had unwanted side effects, and - seems to be no longer necessary with currently supported Windows versions. - -- If no flags are given, and the interactive Windows service is used, "def1" - is implicitly set (because "delete and later reinstall the existing - default route" does not work well here). If not using the service, - the old behaviour is kept. - -- OpenVPN now reloads a CRL only if the modication time or file size has - changed, instead of for each new connection. This reduces the connection - setup time, in particular when using large CRLs. - -- OpenVPN now ships with more up-to-date systemd unit files which take advantage - of the improved service management as well as some hardening steps. The - configuration files are picked up from the /etc/openvpn/server/ and - /etc/openvpn/client/ directories (depending on unit file). This also avoids - these new unit files and how they work to collide with older pre-existing - unit files. - -- Using ``--no-iv`` (which is generally not a recommended setup) will - require explicitly disabling NCP with ``--disable-ncp``. This is - intentional because NCP will by default use AES-GCM, which requires - an IV - so we want users of that option to consciously reconsider. - - -Maintainer-visible changes --------------------------- -- OpenVPN no longer supports building with crypto support, but without TLS - support. As a consequence, OPENSSL_CRYPTO_{CFLAGS,LIBS} and - OPENSSL_SSL_{CFLAGS,LIBS} have been merged into OPENSSL_{CFLAGS,LIBS}. This - is particularly relevant for maintainers who build their own OpenSSL library, - e.g. when cross-compiling. - -- Linux distributions using systemd is highly encouraged to ship these new unit - files instead of older ones, to provide a unified behaviour across systemd - based Linux distributions. - -- With OpenVPN 2.4, the project has moved over to depend on and actively use - the official C99 standard (-std=c99). This may fail on some older compiler/libc - header combinations. In most of these situations it is recommended to - use -std=gnu99 in CFLAGS. This is known to be needed when doing - i386/i686 builds on RHEL5. - - -Version 2.4.5 -============= - -New features ------------- -- The new option ``--tls-cert-profile`` can be used to restrict the set of - allowed crypto algorithms in TLS certificates in mbed TLS builds. The - default profile is 'legacy' for now, which allows SHA1+, RSA-1024+ and any - elliptic curve certificates. The default will be changed to the 'preferred' - profile in the future, which requires SHA2+, RSA-2048+ and any curve. - - -Version 2.4.3 -============= - -New features ------------- -- Support building with OpenSSL 1.1 now (in addition to older versions) - -- On Win10, set low interface metric for TAP adapter when block-outside-dns - is in use, to make Windows prefer the TAP adapter for DNS queries - (avoiding large delays) - - -Security --------- -- CVE-2017-7522: Fix ``--x509-track`` post-authentication remote DoS - A client could crash a v2.4+ mbedtls server, if that server uses the - ``--x509-track`` option and the client has a correct, signed and unrevoked - certificate that contains an embedded NUL in the certificate subject. - Discovered and reported to the OpenVPN security team by Guido Vranken. - -- CVE-2017-7521: Fix post-authentication remote-triggerable memory leaks - A client could cause a server to leak a few bytes each time it connects to the - server. That can eventually cause the server to run out of memory, and thereby - causing the server process to terminate. Discovered and reported to the - OpenVPN security team by Guido Vranken. (OpenSSL builds only.) - -- CVE-2017-7521: Fix a potential post-authentication remote code execution - attack on servers that use the ``--x509-username-field`` option with an X.509 - extension field (option argument prefixed with ``ext:``). A client that can - cause a server to run out-of-memory (see above) might be able to cause the - server to double free, which in turn might lead to remote code execution. - Discovered and reported to the OpenVPN security team by Guido Vranken. - (OpenSSL builds only.) - -- CVE-2017-7520: Pre-authentication remote crash/information disclosure for - clients. If clients use a HTTP proxy with NTLM authentication (i.e. - ``--http-proxy [|'auto'|'auto-nct'] ntlm2``), - a man-in-the-middle attacker between the client and the proxy can cause - the client to crash or disclose at most 96 bytes of stack memory. The - disclosed stack memory is likely to contain the proxy password. If the - proxy password is not reused, this is unlikely to compromise the security - of the OpenVPN tunnel itself. Clients who do not use the ``--http-proxy`` - option with ntlm2 authentication are not affected. - -- CVE-2017-7508: Fix remotely-triggerable ASSERT() on malformed IPv6 packet. - This can be used to remotely shutdown an openvpn server or client, if - IPv6 and ``--mssfix`` are enabled and the IPv6 networks used inside the VPN - are known. - -- Fix null-pointer dereference when talking to a malicious http proxy - that returns a malformed ``Proxy-Authenticate:`` headers for digest auth. - -- Fix overflow check for long ``--tls-cipher`` option - -- Windows: Pass correct buffer size to ``GetModuleFileNameW()`` - (OSTIF/Quarkslabs audit, finding 5.6) - - -User-visible Changes --------------------- -- ``--verify-hash`` can now take an optional flag which changes the hashing - algorithm. It can be either SHA1 or SHA256. The default if not provided is - SHA1 to preserve backwards compatibility with existing configurations. - -- Restrict the supported ``--x509-username-field`` extension fields to subjectAltName - and issuerAltName. Other extensions probably didn't work anyway, and would - cause OpenVPN to crash when a client connects. - - -Bugfixes --------- -- Fix fingerprint calculation in mbed TLS builds. This means that mbed TLS users - of OpenVPN 2.4.0, v2.4.1 and v2.4.2 that rely on the values of the - ``tls_digest_*`` env vars, or that use ``--verify-hash`` will have to change - the fingerprint values they check against. The security impact of the - incorrect calculation is very minimal; the last few bytes (max 4, typically - 4) are not verified by the fingerprint. We expect no real-world impact, - because users that used this feature before will notice that it has suddenly - stopped working, and users that didn't will notice that connection setup - fails if they specify correct fingerprints. - -- Fix edge case with NCP when the server sends an empty PUSH_REPLY message - back, and the client would not initialize it's data channel crypto layer - properly (trac #903) - -- Fix SIGSEGV on unaligned buffer access on OpenBSD/Sparc64 - -- Fix TCP_NODELAY on OpenBSD - -- Remove erroneous limitation on max number of args for ``--plugin`` - -- Fix NCP behaviour on TLS reconnect (Server would not send a proper - "cipher ..." message back to the client, leading to client and server - using different ciphers) (trac #887) - - -Version 2.4.2 -============= - -Bugfixes --------- -- Fix memory leak introduced in OpenVPN 2.4.1: if ``--remote-cert-tls`` is - used, we leaked some memory on each TLS (re)negotiation. - - -Security --------- -- Fix a pre-authentication denial-of-service attack on both clients and - servers. By sending a too-large control packet, OpenVPN 2.4.0 or v2.4.1 can - be forced to hit an ASSERT() and stop the process. If ``--tls-auth`` or - ``--tls-crypt`` is used, only attackers that have the ``--tls-auth`` or - ``--tls-crypt`` key can mount an attack. - (OSTIF/Quarkslab audit finding 5.1, CVE-2017-7478) - -- Fix an authenticated remote DoS vulnerability that could be triggered by - causing a packet id roll over. An attack is rather inefficient; a peer - would need to get us to send at least about 196 GB of data. - (OSTIF/Quarkslab audit finding 5.2, CVE-2017-7479) - - -Version 2.4.1 -============= -- ``--remote-cert-ku`` now only requires the certificate to have at least the - bits set of one of the values in the supplied list, instead of requiring an - exact match to one of the values in the list. -- ``--remote-cert-tls`` now only requires that a keyUsage is present in the - certificate, and leaves the verification of the value up to the crypto - library, which has more information (i.e. the key exchange method in use) - to verify that the keyUsage is correct. -- ``--ns-cert-type`` is deprecated. Use ``--remote-cert-tls`` instead. - The nsCertType x509 extension is very old, and barely used. - ``--remote-cert-tls`` uses the far more common keyUsage and extendedKeyUsage - extension instead. Make sure your certificates carry these to be able to - use ``--remote-cert-tls``. - diff --git a/Makefile.am b/Makefile.am index feeaabb..66252e6 100644 --- a/Makefile.am +++ b/Makefile.am @@ -59,7 +59,7 @@ dist_doc_DATA = \ README \ README.mbedtls \ - Changes.rst \ + Changes.md \ COPYRIGHT.GPL \ COPYING