Skip to contentSkip to conversation

Move examples into openvpn-examples(5) man page

PATCH In review Arne Schwabe 6 participants 20 messages May 20, 2021 – Aug 1, 2021

lore
Share & tools
lore
#0 lore raw

PATCH v2 1/2 Move examples into openvpn-examples(5) man page

---
 .gitignore                 |  2 ++
 doc/Makefile.am            | 25 +++++++++++++++++++++----
 doc/openvpn-examples.5.rst | 17 +++++++++++++++++
 doc/openvpn.8.rst          |  2 +-
 4 files changed, 41 insertions(+), 5 deletions(-)
 create mode 100644 doc/openvpn-examples.5.rst
.gitignore +2 -0
index 25d06235b..178076ede 100644
@@ -49,6 +49,8 @@ version.sh
 msvc-env-local.bat
 config-msvc-local.h
 config-msvc-version.h
+doc/openvpn-examples.5
+doc/openvpn-examples.5.html
 doc/openvpn.8
 doc/openvpn.8.html
 /doc/doxygen/html/
doc/Makefile.am +21 -4
index e411f5f9d..1dbbddf58 100644
@@ -20,6 +20,7 @@ dist_doc_DATA = \
 dist_noinst_DATA = \
 	README.plugins interactive-service-notes.rst \
 	openvpn.8.rst \
+    openvpn-examples.5.rst \
 	man-sections/advanced-options.rst \
 	man-sections/client-options.rst \
 	man-sections/connection-profiles.rst \
@@ -52,6 +53,14 @@ else
 	@echo "Missing python-docutils - skipping man page generation"
 endif
 
+openvpn-examples.5 :
+if HAVE_PYDOCUTILS
+	$(RST2MAN) $(srcdir)/[email protected] > $@
+else
+	@echo "Missing python-docutils - skipping man page generation"
+endif
+
+
 openvpn.8.html:
 if HAVE_PYDOCUTILS
 	$(RST2HTML) $(srcdir)/openvpn.8.rst > $@
@@ -59,13 +68,21 @@ else
 	@echo "Missing python-docutils - skipping man/html page generation"
 endif
 
+openvpn-examples.5.html:
+if HAVE_PYDOCUTILS
+	$(RST2HTML) $(srcdir)/openvpn-examples.5.rst > $@
+else
+	@echo "Missing python-docutils - skipping man/html page generation"
+endif
+
+
 if HAVE_PYDOCUTILS
-dist_noinst_DATA += openvpn.8
-dist_html_DATA = openvpn.8.html
+dist_noinst_DATA += openvpn.8 openvpn-examples.5
+dist_html_DATA = openvpn.8.html openvpn-examples.5.html
 
 # Failsafe - do not delete these files unless we can recreate them
 CLEANFILES = \
-	 openvpn.8 openvpn.8.html
+	 openvpn.8 openvpn.8.html openvpn-examples.5 openvpn-examples.5.html
 
 endif
 
@@ -74,4 +91,4 @@ else
 dist_man_MANS = openvpn.8
 endif
 
-dist-hook : openvpn.8 openvpn.8.html
+dist-hook : openvpn.8 openvpn.8.html openvpn-examples.5 openvpn-examples.5.html
doc/openvpn-examples.5.rst new file +17 -0
new file mode 100644
index 000000000..988b6027b
@@ -0,0 +1,17 @@
+===============================
+ openvpn examples
+===============================
+-------------------------
+ Secure IP tunnel daemon
+-------------------------
+
+:Manual section: 5
+:Manual group: Configuration files
+
+
+INTRODUCTION
+============
+
+This man page gives a few simple examples to create OpenVPN setups and configuration files.
+
+.. include:: man-sections/examples.rst
doc/openvpn.8.rst +1 -1
index db81274fa..995467478 100644
@@ -86,7 +86,6 @@ placed in a configuration file.
 .. include:: man-sections/connection-profiles.rst
 .. include:: man-sections/inline-files.rst
 .. include:: man-sections/signals.rst
-.. include:: man-sections/examples.rst
 
 
 FAQ
@@ -134,6 +133,7 @@ Report all bugs to the OpenVPN team [email protected]...
 SEE ALSO
 ========
 
