Message ID | 20210520150932.2565217-2-arne@rfc2549.org |
---|---|
State | Superseded |
Headers | show |
Series | [Openvpn-devel,v2,1/2] Move examples into openvpn-examples(5) man page | expand |
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi, again, I do not understand why openvpn choose to switch to .pem for this tutorial. PEM -> Private Email, which this is not. You have a certificate and a key and every other openvpn tutorial on openvpn and probably the entire planet uses .crt and .key. This seems to be a poor decision in my opinion. And I presume that --tun-mtu 1400 is not going to break --mssfix 1450 There is also another advantage of using this method which is not documented. Each client can build its own cert/key and send the finger-print to the server in clear text, as can the server FP be sent to the clients. And apologies for the plug but easy-pfp can do all this and more even easier. https://github.com/TinCanTech/easy-pfp Sent with ProtonMail Secure Email. Which does not know how to reply to a git formatted patch and has other stupid quirks too. sed formatted reply. ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Thursday, 20 May 2021 16:09, Arne Schwabe <arne@rfc2549.org> wrote: > This is meant to give new users a quickstart for a useable OpenVPN > setup. Our own documentation is lacking in this regard and many > tutorials that can be found online are often questionable in some > aspects. > > Linking the individaul RST file on github also give a tutorial > in a nicely formatted way. individaul -> individual (ua) > > Patch V2: Fix grammar/spelling mistakes (thanks ticantech), move > to openvpn-examples(5). > > Signed-off-by: Arne Schwabe <arne@rfc2549.org> > --- > Changes.rst | 4 + > doc/Makefile.am | 1 + > doc/man-sections/example-fingerprint.rst | 196 +++++++++++++++++++++++ > doc/openvpn-examples.5.rst | 1 + > 4 files changed, 202 insertions(+) > create mode 100644 doc/man-sections/example-fingerprint.rst > > diff --git a/Changes.rst b/Changes.rst > index 9185b55f7..5ac24307f 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 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 > diff --git a/doc/Makefile.am b/doc/Makefile.am > index 1dbbddf58..d86560174 100644 > --- a/doc/Makefile.am > +++ b/doc/Makefile.am > @@ -25,6 +25,7 @@ dist_noinst_DATA = \ > man-sections/client-options.rst \ > man-sections/connection-profiles.rst \ > man-sections/encryption-options.rst \ > + man-sections/example-fingerprint.rst \ > man-sections/examples.rst \ > man-sections/generic-options.rst \ > man-sections/inline-files.rst \ > diff --git a/doc/man-sections/example-fingerprint.rst b/doc/man-sections/example-fingerprint.rst > new file mode 100644 > index 000000000..c91ca64b9 > --- /dev/null > +++ b/doc/man-sections/example-fingerprint.rst > @@ -0,0 +1,196 @@ > +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 has the advantage of being easy to setup > +and should be suitable for most small lab and home setups without the need for 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 be further modified to customise 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 server.pem -noout > + > + 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/removing one here restart the > + # server > + <peer-fingerprint> > + </peer-fingerprint> > + > + # 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 serverkey.pem server.pem /etc/openvpn/server > + > + 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 This does not generate a certificate and a key *file* and I think that should be stated explicitly. > + 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 > + > + <key> > + -----BEGIN PRIVATE KEY----- > + [Insert here the key created in step 2] > + -----END PRIVATE KEY----- > + </key> > + <cert> > + -----BEGIN CERTIFICATE----- > + [Insert here the certificate created in step 2] > + -----END CERTIFICATE----- > + </cert> > + > + # This is the fingerprint of the server that we trust. We generated this fingerprint > + # in step 2 of the server setup + In this example we do not need to use inline markers <peer-fingerprint> and </peer-fingerprint> It will probably be easier to see in the formatted .rst but just for the record. > + 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 alice.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:`<peer-fingerprint>` > + and :code:`</peer-fingerprint>` > + > + After adding *two* clients the part of configuration would look like this: > + > + :: > + > + <peer-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 > + 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 > + </peer-fingperint> > + > +6. (optional) if the client is an older client that does not support the > + :code:`peer-fingerprint` (e.g. OpenVPN 2.5 and older, OpenVPN Connect 3.3 > + and older), the client config `alice.ovpn` can be modified to still work with > + these clients. This doesn't seem right. Do you mean ? the client config `alice.ovpn` can be modified to still work with *new servers* > + > + Remove the line starting with :code:`peer-fingerprint`. Then > + add a new :code:`<ca>` 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 > + </cert> > + > + # The tun-mtu of the client should match the server MTU > + tun-mtu 1400 > + dev tun > + > + <ca> > + [contents of the server.pem] > + </ca> > + > + Note that we put the :code:`<ca>` section after the :code:`<cert>` section > + to make the fingerprint generation from step 4 still work since it will > + only use the first certificate it find. Forgot the 's' in finds ;-) Hope I'm helping R > + > +7. Import the file into the OpenVPN client or just use the > + :code:`openvpn alice.ovpn` to start the VPN. > diff --git a/doc/openvpn-examples.5.rst b/doc/openvpn-examples.5.rst > index 988b6027b..0e1b6c4f6 100644 > --- a/doc/openvpn-examples.5.rst > +++ b/doc/openvpn-examples.5.rst > @@ -14,4 +14,5 @@ INTRODUCTION > > This man page gives a few simple examples to create OpenVPN setups and configuration files. > > +.. include:: man-sections/example-fingerprint.rst > .. include:: man-sections/examples.rst > -- > 2.31.1 > > > > _______________________________________________ > Openvpn-devel mailing list > Openvpn-devel@lists.sourceforge.net > https://lists.sourceforge.net/lists/listinfo/openvpn-devel -----BEGIN PGP SIGNATURE----- Version: ProtonMail wsBzBAEBCAAGBQJgppStACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ2WGwgAhMxENN0Y9MYIQcTpm51WuOtHmS5yyPTH9tQjw1yPlGkXXakE whB6vVRGZ9BDGxZFsGHxzJ8XllM1HnYROW4rpRhX2IoafW6QIaMZ33mvYVgq rwu/JHbWktXOAzkh3z1Z7v5HCEI5LW1at8ei7+H06pUR9Eo1W6YBDa0nP7Ni AAoik9/cEv1l/7V4pHhBklyydqoUVAPNXP5lOy6NoqKJYkRQOH98BeA+Tctm BaxzC+XFNYMO+khkvSeLNRG0l1coc825VPbwMdmInqlW9f+u5jgh3e9ka6sW UmIEmODei6zSXAChWn6OlBBJhyAMdDEYf53kKAMFf8E+2s4m1ReYaw== =ZRj2 -----END PGP SIGNATURE-----
Hi, On Thu, May 20, 2021 at 04:56:16PM +0000, tincantech via Openvpn-devel wrote: > again, I do not understand why openvpn choose to switch to .pem > for this tutorial. PEM -> Private Email, which this is not. https://www.ssl.com/guide/pem-der-crt-and-cer-x-509-encodings-and-conversions/ gert
Am 20.05.2021 um 18:56 schrieb tincantech: > Hi, > > again, I do not understand why openvpn choose to switch to .pem > for this tutorial. PEM -> Private Email, which this is not. > You have a certificate and a key and every other openvpn tutorial > on openvpn and probably the entire planet uses .crt and .key. > This seems to be a poor decision in my opinion. pem as extension for keys is pretty common and specifies more the encoding than the type. E.g. there is also the der encoding. Arne
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi, ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Thursday, 20 May 2021 19:30, Arne Schwabe <arne@rfc2549.org> wrote: > Am 20.05.2021 um 18:56 schrieb tincantech: > > > Hi, > > again, I do not understand why openvpn choose to switch to .pem > > for this tutorial. PEM -> Private Email, which this is not. > > You have a certificate and a key and every other openvpn tutorial > > on openvpn and probably the entire planet uses .crt and .key. > > This seems to be a poor decision in my opinion. > > pem as extension for keys is pretty common and specifies more the > encoding than the type. E.g. there is also the der encoding. > > Arne I accept the principle but openvpn *only* uses PEM-enc, that I know of. So, why switch to .pem when it has never been used before by openvpn? If you are all happy to let it go that way then so-be-it, Thanks R -----BEGIN PGP SIGNATURE----- Version: ProtonMail wsBzBAEBCAAGBQJgpr0yACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ3AXgf9H+mL+H1aPZ/Gk0lTukZEP7FVXHkO2LBf49KA/YmoyhbHYAFf sICvASsTlkA0q3wuKYzXs8bspMGiebOeqcoJi7QvJSaAq4sDLvWopz/VmN96 SmB33OnN/jYHQmKpk2qOMeZv6PyhFyjFb/3j1ymQ2zuYXh8osrSiiRHftwSx hXg8CMyXOA0THrK6H9mnxisLuss7uhVsclwTOSKMOnRj0NiEx5tFg1itn7+u YmRL/h2taDC6skHbF5PPfU1x/M6HtG05ZajAtNfh3bc0Zw4S7bRiEUc4+4qb f8GEEufo2WAg4CUwaCVJ9O5pSewk48OAScHGx9RMybvfZ1X6V5xnqA== =EBa6 -----END PGP SIGNATURE-----
Hi, On Thu, May 20, 2021 at 3:50 PM tincantech via Openvpn-devel <openvpn-devel@lists.sourceforge.net> wrote: > > -----BEGIN PGP SIGNED MESSAGE----- > Hash: SHA256 > > Hi, > > ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ > On Thursday, 20 May 2021 19:30, Arne Schwabe <arne@rfc2549.org> wrote: > > > Am 20.05.2021 um 18:56 schrieb tincantech: > > > > > Hi, > > > again, I do not understand why openvpn choose to switch to .pem > > > for this tutorial. PEM -> Private Email, which this is not. > > > You have a certificate and a key and every other openvpn tutorial > > > on openvpn and probably the entire planet uses .crt and .key. > > > This seems to be a poor decision in my opinion. > > > > pem as extension for keys is pretty common and specifies more the > > encoding than the type. E.g. there is also the der encoding. > > > > Arne > > I accept the principle but openvpn *only* uses PEM-enc, that I know of. > > So, why switch to .pem when it has never been used before by openvpn? > > If you are all happy to let it go that way then so-be-it, I'm not sure I fully understand the discussion here, but we should stick with consistent extensions for cert and key files in documentation and examples. Currently we use the phrase "PEM certs" in one place and "in .pem format" elsewhere. "PEM encoded" or "PEM format" would be a better description. We use server.crt, server,key etc in some places, .pem in some other. OpenVPN doesn't care about the file extension of keys or certs as long as the content is PEM. In that sense, having .pem in examples may appear to be self-documenting but we have to be consistent. Use of .pem has the drawback that we can use the same filename for cert and key. In practice I prefer .crt and .key as they are generally understood as PEM encoded, and allow the same filename stub to be used for both cert and key files: like server.crt and server.key while with pem it will have to be something like server-cert.pem and server-key.pem. Also, fwiw, .pem is not recognized by Windows explorer, .crt is -- one could double click on the latter and load into the cert store, not so with .pem. Selva
Hi, On 20/05/21 21:49, tincantech via Openvpn-devel wrote: > >>> Hi, >>> again, I do not understand why openvpn choose to switch to .pem >>> for this tutorial. PEM -> Private Email, which this is not. >>> You have a certificate and a key and every other openvpn tutorial >>> on openvpn and probably the entire planet uses .crt and .key. >>> This seems to be a poor decision in my opinion. >> pem as extension for keys is pretty common and specifies more the >> encoding than the type. E.g. there is also the der encoding. >> >> Arne > I accept the principle but openvpn *only* uses PEM-enc, that I know of. > > So, why switch to .pem when it has never been used before by openvpn? > > If you are all happy to let it go that way then so-be-it, > Hopefully this clarifies things: - the default output format of OpenSSL is PEM-encoded ; openssl uses the default extension .pem - the OpenVPN .crt and .key files are ALSO PEM-encoded by default, but they've just been named differently by the easy-rsa tools to ensure that the files can be easily loaded on Windows - FTR: nearly all webservers I have ever seen are configured to use a hostcert.pem and hostkey.pem and my guess is that there are (still) more Linux-based webservers out there than OpenVPN clients and servers. Having said that, I do agree that after using .crt/.key files left and right (to accomodate Windows users) for over 15 years, it does seem confusing to start using files named .pem for peer-fingerprinting all of sudden. On the other hand, with peer-fingerprinting you don't *HAVE* a .crt file (at least, you don't need one, technically) but only a .key file. So choosing a different extension for peer-fingerprinting does have its merits. HTH, JJK
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Sent with ProtonMail Secure Email. ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Thursday, 20 May 2021 22:05, Jan Just Keijser <janjust@nikhef.nl> wrote: > Hi, > > On 20/05/21 21:49, tincantech via Openvpn-devel wrote: > > > > > Hi, > > > > again, I do not understand why openvpn choose to switch to .pem > > > > for this tutorial. PEM -> Private Email, which this is not. > > > > You have a certificate and a key and every other openvpn tutorial > > > > on openvpn and probably the entire planet uses .crt and .key. > > > > This seems to be a poor decision in my opinion. > > > > pem as extension for keys is pretty common and specifies more the > > > > encoding than the type. E.g. there is also the der encoding. > > > > > > Arne > > > I accept the principle but openvpn only uses PEM-enc, that I know of. > > > > So, why switch to .pem when it has never been used before by openvpn? > > If you are all happy to let it go that way then so-be-it, > > Hopefully this clarifies things: > > - the default output format of OpenSSL is PEM-encoded ; openssl uses the > default extension .pem > > - the OpenVPN .crt and .key files are ALSO PEM-encoded by default, but > they've just been named differently by the easy-rsa tools to ensure that > the files can be easily loaded on Windows > > - FTR: nearly all webservers I have ever seen are configured to use a > hostcert.pem and hostkey.pem and my guess is that there are (still) > more Linux-based webservers out there than OpenVPN clients and servers. > > Having said that, I do agree that after using .crt/.key files left and > right (to accomodate Windows users) for over 15 years, it does seem > confusing to start using files named .pem for peer-fingerprinting all > of sudden. On the other hand, with peer-fingerprinting you don't > HAVE a .crt file (at least, you don't need one, technically) but only > a .key file. So choosing a different extension for peer-fingerprinting > does have its merits. FTR: Openvpn still exchanges the full certificates in peer-fingerprint mode. > > HTH, > > JJK > -----BEGIN PGP SIGNATURE----- Version: ProtonMail wsBzBAEBCAAGBQJgptC5ACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ2t0ggAxDZnJr8UhxV79fyAjnScANMeWbN3XZ/QqQuTsgaJp85Fibbz weT1TfvihZ5l1rS6vh1nIDyTtoNRpqLHMxlaNWnmgN9tR4IRlQZuVR8svZl1 UYmrAm1H5g83yHef60nnIiOxGe8tnLdy/fmjqoRFsHaBwSM87zTQ8uG+UJnq GIGhHbdLYWaH4C9SrJ+p64pZYdm3jaQpwMMMMZHdeg3rPdvHAgUixX13KWBU J2UYseRDBLcvNfz6gAgQDtTJtdT9edH3h6m4Tyu0AsIw016hfREeNe20uzrX uyQ6jGGovT2ki9alVN9P5v1k9uYVC0/1mYnFBLR8PI8effQd/zfLiA== =KICZ -----END PGP SIGNATURE-----
On 20/05/21 23:12, tincantech wrote: > [...] >>> So, why switch to .pem when it has never been used before by openvpn? >>> If you are all happy to let it go that way then so-be-it, >> Hopefully this clarifies things: >> >> - the default output format of OpenSSL is PEM-encoded ; openssl uses the >> default extension .pem >> >> - the OpenVPN .crt and .key files are ALSO PEM-encoded by default, but >> they've just been named differently by the easy-rsa tools to ensure that >> the files can be easily loaded on Windows >> >> - FTR: nearly all webservers I have ever seen are configured to use a >> hostcert.pem and hostkey.pem and my guess is that there are (still) >> more Linux-based webservers out there than OpenVPN clients and servers. >> >> Having said that, I do agree that after using .crt/.key files left and >> right (to accomodate Windows users) for over 15 years, it does seem >> confusing to start using files named .pem for peer-fingerprinting all >> of sudden. On the other hand, with peer-fingerprinting you don't >> HAVE a .crt file (at least, you don't need one, technically) but only >> a .key file. So choosing a different extension for peer-fingerprinting >> does have its merits. > FTR: Openvpn still exchanges the full certificates in peer-fingerprint mode. > meh ... I guess it was easier to implement it that way at the TLS level... IMO that does add a "+1" to using .crt/.key extensions - otherwise it might confuse the heck out of end users (like overwriting the private key with the public cert etc ... ) How do the examples distinguish between the cert and the private key in this case then? JJK
> Hopefully this clarifies things: > - the default output format of OpenSSL is PEM-encoded ; openssl uses > the default extension .pem > - the OpenVPN .crt and .key files are ALSO PEM-encoded by default, but > they've just been named differently by the easy-rsa tools to ensure > that the files can be easily loaded on Windows > > - FTR: nearly all webservers I have ever seen are configured to use a > hostcert.pem and hostkey.pem and my guess is that there are (still) > more Linux-based webservers out there than OpenVPN clients and servers. > > Having said that, I do agree that after using .crt/.key files left and > right (to accomodate Windows users) for over 15 years, it does seem > confusing to start using files named .pem for peer-fingerprinting all > of sudden. On the other hand, with peer-fingerprinting you don't > *HAVE* a .crt file (at least, you don't need one, technically) but > only a .key file. So choosing a different extension for > peer-fingerprinting does have its merits. I am used a lot more used to calling these files pem files. I suggest we put that just on the agenda for the next openvpn-meeting, if people have strong preferences there. And no, you still need cert and key like for a normal TLS connection with peer-fingerprint. It *only* replacing the normal check of the certificate with a fingerprint. Basically the same principle that browsers do when you do cert-pinning. Arne
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi, ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Thursday, 20 May 2021 22:22, Jan Just Keijser <janjust@nikhef.nl> wrote: > On 20/05/21 23:12, tincantech wrote: > > > [...] > > > > > > So, why switch to .pem when it has never been used before by openvpn? > > > > If you are all happy to let it go that way then so-be-it, > > > > Hopefully this clarifies things: > > > > > > - the default output format of OpenSSL is PEM-encoded ; openssl uses the > > > default extension .pem > > > > > > - the OpenVPN .crt and .key files are ALSO PEM-encoded by default, but > > > they've just been named differently by the easy-rsa tools to ensure that > > > the files can be easily loaded on Windows > > > > > > - FTR: nearly all webservers I have ever seen are configured to use a > > > hostcert.pem and hostkey.pem and my guess is that there are (still) > > > more Linux-based webservers out there than OpenVPN clients and servers. > > > Having said that, I do agree that after using .crt/.key files left and > > > right (to accomodate Windows users) for over 15 years, it does seem > > > confusing to start using files named .pem for peer-fingerprinting all > > > of sudden. On the other hand, with peer-fingerprinting you don't > > > HAVE a .crt file (at least, you don't need one, technically) but only > > > a .key file. So choosing a different extension for peer-fingerprinting > > > does have its merits. > > FTR: Openvpn still exchanges the full certificates in peer-fingerprint mode. > meh ... I guess it was easier to implement it that way at the TLS level... I cannot comment on the code but there is the case of older clients which require self-signed server".crt" (Easy-RSA) in place of the CA cert. > > IMO that does add a "+1" to using .crt/.key extensions - otherwise it > might confuse the heck out of end users (like overwriting the private > key with the public cert etc ... ) That is another good point. > How do the examples distinguish between the cert and the private key in > this case then? Generally, the distinction between what is private and what is public has not been very well covered. Other than the notable exception of "Protect your Private CA key at all costs!" I have included this Private v Public information in the easy-pfp output. Seems like the only way to get things done sometimes is do-it-yourself ;-) Anyway, all other points aside, the point is that: Changing to .pem (not PEM) feels like an unnecessary complication. Thanks for all your input R -----BEGIN PGP SIGNATURE----- Version: ProtonMail wsBzBAEBCAAGBQJgptYeACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ0haQf/VyfMNC8x8r+8okE+aKW+kp+OMA58J6R7xOdv7D518BsBSJNX BAqDiM1lalAwDvU7edKKMXhc0U2BOgMiaVOXp54jkZvXo7O5tt57A1O+tTKv GNPzqDrhfGQRuaplHTMeiSkcWZOSmyNwIAW0vroCmiPBnGY2/F5GIL8T83Dp qiNsST7Fug+u4nVUv/BUE2K81/B3pNz4Jy6hX2QMmq5LdRJgtNU37AAsZAQ5 Zwr4bewl/l8q36VjsX4QYNQgQekXdK8oT7LXZuqEy+tf4RnVHA8YDQZ2Ed5t tfUUg/b02w3Ml6k9Wt3SHDgoXMAW0utUxxOWCMGVnEhuDRWg0kQ3rw== =B+MM -----END PGP SIGNATURE-----
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi, -‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Thursday, 20 May 2021 22:35, tincantech via Openvpn-devel <openvpn-devel@lists.sourceforge.net> wrote: > Hi, > > ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ > On Thursday, 20 May 2021 22:22, Jan Just Keijser janjust@nikhef.nl wrote: > > > On 20/05/21 23:12, tincantech wrote: > > > > > [...] > > > > > > > > So, why switch to .pem when it has never been used before by openvpn? > > > > > If you are all happy to let it go that way then so-be-it, > > > > > Hopefully this clarifies things: > > > > > > > > - the default output format of OpenSSL is PEM-encoded ; openssl uses the > > > > default extension .pem > > > > > > > > - the OpenVPN .crt and .key files are ALSO PEM-encoded by default, but > > > > they've just been named differently by the easy-rsa tools to ensure that > > > > the files can be easily loaded on Windows > > > > > > > > - FTR: nearly all webservers I have ever seen are configured to use a > > > > hostcert.pem and hostkey.pem and my guess is that there are (still) > > > > more Linux-based webservers out there than OpenVPN clients and servers. > > > > Having said that, I do agree that after using .crt/.key files left and > > > > right (to accomodate Windows users) for over 15 years, it does seem > > > > confusing to start using files named .pem for peer-fingerprinting all > > > > of sudden. On the other hand, with peer-fingerprinting you don't > > > > HAVE a .crt file (at least, you don't need one, technically) but only > > > > a .key file. So choosing a different extension for peer-fingerprinting > > > > does have its merits. > > > > > > > > FTR: Openvpn still exchanges the full certificates in peer-fingerprint mode. > > > > > > meh ... I guess it was easier to implement it that way at the TLS level... > > I cannot comment on the code but there is the case of older clients which require > self-signed server".crt" (Easy-RSA) in place of the CA cert. > > > IMO that does add a "+1" to using .crt/.key extensions - otherwise it > > might confuse the heck out of end users (like overwriting the private > > key with the public cert etc ... ) > > That is another good point. > > > How do the examples distinguish between the cert and the private key in > > this case then? > > Generally, the distinction between what is private and what is public > has not been very well covered. Other than the notable exception of > "Protect your Private CA key at all costs!" > > I have included this Private v Public information in the easy-pfp output. > Seems like the only way to get things done sometimes is do-it-yourself ;-) > > Anyway, all other points aside, the point is that: Changing to .pem (not PEM) > feels like an unnecessary complication. > I would like to hammer one final nail into this discussion. Openvpn option names and inline tags ALL use <cert>ificate .crt and <key> .key. They do not use .pem or PEM and none of the Official online documentation, to date, references use of a {name}.pem file, other than far-flung cases. The files generated in this tutorial will all be PEM encoded regardless. This is why I asked the question of why Openvpn suddenly chooses to change to a .pem extension and add this unnecessary complication. Real users may see this as another hurdle which they just don't want to jump. Do you want to drive them away .. ? As I am also banned from #openvpn-meeting, so I leave this for you to discuss. -- Richard -----BEGIN PGP SIGNATURE----- Version: ProtonMail wsBzBAEBCAAGBQJgpvNyACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ1U5wgAza4n5mxniWpvVrkSxRCN3TEc0MEafFb+Eza0uL/l9i5tVDDQ A4ZwjBuRGgteJzNhbe3Q+YJzZZ1hjf9k9FjPwGtnUK49IZZt8OOe60bfiQt7 aSmhKMRyZzzjRgSv6QNdPWsZEB3JceZ572+EIi5zfQmz6V1q8USsPQPaUZoa k65YA9Z+pU6xsm1+lKMLGbi8rzIvIhNYCEIZ4pGl5OzckQP7o7JKUanhOoHH 7KrD5Nu5ad4CtgMv72RYWCbmW5vsqIcOrYJIG7mASodCTGkL2JH5F2i8fVUJ rg5OrvVViLewxTYyGCVc+PZ7ukB6l/bEYd8efA1G4carr6+hRDTfSA== =T6wH -----END PGP SIGNATURE-----
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi, ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Friday, 21 May 2021 00:40, tincantech <tincantech@protonmail.com> wrote: > I would like to hammer one final nail into this discussion. > > Openvpn option names and inline tags ALL use <cert>ificate .crt and <key> .key. > > They do not use .pem or PEM and none of the Official online documentation, > to date, references use of a {name}.pem file, other than far-flung cases. > > The files generated in this tutorial will all be PEM encoded regardless. One final blow to the nail: There is still the outstanding problem of --remote-cert-tls which this tutorial does not discuss or solve. The user log will show a WARNING message which they *cannot* solve by means of your documentation. -- Thanks R Unfairly banned. -----BEGIN PGP SIGNATURE----- Version: ProtonMail wsBzBAEBCAAGBQJgpvv5ACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ2gkQf9FDId8dPnTrdC4+UHLhFOJOAYelk9SDQ1a3PSVhbag2ZO2FvM 3pCKfqdqSB0zYuu3rXBSdBoToovKw2Zc+8tnF8MaH6Oqm5+cmnRDfc03ZfDs auqD04xIACnt3cPYAXXU+qXxGC8GpwLiUlEIEzlTcTsBrZyLMJhMPx146Dpe MNRQtmYW+FqJfYHO7OscIb1uwUQ4WeWLY+76GkqhRMSPY6hrZ6CRU9htSdoU w+B7KOGCKVE/FsyABNOz4IRNdnM3FMzvAvRD0UcOxJnmz/2BjImP6qNa7D0f VGyg1kvnYQViVOOjE17ejvqbnLcRJRD53gRJcHpb/45UbVWNjSq04A== =C3te -----END PGP SIGNATURE-----
On 20/05/2021 17:09, Arne Schwabe wrote: > This is meant to give new users a quickstart for a useable OpenVPN > setup. Our own documentation is lacking in this regard and many > tutorials that can be found online are often questionable in some > aspects. > > Linking the individaul RST file on github also give a tutorial > in a nicely formatted way. > > Patch V2: Fix grammar/spelling mistakes (thanks ticantech), move > to openvpn-examples(5). > > Signed-off-by: Arne Schwabe <arne@rfc2549.org> > --- > Changes.rst | 4 + > doc/Makefile.am | 1 + > doc/man-sections/example-fingerprint.rst | 196 +++++++++++++++++++++++ > doc/openvpn-examples.5.rst | 1 + > 4 files changed, 202 insertions(+) > create mode 100644 doc/man-sections/example-fingerprint.rst This is basically good; I do have some really minor nit-pick. I've tested an OpenVPN server built from git and with both a git master client as well as a v2.5.3 client. Both works with the instructions as given here. And both man and html files are created correctly. One confusing thing is that the server config complains about missing CA if there are no peer-fingerprint entries are present. But that's outside the scope of this documentation. The nit-pick comes below ... > diff --git a/doc/man-sections/example-fingerprint.rst b/doc/man-sections/example-fingerprint.rst > new file mode 100644 > index 000000000..c91ca64b9 > --- /dev/null > +++ b/doc/man-sections/example-fingerprint.rst > @@ -0,0 +1,196 @@ > +Small OpenVPN setup with peer-fingerprint > +========================================= [...snip...] > +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 Elsewhere in our documentation, we've been using 10.8.0.0/24 for the example VPN subnets. > + server-ipv6 fd00:6f76:706e::/64 The other example subnet we've used for IPv6 is fd15:53b6:dead::2/64, but that's related to --block-ipv6. I vaguely remember we used some other IPv6 subnet in examples, but not able to find it now. If this is the standard subnet, feel free to ignore this comment. These nit-picks does not hold back my approval though; they can be changed on-the-fly if so be. Acked-By: David Sommerseth <davids@openvpn.net>
diff --git a/Changes.rst b/Changes.rst index 9185b55f7..5ac24307f 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 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 diff --git a/doc/Makefile.am b/doc/Makefile.am index 1dbbddf58..d86560174 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -25,6 +25,7 @@ dist_noinst_DATA = \ man-sections/client-options.rst \ man-sections/connection-profiles.rst \ man-sections/encryption-options.rst \ + man-sections/example-fingerprint.rst \ man-sections/examples.rst \ man-sections/generic-options.rst \ man-sections/inline-files.rst \ diff --git a/doc/man-sections/example-fingerprint.rst b/doc/man-sections/example-fingerprint.rst new file mode 100644 index 000000000..c91ca64b9 --- /dev/null +++ b/doc/man-sections/example-fingerprint.rst @@ -0,0 +1,196 @@ +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 has the advantage of being easy to setup +and should be suitable for most small lab and home setups without the need for 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 be further modified to customise 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 server.pem -noout + + 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/removing one here restart the + # server + <peer-fingerprint> + </peer-fingerprint> + + # 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 serverkey.pem server.pem /etc/openvpn/server + + 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 + + <key> + -----BEGIN PRIVATE KEY----- + [Insert here the key created in step 2] + -----END PRIVATE KEY----- + </key> + <cert> + -----BEGIN CERTIFICATE----- + [Insert here the certificate created in step 2] + -----END CERTIFICATE----- + </cert> + + # This is 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 alice.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:`<peer-fingerprint>` + and :code:`</peer-fingerprint>` + + After adding *two* clients the part of configuration would look like this: + + :: + + <peer-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 + 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 + </peer-fingperint> + +6. (optional) if the client is an older client that does not support the + :code:`peer-fingerprint` (e.g. OpenVPN 2.5 and older, OpenVPN Connect 3.3 + and older), the client config `alice.ovpn` can be modified to still work with + these clients. + + Remove the line starting with :code:`peer-fingerprint`. Then + add a new :code:`<ca>` 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 + </cert> + + # The tun-mtu of the client should match the server MTU + tun-mtu 1400 + dev tun + + <ca> + [contents of the server.pem] + </ca> + + Note that we put the :code:`<ca>` section after the :code:`<cert>` section + to make the fingerprint generation from step 4 still work since it will + only use the first certificate it find. + +7. Import the file into the OpenVPN client or just use the + :code:`openvpn alice.ovpn` to start the VPN. diff --git a/doc/openvpn-examples.5.rst b/doc/openvpn-examples.5.rst index 988b6027b..0e1b6c4f6 100644 --- a/doc/openvpn-examples.5.rst +++ b/doc/openvpn-examples.5.rst @@ -14,4 +14,5 @@ INTRODUCTION This man page gives a few simple examples to create OpenVPN setups and configuration files. +.. include:: man-sections/example-fingerprint.rst .. include:: man-sections/examples.rst
This is meant to give new users a quickstart for a useable OpenVPN setup. Our own documentation is lacking in this regard and many tutorials that can be found online are often questionable in some aspects. Linking the individaul RST file on github also give a tutorial in a nicely formatted way. Patch V2: Fix grammar/spelling mistakes (thanks ticantech), move to openvpn-examples(5). Signed-off-by: Arne Schwabe <arne@rfc2549.org> --- Changes.rst | 4 + doc/Makefile.am | 1 + doc/man-sections/example-fingerprint.rst | 196 +++++++++++++++++++++++ doc/openvpn-examples.5.rst | 1 + 4 files changed, 202 insertions(+) create mode 100644 doc/man-sections/example-fingerprint.rst