diff options
Diffstat (limited to 'doc/openvpn.8')
| -rw-r--r-- | doc/openvpn.8 | 128 |
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 |