README.md


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

# Qubes VPN 2FA (with a certificate on USB)

Configuration for
[Qubes-vpn-support](https://github.com/tasket/Qubes-vpn-support) to add support
for 2FA. This specific implementation of 2FA is limited to a certificate stored
on a USB stick.

The canonical URL of this project is
<https://git.axenhus.com/qubes-vpn-2fa-certificate/>

## Prerequisites

 * Qubes-vpn-support installed and working.
 * An USB stick with a certificate. The certificate must be encrypted with a
   password. The certificate must be in the root directory.
 * Configuration for the VPN stored on the USB with the certificate. The file
   must end in ``.ovpn`` and be the only file matching that pattern. It must
   be stored in the root directory.
 * Username and password for the VPN.

## Installation

 * Copy ``00-2fa-usb.conf`` to ``/rw/config/qubes-vpn-handler.service.d``.
 * Copy ``prepare-vpn-usb.sh`` to ``/rw/config``.
 * Restart the ProxyVM or restart the VPN service.

## Usage

When the VPN service starts an xterm prompt will appear. It will prompt for:

 1. A device path. Attach your USB device to the VM. Usually the script can
    autodetect the correct path and you can simply press enter. If it doesn't
    you have to manually enter the correct path.
 2. A key password. This is the password for the private key for the
    certificate.
 3. Username for the VPN service.
 4. Password for the VPN service.

## Implementation notes

This is implemented by overriding some configuration for Qubes-vpn-handler. The
overriden configuration will cause Qubes-vpn-handler to run
``prepare-vpn-usb.sh`` before the actual service is started. That script will
mount the USB device on top of ``/rw/config/vpn`` and create a RAM disk to
store the passwords in for the VPN service.

## Known issues

 * The VPN service appears to be failing to connect the very first time it
   starts, even if the correct credentials are entered. It will successfully
   connect once systemd automatically restarts it (usually happens after a
   few seconds). Patches are welcome.