+``openvpn-examples``\(5),
 ``dhcpcd``\(8),
 ``ifconfig``\(8),
 ``openssl``\(1),
Signature · 1 line
2.31.1
#1 lore raw

PATCH v2 2/2 Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

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).

---
 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
Changes.rst +4 -0
index 9185b55f7..5ac24307f 100644
@@ -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
doc/Makefile.am +1 -0
index 1dbbddf58..d86560174 100644
@@ -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 \
doc/man-sections/example-fingerprint.rst new file +196 -0

196 lines not on this page · raw message

doc/openvpn-examples.5.rst +1 -0
index 988b6027b..0e1b6c4f6 100644
@@ -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
Signature · 1 line
2.31.1
#2 lore raw

Re: [Openvpn-devel] [PATCH v2 2/2] Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

-----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 ‐‐‐‐‐‐‐

Quoted 7 lines · Arne Schwabe

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)

Quoted 127 lines

Patch V2: Fix grammar/spelling mistakes (thanks ticantech), move
to openvpn-examples(5).

---
 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
Changes.rst +4 -0
index 9185b55f7..5ac24307f 100644
@@ -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
doc/Makefile.am +1 -0
index 1dbbddf58..d86560174 100644
@@ -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 \
doc/man-sections/example-fingerprint.rst new file +81 -0
new file mode 100644
index 000000000..c91ca64b9
@@ -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 [email protected]...
+
+Adding a client
+---------------

doc/man-sections/example-fingerprint.rst line 91

Quoted 10 lines
doc/man-sections/example-fingerprint.rst new file +10 -0
+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.

Quoted 33 lines
doc/man-sections/example-fingerprint.rst new file +33 -0
+   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]

doc/man-sections/example-fingerprint.rst line 134

Quoted 10 lines
doc/man-sections/example-fingerprint.rst new file +10 -0
+      -----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.

Quoted 27 lines
doc/man-sections/example-fingerprint.rst new file +27 -0
+      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:
+
+   ::

doc/man-sections/example-fingerprint.rst line 171

Quoted 10 lines
doc/man-sections/example-fingerprint.rst new file +10 -0
+
+      <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*

Quoted 12 lines
doc/man-sections/example-fingerprint.rst new file +12 -0
+
+   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

doc/man-sections/example-fingerprint.rst line 193

Quoted 10 lines
doc/man-sections/example-fingerprint.rst new file +10 -0
+      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

Quoted 18 lines
doc/man-sections/example-fingerprint.rst new file +3 -0
+
+7. Import the file into the OpenVPN client or just use the
+   :code:`openvpn alice.ovpn` to start the VPN.
doc/openvpn-examples.5.rst +1 -1
index 988b6027b..0e1b6c4f6 100644
@@ -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

Quoted 4 lines

_______________________________________________
Openvpn-devel mailing list
[email protected]
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-----

#3 lore raw

Re: [Openvpn-devel] [PATCH v2 2/2] Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

Hi,

Quoted 2 lines · tincantech via Openvpn-devel

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

Signature · 6 lines
"If was one thing all people took for granted, was conviction that if you 
 feed honest figures into a computer, honest figures come out. Never doubted 
 it myself till I met a computer with a sense of humor."
                             Robert A. Heinlein, The Moon is a Harsh Mistress

Gert Doering - Munich, Germany                             [email protected]...
#4 lore raw

Re: [Openvpn-devel] [PATCH v2 2/2] Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

In reply to tincantech

Am 20.05.2021 um 18:56 schrieb tincantech:

Quoted 7 lines

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

#5 lore raw

Re: [Openvpn-devel] [PATCH v2 2/2] Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Hi,

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

Quoted 9 lines · Arne Schwabe

Am 20.05.2021 um 18:56 schrieb tincantech:

Quoted 6 lines

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.

Quoted 4 lines

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-----

#6 lore raw

Re: [Openvpn-devel] [PATCH v2 2/2] Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

Hi,

Quoted 21 lines · tincantech via Openvpn-devel

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Hi,

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

Quoted 12 lines · Arne Schwabe

Am 20.05.2021 um 18:56 schrieb tincantech:

Quoted 6 lines

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.

Quoted 7 lines
Quoted 1 line

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

#7 lore raw

Re: [Openvpn-devel] [PATCH v2 2/2] Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

In reply to tincantech

Hi,

