5 govpn is simple secure virtual private network daemon.
6 It uses DH-EKE for mutual zero-knowledge authentication and
7 authenticated encrypted transport. It runs under GNU/Linux and FreeBSD.
11 * GNU/Linux and FreeBSD support
13 * Encrypted and authenticated transport
14 * Relatively fast handshake
15 * Replay attack protection
16 * Perfect forward secrecy (if long-term pre-shared keys are compromised,
17 no captured traffic can be decrypted anyway)
18 * Mutual two-side authentication (noone will send real network interface
19 data unless the other side is authenticated)
20 * Zero knowledge authentication (pre-shared key is not transmitted in
21 any form between the peers, not even it's hash value)
22 * Built-in rehandshake and heartbeat features
26 All packets captured on network interface are encrypted, authenticated
27 and sent to remote server, that writes them to his interface, and vice
28 versa. Client and server use pre-shared authentication key (PSK).
29 Because of stateless UDP nature, after some timeout of inactivity peers
30 forget about each other and have to retry handshake process again,
31 therefore background heartbeat process will be ran.
33 Handshake is used to mutually authenticate peers, exchange common secret
34 per-session encryption key and checks UDP transport availability.
36 Because of UDP and authentication overhead: each packet grows in size
37 during transmission, so you have to lower you maximum transmission unit
38 (MTU) on network interface.
40 High security is the goal for that daemon. It uses fast cryptography
41 algorithms with 128bit security margin, strong mutual zero-knowledge
42 authentication and perfect-forward secrecy property. An attacker can not
43 know anything from captured traffic, even if pre-shared key is
44 compromised. Rehandshake is performed by client every 4 GiB of
47 Also you can provide up and down scripts that will be executed after
48 either connection is initiated (up-script in background), or is went
49 down. The first argument for them is an interface name.
53 B -- bad or timeouted UDP packet (maybe network is inactive)
54 T -- bad tag on packet (MiTM, unordered packet)
55 R -- invalid sequence number (MiTM, unordered packet)
56 [HS?] -- unknown handshake message
57 w -- successful write to remote peer
58 r -- successful read from remote peer
59 [HS1], [HS2], [HS3], [HS4] -- handshake packet stage
60 [rS?] -- invalid server's random authentication number received (MiTM, bad PSK)
61 [rC?] -- invalid client's random authentication number received (MiTM, bad PSK)
62 [S?] -- invalid handshake stage is trying to perform (MiTM, duplicate packet)
63 [OK] -- handshake's stage passed
67 Let's assume that there is some insecure link between your computer and
68 WiFi-reachable gateway. You have got preconfigured wlan0 network
69 interface with 192.168.0/24 network. You want to create virtual
70 encrypted and authenticated 172.16.0/24 network and use it as a default
71 transport. MTU for that wlan0 is 1500 bytes. GoVPN will say that maximum
72 MTU for the link is 1476, however it does not take in account TAP's
73 Ethernet frame header length, that in my case is 14 bytes long (1476 - 14).
76 common% echo MYLONG64HEXKEY > key.txt
78 GNU/Linux IPv4 client-server example:
80 server% ip addr add 192.168.0.1/24 dev wlan0
81 server% tunctl -t tap10
82 server% ip link set mtu 1462 dev tap10
83 server% ip addr add 172.16.0.1/24 dev tap10
84 server% ip link set up dev tap10
85 server% govpn -key key.txt -iface tap10 -bind 192.168.0.1:1194
87 client% ip addr add 192.168.0.2/24 dev wlan0
88 client% tunctl -t tap10
89 client% ip link set mtu 1462 dev tap10
90 client% ip addr add 172.16.0.2/24 dev tap10
91 client% ip link set up dev tap10
92 client% ip route add default via 172.16.0.1
93 client% while :; do govpn -key key.txt -iface tap10 -remote 192.168.0.1:1194; done
95 FreeBSD IPv6 client-server example:
97 server% ifconfig em0 inet6 fe80::1/64
98 server% ifconfig tap10 create
99 server% ifconfig tap10 inet6 fc00::1/96 mtu 1462 up
100 server% govpn -key key.txt -face tap10 -bind fe80::1%em0
102 client% ifconfig me0 inet6 -ifdisabled auto_linklocal
103 client% ifconfig tap10
104 client% ifconfig tap10 inet6 fc00::2/96 mtu 1462 up
105 client% route -6 add default fc00::1
106 client% while :; do govpn -key key.txt -iface tap10 -remote [fe80::1%me0]:1194; done
110 client% cat > up.sh <<EOF
115 client% chmod +x up.sh
116 client% govpn -key key.txt -iface tap10 -remote [fe80::1%me0]:1194 -up ./up.sh
118 If client won't finish handshake during -timeout, then it will exit.
119 If no packets are received from remote side during timeout, then daemon
120 will stop sending packets to the client and client will exit. In all
121 cases you have to rehandshake again.
126 Message authentication: Poly1305
127 Password authenticated key agreement: Curve25519 based DH-EKE
128 Packet overhead: 24 bytes per packet
129 Handshake overhead: 4 UDP (2 from client, 2 from server) packets,
130 232 bytes total payload
134 SERIAL + ENC(KEY, SERIAL, DATA) + AUTH(SERIAL + ENC_DATA)
136 where SERIAL is message serial number. Odds are reserved for
137 client->server, evens are for server->client. SERIAL is used as a nonce
138 for DATA encryption: encryption key is different during each handshake,
139 so (key, nonce) pair is always used once.
141 We generate Salsa20's output using this key and nonce for each message:
142 * first 256 bits are used as a one-time key for Poly1305 authentication
143 * next 256 bits of output are ignored
144 * and all remaining ones XORed with the data, encrypting it
151 │ │ R=rand(64bit); CPrivKey=rand(256bit)
154 │ R, enc(PSK, R, CPubKey) │
155 │ ────────────────────────────────────────>
158 │ │ │ SPrivKey=rand(256bit)
162 │ │ │ K=DH(SPrivKey, CPubKey)
166 │ │ │ RS=rand(64bit); SS=rand(256bit)
169 │ enc(PSK, R+1, SPubKey); enc(K, R, RS+SS)│
170 │ <────────────────────────────────────────
173 │ │ K=DH(CPrivKey, SPubKey) │
177 │ │ RC=rand(64bit); SC=rand(256bit) │
180 │ enc(K, R+1, RS+RC+SC) │
181 │ ────────────────────────────────────────>
188 │ │ │ MasterKey=SS XOR SC
192 │ <────────────────────────────────────────
199 │ │ MasterKey=SS XOR SC │
205 * client generates CPubKey, random 64bit R that is used as a nonce
207 * R + enc(PSK, R, CPubKey) + NULLs -> Server [56 bytes]
208 * server remembers clients address, decrypt CPubKey, generates
209 SPrivKey/SPubKey, computes common shared key K (based on
210 CPubKey and SPrivKey), generates 64bit random number RS and
211 256bit random SS. PSK-encryption uses incremented R (from previous
213 * enc(PSK, SPubKey) + enc(K, RS + SS) + NULLs -> Client [88 bytes]
214 * client decrypt SPubKey, computes K, decrypts RS, SS with key K,
215 remembers SS, generates 64bit random number RC and 256bit random SC,
216 * enc(K, RS + RC + SC) + NULLs -> Server [64 bytes]
217 * server decrypt RS, RC, SC with key K, compares RS with it's own one
218 send before, computes final main encryption key S = SS XOR SC
219 * ENC(K, RC) + NULLs -> Client [24 bytes]
220 * server switches to the new client
221 * client decrypts RC and compares with it's own generated one, computes
222 final main encryption key S
224 Where PSK is 256bit pre-shared key, NULLs are 16 null-bytes. R* are
225 required for handshake randomization and two-way authentication. K key
226 is used only during handshake. NULLs are required to differentiate
227 common transport protocol messages from handshake ones. DH public keys
228 can be trivially derived from private ones.
233 * http://cr.yp.to/ecdh.html
234 * http://cr.yp.to/snuffle.html
235 * http://cr.yp.to/mac.html
236 * http://grouper.ieee.org/groups/1363/passwdPK/contributions/jablon.pdf
237 * Applied Cryptography (C) 1996 Bruce Schneier
241 * Move decryption and encryption processes into goroutines
242 * Add identity management (client can send it's identification, server has
243 on-disk id↔key plaintext database)
244 * Implement alternative Secure Remote Password protocol (it is much slower,
245 technically has more code, but human memorized passwords can be used
250 This program is free software: you can redistribute it and/or modify
251 it under the terms of the GNU General Public License as published by
252 the Free Software Foundation, either version 3 of the License, or
255 This program is distributed in the hope that it will be useful,
256 but WITHOUT ANY WARRANTY; without even the implied warranty of
257 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
258 GNU General Public License for more details.