From: Arne Schwabe Date: Tue, 8 Sep 2020 15:41:57 +0000 (+0200) Subject: Document the simple self-signed certificate setup in examples X-Git-Tag: v2.6_beta1~595 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=26117a82d70dbd90f2260dd9895620394f040239;p=thirdparty%2Fopenvpn.git 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 Acked-by: Antonio Quartulli 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 --- diff --git a/Changes.rst b/Changes.rst index c0e0d5d97..0c16f6d0b 100644 --- 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 3f494ea4c..314860171 100644 --- 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 cfe1ec98a..8f5e37cb5 100644 --- 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 + 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.