Quoted 10 lines · tincantech via Openvpn-devel
Quoted 10 lines
Quoted 7 lines

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.

Quoted 7 lines
Quoted 1 line

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

#8 lore raw

Re: [Openvpn-devel] [PATCH v2 2/2] Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Sent with ProtonMail Secure Email.

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

Quoted 29 lines · Jan Just Keijser

Hi,

Quoted 9 lines · tincantech via Openvpn-devel
Quoted 9 lines
Quoted 8 lines

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.

Quoted 5 lines
Quoted 2 lines

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:

(quoted diff) +0 -3
-   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

Review

Quoted 10 lines
(quoted diff) +0 -0
    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.

Quoted 5 lines

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-----

#9 lore raw

Re: [Openvpn-devel] [PATCH v2 2/2] Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

Quoted 16 lines · tincantech

[...]

Quoted 15 lines
Quoted 2 lines

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:

(quoted diff) +0 -3
-   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.
Quoted 9 lines
Quoted 7 lines

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

#13 lore raw

Re: [Openvpn-devel] [PATCH v2 2/2] Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

In reply to Jan Just Keijser
Quoted 11 lines

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

#10 lore raw

Re: [Openvpn-devel] [PATCH v2 2/2] Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

In reply to Jan Just Keijser

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Hi,

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

Quoted 26 lines · Jan Just Keijser
Quoted 23 lines · tincantech

[...]

Quoted 21 lines
Quoted 3 lines

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:

(quoted diff) +0 -3
-   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.
Quoted 3 lines
Quoted 1 line

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.

Quoted 4 lines

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.

Quoted 2 lines

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-----

#11 lore raw

Re: [Openvpn-devel] [PATCH v2 2/2] Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Hi,

-‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

Quoted 53 lines · tincantech via Openvpn-devel

Hi,

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

Quoted 27 lines · On Thursday, 20 May 2021 22:22, Jan Just Keijser [email protected]... wrote:
Quoted 24 lines · tincantech

[...]

Quoted 22 lines
Quoted 3 lines

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:

(quoted diff) +0 -3
-   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.
Quoted 4 lines
Quoted 2 lines

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.

Quoted 3 lines

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.

Quoted 2 lines

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!"

Quoted 6 lines

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-----

#12 lore raw

Re: [Openvpn-devel] [PATCH v2 2/2] Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Hi,

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

Quoted 8 lines · tincantech

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-----

Acked-by on v2 1/2
#18 lore raw
In reply to Arne Schwabe
Quoted 27 lines · Arne Schwabe
---
  .gitignore                 |  2 ++
  doc/Makefile.am            | 25 +++++++++++++++++++++----
  doc/openvpn-examples.5.rst | 17 +++++++++++++++++
  doc/openvpn.8.rst          |  2 +-
  4 files changed, 41 insertions(+), 5 deletions(-)

create mode 100644 doc/openvpn-examples.5.rst

.gitignore +2 -0
index 25d06235b..178076ede 100644
@@ -49,6 +49,8 @@ version.sh
  msvc-env-local.bat
  config-msvc-local.h
  config-msvc-version.h
+doc/openvpn-examples.5
+doc/openvpn-examples.5.html
  doc/openvpn.8
  doc/openvpn.8.html
  /doc/doxygen/html/
doc/Makefile.am +0 -0
index e411f5f9d..1dbbddf58 100644

doc/Makefile.am dist_doc_DATA = \ · line 23

Quoted 4 lines
doc/Makefile.am +1 -0
@@ -20,6 +20,7 @@ dist_doc_DATA = \
  dist_noinst_DATA = \
  	README.plugins interactive-service-notes.rst \
  	openvpn.8.rst \
+    openvpn-examples.5.rst \

TAB vs spaces. Makefile.am uses TABs. This might not be a real issue anymore, but there are some older Make versions which will choke on spaces.

This can be fixed during commit.

[...snip...]

Quoted 14 lines
doc/Makefile.am +2 -2
  if HAVE_PYDOCUTILS
-dist_noinst_DATA += openvpn.8
-dist_html_DATA = openvpn.8.html
+dist_noinst_DATA += openvpn.8 openvpn-examples.5
+dist_html_DATA = openvpn.8.html openvpn-examples.5.html
  
  # Failsafe - do not delete these files unless we can recreate them
  CLEANFILES = \
