New upstream version 2.4.3upstream/2.4.3

1 files changed, 100 insertions, 28 deletions

diff --git a/doc/openvpn.8 b/doc/openvpn.8
index 7bd6d9d..56c0f7a 100644
--- a/doc/openvpn.8
+++ b/doc/openvpn.8
@@ -15,10 +15,9 @@
 .\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 .\"  GNU General Public License for more details.
 .\"
-.\"  You should have received a copy of the GNU General Public License
-.\"  along with this program (see the file COPYING included with this
-.\"  distribution); if not, write to the Free Software Foundation, Inc.,
-.\"  59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+.\"  You should have received a copy of the GNU General Public License along
+.\"  with this program; if not, write to the Free Software Foundation, Inc.,
+.\"  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 .\"
 .\" Manual page for openvpn
 .\"
@@ -327,7 +326,7 @@ http\-proxy 192.168.0.8 8080
 persist\-key
 persist\-tun
 pkcs12 client.p12
-ns\-cert\-type server
+remote\-cert\-tls server
 verb 3
 .in -4
 .ft
@@ -2712,6 +2711,34 @@ to the module initialization function.  Multiple
 plugin modules may be loaded into one OpenVPN
 process.
 
+The
+.B module-pathname
+argument can be just a filename or a filename with a relative
+or absolute path.  The format of the filename and path defines
+if the plug-in will be loaded from a default plug-in directory
+or outside this directory.
+
+.nf
+.ft 3
+.in +4
+.B \-\-plugin path\ \ \ \ \ \ \ \ Effective directory used
+====================================================
+ myplug.so            DEFAULT_DIR/myplug.so
+ subdir/myplug.so     DEFAULT_DIR/subdir/myplug.so
+ ./subdir/myplug.so   CWD/subdir/myplug.so
+ /usr/lib/my/plug.so  /usr/lib/my/plug.so
+.in -4
+.fi
+
+DEFAULT_DIR is replaced by the default plug-in directory,
+which is configured at the build time of OpenVPN.  CWD is the
+current directory where OpenVPN was started or the directory
+OpenVPN have swithed into via the
+.B \-\-cd
+option before the
+.B \-\-plugin
+option.
+
 For more information and examples on how to build OpenVPN
 plug-in modules, see the README file in the
 .B plugin
@@ -3969,9 +3996,8 @@ See management\-notes.txt in the OpenVPN distribution for a
 description of the OpenVPN challenge/response protocol.
 .\"*********************************************************
 .TP
-.B \-\-server\-poll\-timeout n
-.B \-\-connect\-timeout n
-when connecting to a remote server do not wait for more than
+\fB\-\-server\-poll\-timeout n\fR, \fB\-\-connect\-timeout n\fR
+When connecting to a remote server do not wait for more than
 .B n
 seconds waiting for a response before trying the next server.
 The default value is 120s. This timeout includes proxy and TCP
@@ -4668,15 +4694,27 @@ and
 Not available with PolarSSL.
 .\"*********************************************************
 .TP
-.B \-\-verify\-hash hash
-Specify SHA1 fingerprint for level-1 cert.  The level-1 cert is the
+.B \-\-verify\-hash hash [algo]
+Specify SHA1 or SHA256 fingerprint for level-1 cert.  The level-1 cert is the
 CA (or intermediate cert) that signs the leaf certificate, and is
 one removed from the leaf certificate in the direction of the root.
 When accepting a connection from a peer, the level-1 cert
 fingerprint must match
 .B hash
 or certificate verification will fail.  Hash is specified
-as XX:XX:...  For example: AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16
+as XX:XX:... For example:
+
+.nf
+.ft 3
+.in +4
+AD:B0:95:D8:09:C8:36:45:12:A9:89:C8:90:09:CB:13:72:A6:AD:16
+.in -4
+.ft
+.fi
+
+The
+.B algo
+flag can be either SHA1 or SHA256.  If not provided, it defaults to SHA1.
 .\"*********************************************************
 .TP
 .B \-\-pkcs11\-cert\-private [0|1]...
@@ -5064,6 +5102,29 @@ In contrast to
 .B \-\-tls\-crypt
 does *not* require the user to set
 .B \-\-key\-direction\fR.
