OpenVPN: Added information about mfa settings

docs/configuration/interfaces/openvpn.rst

@@ -45,13 +45,13 @@
 still don't support it. However, it's very useful for quickly setting up
 tunnels between routers.
 
 As of VyOS 1.4, OpenVPN site-to-site mode can use either pre-shared keys or x.509 certificates.
 
 The pre-shared key mode is deprecated and will be removed from future OpenVPN versions,
 so VyOS will have to remove support for that option as well. The reason is that using pre-shared keys
 is significantly less secure than using TLS.
 
 We'll configure OpenVPN using self-signed certificates, and then discuss the legacy
 pre-shared key mode.
 
 In both cases, we will use the following settings:
@@ -73,16 +73,16 @@
 Setting up certificates
 =======================
 
 Setting up a full-blown PKI with a CA certificate would arguably defeat the purpose
 of site-to-site OpenVPN, since its main goal is supposed to be configuration simplicity,
 compared to server setups that need to support multiple clients.
 
 However, since VyOS 1.4, it is possible to verify self-signed certificates using
 certificate fingerprints.
 
 On both sides, you need to generate a self-signed certificate, preferrably using the "ec" (elliptic curve) type.
 You can generate them by executing command ``run generate pki certificate self-signed install <name>`` in the configuration mode.
 Once the command is complete, it will add the certificate to the configuration session, to the ``pki`` subtree.
 You can then review the proposed changes and commit them.
 
 .. code-block:: none
@@ -116,13 +116,13 @@
 
   vyos@vyos# commit
 
 You do **not** need to copy the certificate to the other router. Instead, you need to retrieve its SHA-256 fingerprint.
 OpenVPN only supports SHA-256 fingerprints at the moment, so you need to use the following command:
 
 .. code-block:: none
 
   vyos@vyos# run show pki certificate openvpn-local fingerprint sha256 
   5C:B8:09:64:8B:59:51:DC:F4:DF:2C:12:5C:B7:03:D1:68:94:D7:5B:62:C2:E1:83:79:F1:F0:68:B2:81:26:79
 
 Note: certificate names don't matter, we use 'openvpn-local' and 'openvpn-remote' but they can be arbitrary.
 
@@ -652,6 +652,88 @@
    quotes. This is done through a hack on our config generator. You can pass
    quotes using the ``&quot;`` statement.
 
+***************************
+Multi-factor Authentication
+***************************
+
+VyOS supports multi-factor authentication (MFA) or two-factor authentication 
+using Time-based One-Time Password (TOTP). Compatible with Google Authenticator
+software token, other software tokens.
+
+MFA TOTP options
+================
+
+.. cfgcmd:: set interfaces openvpn <interface> server mfa totp challenge <enable | disable>
+
+  If set to enable, openvpn-otp will expect password as result of challenge/
+  response protocol.
+
+.. cfgcmd:: set interfaces openvpn <interface> server mfa totp digits <1-65535>    
+
+  Configure number of digits to use for totp hash (default: 6)
+
+.. cfgcmd:: set interfaces openvpn <interface> server mfa totp drift <1-65535>
+
+  Configure time drift in seconds (default: 0)
+
+.. cfgcmd:: set interfaces openvpn <interface> server mfa totp slop <1-65535>
+
+  Configure maximum allowed clock slop in seconds (default: 180)
+
+.. cfgcmd:: set interfaces openvpn <interface> server mfa totp step <1-65535>
+
+  Configure step value for totp in seconds (default: 30)
+
+Example
+=======
+
+.. code-block:: none
+
+  set interfaces openvpn vtun20 encryption cipher 'aes256'
+  set interfaces openvpn vtun20 hash 'sha512'
+  set interfaces openvpn vtun20 mode 'server'
+  set interfaces openvpn vtun20 persistent-tunnel
+  set interfaces openvpn vtun20 server client user1
+  set interfaces openvpn vtun20 server mfa totp challenge 'disable'
+  set interfaces openvpn vtun20 server subnet '10.10.2.0/24'
+  set interfaces openvpn vtun20 server topology 'subnet'
+  set interfaces openvpn vtun20 tls ca-certificate 'openvpn_vtun20'
+  set interfaces openvpn vtun20 tls certificate 'openvpn_vtun20'
+  set interfaces openvpn vtun20 tls dh-params 'dh-pem'
+
+For every client in the openvpn server configuration a totp secret is created.
+To display the authentication information, use the command:
+
+.. cfgcmd:: show interfaces openvpn <interface> user <username> mfa <qrcode|secret|uri>
+
+An example:
+
+.. code-block:: none
+
+   vyos@vyos:~$ sh interfaces openvpn vtun20 user user1 mfa qrcode
+   █████████████████████████████████████
+   █████████████████████████████████████
+   ████ ▄▄▄▄▄ █▀▄▀ ▀▀▄▀ ▀▀▄ █ ▄▄▄▄▄ ████
+   ████ █   █ █▀▀▄ █▀▀▀█▀██ █ █   █ ████
+   ████ █▄▄▄█ █▀█ ▄ █▀▀ █▄▄▄█ █▄▄▄█ ████
+   ████▄▄▄▄▄▄▄█▄█ █ █ ▀ █▄▀▄█▄▄▄▄▄▄▄████
+   ████▄▄ ▄ █▄▄ ▄▀▄█▄ ▄▀▄█ ▄▄▀ ▀▄█ ▀████
+   ████ ▀██▄▄▄█▄ ██ █▄▄▄▄ █▄▀█ █ █▀█████
+   ████ ▄█▀▀▄▄  ▄█▀  ▀▄ ▄▄▀▄█▀▀▀ ▄▄▀████
+   ████▄█ ▀▄▄▄▀  ▀ ▄█ ▄ █▄█▀ █▀  █▀█████
+   ████▀█▀ ▀ ▄█▀▄▀▀█▄██▄█▀▀  ▀ ▀ ▄█▀████
+   ████ ██▄▄▀▄▄█ ██ ▀█ ▄█ ▀▄█  █▀██▀████
+   ████▄███▄█▄█ ▀█▄ ██▄▄▄█▀ ▄▄▄ █ ▀ ████
+   ████ ▄▄▄▄▄ █▄█▀▄ ▀▄ ▀█▀  █▄█ ██▀█████
+   ████ █   █ █ ▄█▀█▀▀▄ ▄▀▀▄▄▄▄▄▄   ████
+   ████ █▄▄▄█ █ ▄ ▀ █▄▄▄██▄▀█▄▀▄█▄ █████
+   ████▄▄▄▄▄▄▄█▄██▄█▄▄▄▄▄█▄█▄█▄██▄██████
+   █████████████████████████████████████
+   █████████████████████████████████████
+
+Use the QR code to add the user account in Google authenticator application and
+on client side, use the OTP number as password.
+
 
 **********************************
 OpenVPN Data Channel Offload (DCO)