doc/Makefile.am +1 -1
-	 openvpn.8 openvpn.8.html
+	 openvpn.8 openvpn.8.html openvpn-examples.5 openvpn-examples.5.html
 
  endif

doc/Makefile.am else · line 91

Quoted 1 line
doc/Makefile.am +0 -0
@@ -74,4 +91,4 @@ else
  dist_man_MANS = openvpn.8

You missed openvpn-examples.5 here. But I do have a patch ready which avoids lots of the rule duplications. Gert got a copy of a preliminary patch to test on some BSD hosts. So we can ignore this for now.

Except of these two really minor things, this is good to go.

Signature · 4 lines
kind regards,

David Sommerseth
OpenVPN Inc
Acked-by on v2 2/2
#14 lore raw

Re: [Openvpn-devel] [PATCH v2 2/2] Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

In reply to Arne Schwabe
Quoted 11 lines · Arne Schwabe

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).

Quoted 8 lines
---
  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 ...

Quoted 8 lines
doc/man-sections/example-fingerprint.rst new file +2 -0
new file mode 100644
index 000000000..c91ca64b9
@@ -0,0 +1,196 @@
+Small OpenVPN setup with peer-fingerprint
+=========================================

[...snip...]

Quoted 5 lines

+3. Write a server configuration (server.conf):
+::

doc/man-sections/example-fingerprint.rst new file +3 -0
+
+    # The server certificate we created in step 1
+    cert server.pem

doc/man-sections/example-fingerprint.rst line 51

Quoted 10 lines
doc/man-sections/example-fingerprint.rst new file +10 -0
+    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.

Quoted 1 line

+ 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.

Signature · 4 lines
kind regards,

David Sommerseth
OpenVPN Inc
#19 lore raw
In reply to Arne Schwabe

I have adjusted the tab, and added openvpn-examples.5 to dist_man_MANS, as instructed.

I have run "make distcheck" on a machine with and without py-docutils (with docutils, it creates the openvpn-examples.5 page and packs it, without, it fails - at it must be) and verified that the generated .5/.5.html files make it to the tarball.

Since *this* patch is only about splitting the man pages (and does not concern itself with actual content which might depend on "is only in master") it makes sense to have it in 2.5 as well -> done.

Your patch has been applied to the master branch.

commit 0c5380e906116b61ce9ed5310181291941b75227 (master) commit 11fe49e31afd9b05da751d60680e8d2254fd9cd6 (release/2.5)

Author: Arne Schwabe
Date:   Thu May 20 17:09:31 2021 +0200
     Move examples into openvpn-examples(5) man page

     Signed-off-by: Arne Schwabe <[email protected]...>
     Acked-by: David Sommerseth <[email protected]...>
     Message-Id: <[email protected]...>
     URL: https://www.mail-archive.com/[email protected]/msg22414.html
     Signed-off-by: Gert Doering <[email protected]...>

--
kind regards,

Gert Doering

#15 lore raw

PATCH v3 1/1 Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

In reply to Arne Schwabe

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).

Patch v3: use server.key and server.crt instead of server.pem/serverkey.pem

---
 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
Changes.rst +4 -0
index 9185b55f7..5ac24307f 100644
@@ -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
doc/Makefile.am +1 -0
index 1e4fcdea3..1a67f7b52 100644
@@ -31,6 +31,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 \
doc/man-sections/example-fingerprint.rst new file +196 -0

196 lines not on this page · raw message

doc/openvpn-examples.5.rst +1 -0
index 988b6027b..0e1b6c4f6 100644
@@ -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
Signature · 1 line
2.32.0
#16 lore raw

Re: [Openvpn-devel] [PATCH v3] Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Hi,

six minor improvements, could probably be made on commit.

One comment: This tutorial will not work on Windows because it relies on a bashism to generate the self-signed certs. There is no mention of that anywhere, may be it could be pointed out somewhere ?

Other than that, excellent work!

And for the record: Easy-TLS can create these cert/keys and share fingerprints to relevant inline files with relative ease.
https://github.com/TinCanTech/easy-tls

Sent with ProtonMail Secure (but still git unfriendly) Email.

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

Quoted 1 line · Arne Schwabe

This is meant to give new users a quickstart for a useable OpenVPN

