[Openvpn-devel,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).

Signed-off-by: Arne Schwabe <arne@rfc2549.org>
---
 Changes.rst                              |   4 +
 doc/Makefile.am                          |   1 +
 doc/man-sections/example-fingerprint.rst | 196 +++++++++++++++++++++++
 doc/openvpn-examples.5.rst               |   1 +
 4 files changed, 202 insertions(+)
 create mode 100644 doc/man-sections/example-fingerprint.rst

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

Hi,

again, I do not understand why openvpn choose to switch to .pem
for this tutorial.  PEM -> Private Email, which this is not.
You have a certificate and a key and every other openvpn tutorial
on openvpn and probably the entire planet uses .crt and .key.
This seems to be a poor decision in my opinion.

And I presume that --tun-mtu 1400 is not going to break --mssfix 1450

There is also another advantage of using this method which is not
documented.  Each client can build its own cert/key and send the
finger-print to the server in clear text, as can the server FP
be sent to the clients.

And apologies for the plug but easy-pfp can do all this and more
even easier. https://github.com/TinCanTech/easy-pfp


Sent with ProtonMail Secure Email.  Which does not know how to
reply to a git formatted patch and has other stupid quirks too.
sed formatted reply.


‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
On Thursday, 20 May 2021 16:09, Arne Schwabe <arne@rfc2549.org> wrote:

> This is meant to give new users a quickstart for a useable OpenVPN
> setup. Our own documentation is lacking in this regard and many
> tutorials that can be found online are often questionable in some
> aspects.
>
> Linking the individaul RST file on github also give a tutorial
> in a nicely formatted way.

individaul -> individual (ua)


>
> Patch V2: Fix grammar/spelling mistakes (thanks ticantech), move
>           to openvpn-examples(5).
>
> Signed-off-by: Arne Schwabe <arne@rfc2549.org>
> ---
>  Changes.rst                              |   4 +
>  doc/Makefile.am                          |   1 +
>  doc/man-sections/example-fingerprint.rst | 196 +++++++++++++++++++++++
>  doc/openvpn-examples.5.rst               |   1 +
>  4 files changed, 202 insertions(+)
>  create mode 100644 doc/man-sections/example-fingerprint.rst
>
> diff --git a/Changes.rst b/Changes.rst
> index 9185b55f7..5ac24307f 100644
> --- a/Changes.rst
> +++ b/Changes.rst
> @@ -25,6 +25,10 @@ Certificate pinning/verify peer fingerprint
>      fingerprint of the peer. The option takes use a number of allowed
>      SHA256 certificate fingerprints.
>
> +    See the man page section "Small OpenVPN setup with peer-fingerprint"
> +    for a tutorial on how to use this feature. This is also available online
> +    under https://github.com/openvpn/openvpn/blob/master/doc/man-sections/example-fingerprint.rst
> +
>  TLS mode with self-signed certificates
>      When ``--peer-fingerprint`` is used, the ``--ca`` and ``--capath`` option
>      become optional. This allows for small OpenVPN setups without setting up
> diff --git a/doc/Makefile.am b/doc/Makefile.am
> index 1dbbddf58..d86560174 100644
> --- a/doc/Makefile.am
> +++ b/doc/Makefile.am
> @@ -25,6 +25,7 @@ dist_noinst_DATA = \
>  	man-sections/client-options.rst \
>  	man-sections/connection-profiles.rst \
>  	man-sections/encryption-options.rst \
> +	man-sections/example-fingerprint.rst \
>  	man-sections/examples.rst \
>  	man-sections/generic-options.rst \
>  	man-sections/inline-files.rst \
> diff --git a/doc/man-sections/example-fingerprint.rst b/doc/man-sections/example-fingerprint.rst
> new file mode 100644
> index 000000000..c91ca64b9
> --- /dev/null
> +++ b/doc/man-sections/example-fingerprint.rst
> @@ -0,0 +1,196 @@
> +Small OpenVPN setup with peer-fingerprint
> +=========================================
> +This section consists of instructions how to build a small OpenVPN setup with the
> +:code:`peer-fingerprint` option. This has the advantage of being easy to setup
> +and should be suitable for most small lab and home setups without the need for a PKI.
> +For bigger scale setup setting up a PKI (e.g. via easy-rsa) is still recommended.
> +
> +Both server and client configuration can of be further modified to customise the
> +setup.
> +
> +Server setup
> +------------
> +1. Install openvpn
> +
> +   Compile from source-code (see `INSTALL` file) or install via a distribution (apt/yum/ports)
> +   or via installer (Windows).
> +
> +2. Generate a self-signed certificate for the server:
> +   ::
> +
> +    openssl req -x509 -newkey ec:<(openssl ecparam -name secp384r1) -keyout serverkey.pem -out server.pem -nodes -sha256 -days 3650 -subj '/CN=server'
> +
> +3. Generate SHA256 fingerprint of the server certificate
> +
> +   Use the OpenSSL command line utility to view the fingerprint of just
> +   created certificate:
> +   ::
> +
> +    openssl x509 -fingerprint -sha256 -in server.pem -noout
> +
> +   This output something similar to:
> +   ::
> +
> +     SHA256 Fingerprint=00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff
> +
> +
> +3. Write a server configuration (`server.conf`):
> +::
> +
> +    # The server certificate we created in step 1
> +    cert server.pem
> +    key serverkey.pem
> +
> +    dh none
> +    dev tun
> +
> +    # Listen on IPv6+IPv4 simultaneously
> +    proto udp6
> +
> +    # The ip address the server will distribute
> +    server 192.168.234.0 255.255.255.0
> +    server-ipv6 fd00:6f76:706e::/64
> +
> +    # A tun-mtu of 1400 avoids problems of too big packets after VPN encapsulation
> +    tun-mtu 1400
> +
> +    # The fingerprints of your clients. After adding/removing one here restart the
> +    # server
> +    <peer-fingerprint>
> +    </peer-fingerprint>
> +
> +    # Notify clients when you restart the server to reconnect quickly
> +    explicit-exit-notify 1
> +
> +    # Ping every 60s, restart if no data received for 5 minutes
> +    keepalive 60 300
> +
> +4. Add at least one client as described in the client section.
> +
> +5. Start the server.
> +    - On systemd based distributions move `server.pem`, `serverkey.pem` and
> +      `server.conf` to :code:`/etc/openvpn/server` and start it via systemctl
> +
> +      ::
> +
> +          sudo mv server.conf serverkey.pem server.pem /etc/openvpn/server
> +
> +          sudo systemctl start openvpn-server@server
> +
> +Adding a client
> +---------------
> +1. Install OpenVPN
> +
> +2. Generate a self-signed certificate for the client. In this example the client
> +   name is alice. Each client should have a unique name. Replace alice with a
> +   different name for each client.
> +   ::
> +
> +      openssl req -x509 -newkey ec:<(openssl ecparam -name secp384r1) -nodes -sha256 -days 3650 -subj '/CN=alice'
> +
> +   This generate a certificate and a key for the client. The output of the command will look

