Document the simple self-signed certificate setup in examples

Also remove the static key setup example as it is less secure and we
want to avoid it for new setups as we want to slowly deprecate these.

Signed-off-by: Arne Schwabe <arne@rfc2549.org>
Acked-by: Antonio Quartulli <antonio@openvpn.net>
Message-Id: <20200908154157.13809-5-arne@rfc2549.org>
URL: https://www.mail-archive.com/openvpn-devel@lists.sourceforge.net/msg20904.html
Signed-off-by: Gert Doering <gert@greenie.muc.de>

diff --git a/Changes.rst b/Changes.rst
index c0e0d5d9786f5437da3c6ee65c15c77265e03d01..0c16f6d0b57b8c0f0d6f8950a4310d1b3cb6a6b2 100644 (file)
--- a/Changes.rst
+++ b/Changes.rst
@@ -25,6 +25,11 @@ Certificate pinning/verify peer fingerprint
     fingerprint of the peer. The option takes use a number of allowed
     SHA256 certificate fingerprints.
 
+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
+    a PKI with Easy-RSA or similar software.
+
 
 Deprecated features
 -------------------

diff --git a/doc/man-sections/examples.rst b/doc/man-sections/examples.rst
index 3f494ea4c34d2bd2ddbcae5626b8c3d98140dc14..3148601711c1d283d1a713a0359c89af9a8605cf 100644 (file)
--- a/doc/man-sections/examples.rst
+++ b/doc/man-sections/examples.rst
@@ -60,8 +60,8 @@ that is part of your local subnet for either of the tunnel endpoints,
 you will get a weird feedback loop.
 
 
-Example 1: A simple tunnel without security
--------------------------------------------
+Example 1: A simple tunnel without security (not recommended)
+-------------------------------------------------------------
 
 On bob:
 ::
@@ -92,31 +92,41 @@ The ``--verb 9`` option will produce verbose output, similar to the
 quietly.
 
 
-Example 2: A tunnel with static-key security (i.e. using a pre-shared secret)
------------------------------------------------------------------------------
+Example 2: A tunnel with self-signed certificates and fingerprint
+-----------------------------------------------------------------
 
-First build a static key on bob.
+First build a self-signed certificate on bob and display its fingerprint.
 ::
 
-   openvpn --genkey --secret key
+   openssl req -x509 -newkey ec:<(openssl ecparam -name secp384r1) -keyout bob.pem -out bob.pem -nodes -sha256 -days 3650 -subj '/CN=bob'
+   openssl x509 -noout -sha256 -fingerprint -in bob.pem
 
-This command will build a key file called ``key`` (in ascii format). Now
-copy ``key`` to ``alice.example.com`` over a secure medium such as by using
-the ``scp``\(1) program.
+and the same on alice:
+::
+
+   openssl req -x509 -newkey ec:<(openssl ecparam -name secp384r1) -keyout alice.pem -out alice.pem -nodes -sha256 -days 3650 -subj '/CN=alice'
+   openssl x509 -noout -sha256 -fingerprint -in alice.pem
+
+
+These commands will build a text file called ``bob.pem`` or ``alice.pem`` (in ascii format)
+that contain both self-signed certificate and key and show the fingerprint of the certificates.
+Transfer the fingerprints  over a secure medium such as by using
+the ``scp``\(1) or ``ssh``\(1) program.
 
 On bob:
 ::
 
-   openvpn --remote alice.example.com --dev tun1  \
-            --ifconfig 10.4.0.1 10.4.0.2 --verb 5 \
-            --secret key
+   openvpn --ifconfig 10.4.0.1 10.4.0.2 --tls-server --dev tun --dh none \
+           --cert bob.pem --key bob.pem --cipher AES-256-GCM \
+           --peer-fingerprint "$fingerprint_of_alices_cert"
 
 On alice:
 ::
 
-   openvpn --remote bob.example.com --dev tun1   \
-           --ifconfig 10.4.0.2 10.4.0.1 --verb 5 \
-           --secret key
+   openvpn --remote bob.example.com --tls-client --dev tun1   \
+           --ifconfig 10.4.0.2 10.4.0.1 --cipher AES-256-GCM  \
+           --cert alice.pem --key alice.pem
+           --peer-fingerprint "$fingerprint_of_bobs_cert"
 
 Now verify the tunnel is working by pinging across the tunnel.
 
@@ -130,9 +140,11 @@ On alice:
 
    ping 10.4.0.1
 
+Note: This example use a elliptic curve (`secp384`), which allows
+``--dh`` to be set to ``none``.
 
-Example 3: A tunnel with full TLS-based security
-------------------------------------------------
+Example 3: A tunnel with full PKI and TLS-based security
+--------------------------------------------------------
 
 For this test, we will designate ``bob`` as the TLS client and ``alice``
 as the TLS server.

diff --git a/doc/man-sections/tls-options.rst b/doc/man-sections/tls-options.rst
index cfe1ec98adee0b0e200a28c4ff20600de2a16490..8f5e37cb5c9f99d69d78e37d3b935d33b79d710a 100644 (file)
--- a/doc/man-sections/tls-options.rst
+++ b/doc/man-sections/tls-options.rst
@@ -612,6 +612,10 @@ If the option is inlined, ``algo`` is always :code:`SHA256`.
     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:00
     </peer-fingerprint>
 
+  When the ``--peer-fingerprint`` option is used, specifying a CA with ``--ca`` or ``--capath`` is
+  optional. This allows the he ``--peer-fingerprint`` to be used as alternative to a PKI with
+  self-signed certificates for small setups. See the examples section for such a setup.
+
 --verify-x509-name args
   Accept connections only if a host's X.509 name is equal to **name.** The
   remote host must also pass all other tests of verification.