quickstart -> quick start

Quoted 5 lines

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

individual (au->ua)

Quoted 3 lines

in a nicely formatted way.

Patch V2: Fix grammar/spelling mistakes (thanks ticantech), move

tincantech

Quoted 63 lines

to openvpn-examples(5).

Patch v3: use server.key and server.crt instead of server.pem/serverkey.pe= m

---
 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
Changes.rst +2 -0
index 9185b55f7..5ac24307f 100644
@@ -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 onl=

ine
+ 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`` op=

tion
become optional. This allows for small OpenVPN setups without setting=
up

doc/Makefile.am +1 -0
index 1e4fcdea3..1a67f7b52 100644
@@ -31,6 +31,7 @@ dist_noinst_DATA =3D \
 	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 \
doc/man-sections/e= renamed from doc/man-sections/example-fingerprint.rst +0 -0

xample-fingerprint.rst
new file mode 100644
index 000000000..ba948dd07

doc/man-sections/example-fingerprint.rst new file +2 -0
@@ -0,0 +1,196 @@
+Small OpenVPN setup with peer-fingerprint
+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=

=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
+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 nee= d for a PKI.
+For bigger scale setup setting up a PKI (e.g. via easy-rsa) is still reco= mmended.

doc/man-sections/example-fingerprint.rst

Quoted 2 lines
doc/man-sections/example-fingerprint.rst new file +2 -0
+
+Both server and client configuration can of be further modified to custom=

"can of be" -> can be

Also, it could simply read: "can be further customised."

Quoted 10 lines

ise the

doc/man-sections/example-fingerprint.rst new file +7 -0
+setup.
+
+Server setup
+------------
+1. Install openvpn
+
+   Compile from source-code (see `INSTALL` file) or install via a distrib=

ution (apt/yum/ports)
+ or via installer (Windows).

The following method does not work in Windows.

Quoted 104 lines
doc/man-sections/example-fingerprint.rst new file +5 -0
+
+2. Generate a self-signed certificate for the server:
+   ::
+
+    openssl req -x509 -newkey ec:<(openssl ecparam -name secp384r1) -keyo=

ut server.key -out server.crt -nodes -sha256 -days 3650 -subj '/CN=3Dserve= r'

doc/man-sections/example-fingerprint.rst new file +13 -0
+
+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.crt -noout
+
+   This output something similar to:
+   ::
+
+     SHA256 Fingerprint=3D00: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

doc/man-sections/example-fingerprint.rst new file +20 -0
+
+
+3. Write a server configuration (`server.conf`):
+::
+
+    # The server certificate we created in step 1
+    cert server.crt
+    key server.key
+
+    dh none
+    dev tun
+
+    # Listen on IPv6+IPv4 simultaneously
+    proto udp6
+
+    # The ip address the server will distribute
+    server 10.8.0.0 255.255.255.0
+    server-ipv6 fd00:6f76:706e::/64
+
+    # A tun-mtu of 1400 avoids problems of too big packets after VPN enca=

psulation

doc/man-sections/example-fingerprint.rst new file +3 -0
+    tun-mtu 1400
+
+    # The fingerprints of your clients. After adding/removing one here re=

start the

doc/man-sections/example-fingerprint.rst new file +15 -0
+    # 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.crt`, `server.key` and
+      `server.conf` to :code:`/etc/openvpn/server` and start it via syste=

mctl

doc/man-sections/example-fingerprint.rst new file +13 -0
+
+      ::
+
+          sudo mv server.conf server.key server.crt /etc/openvpn/server
+
+          sudo systemctl start [email protected]...
+
+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 wi=

th a

doc/man-sections/example-fingerprint.rst new file +4 -0
+   different name for each client.
+   ::
+
+      openssl req -x509 -newkey ec:<(openssl ecparam -name secp384r1) -no=

des -sha256 -days 3650 -subj '/CN=3Dalice'

doc/man-sections/example-fingerprint.rst new file +2 -0
+
+   This generate a certificate and a key for the client. The output of th=

e command will look

doc/man-sections/example-fingerprint.rst new file +13 -0
+   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 t=

he file

doc/man-sections/example-fingerprint.rst new file +5 -0
+   `alice.ovpn`:
+
+   ::
+
+      # The name of your server to connect to