+
+.B Security Considerations
+
+All peers use the same
+.B \-\-tls-crypt
+pre-shared group key to authenticate and encrypt control channel messages.  To
+ensure that IV collisions remain unlikely, this key should not be used to
+encrypt more than 2^48 client-to-server or 2^48 server-to-client control
+channel messages.  A typical initial negotiation is about 10 packets in each
+direction.  Assuming both initial negotiation and renegotiations are at most
+2^16 (65536) packets (to be conservative), and (re)negotiations happen each
+minute for each user (24/7), this limits the tls\-crypt key lifetime to 8171
+years divided by the number of users.  So a setup with 1000 users should rotate
+the key at least once each eight years.  (And a setup with 8000 users each
+year.)
+
+If IV collisions were to occur, this could result in the security of
+.B \-\-tls\-crypt
+degrading to the same security as using
+.B \-\-tls\-auth\fR.
+That is, the control channel still benefits from the extra protection against
+active man-in-the-middle-attacks and DoS attacks, but may no longer offer
+extra privacy and post-quantum security on top of what TLS itself offers.
 .\"*********************************************************
 .TP
 .B \-\-askpass [file]
@@ -5247,6 +5308,8 @@ option will match against the chosen
 .B fieldname
 instead of the Common Name.
 
+Only the subjectAltName and issuerAltName X.509 extensions are supported.
+
 .B Please note:
 This option has a feature which will convert an all-lowercase
 .B fieldname
@@ -5314,7 +5377,11 @@ as X509_<depth>_<attribute>=<value>.  Multiple
 options can be defined to track multiple attributes.
 .\"*********************************************************
 .TP
-.B \-\-ns\-cert\-type client|server
+.B \-\-ns\-cert\-type client|server (DEPRECATED)
+This option is deprecated.  Use the more modern equivalent
+.B \-\-remote\-cert\-tls
+instead.  This option will be removed in OpenVPN 2.5.
+
 Require that peer certificate was signed with an explicit
 .B nsCertType
 designation of "client" or "server".
@@ -5341,15 +5408,25 @@ or
 .B \-\-tls\-verify.
 .\"*********************************************************
 .TP
-.B \-\-remote\-cert\-ku v...
+.B \-\-remote\-cert\-ku [v...]
 Require that peer certificate was signed with an explicit
 .B key usage.
 
-This is a useful security option for clients, to ensure that
-the host they connect to is a designated server.
+If present in the certificate, the keyUsage value is validated by the TLS
+library during the TLS handshake.  Specifying this option without arguments
+requires this extension to be present (so the TLS library will verify it).
 
-The key usage should be encoded in hex, more than one key
-usage can be specified.
+If the list
+.B v...
+is also supplied, the keyUsage field must have
+.B at least
+the same bits set as the bits in
+.B one of
+the values supplied in the list
+.B v...
+
+The key usage values in the list must be encoded in hex, e.g.
+"\-\-remote\-cert\-ku a0"
 .\"*********************************************************
 .TP
 .B \-\-remote\-cert\-eku oid
@@ -5370,24 +5447,21 @@ and
 .B extended key usage
 based on RFC3280 TLS rules.
 
-This is a useful security option for clients, to ensure that
-the host they connect to is a designated server.
+This is a useful security option for clients, to ensure that the host they
+connect to is a designated server.  Or the other way around; for a server to
+verify that only hosts with a client certificate can connect.
 
 The
 .B \-\-remote\-cert\-tls client
 option is equivalent to
 .B
-\-\-remote\-cert\-ku 80 08 88 \-\-remote\-cert\-eku "TLS Web Client Authentication"
-
-The key usage is digitalSignature and/or keyAgreement.
+\-\-remote\-cert\-ku \-\-remote\-cert\-eku "TLS Web Client Authentication"
 
 The
 .B \-\-remote\-cert\-tls server
 option is equivalent to
 .B
-\-\-remote\-cert\-ku a0 88 \-\-remote\-cert\-eku "TLS Web Server Authentication"
-
-The key usage is digitalSignature and ( keyEncipherment or keyAgreement ).
+\-\-remote\-cert\-ku \-\-remote\-cert\-eku "TLS Web Server Authentication"
 
 This is an important security precaution to protect against
 a man-in-the-middle attack where an authorized client
@@ -5819,9 +5893,7 @@ flag.
 .TP
 .B \-\-dhcp\-release
 Ask Windows to release the TAP adapter lease on shutdown.
-This option has the same caveats as
-.B \-\-dhcp\-renew
-above.
+This option has no effect now, as it is enabled by default starting with version 2.4.1.
 .\"*********************************************************
 .TP
 .B \-\-register\-dns