| Message ID | 20210512131511.1309914-10-arne@rfc2549.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Miscellaneous cleanup patches/small fixes | expand |
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi, I was in the process of reviewing this patch when I found that protonmail had changed most of the git '+' to '-', see below. I have reported a bug to protonmail. Anyway, I can see a few typos and some other odd errors. Hopefully, protonmail will have a solution, or maybe someone here knows what I can do/try ? Finally, I wrote a simple script which generates self-signed certs, keys and inlines the fingerprint for use with Openvpn. https://github.com/TinCanTech/easy-pfp I hope it is of some use in the future. Thanks R ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Wednesday, 12 May 2021 14:15, 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 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 arne@rfc2549.org > > 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 > > ======= > > - <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 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 > > > - > - <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 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:`<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` (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:`<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 its find. > > - > > +7. Import the file into the OpenVPN client or just use the > > - :code:`openvpn alice.ovpn` to start the VPN. > -- > 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 wsBzBAEBCAAGBQJgnZQBACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ28dwgAuy7fuhyoasafHKdlfo1PENgbpA8jS+oX0+FAW0CmbZV/4cvn 7hA46fBg2ys7y1xjTLgWGDJXQx6lqSH3RJSuaCMQ4Lfu5uFQK/8FjB9nz1zu Pe4M0mTRbenC1RdHTipH2u6wi4S3L7vV35mcCmhLmXiXNcAstJ/Ta5PfLP5u 55voFJNxicyVgCPHzTgMdY3hZWC5/s3/j5TNiuJOsS1Tge+31+7X6YfyFrJR r2TtTD9TKZ5xuSpDZQl9iQAtzcGiaUYpYgDo/iVlkLEW8F4Uosqe698BmcI4 JuS++8adaxKJvDkbiwnqJDsK06SCHER9TIZLP51VKhRq0noiEg/laA== =G2yu -----END PGP SIGNATURE-----
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi, I used sed to create my own reply .. comments inline. ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Wednesday, 12 May 2021 14:15, 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 often > tutorials that can be found online are often questionable in some > aspects. > > Linking the invidiaul RST file on github also give a tutorial invidiaul -> individual > in a nicely formatted way. > > Signed-off-by: Arne Schwabe <arne@rfc2549.org> > --- > 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 tutorial how -> tutorial on how (just reads better) > + 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. Reword suggestion: 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. Using Peer-fingerprint mode has the advantage of being easy to setup without the need for a PKI. It is suitable for most small lab and home setups. > +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. individualise ? - This word is odd .. how about customise ? > + > +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' Why not using .key and .crt as is the custom when files are created by Easy-RSA ? Also, it is simpler to understand what the file type is .. > + > +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 Why stix-win .. would it not be more suitable to use consistent names of files ? Also, this command is incorrect, the server.pem causes openssl error: x509: Unknown parameter 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 I just want this to be verified because the manual reads that: udp6 will force only udp on IPv6, at least that is how I read it. > + > + # 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 remvoing -> removing > + # 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 I presume you are all sure that this is suitable for consumer grade routers. > + > +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 destination folder should be /etc/openvpn/server and serverkey.pem is missing. > + > + 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----- I presume here that the idea is to not save any client key/cert files and then inline them manually from the output ? It might make sense to add a comment to that effect. > + > +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 the fingerprint of the server that we trust. We generated this fingerprint This *is* the fingerprint of the ... > + # 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 Another new file name ? And this is a server file not a client file .. confusing. > + > + 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` (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 Second 'line' is superfluous. > + 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 its find. its find -> it finds (move the s) > + > +7. Import the file into the OpenVPN client or just use the > + :code:`openvpn alice.ovpn` to start the VPN. > -- > 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 wsBzBAEBCAAGBQJgnZ7BACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ06Qwf+KUQVSE5cElO0CD+IfIWRzSCXEeb6pjUXPi29iHn2ZEhwU60N SrDKGxB7SFEGG6RZsEN39Hky9yArMQneSbktQ8lr5P2+QuBdki3wySWvqabo 6hakuOAXUCeCgj5I2X3BHv9Bz33toXD5JVyVwrrZ+bO5dBNE/Jtzycaa3HCg Hx2wY02RVIG6SHUAOJJv3LuRIt6pXvRO1BHXcrSy93tlBE1CHeZ+XGVjdj5W 0R2VXrRToQQdJ3AjI4YkKgIaze9KSXNgfwE9IBB5gmYf4Nk3Gkej1OKSgVKs vwOZ0jwXIou0JiN8UHmVJEz4s/WfOwH2Zl2Hb6zmZmujOL5W8kI0Kg== =RSkh -----END PGP SIGNATURE-----
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi, missed one.. ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Thursday, 13 May 2021 22:48, tincantech via Openvpn-devel <openvpn-devel@lists.sourceforge.net> wrote: > Hi, > > I used sed to create my own reply .. > > comments inline. > > ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ > On Wednesday, 12 May 2021 14:15, 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 often > > tutorials that can be found online are often questionable in some > > aspects. many often tutorials -> many tutorials (extra 'often') -----BEGIN PGP SIGNATURE----- Version: ProtonMail wsBzBAEBCAAGBQJgnaAYACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ0jjwgAygbBIeAgigR5msWnDad8NZboh62d7CDlMMEJGQBm5AU54R28 IYQInLl4LoRx4oFiMQ6aDUzSbkc3dHwnPIDxhEJkh+Js36GOEOBEaOlnPCSq lZQEX0l3scOuBdgSXpqYQkysOySnyqxbiTPR+dVZ1h5PsFTMsSFSD/w93n5y v+pNi4zXy5fae07dJeQCRCermE+FeRwK8jdGVpUS6awE2q87pcZ7rAF6E13s T7WCEkvZt0baK/gInoa5Yv7EcodtJX02uL+A+zfLltg7rgZgrB+Fv7ld3LHo X1dHTBDBhCrGANJP/rRwL/D+zzrqCAdR+onSqaH6esaa/nfAAi2Asw== =LDsm -----END PGP SIGNATURE-----
On 12/05/2021 15:15, 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 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 <arne@rfc2549.org> > --- > 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 \ I suspect you intended to add doc/man-sections/example-fingerprint.rst instead of adding examples.rst twice. To make this file appear in the openvpn(8) man page, you also need to include it from doc/openvpn.8.rst. Maybe we should also consider moving all these configuration examples out of the main openvpn(8) man page and into a openvpn-examples(7) man page. This can be done after this change, though.
>> +++ 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 \ > > I suspect you intended to add doc/man-sections/example-fingerprint.rst > instead of adding examples.rst twice. > > To make this file appear in the openvpn(8) man page, you also need to > include it from doc/openvpn.8.rst. > > Maybe we should also consider moving all these configuration examples > out of the main openvpn(8) man page and into a openvpn-examples(7) man > page. This can be done after this change, though. > > We can also make that a patch before this patch in the patch set. However, I haven't looked at all the man page generation magic to understand how hard it would be to create an extra man page. Arne
On 14/05/2021 15:57, Arne Schwabe wrote: > >>> +++ 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 \ >> >> I suspect you intended to add doc/man-sections/example-fingerprint.rst >> instead of adding examples.rst twice. >> >> To make this file appear in the openvpn(8) man page, you also need to >> include it from doc/openvpn.8.rst. >> >> Maybe we should also consider moving all these configuration examples >> out of the main openvpn(8) man page and into a openvpn-examples(7) man >> page. This can be done after this change, though. >> >> > > We can also make that a patch before this patch in the patch set. > However, I haven't looked at all the man page generation magic to > understand how hard it would be to create an extra man page. Most of the magic happens in openvpn.8.rst. We facilitate the ..include:: statement to "glue" together the main man page from all the files in man-sections/. And this is all parsed and handled by rst2man and rst2html. The Makefile.am ensures the openvpn.8 and openvpn.8.html are properly built when it should. We're doing a little trick with a dist-hook, so these files are prebuilt and packaged when running 'make dist' and 'make distcheck', which ensures prebuilt man page files (groff and html) are packaged into the source tarball. And these files are normally not rebuilt unless missing. In Makefile.am it could be created some more generic %.8 and %.8.html rules, also for the man 7 page section. And then the main framework should be in in place. A nice touch could be though to extract the ..include:: statements from the .rst files we're building to generate the file list for dist_noinst_DATA automatically, as I consider this the most fragile aspect. It could probably also be done the other way too (Makefile.am generating an .rst include file before the main rst2{html,man} run), but I consider this less preferred as then the order of section is defined inside Makefile.am and not a document file itself.
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi, ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Wednesday, 12 May 2021 14:15, 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 often > tutorials that can be found online are often questionable in some > aspects. > I believe Openvpn in standard mode (Full PKI) would reject an expired client certificate. Note: There is absolutely nothing in the manual to confirm this ! https://build.openvpn.net/man/openvpn-2.5/openvpn.8.html On that page there are eight uses of the word 'expire' and they all relate to an expired auth-token, this could also probably be improved. However, Openvpn in peer-fingerprint mode allows an expired client certificate to connect. The client log *does* have a 'WARNING: Your certificate has expired!' The server log has nothing about an expired client certificate. And, as we all know, _who reads their log files_ anyway ? The issue here is that the server allows an expired client certificate to connect and there is no mention of this change in behaviour. Thanks R -----BEGIN PGP SIGNATURE----- Version: ProtonMail wsBzBAEBCAAGBQJgoqTPACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ18DQgAiFbKtIV3YXi4YG3qiN429AsLyGd8FR+ysy09aNB/FM9p/70E FgobM0x2waAWILLaNOgG/u3B8ocHa6ld0s2h0fJ7ef7FAdo4SRYbosyQFq+Q gcv5Z8AzivkOVbK2d9kP9T9HWd4BVOtduHKg/u/pwwQD7GUB4mM9HrztTzy8 X+oG6197ZZnA9jLUE+wxShttgXf1PP9q39r7gJ798kt1P0zDrtN4gjSTLp5v JwdyxMLHnD5YdwqsW31Zu3AnYP+s12xXfq8dZtAP0JaY/qYt/FqU6t+3hNOB PLtXCdmr53wPdrkyUOHnzLcOoF2S3M9pDLZW1/JSowginVfUpRpUWQ== =kmta -----END PGP SIGNATURE-----
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi, ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Monday, 17 May 2021 18:16, tincantech via Openvpn-devel <openvpn-devel@lists.sourceforge.net> wrote: > Hi, > > ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ > On Wednesday, 12 May 2021 14:15, 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 often > > tutorials that can be found online are often questionable in some > > aspects. I think it is also worth noting that, in it's current form, the documentation given does not provide for a --remote-cert-tls solution. I may be able to help with that but prefer to log it here first. Thanks R -----BEGIN PGP SIGNATURE----- Version: ProtonMail wsBzBAEBCAAGBQJgor7wACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ3g5wf9EXijgq5+j38umqKpdwIeQQ1F78OeEPMi8/LAxyrGZlSJNvr+ 9OIDwj9ZBE1SOY80f2AGR5tXE7Czl1VT0S+CPcrVnaKadR5dfNB3HpVShOWY sFPvmjzY++U0Jmw6/vsV09SCigBv85DU2s+VYmwoBwgq08vc28WvKXPY6DJl PxmePhpVbsV/5uZAw+3MismpvPvw7hzDmEEKtZLeqduLFGx9l0D7Apeq+d1Q 4348BdmeZFaIjk6sKBW45akIjxeLN3wejfp0hUFBYrITVs8ssQUbQUc9uDDu CdUxMwoeu5ZhVT7TN5Rh2iSjkFQjjsewTimGLuNr4dT+dUH3ypJvsQ== =ql9l -----END PGP SIGNATURE-----
Am 17.05.21 um 19:16 schrieb tincantech: > Hi, > > ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ > On Wednesday, 12 May 2021 14:15, 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 often >> tutorials that can be found online are often questionable in some >> aspects. > > > I believe Openvpn in standard mode (Full PKI) would reject an expired > client certificate. > > Note: There is absolutely nothing in the manual to confirm this ! > https://build.openvpn.net/man/openvpn-2.5/openvpn.8.html > On that page there are eight uses of the word 'expire' and they all > relate to an expired auth-token, this could also probably be improved. > > However, Openvpn in peer-fingerprint mode allows an expired client > certificate to connect. > > The client log *does* have a 'WARNING: Your certificate has expired!' > The server log has nothing about an expired client certificate. > And, as we all know, _who reads their log files_ anyway ? > > The issue here is that the server allows an expired client certificate > to connect and there is no mention of this change in behaviour. Yes. We just trust the fingerprint of the certificate. The behaviour to ignore expiry is a side effect of that. It is kinda designed to be this way. Arne
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi, ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Tuesday, 18 May 2021 13:21, Arne Schwabe <arne@rfc2549.org> wrote: > Am 17.05.21 um 19:16 schrieb tincantech: > > > Hi, > > ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ > > On Wednesday, 12 May 2021 14:15, 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 often > > > tutorials that can be found online are often questionable in some > > > aspects. > > > > I believe Openvpn in standard mode (Full PKI) would reject an expired > > client certificate. > > Note: There is absolutely nothing in the manual to confirm this ! > > https://build.openvpn.net/man/openvpn-2.5/openvpn.8.html > > On that page there are eight uses of the word 'expire' and they all > > relate to an expired auth-token, this could also probably be improved. > > However, Openvpn in peer-fingerprint mode allows an expired client > > certificate to connect. > > The client log does have a 'WARNING: Your certificate has expired!' > > The server log has nothing about an expired client certificate. > > And, as we all know, who reads their log files anyway ? > > The issue here is that the server allows an expired client certificate > > to connect and there is no mention of this change in behaviour. > > Yes. We just trust the fingerprint of the certificate. The behaviour to > ignore expiry is a side effect of that. It is kinda designed to be this way. > > Arne The change itself is ok, I just thought it worth mentioning is this guide. Thanks R -----BEGIN PGP SIGNATURE----- Version: ProtonMail wsBzBAEBCAAGBQJgo76EACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ1pAAf+M7BWGoMLjSdhrcfokV0mu9M8eND0XF7AvEI3d+DQEGqJ2S9I l6aVCCXsIKi1m/fJbYSYROhD7zvKj3i1KQebXxUTTonmlhEIMLhXnzHmdAPH Owh3Ixpf284NMTcjZgcQAhGcLdlMeVpykJrIIx4lpR75u0+FV6STUmtIgG2Q gWOi4OduA5gNJanu4BlF/7JCHNXSQvHQ5yrSGBrRdT2kIIGnrHSYfmUz1Jq4 v0AHQP8aTFD6sUaYw2j0nRGKj43rAmV+yyx2oLU1/6jbiBl5wq25fgNi3cCa 22HuxRP1SsbSf5PoWbUyZmXagpnHKRmgj42DkMn3pMTLjGnDD6NmVA== =Fotu -----END PGP SIGNATURE-----
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi, ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Monday, 17 May 2021 20:07, tincantech <tincantech@protonmail.com> wrote: > Hi, > > ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ > On Monday, 17 May 2021 18:16, tincantech via Openvpn-devel openvpn-devel@lists.sourceforge.net wrote: > > > Hi, > > ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ > > On Wednesday, 12 May 2021 14:15, 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 often > > > tutorials that can be found online are often questionable in some > > > aspects. > > I think it is also worth noting that, in it's current form, the > documentation given does not provide for a --remote-cert-tls solution. > > I may be able to help with that but prefer to log it here first. > If/how you choose to document this here, I leave that to you. I have expanded easypfp to create either Server or Client certificates by adding X509v3 Extended Key Usage: TLS Web Client Authentication and TLS Web Server Authentication as optional extras. All tests passed. https://github.com/TinCanTech/easy-pfp Thanks R -----BEGIN PGP SIGNATURE----- Version: ProtonMail wsBzBAEBCAAGBQJgpAgIACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ2goggAsxXM0nhW/aKCPi5ZiAgn4ZwSXwDuCQRU/G5Ff57RKfdiPjim ZWyWtttrUBlyBNRKUzKVoMbiAdXuf8WIUIgx11SqG0ZrJEbzvyhN6rcsCX33 6c6C2EPFriFwtMDjyiBiS4OtxKVs/L/GpbjfbxU6oPvQfQLVs/licvPOOHGs xAFXMOF8COPvcANstUUFzr9BTq7kc6KUzaI01zrBkDAh7zRapHupo6wiPrjB xRuhWnwV8dGxaeDNoxB7VXAqbWaPQFCsxc+gt9wPlFcG28Y0Ct1ME1MIIKKc +w6+wzEgGq01OTKFIzKJ6CVjIVUTziHZ65nsmHd/JqXOWZ146ZXJ5w== =+xAi -----END PGP SIGNATURE-----
> I just want this to be verified because the manual reads that: > udp6 will force only udp on IPv6, at least that is how I read it. Not on the server side. It is one of the quirks that we need to fix at some point. See the ipv6only option of --bind for more details > >> + >> + # 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 > > remvoing -> removing > > >> + # 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 > > I presume you are all sure that this is suitable for consumer grade routers. I think 60 300 is a good starting point but we might later modify it if this becomes a problem. Thanks for spell/grammar checking it! Arne
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi, ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Thursday, 20 May 2021 00:36, Arne Schwabe <arne@rfc2549.org> wrote: > > I just want this to be verified because the manual reads that: > > udp6 will force only udp on IPv6, at least that is how I read it. > > Not on the server side. It is one of the quirks that we need to fix at > some point. See the ipv6only option of --bind for more details I actually checked this and believe it is a reasoanble decision. It works for me and I was not expecting it to do so. > > > > - > > > - 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 > > > > > > ============================================================================= > > > > > > > remvoing -> removing > > > > > - 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 > > > > I presume you are all sure that this is suitable for consumer grade routers. > > I think 60 300 is a good starting point but we might later modify it if > this becomes a problem. OK. It is a big difference from the standard setting so I just wanted to call it here. > > Thanks for spell/grammar checking it! > > Arne No problem. Thanks for everything you've done too. Richard -----BEGIN PGP SIGNATURE----- Version: ProtonMail wsBzBAEBCAAGBQJgpaUbACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ1iEQf9HSb9ReZSAve3LfzgDNo4hb0c1mGNWSNcIQudw8fdaYc8TfjU UD1MLdTM9CM5uuHEz3O29nyBPEjCUJS16bQ45lVtHzAbGcdzUEF9cn/gUsST 7v/3aMeFM76YSDXnI3DrA6PtlqXoWJ7K+NC3tzXb7suF3Zy0Gi8AWgJhKD8q tXvHtXdGD9ohsZTF4yio8PWCW4n0UFPUTImndr/R8D6TRO5umhBDkmQ9fWx0 3gPN6ln9FF2bE/gqG7Sj1s6uu5OLNqJ+aswet2B22DI/7CHlgQzFC38nuy5f CKFJ0eZnrQ8baDDOpOHlmLTarisRLcOP7rxT1qz5S6PWdGTP4+s/rg== =VNul -----END PGP SIGNATURE-----
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi, just FYI I was also going to question the --tun-mtu 1400 setting but decided that was above my pay-grade. I think it is probably a good long-term decision that will probably invade some of those less respectable blogs and be a good thing over-all. I know, it is complicated ! Cheers R -----BEGIN PGP SIGNATURE----- Version: ProtonMail wsBzBAEBCAAGBQJgpamaACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ3PVQgAju8gPugglio2RQ1Qr/fcXFyq7tAQEy/njizNTIDBEAE3E1tr J0gOsMMe1fQTDjen5DCtJEyq7pwIgMVKWw/kVP7DzOlTzC+oUb4avysoi3Ld pUFDmJdD2eP1Ls+Ylc9O2HDlK1q8n46mUjX5Fuv1+0UN/HFUb1d7z9IgRHTf 0h+6f7dkn4z0QgFjY97esSKDu9x3ZZhhIfUPwPOUF4mLEQv+6PczpzAvm7eS oZRr/GNjSBq1dBzzWNi80v9cv31Uxz7VTuy3ntKp5k0n80W0b93tbG0xVcu7 qi1ZCQh5VgFdh/35+7uwsJkpA9Eoc+ijFqV1+gz1+FekdRAmO1iCpA== =rh5B -----END PGP SIGNATURE-----
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 Hi, missed another one .. ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐ On Thursday, 20 May 2021 01:13, tincantech <tincantech@protonmail.com> wrote: > Hi, > > just FYI > > I was also going to question the --tun-mtu 1400 setting but decided > that was above my pay-grade. I think it is probably a good long-term > decision that will probably invade some of those less respectable blogs > and be a good thing over-all. I know, it is complicated ! > How would that effect the default --mssfix ? Swings and roundabouts R -----BEGIN PGP SIGNATURE----- Version: ProtonMail wsBzBAEBCAAGBQJgpa+8ACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ1f9Af/ZxK/IusDe82uZsnlZXlRAJElzyamWPA+Splu+nOoUVQhSjah eyc6YqM4+FNNP6dyZxVELT0RKC5p8c7KUEqFzay+2nflnwALDu9m5ak4WVyb EFmXPFctfu1myCdqZ70705DhfORainxI7tLrbzTwLMeZMH1xPJ9IszBE5wqb nUcBO1B3g+E01b/cF9GL6wHF32kW9BH5uc+0A1mb4/3+iO83VP3nUnKBm+sj pZUR4G3VpgLzyc1ymIkxQIxsas1f6M3r8qvBI+ol1F1YkZJXy76Piuh7I5rF 0fYcm0jtxKmf/ETHPIQFL6J3N2zrar8+kazS0GRW9hPLPfqODXqqDQ== =I3MI -----END PGP SIGNATURE-----
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 + <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 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 + + <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 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:`<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` (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:`<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 its find. + +7. Import the file into the OpenVPN client or just use the + :code:`openvpn alice.ovpn` to start the VPN.
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 <arne@rfc2549.org> --- 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