This does not generate a certificate and a key *file* and I think that should be stated explicitly.


> +   something like this:
> +   ::
> +
> +      -----BEGIN PRIVATE KEY-----
> +      [base64 content]
> +      -----END PRIVATE KEY-----
> +      -----
> +      -----BEGIN CERTIFICATE-----
> +      [base 64 content]
> +      -----END CERTIFICATE-----
> +
> +
> +3. Create a new client configuration file. In this example we will name the file
> +   `alice.ovpn`:
> +
> +   ::
> +
> +      # The name of your server to connect to
> +      remote yourserver.example.net
> +      client
> +      # use a random source port instead the fixed 1194
> +      nobind
> +
> +      # Uncomment the following line if you want to route
> +      # all traffic via the VPN
> +      # redirect-gateway def1 ipv6
> +
> +      # To set a a DNS server
> +      # dhcp-option DNS 192.168.234.1
> +
> +      <key>
> +      -----BEGIN PRIVATE KEY-----
> +      [Insert here the key created in step 2]
> +      -----END PRIVATE KEY-----
> +      </key>
> +      <cert>
> +      -----BEGIN CERTIFICATE-----
> +      [Insert here the certificate created in step 2]
> +      -----END CERTIFICATE-----
> +      </cert>
> +
> +      # This is the fingerprint of the server that we trust. We generated this fingerprint
> +      # in step 2 of the server setup

+ In this example we do not need to use inline markers <peer-fingerprint> and </peer-fingerprint>
It will probably be easier to see in the formatted .rst but just for the record.

