From patchwork Wed May 12 03:15:11 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Arne Schwabe X-Patchwork-Id: 1809 Return-Path: Delivered-To: patchwork@openvpn.net Delivered-To: patchwork@openvpn.net Received: from director10.mail.ord1d.rsapps.net ([172.31.255.6]) by backend30.mail.ord1d.rsapps.net with LMTP id gD/XLCvVm2DQdQAAIUCqbw (envelope-from ) for ; Wed, 12 May 2021 09:16:27 -0400 Received: from proxy5.mail.iad3b.rsapps.net ([172.31.255.6]) by director10.mail.ord1d.rsapps.net with LMTP id sJ6xLCvVm2CsAQAApN4f7A (envelope-from ) for ; Wed, 12 May 2021 09:16:27 -0400 Received: from smtp34.gate.iad3b ([172.31.255.6]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) by proxy5.mail.iad3b.rsapps.net with LMTPS id cKJzJCvVm2AgGAAA13hMnw (envelope-from ) for ; Wed, 12 May 2021 09:16:27 -0400 X-Spam-Threshold: 95 X-Spam-Score: 0 X-Spam-Flag: NO X-Virus-Scanned: OK X-Orig-To: openvpnslackdevel@openvpn.net X-Originating-Ip: [216.105.38.7] Authentication-Results: smtp34.gate.iad3b.rsapps.net; iprev=pass policy.iprev="216.105.38.7"; spf=pass smtp.mailfrom="openvpn-devel-bounces@lists.sourceforge.net" smtp.helo="lists.sourceforge.net"; dkim=fail (signature verification failed) header.d=sourceforge.net; dkim=fail (signature verification failed) header.d=sf.net; dmarc=none (p=nil; dis=none) header.from=rfc2549.org X-Suspicious-Flag: YES X-Classification-ID: 417f926a-b324-11eb-bf1a-5254005e8ddb-1-1 Received: from [216.105.38.7] ([216.105.38.7:48588] helo=lists.sourceforge.net) by smtp34.gate.iad3b.rsapps.net (envelope-from ) (ecelerity 4.2.38.62370 r(:)) with ESMTPS (cipher=DHE-RSA-AES256-GCM-SHA384) id 92/D0-19686-A25DB906; Wed, 12 May 2021 09:16:27 -0400 Received: from [127.0.0.1] (helo=sfs-ml-2.v29.lw.sourceforge.com) by sfs-ml-2.v29.lw.sourceforge.com with esmtp (Exim 4.92.3) (envelope-from ) id 1lgoi1-0001nb-OF; Wed, 12 May 2021 13:15:29 +0000 Received: from [172.30.20.202] (helo=mx.sourceforge.net) by sfs-ml-2.v29.lw.sourceforge.com with esmtps (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.92.3) (envelope-from ) id 1lgohz-0001mc-Cw for openvpn-devel@lists.sourceforge.net; Wed, 12 May 2021 13:15:27 +0000 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sourceforge.net; s=x; h=Content-Transfer-Encoding:MIME-Version:References: In-Reply-To:Message-Id:Date:Subject:To:From:Sender:Reply-To:Cc:Content-Type: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=4lOuhkM6efrgCajUsJ0LEwNLOkBpgTM5Bvt5eXMy/QM=; b=Cj5ElmTmEA9LbmBWYtyRYH4+sX em0gAFiJ4qYSTSOaMIGyyXE0VdTcNjKSZPjXeLqrPO3D9RemyD9dmz1CI9fplL3v97YrmvSUxvTuw MOr75FJx2yBaJOoZD9iBPw9zdgk7MmwXyeNMMTRX/7eOlphBydaql0WmLMos+QFBPzmc=; DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=sf.net; s=x ; h=Content-Transfer-Encoding:MIME-Version:References:In-Reply-To:Message-Id: Date:Subject:To:From:Sender:Reply-To:Cc:Content-Type:Content-ID: Content-Description:Resent-Date:Resent-From:Resent-Sender:Resent-To:Resent-Cc :Resent-Message-ID:List-Id:List-Help:List-Unsubscribe:List-Subscribe: List-Post:List-Owner:List-Archive; bh=4lOuhkM6efrgCajUsJ0LEwNLOkBpgTM5Bvt5eXMy/QM=; b=LI787VuoM57ohnHHhgnE+wQvdD SWD5JQ8uXn3zCXw6v+B9Eat5k2LlY+NHRJpxCps0G7y0MTtCwdark8JYa4LyccXUEkXqRnwNGt+LV FWXHmhk4xdd0ygOsw9iTDQLGoAp+Ob49OUj8e3D7iy4IE2pyC8BV0lPt1kVWYFp99ZR4=; Received: from mail.blinkt.de ([192.26.174.232]) by sfi-mx-2.v28.lw.sourceforge.com with esmtps (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.92.3) id 1lgoht-0008VH-Ul for openvpn-devel@lists.sourceforge.net; Wed, 12 May 2021 13:15:27 +0000 Received: from kamera.blinkt.de ([2001:638:502:390:20c:29ff:fec8:535c]) by mail.blinkt.de with smtp (Exim 4.94.2 (FreeBSD)) (envelope-from ) id 1lgohj-000BzQ-N9 for openvpn-devel@lists.sourceforge.net; Wed, 12 May 2021 15:15:11 +0200 Received: (nullmailer pid 1309989 invoked by uid 10006); Wed, 12 May 2021 13:15:12 -0000 From: Arne Schwabe To: openvpn-devel@lists.sourceforge.net Date: Wed, 12 May 2021 15:15:11 +0200 Message-Id: <20210512131511.1309914-10-arne@rfc2549.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20210512131511.1309914-1-arne@rfc2549.org> References: <20210512131511.1309914-1-arne@rfc2549.org> MIME-Version: 1.0 X-Spam-Report: Spam Filtering performed by mx.sourceforge.net. See http://spamassassin.org/tag/ for more details. 0.0 URIBL_BLOCKED ADMINISTRATOR NOTICE: The query to URIBL was blocked. See http://wiki.apache.org/spamassassin/DnsBlocklists#dnsbl-block for more information. [URIs: rfc2549.org] 0.2 HEADER_FROM_DIFFERENT_DOMAINS From and EnvelopeFrom 2nd level mail domains are different 0.0 SPF_NONE SPF: sender does not publish an SPF Record 0.0 SPF_HELO_NONE SPF: HELO does not publish an SPF Record X-Headers-End: 1lgoht-0008VH-Ul Subject: [Openvpn-devel] [PATCH 9/9] Add detailed man page section to setup a OpenVPN setup with peer-fingerprint X-BeenThere: openvpn-devel@lists.sourceforge.net X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: openvpn-devel-bounces@lists.sourceforge.net X-getmail-retrieved-from-mailbox: Inbox This is meant to give new users a quickstart for a useable OpenVPN setup. Our own documentation is lacking in this regard and many often tutorials that can be found online are often questionable in some aspects. Linking the invidiaul RST file on github also give a tutorial in a nicely formatted way. Signed-off-by: Arne Schwabe --- Changes.rst | 4 + doc/Makefile.am | 1 + doc/man-sections/example-fingerprint.rst | 194 +++++++++++++++++++++++ 3 files changed, 199 insertions(+) create mode 100644 doc/man-sections/example-fingerprint.rst diff --git a/Changes.rst b/Changes.rst index 9185b55f7..f1c739f99 100644 --- a/Changes.rst +++ b/Changes.rst @@ -25,6 +25,10 @@ Certificate pinning/verify peer fingerprint 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 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 diff --git a/doc/Makefile.am b/doc/Makefile.am index e411f5f9d..e7022c085 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -25,6 +25,7 @@ dist_noinst_DATA = \ man-sections/connection-profiles.rst \ man-sections/encryption-options.rst \ man-sections/examples.rst \ + man-sections/examples.rst \ man-sections/generic-options.rst \ man-sections/inline-files.rst \ man-sections/link-options.rst \ diff --git a/doc/man-sections/example-fingerprint.rst b/doc/man-sections/example-fingerprint.rst new file mode 100644 index 000000000..7d915aedb --- /dev/null +++ b/doc/man-sections/example-fingerprint.rst @@ -0,0 +1,194 @@ +Small OpenVPN setup with peer-fingerprint +========================================= +This section consists of instructions how to build a small OpenVPN setup with the +:code:`peer-fingerprint` option. This setup has the advantage to be easy to setup +and should for most small lab and home setups without the need to setup a PKI. +For bigger scale setup setting up a PKI (e.g. via easy-rsa) is still recommended. + +Both server and client configuration can of course be further modified to individualise the +setup. + +Server setup +------------ +1. Install openvpn + + Compile from source-code (see `INSTALL` file) or install via a distribution (apt/yum/ports) + or via installer (Windows). + +2. Generate a self-signed certificate for the server: + :: + + openssl req -x509 -newkey ec:<(openssl ecparam -name secp384r1) -keyout serverkey.pem -out server.pem -nodes -sha256 -days 3650 -subj '/CN=server' + +3. Generate SHA256 fingerprint of the server certificate + + Use the OpenSSL command line utility to view the fingerprint of just + created certificate: + :: + + openssl x509 -fingerprint -sha256 -in styx-win.pem -noout server.pem + + This output something similar to: + :: + + SHA256 Fingerprint=00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff + + +3. Write a server configuration (`server.conf`): +:: + + # The server certificate we created in step 1 + cert server.pem + key serverkey.pem + + dh none + dev tun + + # Listen on IPv6+IPv4 simultaneously + proto udp6 + + # The ip address the server will distribute + server 192.168.234.0 255.255.255.0 + server-ipv6 fd00:6f76:706e::/64 + + # A tun-mtu of 1400 avoids problems of too big packets after VPN encapsulation + tun-mtu 1400 + + # The fingerprints of your clients. After adding/remvoing one here restart the + # server + + + + # Notify clients when you restart the server to reconnect quickly + explicit-exit-notify 1 + + # Ping every 60s, restart if no data received for 5 minutes + keepalive 60 300 + +4. Add at least one client as described in the client section. + +5. Start the server. + - On systemd based distributions move `server.pem`, `serverkey.pem` and + `server.conf` to :code:`/etc/openvpn/server` and start it via systemctl + + :: + + sudo mv server.conf server.pem /etc/openvpn + + sudo systemctl start openvpn-server@server + +Adding a client +--------------- +1. Install OpenVPN + +2. Generate a self-signed certificate for the client. In this example the client + name is alice. Each client should have a unique name. Replace alice with a + different name for each client. + :: + + openssl req -x509 -newkey ec:<(openssl ecparam -name secp384r1) -nodes -sha256 -days 3650 -subj '/CN=alice' + + This generate a certificate and a key for the client. The output of the command will look + something like this: + :: + + -----BEGIN PRIVATE KEY----- + [base64 content] + -----END PRIVATE KEY----- + ----- + -----BEGIN CERTIFICATE----- + [base 64 content] + -----END CERTIFICATE----- + +3. Create a new client configuration file. In this example we will name the file + `alice.ovpn`: + + :: + + # The name of your server to connect to + remote yourserver.example.net + client + # use a random source port instead the fixed 1194 + nobind + + # Uncomment the following line if you want to route + # all traffic via the VPN + # redirect-gateway def1 ipv6 + + # To set a a DNS server + # dhcp-option DNS 192.168.234.1 + + + -----BEGIN PRIVATE KEY----- + [Insert here the key created in step 2] + -----END PRIVATE KEY----- + + + -----BEGIN CERTIFICATE----- + [Insert here the certificate created in step 2] + -----END CERTIFICATE----- + + + # This the fingerprint of the server that we trust. We generated this fingerprint + # in step 2 of the server setup + peer-fingerprint 00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff + + # The tun-mtu of the client should match the server MTU + tun-mtu 1400 + dev tun + + +4. Generate the fingerprint of the client certificate. For that we will + let OpenSSL read the client configuration file as the x509 command will + ignore anything that is not between the begin and end markers of the certificate: + + :: + + openssl x509 -fingerprint -sha256 -noout -in ./focal-server-locked.ovpn + + This will again output something like + :: + + SHA256 Fingerprint=ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00:ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00 + +5. Edit the `server.conf` configuration file and add this new client + fingerprint as additional line between :code:`` + and :code:`` + + After adding *two* clients the part of configuration would look like this: + + :: + + + ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00:ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00 + 99:88:77:66:55:44:33:22:11:00:ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00:88:77:66:55:44:33 + + +6. (optional) if the client is an older client that does not support the + :code:`peer-fingerprint` (OpenVPN 2.5 and older, OpenVPN Connect 3.3 + and older), the config can be modified to still work with those. + + Remove the line starting with :code:`peer-fingerprint` line. Then + add a new :code:`` section at the end of the configuration file + with the contents of the :code:`server.pem` created in step 2 of the + server setup. The end of `alice.ovpn` file should like: + + :: + + [...] # Beginning of the file skipped + + + # The tun-mtu of the client should match the server MTU + tun-mtu 1400 + dev tun + + + [contents of the server.pem] + + + Note that we put the :code:`` section after the :code:`` section + to make the fingerprint generation from step 4 still work since it will + only use the first certificate its find. + +7. Import the file into the OpenVPN client or just use the + :code:`openvpn alice.ovpn` to start the VPN.