2 @setfilename govpn.info
3 @documentencoding UTF-8
8 This program is free software: you can redistribute it and/or modify
9 it under the terms of the GNU General Public License as published by
10 the Free Software Foundation, either version 3 of the License, or
13 This program is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 GNU General Public License for more details.
24 This manual is for GoVPN -- simple secure free software
25 virtual private network (VPN) daemon.
31 * Getting source code::
35 * Copying conditions::
41 GoVPN is simple secure virtual private network daemon. It uses
42 Diffie-Hellman Encrypted Key Exchange (DH-EKE) for mutual zero-knowledge
43 peers authentication and authenticated encrypted data transport.
45 All packets captured on network interface are encrypted, authenticated
46 and sent to remote server, that writes them to his interface, and vice
47 versa. Client and server use pre-shared authentication key (PSK) and
48 128-bit identification key.
50 Because of stateless UDP nature, after some timeout of inactivity peers
51 forget about each other and have to retry handshake process again,
52 therefore background heartbeat process will be ran.
54 Handshake is used to mutually authenticate peers, exchange common secret
55 per-session encryption key and check UDP transport availability.
57 Because of UDP and authentication overhead: each packet grows in size
58 during transmission, so you have to lower you maximum transmission unit
59 (MTU) on virtual network interface.
61 High security is the goal for that daemon. It uses fast cryptography
62 algorithms with 128bit security margin, strong mutual zero-knowledge
63 authentication and perfect-forward secrecy property. An attacker can not
64 know anything about payload (except it's size and time) from captured
65 traffic, even if pre-shared key is compromised. Rehandshake is performed
66 by client every 4 GiB of transfered data.
68 Each client also has it's own identification key and server works with
69 all of them independently. Identification key is not secret, but it is
70 encrypted (obfuscated) during transmission.
73 @item GNU/Linux and FreeBSD support
75 @item Encrypted and authenticated transport
76 @item Relatively fast handshake
77 @item Replay attack protection
79 Perfect forward secrecy (if long-term pre-shared keys are compromised,
80 no captured traffic can be decrypted anyway)
82 Mutual two-side authentication (noone will send real network interface
83 data unless the other side is authenticated)
85 Zero knowledge authentication (pre-shared key is not transmitted in
86 any form between the peers, not even it's hash value)
87 @item Built-in rehandshake and heartbeat features
88 @item Several simultaneous clients support
94 @verbatiminclude ../NEWS
96 @node Getting source code
97 @unnumbered Getting source code
99 GoVPN is written on Go programming language and depends on
100 @code{golang.org/x/crypto} libraries.
102 @include download.texi
104 You @strong{have to} verify downloaded archives integrity and check
105 their signature to be sure that you have got trusted, untampered
106 software. For integrity and authentication of downloaded binaries
107 @url{https://www.gnupg.org/, The GNU Privacy Guard} is used. You must
108 download signature provided with the tarball and run for example:
111 gpg --verify govpn-1.5.tar.xz.sig govpn-1.5.tar.xz
114 For the very first time you must also import signing public keys. They
115 are provided below, but be sure that you are reading them from the
116 trusted source. Alternatively check this page from other sources and
117 look for the mailing list announcements.
120 pub rsa2048/FFE2F4A1 2015-03-10
121 uid [ultimate] Sergey Matveev (GoVPN release signing key) <stargrave@stargrave.org>
122 sub rsa2048/8A6C750A 2015-03-10
124 -----BEGIN PGP PUBLIC KEY BLOCK-----
126 mQENBFT/H6cBCADTf/oqoTTBAA/CCQuYtzg8vrXxyjXj9yy4lTWqMSwgLXMm8br/
127 kG0Jnk63oP3hggI3hm2mpuiNwpwrJiORLBZCe8JgZW71zG4LfhVpQeWd7fu8WxDx
128 0uUZWByz5KcK8c/kNWNDpSkMmmqdE/8v0YDFbsz5U+ytp/Kki/gj3BCeIX3jYOL1
129 fxczkv2okoU+aGYXt9z50VzheLUSRLzkkX8yNSpszqfB0LEEmUk8HO2fSS/bXwaY
130 ZXX5//suH8V5hwq8vB8dHHCquZW6blyzcTa2KGIh6g2CmpypIQp/i5QAbzOCHKTM
131 A1F7A1r0kYF2WfZOrycCfjUx3GA5B7sytuA3ABEBAAG0RFNlcmdleSBNYXR2ZWV2
132 IChHb1ZQTiByZWxlYXNlIHNpZ25pbmcga2V5KSA8c3RhcmdyYXZlQHN0YXJncmF2
133 ZS5vcmc+iQE8BBMBCAAmBQJU/x+nAhsDCAsKCQgHBAMCBxUKCQgLAwIFFgIBAwAC
134 HgECF4AACgkQ8vWQRf/i9KEZ/AgAqYF/RRNwwhgLgFqTLfw3ha0FeiSso7H9ITDo
135 cdJ/domLHaFvmwFIDQQKV8Zd1Rnj6xTCs2bq2O5hYMLrFZg85A9i5tLwkgFc9J5G
136 +8K3K/dh9Y4pArbM+craO+xydrwLyg1zlXCezthWbL0iXO/CuGiuBBCZJqRJ9HV4
137 cZr4TRA3Znm5nt96rRsR86XqOgr0iOEDtYKfKW/IzDqOEgXUN5o2bUwuQawe9Y8d
138 CngXzJcfb2eJ/TqSP9CxVWscjz4sAmD3/ECrHSjX7xsusIs46F2+VMlEXFuST52r
139 zamfiGKlol8XvimUjKhlMWjqfdcJ0+jvFftsa7HXQUwRoQ1vJYheBBARCAAGBQJU
140 /x/VAAoJEK4agQnkmFfvqn8A/ReK2ZZrnI9s0rzTsF1jrTZ1o5YowuINOzVMmLbE
141 aYuGAP4iGwPgwVbANu4dWaP2N03oL4xFtmdaeNn3sB9ZqJOOyrkBDQRU/x+nAQgA
142 uYBRyJVwhlE2SRIEmMggwr4gq1JBM2Ge5O46usf+YPUjCJKWoAj+MpQoq7r+oA/s
143 E/6kGvWgngwV9prCdNkvcdwEWbb+n9PcMc2ZuIGRV3iOKYlYEBFV0bfM9zEV2jar
144 1YQ+J/48UX7R00cYJuXel7Dy77V9eNd+Ukyowm93fggFlBDBGBjVbNtfIorHNYjB
145 01CCu3i/8yxrMyFRvMKyAVEGp3obgmlam4DNkNIhFMv3du0tFnDFBsZf7N0kbLWI
146 xEEJoc/jxaezDytQpUr3RhlMsLV6N/jjIZuy36QO1sbFeOe2to0E7ixaFzNCWsqY
147 cxUfnJ3wi7hOiOwE2PF3tQARAQABiQEfBBgBCAAJBQJU/x+nAhsMAAoJEPL1kEX/
148 4vShrVcIAKLUwMn7WgK6thmwPjdwP5V/jTlsWLWk2O/LEN4W/R0mw2hRsgRG/8Sz
149 qlAP6vfl7ERaWuyL+fp72rKnGTGU9CEvn6PKmaG7bi4tGEvWXscNc10r0leIAP63
150 pkQOa6Nyx2axJlJdSuTsYetd1ZgNpHNng+lxSUBlkPMOhPd/P/Ok7DShZjd2jhQ1
151 jUbjWn+P7ARGEvgdd5utNjy/RaSwrLG8NXj3I+XuksG0/TPeG0zu9NOPzWZq9sCc
152 5VbDNJTYtsMFs1etHE95Efmx6yUquQyB+g/HgvkH/LzthBawVVHxZNzzHgc6KN5w
153 E0itJPXMaQL+juUfiNM0i2R1O8nJo14=
155 -----END PGP PUBLIC KEY BLOCK-----
159 @unnumbered User manual
161 GoVPN is split into two pieces: client and server. Each of them work on
162 top of UDP and TAP virtual network interfaces. Client and server have
163 several common configuration command line options:
167 Because of stateless UDP nature there is no way to know if
168 remote peer is dead, but after some timeout. Client and server
169 heartbeats each other every third part of heartbeat. Also this timeout
170 is the time when server purge his obsolete handshake and peers states.
171 @item Allowable nonce difference
172 To prevent replay attacks we just remembers
173 latest received nonce number from the remote peer and drops those who
174 has lower ones. Because UDP packets can be reordered during: that
175 behaviour can lead to dropping of not replayed ones. This options gives
176 ability to create some window of allows difference. That opens the door
177 for replay attacks for narrow time interval.
179 Maximum transmission unit.
182 Client needs to know his identification, path to the authentication key,
183 remote server's address, TAP interface name, and optional path to up and
184 down scripts, that will be executed after connection is either initiated
187 Server needs to know only the address to listen on and path to directory
188 containing peers information. This directory must contain subdirectories
189 with the names equal to client's identifications. Each of them must have
190 key file with corresponding authentication key, up.sh script that has to
191 print interface's name on the first line and optional down.sh.
198 @section Example usage
200 Let's assume that there is some insecure link between your computer and
201 WiFi-reachable gateway. You have got preconfigured @code{wlan0} network
202 interface with 192.168.0/24 network. You want to create virtual
203 encrypted and authenticated 172.16.0/24 network and use it as a default
204 transport. MTU for that wlan0 is 1500 bytes. GoVPN will say that maximum
205 MTU for the link is 1476, however it does not take in account TAP's
206 Ethernet frame header length, that in my case is 14 bytes long (1476 - 14).
208 GNU/Linux IPv4 client-server example:
211 server% mkdir -p peers/CLIENTID
213 server% echo MYLONG64HEXKEY > peers/CLIENTID/key
214 server% echo "#!/bin/sh" > peers/CLIENTID/up.sh
215 server% echo "echo tap10" > peers/CLIENTID/up.sh
216 server% chmod 500 peers/CLIENTID/up.sh
217 server% ip addr add 192.168.0.1/24 dev wlan0
218 server% tunctl -t tap10
219 server% ip link set mtu 1462 dev tap10
220 server% ip addr add 172.16.0.1/24 dev tap10
221 server% ip link set up dev tap10
222 server% govpn -bind 192.168.0.1:1194
227 client% echo MYLONG64HEXKEY > key.txt
228 client% ip addr add 192.168.0.2/24 dev wlan0
229 client% tunctl -t tap10
230 client% ip link set mtu 1462 dev tap10
231 client% ip addr add 172.16.0.2/24 dev tap10
232 client% ip link set up dev tap10
233 client% ip route add default via 172.16.0.1
235 govpn -key key.txt -id CLIENTID -iface tap10 -remote 192.168.0.1:1194
239 FreeBSD IPv6 client-server example:
242 server% mkdir -p peers/CLIENTID
244 server% echo MYLONG64HEXKEY > peers/CLIENTID/key
245 server% echo "#!/bin/sh" >
246 server% cat > peers/CLIENTID/up.sh <<EOF
248 $tap=$(ifconfig tap create)
249 ifconfig $tap inet6 fc00::1/96 mtu 1462 up
252 server% chmod 500 peers/CLIENTID/up.sh
253 server% ifconfig em0 inet6 fe80::1/64
254 server% govpn -bind fe80::1%em0
258 client% ifconfig me0 inet6 -ifdisabled auto_linklocal
259 client% ifconfig tap10
260 client% ifconfig tap10 inet6 fc00::2/96 mtu 1462 up
261 client% route -6 add default fc00::1
263 govpn -key key.txt -id CLIENTID -iface tap10 -remote [fe80::1%me0]:1194
270 client% cat > up.sh <<EOF
275 client% chmod +x up.sh
276 client% govpn -id CLIENTID -key key.txt -iface tap10 -remote [fe80::1%me0]:1194 -up ./up.sh
279 Client will exit if won't finish handshake during @code{-timeout}.
280 If no packets are received from remote side during timeout, then daemon
281 will stop sending packets to the client and client will exit. In all
282 cases you have to rehandshake again.
284 @node Developer manual
285 @unnumbered Developer manual
288 @item Nonce and identification encryption
290 @item Data encryption
292 @item Message authentication
294 @item Password authenticated key agreement
295 Curve25519 based DH-EKE
296 @item Packet overhead
298 @item Handshake overhead
299 4 UDP (2 from client, 2 from server) packets, 240 bytes total payload
303 * Transport protocol::
304 * Handshake protocol::
307 @node Transport protocol
308 @section Transport protocol
311 ENCn(SERIAL) + ENC(KEY, ENCn(SERIAL), DATA) +
312 AUTH(ENCn(SERIAL) + ENC(KEY, ENCn(SERIAL), DATA))
315 Each transport message is indistinguishable from pseudo random noise.
317 @code{SERIAL} is message's serial number. Odds are reserved for client(→server)
318 messages, evens for server(→client) messages.
320 @code{ENCn} is XTEA block cipher algorithm used here as PRP (pseudo
321 random permutation) to randomize, obfuscate @code{SERIAL}. Plaintext
322 @code{SERIAL} state is kept in peers internal state, but encrypted
323 before transmission. XTEA is compact and fast enough. Salsa20 is PRF
324 function and requires much more code to create PRP from it. XTEA's
325 encryption key is the first 128-bit of Salsa20's output with established
326 common key and zero nonce (message nonces start from 1).
328 Encrypted @code{SERIAL} is used as a nonce for @code{DATA} encryption:
329 encryption key is different during each handshake, so (key, nonce) pair
330 is always used only once. @code{ENC} is Salsa20 cipher, with established
331 session @code{KEY} and encrypted @code{SERIAL} used as a nonce.
333 @code{AUTH} is Poly1305 authentication function. First 256 bits of
334 Salsa20 output are used as a one-time key for @code{AUTH}. Next 256 bits
335 of Salsa20 are ignored. All remaining output is XORed with the data,
338 To prevent replay attacks we remember latest @code{SERIAL} from the
339 remote peer. If received message's @code{SERIAL} is not greater that the
340 saved one, then drop it. Optionally, because some UDP packets can be
341 reordered during transmission, we can allow some window for valid
342 serials with the @code{-noncediff} option. @code{-noncediff 10} with
343 current saved serial state equals to 78 allows messages with 68…78
344 serials. That time window can be used by attacker to replay packets, so
345 by default it equals to 1. However it can improve performance because of
346 rearranged UDP packets.
348 @node Handshake protocol
349 @section Handshake protocol
351 @verbatiminclude handshake.utxt
355 client generates @code{CPubKey}, random 64bit @code{R} that is used as a
356 nonce for encryption, and an encrypted @code{R} with XTEA, where the key
357 equals to client's identity
359 @verb{|R + enc(PSK, R, CPubKey) + xtea(ID, R) + NULL + NULLs -> Server|} [65 bytes]
361 server remembers clients address, decrypt @code{CPubKey}, generates
362 @code{SPrivKey}/@code{SPubKey}, computes common shared key @code{K}
363 (based on @code{CPubKey} and @code{SPrivKey}), generates 64bit random
364 number @code{RS} and 256bit random @code{SS}. PSK-encryption uses
365 incremented @code{R} (from previous message) for nonce
367 @verb{|enc(PSK, SPubKey) + enc(K, RS + SS) + NULLs -> Client|} [88 bytes]
369 client decrypt @code{SPubKey}, computes @code{K}, decrypts @code{RS},
370 @code{SS} with key @code{K}, remembers @code{SS}, generates 64bit random
371 number @code{RC} and 256bit random @code{SC},
373 @verb{|enc(K, RS + RC + SC) + NULLs -> Server|} [64 bytes]
375 server decrypt @code{RS}, @code{RC}, @code{SC} with key @code{K},
376 compares @code{RS} with it's own one send before, computes final main
377 encryption key @code{S = SS XOR SC}
379 @verb{|ENC(K, RC) + NULLs -> Client|} [24 bytes]
381 server switches to the new client
383 client decrypts @code{RC} and compares with it's own generated one,
384 computes final main encryption key @code{S}
387 Where PSK is 256bit pre-shared key, @code{NULLs} are 16 null-bytes.
388 @code{R*} are required for handshake randomization and two-way
389 authentication. K key is used only during handshake. @code{NULLs} are
390 required to differentiate common transport protocol messages from
391 handshake ones. DH public keys can be trivially derived from private
395 @unnumbered Reporting bugs
397 Please send all your bug requests, patches and related questions to
398 @email{govpn-devel@@lists.cypherpunks.ru} mailing list.
399 Visit @url{https://lists.cypherpunks.ru/mailman/listinfo/govpn-devel}
400 for information about subscription options and archived messages access.
402 Development Git source code repository currently is located on:
403 @url{https://github.com/stargrave/govpn}.
405 @node Copying conditions
406 @unnumbered Copying conditions