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.git 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 At first you have to generate client's authentication key and client's
234 unique identification. There is @code{utils/newclient.sh} script for
238 % ./utils/newclient.sh Alice
239 peers/9b40701bdaf522f2b291cb039490312/Alice
242 @code{9b40701bdaf522f2b291cb039490312} is client's identification.
243 @code{Alice} is just an empty file that can help to search them like
244 this: @verb{|find peers -name Alice|}. @code{key} file inside peer's
245 directory contains authentication key.
247 GNU/Linux IPv4 client-server example:
250 server% echo "#!/bin/sh" > peers/CLIENTID/up.sh
251 server% echo "echo tap10" >> peers/CLIENTID/up.sh
252 server% chmod 500 peers/CLIENTID/up.sh
253 server% ip addr add 192.168.0.1/24 dev wlan0
254 server% tunctl -t tap10
255 server% ip link set mtu 1462 dev tap10
256 server% ip addr add 172.16.0.1/24 dev tap10
257 server% ip link set up dev tap10
258 server% GOMAXPROC=4 govpn-server -bind 192.168.0.1:1194
263 client% echo MYLONG64HEXKEY > key.txt
264 client% ip addr add 192.168.0.2/24 dev wlan0
265 client% tunctl -t tap10
266 client% ip link set mtu 1462 dev tap10
267 client% ip addr add 172.16.0.2/24 dev tap10
268 client% ip link set up dev tap10
269 client% ip route add default via 172.16.0.1
270 client% export GOMAXPROC=4
272 govpn-client -key key.txt -id CLIENTID -iface tap10 -remote 192.168.0.1:1194
276 FreeBSD IPv6 client-server example:
279 server% cat > peers/CLIENTID/up.sh <<EOF
281 $tap=$(ifconfig tap create)
282 ifconfig $tap inet6 fc00::1/96 mtu 1462 up
285 server% chmod 500 peers/CLIENTID/up.sh
286 server% ifconfig em0 inet6 fe80::1/64
287 server% GOMAXPROC=4 govpn-server -bind fe80::1%em0
291 client% ifconfig me0 inet6 -ifdisabled auto_linklocal
292 client% ifconfig tap10
293 client% ifconfig tap10 inet6 fc00::2/96 mtu 1462 up
294 client% route -6 add default fc00::1
295 client% export GOMAXPROC=4
297 govpn-client -key key.txt -id CLIENTID -iface tap10 -remote [fe80::1%me0]:1194
304 client% cat > up.sh <<EOF
309 client% chmod +x up.sh
310 client% govpn -id CLIENTID -key key.txt -iface tap10 -remote [fe80::1%me0]:1194 -up ./up.sh
313 Client will exit if won't finish handshake during @code{-timeout}.
314 If no packets are received from remote side during timeout, then daemon
315 will stop sending packets to the client and client will exit. In all
316 cases you have to rehandshake again.
318 @node Developer manual
319 @unnumbered Developer manual
322 @item Nonce and identification encryption
323 @url{http://143.53.36.235:8080/tea.htm, XTEA}
324 @item Data encryption
325 @url{http://cr.yp.to/snuffle.html, Salsa20}
326 @item Message authentication
327 @url{http://cr.yp.to/mac.html, Poly1305}
328 @item Password authenticated key agreement
329 DH-EKE powered by @url{http://cr.yp.to/ecdh.html, Curve25519}
330 @item Packet overhead
332 @item Handshake overhead
333 4 UDP (2 from client, 2 from server) packets, 240 bytes total payload
337 * Transport protocol::
338 * Handshake protocol::
341 @node Transport protocol
342 @section Transport protocol
345 ENCn(SERIAL) + ENC(KEY, ENCn(SERIAL), DATA) +
346 AUTH(ENCn(SERIAL) + ENC(KEY, ENCn(SERIAL), DATA))
349 Each transport message is indistinguishable from pseudo random noise.
351 @code{SERIAL} is message's serial number. Odds are reserved for
352 client(→server) messages, evens for server(→client) messages.
354 @code{ENCn} is XTEA block cipher algorithm used here as PRP (pseudo
355 random permutation) to randomize, obfuscate @code{SERIAL}. Plaintext
356 @code{SERIAL} state is kept in peers internal state, but encrypted
357 before transmission. XTEA is compact and fast enough. Salsa20 is PRF
358 function and requires much more code to create PRP from it. XTEA's
359 encryption key is the first 128-bit of Salsa20's output with established
360 common key and zero nonce (message nonces start from 1).
362 Encrypted @code{SERIAL} is used as a nonce for @code{DATA} encryption:
363 encryption key is different during each handshake, so (key, nonce) pair
364 is always used only once. @code{ENC} is Salsa20 cipher, with established
365 session @code{KEY} and encrypted @code{SERIAL} used as a nonce.
367 @code{AUTH} is Poly1305 authentication function. First 256 bits of
368 Salsa20 output are used as a one-time key for @code{AUTH}. Next 256 bits
369 of Salsa20 are ignored. All remaining output is XORed with the data,
372 To prevent replay attacks we remember latest @code{SERIAL} from the
373 remote peer. If received message's @code{SERIAL} is not greater that the
374 saved one, then drop it. Optionally, because some UDP packets can be
375 reordered during transmission, we can allow some window for valid
376 serials with the @code{-noncediff} option. @code{-noncediff 10} with
377 current saved serial state equals to 78 allows messages with 68…78
378 serials. That time window can be used by attacker to replay packets, so
379 by default it equals to 1. However it can improve performance because of
380 rearranged UDP packets.
382 @node Handshake protocol
383 @section Handshake protocol
385 @verbatiminclude handshake.utxt
389 client generates @code{CPubKey}, random 64bit @code{R} that is used as a
390 nonce for encryption, and an encrypted @code{R} with XTEA, where the key
391 equals to client's identity
393 @verb{|R + enc(PSK, R, CPubKey) + xtea(ID, R) + NULL + NULLs -> Server|} [65 bytes]
395 server remembers clients address, decrypt @code{CPubKey}, generates
396 @code{SPrivKey}/@code{SPubKey}, computes common shared key @code{K}
397 (based on @code{CPubKey} and @code{SPrivKey}), generates 64bit random
398 number @code{RS} and 256bit random @code{SS}. PSK-encryption uses
399 incremented @code{R} (from previous message) for nonce
401 @verb{|enc(PSK, R+1, SPubKey) + enc(K, R, RS + SS) + NULLs -> Client|} [88 bytes]
403 client decrypt @code{SPubKey}, computes @code{K}, decrypts @code{RS},
404 @code{SS} with key @code{K}, remembers @code{SS}, generates 64bit random
405 number @code{RC} and 256bit random @code{SC},
407 @verb{|enc(K, R+1, RS + RC + SC) + NULLs -> Server|} [64 bytes]
409 server decrypt @code{RS}, @code{RC}, @code{SC} with key @code{K},
410 compares @code{RS} with it's own one send before, computes final main
411 encryption key @code{S = SS XOR SC}
413 @verb{|ENC(K, 0, RC) + NULLs -> Client|} [24 bytes]
415 server switches to the new client
417 client decrypts @code{RC} and compares with it's own generated one,
418 computes final main encryption key @code{S}
421 Where PSK is 256bit pre-shared key, @code{NULLs} are 16 null-bytes.
422 @code{R*} are required for handshake randomization and two-way
423 authentication. K key is used only during handshake. @code{NULLs} are
424 required to differentiate common transport protocol messages from
425 handshake ones. DH public keys can be trivially derived from private
429 @unnumbered Reporting bugs
431 Please send all your bug requests, patches and related questions to
432 @email{govpn-devel@@lists.cypherpunks.ru} mailing list.
433 Visit @url{https://lists.cypherpunks.ru/mailman/listinfo/govpn-devel}
434 for information about subscription options and archived messages access.
436 Official website is @url{http://www.cypherpunks.ru/govpn/}, also available
437 as @url{https://www.torproject.org/, Tor} hidden service:
438 @url{http://vabu56j2ep2rwv3b.onion/govpn/}.
439 Development Git source code repository currently is located here:
440 @url{https://github.com/stargrave/govpn.git}.
442 @node Copying conditions
443 @unnumbered Copying conditions