> +      peer-fingerprint 00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff:00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff
> +
> +      # The tun-mtu of the client should match the server MTU
> +      tun-mtu 1400
> +      dev tun
> +
> +
> +4. Generate the fingerprint of the client certificate. For that we will
> +   let OpenSSL read the client configuration file as the x509 command will
> +   ignore anything that is not between the begin and end markers of the certificate:
> +
> +   ::
> +
> +      openssl x509 -fingerprint -sha256 -noout -in alice.ovpn
> +
> +   This will again output something like
> +   ::
> +
> +        SHA256 Fingerprint=ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00:ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00
> +
> +5. Edit the `server.conf` configuration file and add this new client
> +   fingerprint as additional line  between :code:`<peer-fingerprint>`
> +   and :code:`</peer-fingerprint>`
> +
> +   After adding *two* clients the part of configuration would look like this:
> +
> +   ::
> +
> +      <peer-fingerprint>
> +      ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00:ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00
> +      99:88:77:66:55:44:33:22:11:00:ff:ee:dd:cc:bb:aa:99:88:77:66:55:44:33:22:11:00:88:77:66:55:44:33
> +      </peer-fingperint>
> +
> +6. (optional) if the client is an older client that does not support the
> +   :code:`peer-fingerprint` (e.g. OpenVPN 2.5 and older, OpenVPN Connect 3.3
> +   and older), the client config `alice.ovpn` can be modified to still work with
> +   these clients.

This doesn't seem right.  Do you mean ?
the client config `alice.ovpn` can be modified to still work with *new servers*


> +
> +   Remove the line starting with :code:`peer-fingerprint`. Then
> +   add a new :code:`<ca>` section at the end of the configuration file
> +   with the contents of the :code:`server.pem` created in step 2 of the
> +   server setup. The end of `alice.ovpn` file should like:
> +
> +   ::
> +
> +      [...]  # Beginning of the file skipped
> +      </cert>
> +
> +      # The tun-mtu of the client should match the server MTU
> +      tun-mtu 1400
> +      dev tun
> +
> +      <ca>
> +      [contents of the server.pem]
> +      </ca>
> +
> +   Note that we put the :code:`<ca>` section after the :code:`<cert>` section
> +   to make the fingerprint generation from step 4 still work since it will
> +   only use the first certificate it find.

Forgot the 's' in finds ;-)


Hope I'm helping
R



> +
> +7. Import the file into the OpenVPN client or just use the
> +   :code:`openvpn alice.ovpn` to start the VPN.
> diff --git a/doc/openvpn-examples.5.rst b/doc/openvpn-examples.5.rst
> index 988b6027b..0e1b6c4f6 100644
> --- a/doc/openvpn-examples.5.rst
> +++ b/doc/openvpn-examples.5.rst
> @@ -14,4 +14,5 @@ INTRODUCTION
>
>  This man page gives a few simple examples to create OpenVPN setups and configuration files.
>
> +.. include:: man-sections/example-fingerprint.rst
>  .. include:: man-sections/examples.rst
> --
> 2.31.1
>
>
>
> _______________________________________________
> Openvpn-devel mailing list
> Openvpn-devel@lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/openvpn-devel
-----BEGIN PGP SIGNATURE-----
Version: ProtonMail

wsBzBAEBCAAGBQJgppStACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec
9muQuJ2WGwgAhMxENN0Y9MYIQcTpm51WuOtHmS5yyPTH9tQjw1yPlGkXXakE
whB6vVRGZ9BDGxZFsGHxzJ8XllM1HnYROW4rpRhX2IoafW6QIaMZ33mvYVgq
rwu/JHbWktXOAzkh3z1Z7v5HCEI5LW1at8ei7+H06pUR9Eo1W6YBDa0nP7Ni
AAoik9/cEv1l/7V4pHhBklyydqoUVAPNXP5lOy6NoqKJYkRQOH98BeA+Tctm
BaxzC+XFNYMO+khkvSeLNRG0l1coc825VPbwMdmInqlW9f+u5jgh3e9ka6sW
UmIEmODei6zSXAChWn6OlBBJhyAMdDEYf53kKAMFf8E+2s4m1ReYaw==
=ZRj2
-----END PGP SIGNATURE-----

Hi,

On Thu, May 20, 2021 at 04:56:16PM +0000, tincantech via Openvpn-devel wrote:
> again, I do not understand why openvpn choose to switch to .pem
> for this tutorial.  PEM -> Private Email, which this is not.

https://www.ssl.com/guide/pem-der-crt-and-cer-x-509-encodings-and-conversions/

gert

Am 20.05.2021 um 18:56 schrieb tincantech:
> Hi,
>
> again, I do not understand why openvpn choose to switch to .pem
> for this tutorial.  PEM -> Private Email, which this is not.
> You have a certificate and a key and every other openvpn tutorial
> on openvpn and probably the entire planet uses .crt and .key.
> This seems to be a poor decision in my opinion.

pem as extension for keys is pretty common and specifies more the 
encoding than the type. E.g. there is also the der encoding.

Arne

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

Hi,

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
On Thursday, 20 May 2021 19:30, Arne Schwabe <arne@rfc2549.org> wrote:

