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.
23 This manual is for GoVPN -- simple secure free software virtual private
24 network (VPN) daemon, written entirely on Go programming language.
34 * Copying conditions::
40 GoVPN is simple secure virtual private network daemon. It uses
41 @url{https://en.wikipedia.org/wiki/Encrypted_key_exchange, Diffie-Hellman Encrypted Key Exchange}
42 (DH-EKE) for mutual zero-knowledge peers authentication and
43 authenticated encrypted data transport. It is written entirely on
44 @url{http://golang.org/, Go programming language}.
46 All packets captured on network interface are encrypted, authenticated
47 and sent to remote server, that writes them to his interface, and vice
48 versa. Client and server use pre-shared authentication key (PSK) and
49 128-bit identification key.
51 Because of stateless UDP nature, after some timeout of inactivity peers
52 forget about each other and have to retry handshake process again,
53 therefore background heartbeat process will be ran.
55 Handshake is used to mutually authenticate peers, exchange common secret
56 per-session encryption key and check UDP transport availability.
58 Because of UDP and authentication overhead: each packet grows in size
59 during transmission, so you have to lower you maximum transmission unit
60 (MTU) on virtual network interface.
62 High security is the goal for that daemon. It uses fast cryptography
63 algorithms with 128bit security margin, strong mutual zero-knowledge
64 authentication and perfect-forward secrecy property. An attacker can not
65 know anything about payload (except it's size and time) from captured
66 traffic, even if pre-shared key is compromised. Rehandshake is performed
67 by client every 4 GiB of transfered data.
69 Each client also has it's own identification key and server works with
70 all of them independently. Identification key is not secret, but it is
71 encrypted (obfuscated) during transmission.
73 The only platform specific requirement is TAP network interface support.
74 API to that kind of device is different, OS dependent and non portable.
75 So only a few operating systems is officially supported. Author has no
76 proprietary software to work with, so currently there is lack of either
77 popular Microsoft Windows or Apple OS X support.
81 Works with @url{https://en.wikipedia.org/wiki/TAP_(network_driver), TAP}
82 network interfaces on top of UDP entirely
84 @url{https://www.gnu.org/, GNU}/Linux and
85 @url{http://www.freebsd.org/, FreeBSD} support
87 @item Encrypted and authenticated transport
88 @item Relatively fast handshake
90 @url{https://en.wikipedia.org/wiki/Replay_attack, Replay attack} protection
92 @url{https://en.wikipedia.org/wiki/Forward_secrecy, Perfect forward secrecy}
93 (if long-term pre-shared keys are compromised, no captured traffic can
96 Mutual two-side authentication (noone will send real network interface
97 data unless the other side is authenticated)
99 @url{https://en.wikipedia.org/wiki/Zero-knowledge_password_proof, Zero knowledge}
100 authentication (pre-shared key is not transmitted in any form between
101 the peers, not even it's hash value)
102 @item Built-in rehandshake and heartbeat features
103 @item Several simultaneous clients support
109 @verbatiminclude ../NEWS
112 @unnumbered Installation
114 GoVPN is written on Go programming language, But
115 @url{https://www.gnu.org/software/make/, Make} program is recommended
116 also to be used. @url{https://www.gnu.org/software/texinfo/, Texinfo} is
117 used for building documentation. Also it depends on
118 @code{golang.org/x/crypto} Go libraries.
120 @include download.texi
122 You @strong{have to} verify downloaded archives integrity and check
123 their signature to be sure that you have got trusted, untampered
124 software. For integrity and authentication of downloaded binaries
125 @url{https://www.gnupg.org/, The GNU Privacy Guard} is used. You must
126 download signature provided with the tarball and run for example:
129 gpg --verify govpn-1.5.tar.xz.sig govpn-1.5.tar.xz
132 For the very first time you must also import signing public keys. They
133 are provided below, but be sure that you are reading them from the
134 trusted source. Alternatively check this page from other sources and
135 look for the mailing list announcements.
137 You have to set up @code{$GOPATH} properly first. For example you can
138 clone the repository or decompress tarball and set path like this:
142 % git clone https://github.com/stargrave/govpn govpn/src/govpn
144 % tar xfC govpn-1.5.tar.xz govpn/src && mv govpn/src/govpn-1.5 govpn/src/govpn
145 % export GOPATH=$(pwd)/govpn:$GOPATH
148 After that you can just type @code{make} and all necessary Go libraries
149 will be installed and client/server binaries are built in the current
155 [or gmake under FreeBSD]
161 @unnumbered Precautions
163 The very important precaution is the @strong{cryptographically good}
164 pseudo random number generator. GoVPN uses native operating system PRNG
165 as entropy source. You have no way to check it's quality in closed
166 source code operating systems, so it is recommended not to use them if
167 you really needs security. Moreover it is possible that those OS leaks
168 information about possible PRNG states. And at least Apple OS X and
169 Microsoft Windows are already known to have weak CSPRNGs.
171 GoVPN could use it's own PRNG implementation like
172 @url{https://www.schneier.com/fortuna.html, Fortuna}, but it is
173 much easier to use the right OS, to use free software.
175 Also you should @strong{never} use one key for multiple clients. Salsa20
176 encryption is randomized in each session, but it depends again on PRNG.
177 If it fails, produces equal values at least once, then all you traffic
178 related to that key could be decrypted.
181 @unnumbered User manual
183 GoVPN is split into two pieces: client and server. Each of them work on
184 top of UDP and TAP virtual network interfaces. Client and server have
185 several common configuration command line options:
189 Because of stateless UDP nature there is no way to know if
190 remote peer is dead, but after some timeout. Client and server
191 heartbeats each other every third part of heartbeat. Also this timeout
192 is the time when server purge his obsolete handshake and peers states.
193 @item Allowable nonce difference
194 To prevent replay attacks we just remembers
195 latest received nonce number from the remote peer and drops those who
196 has lower ones. Because UDP packets can be reordered during: that
197 behaviour can lead to dropping of not replayed ones. This options gives
198 ability to create some window of allows difference. That opens the door
199 for replay attacks for narrow time interval.
201 Maximum transmission unit.
204 Client needs to know his identification, path to the authentication key,
205 remote server's address, TAP interface name, and optional path to up and
206 down scripts, that will be executed after connection is either initiated
209 Server needs to know only the address to listen on and path to directory
210 containing peers information. This directory must contain subdirectories
211 with the names equal to client's identifications. Each of them must have
212 key file with corresponding authentication key, up.sh script that has to
213 print interface's name on the first line and optional down.sh.
220 @section Example usage
222 Let's assume that there is some insecure link between your computer and
223 WiFi-reachable gateway. You have got preconfigured @code{wlan0} network
224 interface with 192.168.0/24 network. You want to create virtual
225 encrypted and authenticated 172.16.0/24 network and use it as a default
226 transport. MTU for that wlan0 is 1500 bytes. GoVPN will say that maximum
227 MTU for the link is 1476, however it does not take in account TAP's
228 Ethernet frame header length, that in my case is 14 bytes long (1476 - 14).
230 Do not forget about setting @code{GOMAXPROC} environment variable for
231 using more than one CPU.
233 GNU/Linux IPv4 client-server example:
236 server% mkdir -p peers/CLIENTID
238 server% echo MYLONG64HEXKEY > peers/CLIENTID/key
239 server% echo "#!/bin/sh" > peers/CLIENTID/up.sh
240 server% echo "echo tap10" > peers/CLIENTID/up.sh
241 server% chmod 500 peers/CLIENTID/up.sh
242 server% ip addr add 192.168.0.1/24 dev wlan0
243 server% tunctl -t tap10
244 server% ip link set mtu 1462 dev tap10
245 server% ip addr add 172.16.0.1/24 dev tap10
246 server% ip link set up dev tap10
247 server% GOMAXPROC=4 govpn-server -bind 192.168.0.1:1194
252 client% echo MYLONG64HEXKEY > key.txt
253 client% ip addr add 192.168.0.2/24 dev wlan0
254 client% tunctl -t tap10
255 client% ip link set mtu 1462 dev tap10
256 client% ip addr add 172.16.0.2/24 dev tap10
257 client% ip link set up dev tap10
258 client% ip route add default via 172.16.0.1
259 client% export GOMAXPROC=4
261 govpn-client -key key.txt -id CLIENTID -iface tap10 -remote 192.168.0.1:1194
265 FreeBSD IPv6 client-server example:
268 server% mkdir -p peers/CLIENTID
270 server% echo MYLONG64HEXKEY > peers/CLIENTID/key
271 server% echo "#!/bin/sh" >
272 server% cat > peers/CLIENTID/up.sh <<EOF
274 $tap=$(ifconfig tap create)
275 ifconfig $tap inet6 fc00::1/96 mtu 1462 up
278 server% chmod 500 peers/CLIENTID/up.sh
279 server% ifconfig em0 inet6 fe80::1/64
280 server% GOMAXPROC=4 govpn-server -bind fe80::1%em0
284 client% ifconfig me0 inet6 -ifdisabled auto_linklocal
285 client% ifconfig tap10
286 client% ifconfig tap10 inet6 fc00::2/96 mtu 1462 up
287 client% route -6 add default fc00::1
288 client% export GOMAXPROC=4
290 govpn-client -key key.txt -id CLIENTID -iface tap10 -remote [fe80::1%me0]:1194
297 client% cat > up.sh <<EOF
302 client% chmod +x up.sh
303 client% govpn -id CLIENTID -key key.txt -iface tap10 -remote [fe80::1%me0]:1194 -up ./up.sh
306 Client will exit if won't finish handshake during @code{-timeout}.
307 If no packets are received from remote side during timeout, then daemon
308 will stop sending packets to the client and client will exit. In all
309 cases you have to rehandshake again.
311 @node Developer manual
312 @unnumbered Developer manual
315 @item Nonce and identification encryption
316 @url{http://143.53.36.235:8080/tea.htm, XTEA}
317 @item Data encryption
318 @url{http://cr.yp.to/snuffle.html, Salsa20}
319 @item Message authentication
320 @url{http://cr.yp.to/mac.html, Poly1305}
321 @item Password authenticated key agreement
322 @url{http://cr.yp.to/ecdh.html, Curve25519} based DH-EKE
323 @item Packet overhead
325 @item Handshake overhead
326 4 UDP (2 from client, 2 from server) packets, 240 bytes total payload
330 * Transport protocol::
331 * Handshake protocol::
334 @node Transport protocol
335 @section Transport protocol
338 ENCn(SERIAL) + ENC(KEY, ENCn(SERIAL), DATA) +
339 AUTH(ENCn(SERIAL) + ENC(KEY, ENCn(SERIAL), DATA))
342 Each transport message is indistinguishable from pseudo random noise.
344 @code{SERIAL} is message's serial number. Odds are reserved for
345 client(→server) messages, evens for server(→client) messages.
347 @code{ENCn} is XTEA block cipher algorithm used here as PRP (pseudo
348 random permutation) to randomize, obfuscate @code{SERIAL}. Plaintext
349 @code{SERIAL} state is kept in peers internal state, but encrypted
350 before transmission. XTEA is compact and fast enough. Salsa20 is PRF
351 function and requires much more code to create PRP from it. XTEA's
352 encryption key is the first 128-bit of Salsa20's output with established
353 common key and zero nonce (message nonces start from 1).
355 Encrypted @code{SERIAL} is used as a nonce for @code{DATA} encryption:
356 encryption key is different during each handshake, so (key, nonce) pair
357 is always used only once. @code{ENC} is Salsa20 cipher, with established
358 session @code{KEY} and encrypted @code{SERIAL} used as a nonce.
360 @code{AUTH} is Poly1305 authentication function. First 256 bits of
361 Salsa20 output are used as a one-time key for @code{AUTH}. Next 256 bits
362 of Salsa20 are ignored. All remaining output is XORed with the data,
365 To prevent replay attacks we remember latest @code{SERIAL} from the
366 remote peer. If received message's @code{SERIAL} is not greater that the
367 saved one, then drop it. Optionally, because some UDP packets can be
368 reordered during transmission, we can allow some window for valid
369 serials with the @code{-noncediff} option. @code{-noncediff 10} with
370 current saved serial state equals to 78 allows messages with 68…78
371 serials. That time window can be used by attacker to replay packets, so
372 by default it equals to 1. However it can improve performance because of
373 rearranged UDP packets.
375 @node Handshake protocol
376 @section Handshake protocol
378 @verbatiminclude handshake.utxt
382 client generates @code{CPubKey}, random 64bit @code{R} that is used as a
383 nonce for encryption, and an encrypted @code{R} with XTEA, where the key
384 equals to client's identity
386 @verb{|R + enc(PSK, R, CPubKey) + xtea(ID, R) + NULL + NULLs -> Server|} [65 bytes]
388 server remembers clients address, decrypt @code{CPubKey}, generates
389 @code{SPrivKey}/@code{SPubKey}, computes common shared key @code{K}
390 (based on @code{CPubKey} and @code{SPrivKey}), generates 64bit random
391 number @code{RS} and 256bit random @code{SS}. PSK-encryption uses
392 incremented @code{R} (from previous message) for nonce
394 @verb{|enc(PSK, SPubKey) + enc(K, RS + SS) + NULLs -> Client|} [88 bytes]
396 client decrypt @code{SPubKey}, computes @code{K}, decrypts @code{RS},
397 @code{SS} with key @code{K}, remembers @code{SS}, generates 64bit random
398 number @code{RC} and 256bit random @code{SC},
400 @verb{|enc(K, RS + RC + SC) + NULLs -> Server|} [64 bytes]
402 server decrypt @code{RS}, @code{RC}, @code{SC} with key @code{K},
403 compares @code{RS} with it's own one send before, computes final main
404 encryption key @code{S = SS XOR SC}
406 @verb{|ENC(K, RC) + NULLs -> Client|} [24 bytes]
408 server switches to the new client
410 client decrypts @code{RC} and compares with it's own generated one,
411 computes final main encryption key @code{S}
414 Where PSK is 256bit pre-shared key, @code{NULLs} are 16 null-bytes.
415 @code{R*} are required for handshake randomization and two-way
416 authentication. K key is used only during handshake. @code{NULLs} are
417 required to differentiate common transport protocol messages from
418 handshake ones. DH public keys can be trivially derived from private
422 @unnumbered Reporting bugs
424 Please send all your bug requests, patches and related questions to
425 @email{govpn-devel@@lists.cypherpunks.ru} mailing list.
426 Visit @url{https://lists.cypherpunks.ru/mailman/listinfo/govpn-devel}
427 for information about subscription options and archived messages access.
429 Development Git source code repository currently is located on:
430 @url{https://github.com/stargrave/govpn}.
432 @node Copying conditions
433 @unnumbered Copying conditions