doc/man-sections/example-fingerprint.rst line 119

Quoted 10 lines
doc/man-sections/example-fingerprint.rst new file +10 -0
+      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

a a !

Quoted 82 lines
doc/man-sections/example-fingerprint.rst new file +16 -0
+      # 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

doc/man-sections/example-fingerprint.rst new file +8 -0
+
+      # 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 wil=

l
+ ignore anything that is not between the begin and end markers of the c=
ertificate:

doc/man-sections/example-fingerprint.rst new file +9 -0
+
+   ::
+
+      openssl x509 -fingerprint -sha256 -noout -in alice.ovpn
+
+   This will again output something like
+   ::
+
+        SHA256 Fingerprint=3Dff: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

doc/man-sections/example-fingerprint.rst new file +6 -0
+
+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 t=

his:

doc/man-sections/example-fingerprint.rst new file +5 -0
+
+   ::
+
+      <peer-fingerprint>
+      ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00:ff:ee:dd:cc:bb:aa:9=

9: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:3=
3:22:11:00:88:77:66:55:44:33

doc/man-sections/example-fingerprint.rst new file +4 -0
+      </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 wo=
rk with

doc/man-sections/example-fingerprint.rst new file +21 -0
+   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.crt` 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.crt]
+      </ca>
+
+   Note that we put the :code:`<ca>` section after the :code:`<cert>` sec=
Quoted 4 lines

tion
+ to make the fingerprint generation from step 4 still work since it wil=
l
+ only use the first certificate it find.

'it find' -> found

Quoted 12 lines
doc/man-sections/example-fingerprint.rst new file +3 -0
+
+7. Import the file into the OpenVPN client or just use the
+   :code:`openvpn alice.ovpn` to start the VPN.
doc/openvpn-examples.5.rst +0 -0
index 988b6027b..0e1b6c4f6 100644
@@ -14,4 +14,5 @@ INTRODUCTION
 
 This man page gives a few simple examples to create OpenVPN setups and co=

nfiguration files.

Quoted 5 lines

+.. include:: man-sections/example-fingerprint.rst
.. include:: man-sections/examples.rst
--
2.32.0

-----BEGIN PGP SIGNATURE-----
Version: ProtonMail

wsBzBAEBCAAGBQJhAbdiACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec 9muQuJ3NdQgAscHRyr3wCUuRtnIdbMBWjAfbvfP5iwPiGHyGh1S00PAUDHeJ RRSjJAIPlDcVhJircaeRzOVe+rPIf6icwdrzOzkE8wnifE570ivq/z8BtT6d zgC9s2CXKBVRTY5L/UGWlWkk15yaSzFjHS3ZtXGVlTyfQ2SItHbHh6ceeazo l44PxOt+qJtDqA6FKzj7SfnAVyVBLq1XSpkebnuL/CXJzVdVXsXGCDl1CSwf srnLPfAoW8dcKrJyUE4meYovCq8Ym+zHZZY70iLfB6kxfz+1Uyase/BkmrAY b+j9BUOQ+OPFtGABBJB+FBR9dIN44Q6KTbgmXUC0mq1bYK7QfLZMdw== =0swD
-----END PGP SIGNATURE-----

Acked-by on v3 1/1
#17 lore raw

[Openvpn-devel] [PATCH applied] Re: Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

In reply to Arne Schwabe

I've taken David's ACK on v2, compared the changes to v3 (some of the nitpicks David has pointed out, .pem/.key/.crt changes, plus language changes by Richard), and added my own ACK based on that.

Integrated Richard's "6 minor improvements" - thanks :-)

Your patch has been applied to the master branch.

commit f235b5efd6106ad4f899d6da899c617afc6ff9e9

Author: Arne Schwabe
Date:   Wed Jul 28 17:49:22 2021 +0200
     Add detailed man page section to setup a OpenVPN setup with peer-fingerprint

     Signed-off-by: Arne Schwabe <[email protected]...>
     Acked-by: David Sommerseth <[email protected]...>
     Acked-by: Gert Doering <[email protected]...>
     Message-Id: <[email protected]...>
     URL: https://www.mail-archive.com/[email protected]/msg22674.html
     Signed-off-by: Gert Doering <[email protected]...>

--
kind regards,

Gert Doering