> Am 20.05.2021 um 18:56 schrieb tincantech:
>
> > Hi,
> > again, I do not understand why openvpn choose to switch to .pem
> > for this tutorial.  PEM -> Private Email, which this is not.
> > You have a certificate and a key and every other openvpn tutorial
> > on openvpn and probably the entire planet uses .crt and .key.
> > This seems to be a poor decision in my opinion.
>
> pem as extension for keys is pretty common and specifies more the
> encoding than the type. E.g. there is also the der encoding.
>
> Arne

I accept the principle but openvpn *only* uses PEM-enc, that I know of.

So, why switch to .pem when it has never been used before by openvpn?

If you are all happy to let it go that way then so-be-it,

Thanks
R

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

wsBzBAEBCAAGBQJgpr0yACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec
9muQuJ3AXgf9H+mL+H1aPZ/Gk0lTukZEP7FVXHkO2LBf49KA/YmoyhbHYAFf
sICvASsTlkA0q3wuKYzXs8bspMGiebOeqcoJi7QvJSaAq4sDLvWopz/VmN96
SmB33OnN/jYHQmKpk2qOMeZv6PyhFyjFb/3j1ymQ2zuYXh8osrSiiRHftwSx
hXg8CMyXOA0THrK6H9mnxisLuss7uhVsclwTOSKMOnRj0NiEx5tFg1itn7+u
YmRL/h2taDC6skHbF5PPfU1x/M6HtG05ZajAtNfh3bc0Zw4S7bRiEUc4+4qb
f8GEEufo2WAg4CUwaCVJ9O5pSewk48OAScHGx9RMybvfZ1X6V5xnqA==
=EBa6
-----END PGP SIGNATURE-----

Hi,

On Thu, May 20, 2021 at 3:50 PM tincantech via Openvpn-devel
<openvpn-devel@lists.sourceforge.net> wrote:
>
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA256
>
> Hi,
>
> ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
> On Thursday, 20 May 2021 19:30, Arne Schwabe <arne@rfc2549.org> wrote:
>
> > Am 20.05.2021 um 18:56 schrieb tincantech:
> >
> > > Hi,
> > > again, I do not understand why openvpn choose to switch to .pem
> > > for this tutorial.  PEM -> Private Email, which this is not.
> > > You have a certificate and a key and every other openvpn tutorial
> > > on openvpn and probably the entire planet uses .crt and .key.
> > > This seems to be a poor decision in my opinion.
> >
> > pem as extension for keys is pretty common and specifies more the
> > encoding than the type. E.g. there is also the der encoding.
> >
> > Arne
>
> I accept the principle but openvpn *only* uses PEM-enc, that I know of.
>
> So, why switch to .pem when it has never been used before by openvpn?
>
> If you are all happy to let it go that way then so-be-it,

I'm not sure I fully understand the discussion here, but we should
stick with consistent extensions for cert and key files in
documentation and examples. Currently we use the phrase "PEM certs" in
one place and "in .pem format" elsewhere. "PEM encoded" or "PEM
format" would be a better description. We use server.crt, server,key
etc in some places, .pem in some other.

OpenVPN doesn't care about the file extension of keys or certs as long
as the content is PEM. In that sense, having .pem in examples may
appear to be self-documenting but we have to be consistent. Use of
.pem has the drawback that we can use the same filename for cert and
key.

In practice I prefer .crt and .key as they are generally understood as
PEM encoded, and allow the same filename stub to be used for both cert
and key files: like server.crt and server.key while with pem it will
have to be something like server-cert.pem and server-key.pem.

Also, fwiw, .pem is not recognized by Windows explorer, .crt is -- one
could double click on the latter and load into the cert store, not so
with .pem.


Selva

Hi,

On 20/05/21 21:49, tincantech via Openvpn-devel wrote:
>
>>> Hi,
>>> again, I do not understand why openvpn choose to switch to .pem
>>> for this tutorial.  PEM -> Private Email, which this is not.
>>> You have a certificate and a key and every other openvpn tutorial
>>> on openvpn and probably the entire planet uses .crt and .key.
>>> This seems to be a poor decision in my opinion.
>> pem as extension for keys is pretty common and specifies more the
>> encoding than the type. E.g. there is also the der encoding.
>>
>> Arne
> I accept the principle but openvpn *only* uses PEM-enc, that I know of.
>
> So, why switch to .pem when it has never been used before by openvpn?
>
> If you are all happy to let it go that way then so-be-it,
>

Hopefully this clarifies things:
- the default output format of OpenSSL is PEM-encoded ; openssl uses the 
default extension .pem
- the OpenVPN .crt and .key files are ALSO PEM-encoded by default, but 
they've just been named differently by the easy-rsa tools to ensure that 
the files can be easily loaded on Windows

- FTR: nearly all webservers I have ever seen are configured to use a 
hostcert.pem and hostkey.pem and my guess is that there are (still) 
more  Linux-based webservers out there than OpenVPN clients and servers.

Having said that, I do agree that after using .crt/.key files left and 
right (to accomodate Windows users) for over 15 years, it does seem 
confusing to start using files named .pem for peer-fingerprinting all 
of  sudden. On the other hand, with peer-fingerprinting you don't  
*HAVE* a .crt file (at least, you don't need one, technically) but only 
a .key file. So choosing a different extension for peer-fingerprinting 
does have its merits.

HTH,

JJK

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




Sent with ProtonMail Secure Email.

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
On Thursday, 20 May 2021 22:05, Jan Just Keijser <janjust@nikhef.nl> wrote:

> Hi,
>
> On 20/05/21 21:49, tincantech via Openvpn-devel wrote:
>
> > > > Hi,
> > > > again, I do not understand why openvpn choose to switch to .pem
> > > > for this tutorial.  PEM -> Private Email, which this is not.
> > > > You have a certificate and a key and every other openvpn tutorial
> > > > on openvpn and probably the entire planet uses .crt and .key.
> > > > This seems to be a poor decision in my opinion.
> > > > pem as extension for keys is pretty common and specifies more the
> > > > encoding than the type. E.g. there is also the der encoding.
> > >
> > > Arne
> > > I accept the principle but openvpn only uses PEM-enc, that I know of.
> >
> > So, why switch to .pem when it has never been used before by openvpn?
> > If you are all happy to let it go that way then so-be-it,
>
> Hopefully this clarifies things:
>
> -   the default output format of OpenSSL is PEM-encoded ; openssl uses the
>     default extension .pem
>
> -   the OpenVPN .crt and .key files are ALSO PEM-encoded by default, but
>     they've just been named differently by the easy-rsa tools to ensure that
>     the files can be easily loaded on Windows
>
> -   FTR: nearly all webservers I have ever seen are configured to use a
>     hostcert.pem and hostkey.pem and my guess is that there are (still)
>     more  Linux-based webservers out there than OpenVPN clients and servers.
>
>     Having said that, I do agree that after using .crt/.key files left and
>     right (to accomodate Windows users) for over 15 years, it does seem
>     confusing to start using files named .pem for peer-fingerprinting all
>     of  sudden. On the other hand, with peer-fingerprinting you don't 
>     HAVE a .crt file (at least, you don't need one, technically) but only
>     a .key file. So choosing a different extension for peer-fingerprinting
>     does have its merits.

FTR: Openvpn still exchanges the full certificates in peer-fingerprint mode.


>
>     HTH,
>
>     JJK
>


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

wsBzBAEBCAAGBQJgptC5ACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec
9muQuJ2t0ggAxDZnJr8UhxV79fyAjnScANMeWbN3XZ/QqQuTsgaJp85Fibbz
weT1TfvihZ5l1rS6vh1nIDyTtoNRpqLHMxlaNWnmgN9tR4IRlQZuVR8svZl1
UYmrAm1H5g83yHef60nnIiOxGe8tnLdy/fmjqoRFsHaBwSM87zTQ8uG+UJnq
GIGhHbdLYWaH4C9SrJ+p64pZYdm3jaQpwMMMMZHdeg3rPdvHAgUixX13KWBU
J2UYseRDBLcvNfz6gAgQDtTJtdT9edH3h6m4Tyu0AsIw016hfREeNe20uzrX
uyQ6jGGovT2ki9alVN9P5v1k9uYVC0/1mYnFBLR8PI8effQd/zfLiA==
=KICZ
-----END PGP SIGNATURE-----

On 20/05/21 23:12, tincantech wrote:
> [...]
>>> So, why switch to .pem when it has never been used before by openvpn?
>>> If you are all happy to let it go that way then so-be-it,
>> Hopefully this clarifies things:
>>
>> -   the default output format of OpenSSL is PEM-encoded ; openssl uses the
>>      default extension .pem
>>
>> -   the OpenVPN .crt and .key files are ALSO PEM-encoded by default, but
>>      they've just been named differently by the easy-rsa tools to ensure that
>>      the files can be easily loaded on Windows
>>
>> -   FTR: nearly all webservers I have ever seen are configured to use a
>>      hostcert.pem and hostkey.pem and my guess is that there are (still)
>>      more  Linux-based webservers out there than OpenVPN clients and servers.
>>
>>      Having said that, I do agree that after using .crt/.key files left and
>>      right (to accomodate Windows users) for over 15 years, it does seem
>>      confusing to start using files named .pem for peer-fingerprinting all
>>      of  sudden. On the other hand, with peer-fingerprinting you don't
>>      HAVE a .crt file (at least, you don't need one, technically) but only
>>      a .key file. So choosing a different extension for peer-fingerprinting
>>      does have its merits.
> FTR: Openvpn still exchanges the full certificates in peer-fingerprint mode.
>
meh ... I guess it was easier to implement it that way at the TLS level...

IMO that does add a "+1" to using .crt/.key  extensions - otherwise it 
might confuse the heck out of end users (like overwriting the private 
key with the public cert etc ... )
How do the examples distinguish between the cert and the private key in 
this case then?

JJK

> Hopefully this clarifies things:
> - the default output format of OpenSSL is PEM-encoded ; openssl uses 
> the default extension .pem
> - the OpenVPN .crt and .key files are ALSO PEM-encoded by default, but 
> they've just been named differently by the easy-rsa tools to ensure 
> that the files can be easily loaded on Windows
>
> - FTR: nearly all webservers I have ever seen are configured to use a 
> hostcert.pem and hostkey.pem and my guess is that there are (still) 
> more  Linux-based webservers out there than OpenVPN clients and servers.
>
> Having said that, I do agree that after using .crt/.key files left and 
> right (to accomodate Windows users) for over 15 years, it does seem 
> confusing to start using files named .pem for peer-fingerprinting all 
> of  sudden. On the other hand, with peer-fingerprinting you don't  
> *HAVE* a .crt file (at least, you don't need one, technically) but 
> only a .key file. So choosing a different extension for 
> peer-fingerprinting does have its merits.

I am used a lot more used to calling these files pem files. I suggest we 
put that just on the agenda for the next openvpn-meeting, if people have 
strong preferences there.

And no, you still need cert and key like for a normal TLS connection 
with peer-fingerprint. It *only* replacing the normal check of the 
certificate with a fingerprint. Basically the same principle that 
browsers do when you do cert-pinning.

Arne

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

Hi,

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
On Thursday, 20 May 2021 22:22, Jan Just Keijser <janjust@nikhef.nl> wrote:

> On 20/05/21 23:12, tincantech wrote:
>
> > [...]
> >
> > > > So, why switch to .pem when it has never been used before by openvpn?
> > > > If you are all happy to let it go that way then so-be-it,
> > > > Hopefully this clarifies things:
> > >
> > > -   the default output format of OpenSSL is PEM-encoded ; openssl uses the
> > >     default extension .pem
> > >
> > > -   the OpenVPN .crt and .key files are ALSO PEM-encoded by default, but
> > >     they've just been named differently by the easy-rsa tools to ensure that
> > >     the files can be easily loaded on Windows
> > >
> > > -   FTR: nearly all webservers I have ever seen are configured to use a
> > >     hostcert.pem and hostkey.pem and my guess is that there are (still)
> > >     more  Linux-based webservers out there than OpenVPN clients and servers.
> > >     Having said that, I do agree that after using .crt/.key files left and
> > >     right (to accomodate Windows users) for over 15 years, it does seem
> > >     confusing to start using files named .pem for peer-fingerprinting all
> > >     of  sudden. On the other hand, with peer-fingerprinting you don't
> > >     HAVE a .crt file (at least, you don't need one, technically) but only
> > >     a .key file. So choosing a different extension for peer-fingerprinting
> > >     does have its merits.

> >     FTR: Openvpn still exchanges the full certificates in peer-fingerprint mode.

> meh ... I guess it was easier to implement it that way at the TLS level...

I cannot comment on the code but there is the case of older clients which require
self-signed server".crt" (Easy-RSA) in place of the CA cert.

>
> IMO that does add a "+1" to using .crt/.key  extensions - otherwise it
> might confuse the heck out of end users (like overwriting the private
> key with the public cert etc ... )

That is another good point.


> How do the examples distinguish between the cert and the private key in
> this case then?

Generally, the distinction between what is private and what is public
has not been very well covered. Other than the notable exception of
"Protect your Private CA key at all costs!"

I have included this Private v Public information in the easy-pfp output.
Seems like the only way to get things done sometimes is do-it-yourself ;-)

Anyway, all other points aside, the point is that: Changing to .pem (not PEM)
feels like an unnecessary complication.

Thanks for all your input
R

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

wsBzBAEBCAAGBQJgptYeACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec
9muQuJ0haQf/VyfMNC8x8r+8okE+aKW+kp+OMA58J6R7xOdv7D518BsBSJNX
BAqDiM1lalAwDvU7edKKMXhc0U2BOgMiaVOXp54jkZvXo7O5tt57A1O+tTKv
GNPzqDrhfGQRuaplHTMeiSkcWZOSmyNwIAW0vroCmiPBnGY2/F5GIL8T83Dp
qiNsST7Fug+u4nVUv/BUE2K81/B3pNz4Jy6hX2QMmq5LdRJgtNU37AAsZAQ5
Zwr4bewl/l8q36VjsX4QYNQgQekXdK8oT7LXZuqEy+tf4RnVHA8YDQZ2Ed5t
tfUUg/b02w3Ml6k9Wt3SHDgoXMAW0utUxxOWCMGVnEhuDRWg0kQ3rw==
=B+MM
-----END PGP SIGNATURE-----

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

Hi,

-‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
On Thursday, 20 May 2021 22:35, tincantech via Openvpn-devel <openvpn-devel@lists.sourceforge.net> wrote:

> Hi,
>
> ‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
> On Thursday, 20 May 2021 22:22, Jan Just Keijser janjust@nikhef.nl wrote:
>
> > On 20/05/21 23:12, tincantech wrote:
> >
> > > [...]
> > >
> > > > > So, why switch to .pem when it has never been used before by openvpn?
> > > > > If you are all happy to let it go that way then so-be-it,
> > > > > Hopefully this clarifies things:
> > > >
> > > > -   the default output format of OpenSSL is PEM-encoded ; openssl uses the
> > > >     default extension .pem
> > > >
> > > > -   the OpenVPN .crt and .key files are ALSO PEM-encoded by default, but
> > > >     they've just been named differently by the easy-rsa tools to ensure that
> > > >     the files can be easily loaded on Windows
> > > >
> > > > -   FTR: nearly all webservers I have ever seen are configured to use a
> > > >     hostcert.pem and hostkey.pem and my guess is that there are (still)
> > > >     more  Linux-based webservers out there than OpenVPN clients and servers.
> > > >     Having said that, I do agree that after using .crt/.key files left and
> > > >     right (to accomodate Windows users) for over 15 years, it does seem
> > > >     confusing to start using files named .pem for peer-fingerprinting all
> > > >     of  sudden. On the other hand, with peer-fingerprinting you don't
> > > >     HAVE a .crt file (at least, you don't need one, technically) but only
> > > >     a .key file. So choosing a different extension for peer-fingerprinting
> > > >     does have its merits.
> > > >
>
> > >     FTR: Openvpn still exchanges the full certificates in peer-fingerprint mode.
> > >
>
> > meh ... I guess it was easier to implement it that way at the TLS level...
>
> I cannot comment on the code but there is the case of older clients which require
> self-signed server".crt" (Easy-RSA) in place of the CA cert.
>
> > IMO that does add a "+1" to using .crt/.key  extensions - otherwise it
> > might confuse the heck out of end users (like overwriting the private
> > key with the public cert etc ... )
>
> That is another good point.
>
> > How do the examples distinguish between the cert and the private key in
> > this case then?
>
> Generally, the distinction between what is private and what is public
> has not been very well covered. Other than the notable exception of
> "Protect your Private CA key at all costs!"
>
> I have included this Private v Public information in the easy-pfp output.
> Seems like the only way to get things done sometimes is do-it-yourself ;-)
>
> Anyway, all other points aside, the point is that: Changing to .pem (not PEM)
> feels like an unnecessary complication.
>

I would like to hammer one final nail into this discussion.

Openvpn option names and inline tags ALL use <cert>ificate .crt and <key> .key.

They do not use .pem or PEM and none of the Official online documentation,
to date, references use of a {name}.pem file, other than far-flung cases.

The files generated in this tutorial will all be PEM encoded regardless.

This is why I asked the question of why Openvpn suddenly chooses to change
to a .pem extension and add this unnecessary complication.

Real users may see this as another hurdle which they just don't want to jump.
Do you want to drive them away .. ?

As I am also banned from #openvpn-meeting, so I leave this for you to discuss.

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

wsBzBAEBCAAGBQJgpvNyACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec
9muQuJ1U5wgAza4n5mxniWpvVrkSxRCN3TEc0MEafFb+Eza0uL/l9i5tVDDQ
A4ZwjBuRGgteJzNhbe3Q+YJzZZ1hjf9k9FjPwGtnUK49IZZt8OOe60bfiQt7
aSmhKMRyZzzjRgSv6QNdPWsZEB3JceZ572+EIi5zfQmz6V1q8USsPQPaUZoa
k65YA9Z+pU6xsm1+lKMLGbi8rzIvIhNYCEIZ4pGl5OzckQP7o7JKUanhOoHH
7KrD5Nu5ad4CtgMv72RYWCbmW5vsqIcOrYJIG7mASodCTGkL2JH5F2i8fVUJ
rg5OrvVViLewxTYyGCVc+PZ7ukB6l/bEYd8efA1G4carr6+hRDTfSA==
=T6wH
-----END PGP SIGNATURE-----

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

Hi,

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐
On Friday, 21 May 2021 00:40, tincantech <tincantech@protonmail.com> wrote:


> I would like to hammer one final nail into this discussion.
>
> Openvpn option names and inline tags ALL use <cert>ificate .crt and <key> .key.
>
> They do not use .pem or PEM and none of the Official online documentation,
> to date, references use of a {name}.pem file, other than far-flung cases.
>
> The files generated in this tutorial will all be PEM encoded regardless.

One final blow to the nail:

There is still the outstanding problem of --remote-cert-tls
which this tutorial does not discuss or solve.

The user log will show a WARNING message which they *cannot* solve
by means of your documentation.

--
Thanks
R

Unfairly banned.
-----BEGIN PGP SIGNATURE-----
Version: ProtonMail

wsBzBAEBCAAGBQJgpvv5ACEJEE+XnPZrkLidFiEECbw9RGejjXJ5xVVVT5ec
9muQuJ2gkQf9FDId8dPnTrdC4+UHLhFOJOAYelk9SDQ1a3PSVhbag2ZO2FvM
3pCKfqdqSB0zYuu3rXBSdBoToovKw2Zc+8tnF8MaH6Oqm5+cmnRDfc03ZfDs
auqD04xIACnt3cPYAXXU+qXxGC8GpwLiUlEIEzlTcTsBrZyLMJhMPx146Dpe
MNRQtmYW+FqJfYHO7OscIb1uwUQ4WeWLY+76GkqhRMSPY6hrZ6CRU9htSdoU
w+B7KOGCKVE/FsyABNOz4IRNdnM3FMzvAvRD0UcOxJnmz/2BjImP6qNa7D0f
VGyg1kvnYQViVOOjE17ejvqbnLcRJRD53gRJcHpb/45UbVWNjSq04A==
=C3te
-----END PGP SIGNATURE-----

On 20/05/2021 17:09, Arne Schwabe wrote:
> This is meant to give new users a quickstart for a useable OpenVPN
> setup. Our own documentation is lacking in this regard and many
> tutorials that can be found online are often questionable in some
> aspects.
> 
> Linking the individaul RST file on github also give a tutorial
> in a nicely formatted way.
> 
> Patch V2: Fix grammar/spelling mistakes (thanks ticantech), move
>            to openvpn-examples(5).
> 
> Signed-off-by: Arne Schwabe <arne@rfc2549.org>
> ---
>   Changes.rst                              |   4 +
>   doc/Makefile.am                          |   1 +
>   doc/man-sections/example-fingerprint.rst | 196 +++++++++++++++++++++++
>   doc/openvpn-examples.5.rst               |   1 +
>   4 files changed, 202 insertions(+)
>   create mode 100644 doc/man-sections/example-fingerprint.rst

This is basically good; I do have some really minor nit-pick.  I've 
tested an OpenVPN server built from git and with both a git master 
client as well as a v2.5.3 client.  Both works with the instructions as 
given here.   And both man and html files are created correctly.

One confusing thing is that the server config complains about missing CA 
if there are no peer-fingerprint entries are present.  But that's 
outside the scope of this documentation.

The nit-pick comes below ...


> diff --git a/doc/man-sections/example-fingerprint.rst b/doc/man-sections/example-fingerprint.rst
> new file mode 100644
> index 000000000..c91ca64b9
> --- /dev/null
> +++ b/doc/man-sections/example-fingerprint.rst
> @@ -0,0 +1,196 @@
> +Small OpenVPN setup with peer-fingerprint
> +=========================================
[...snip...]
> +3. Write a server configuration (`server.conf`):
> +::
> +
> +    # The server certificate we created in step 1
> +    cert server.pem
> +    key serverkey.pem
> +
> +    dh none
> +    dev tun
> +
> +    # Listen on IPv6+IPv4 simultaneously
> +    proto udp6
> +
> +    # The ip address the server will distribute
> +    server 192.168.234.0 255.255.255.0

Elsewhere in our documentation, we've been using 10.8.0.0/24 for the 
example VPN subnets.

> +    server-ipv6 fd00:6f76:706e::/64

The other example subnet we've used for IPv6 is fd15:53b6:dead::2/64, 
but that's related to --block-ipv6.  I vaguely remember we used some 
other IPv6 subnet in examples, but not able to find it now.  If this is 
the standard subnet, feel free to ignore this comment.


These nit-picks does not hold back my approval though; they can be 
changed on-the-fly if so be.

Acked-By: David Sommerseth <davids@openvpn.net>