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.
29 * Getting and building source code::
33 * Copying conditions::
39 GoVPN is simple secure virtual private network daemon. It uses
40 @url{https://en.wikipedia.org/wiki/Encrypted_key_exchange, Diffie-Hellman Encrypted Key Exchange}
41 (DH-EKE) for mutual zero-knowledge peers authentication and
42 authenticated encrypted data transport. It is written entirely on
43 @url{http://golang.org/, Go programming language}.
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.
72 The only platform specific requirement is TAP network interface support.
73 API to that kind of device is different, OS dependent and non portable.
74 So only a few operating systems is officially supported. Author has no
75 proprietary software to work with, so currently there is lack of either
76 popular Microsoft Windows or Apple OS X support.
80 Works with @url{https://en.wikipedia.org/wiki/TAP_(network_driver), TAP}
81 network interfaces on top of UDP entirely
83 @url{https://www.gnu.org/, GNU}/Linux and
84 @url{http://www.freebsd.org/, FreeBSD} support
86 @item Encrypted and authenticated transport
87 @item Relatively fast handshake
89 @url{https://en.wikipedia.org/wiki/Replay_attack, Replay attack} protection
91 @url{https://en.wikipedia.org/wiki/Forward_secrecy, Perfect forward secrecy}
92 (if long-term pre-shared keys are compromised, no captured traffic can
95 Mutual two-side authentication (noone will send real network interface
96 data unless the other side is authenticated)
98 @url{https://en.wikipedia.org/wiki/Zero-knowledge_password_proof, Zero knowledge}
99 authentication (pre-shared key is not transmitted in any form between
100 the peers, not even it's hash value)
101 @item Built-in rehandshake and heartbeat features
102 @item Several simultaneous clients support
108 @verbatiminclude ../NEWS
110 @node Getting and building source code
111 @unnumbered Getting and building source code
113 GoVPN is written on Go programming language, But
114 @url{https://www.gnu.org/software/make/, Make} program is recommended
115 also to be used. @url{https://www.gnu.org/software/texinfo/, Texinfo} is
116 used for building documentation. Also it depends on
117 @code{golang.org/x/crypto} Go libraries.
119 @include download.texi
121 You @strong{have to} verify downloaded archives integrity and check
122 their signature to be sure that you have got trusted, untampered
123 software. For integrity and authentication of downloaded binaries
124 @url{https://www.gnupg.org/, The GNU Privacy Guard} is used. You must
125 download signature provided with the tarball and run for example:
128 gpg --verify govpn-1.5.tar.xz.sig govpn-1.5.tar.xz
131 For the very first time you must also import signing public keys. They
132 are provided below, but be sure that you are reading them from the
133 trusted source. Alternatively check this page from other sources and
134 look for the mailing list announcements.
136 You have to set up @code{$GOPATH} properly first. For example you can
137 clone the repository or decompress tarball and set path like this:
141 % git clone https://github.com/stargrave/govpn govpn/src/govpn
143 % tar xfC govpn-1.5.tar.xz govpn/src && mv govpn/src/govpn-1.5 govpn/src/govpn
144 % export GOPATH=$(pwd)/govpn:$GOPATH
147 After that you can just type @code{make} and all necessary Go libraries
148 will be installed and client/server binaries are built in the current
154 [or gmake under FreeBSD]
160 @unnumbered User manual
162 GoVPN is split into two pieces: client and server. Each of them work on
163 top of UDP and TAP virtual network interfaces. Client and server have
164 several common configuration command line options:
168 Because of stateless UDP nature there is no way to know if
169 remote peer is dead, but after some timeout. Client and server
170 heartbeats each other every third part of heartbeat. Also this timeout
171 is the time when server purge his obsolete handshake and peers states.
172 @item Allowable nonce difference
173 To prevent replay attacks we just remembers
174 latest received nonce number from the remote peer and drops those who
175 has lower ones. Because UDP packets can be reordered during: that
176 behaviour can lead to dropping of not replayed ones. This options gives
177 ability to create some window of allows difference. That opens the door
178 for replay attacks for narrow time interval.
180 Maximum transmission unit.
183 Client needs to know his identification, path to the authentication key,
184 remote server's address, TAP interface name, and optional path to up and
185 down scripts, that will be executed after connection is either initiated
188 Server needs to know only the address to listen on and path to directory
189 containing peers information. This directory must contain subdirectories
190 with the names equal to client's identifications. Each of them must have
191 key file with corresponding authentication key, up.sh script that has to
192 print interface's name on the first line and optional down.sh.
199 @section Example usage
201 Let's assume that there is some insecure link between your computer and
202 WiFi-reachable gateway. You have got preconfigured @code{wlan0} network
203 interface with 192.168.0/24 network. You want to create virtual
204 encrypted and authenticated 172.16.0/24 network and use it as a default
205 transport. MTU for that wlan0 is 1500 bytes. GoVPN will say that maximum
206 MTU for the link is 1476, however it does not take in account TAP's
207 Ethernet frame header length, that in my case is 14 bytes long (1476 - 14).
209 Do not forget about setting @code{GOMAXPROC} environment variable for
210 using more than one CPU.
212 GNU/Linux IPv4 client-server example:
215 server% mkdir -p peers/CLIENTID
217 server% echo MYLONG64HEXKEY > peers/CLIENTID/key
218 server% echo "#!/bin/sh" > peers/CLIENTID/up.sh
219 server% echo "echo tap10" > peers/CLIENTID/up.sh
220 server% chmod 500 peers/CLIENTID/up.sh
221 server% ip addr add 192.168.0.1/24 dev wlan0
222 server% tunctl -t tap10
223 server% ip link set mtu 1462 dev tap10
224 server% ip addr add 172.16.0.1/24 dev tap10
225 server% ip link set up dev tap10
226 server% GOMAXPROC=4 govpn-server -bind 192.168.0.1:1194
231 client% echo MYLONG64HEXKEY > key.txt
232 client% ip addr add 192.168.0.2/24 dev wlan0
233 client% tunctl -t tap10
234 client% ip link set mtu 1462 dev tap10
235 client% ip addr add 172.16.0.2/24 dev tap10
236 client% ip link set up dev tap10
237 client% ip route add default via 172.16.0.1
238 client% export GOMAXPROC=4
240 govpn-client -key key.txt -id CLIENTID -iface tap10 -remote 192.168.0.1:1194
244 FreeBSD IPv6 client-server example:
247 server% mkdir -p peers/CLIENTID
249 server% echo MYLONG64HEXKEY > peers/CLIENTID/key
250 server% echo "#!/bin/sh" >
251 server% cat > peers/CLIENTID/up.sh <<EOF
253 $tap=$(ifconfig tap create)
254 ifconfig $tap inet6 fc00::1/96 mtu 1462 up
257 server% chmod 500 peers/CLIENTID/up.sh
258 server% ifconfig em0 inet6 fe80::1/64
259 server% GOMAXPROC=4 govpn-server -bind fe80::1%em0
263 client% ifconfig me0 inet6 -ifdisabled auto_linklocal
264 client% ifconfig tap10
265 client% ifconfig tap10 inet6 fc00::2/96 mtu 1462 up
266 client% route -6 add default fc00::1
267 client% export GOMAXPROC=4
269 govpn-client -key key.txt -id CLIENTID -iface tap10 -remote [fe80::1%me0]:1194
276 client% cat > up.sh <<EOF
281 client% chmod +x up.sh
282 client% govpn -id CLIENTID -key key.txt -iface tap10 -remote [fe80::1%me0]:1194 -up ./up.sh
285 Client will exit if won't finish handshake during @code{-timeout}.
286 If no packets are received from remote side during timeout, then daemon
287 will stop sending packets to the client and client will exit. In all
288 cases you have to rehandshake again.
290 @node Developer manual
291 @unnumbered Developer manual
294 @item Nonce and identification encryption
295 @url{http://143.53.36.235:8080/tea.htm, XTEA}
296 @item Data encryption
297 @url{http://cr.yp.to/snuffle.html, Salsa20}
298 @item Message authentication
299 @url{http://cr.yp.to/mac.html, Poly1305}
300 @item Password authenticated key agreement
301 @url{http://cr.yp.to/ecdh.html, Curve25519} based DH-EKE
302 @item Packet overhead
304 @item Handshake overhead
305 4 UDP (2 from client, 2 from server) packets, 240 bytes total payload
309 * Transport protocol::
310 * Handshake protocol::
313 @node Transport protocol
314 @section Transport protocol
317 ENCn(SERIAL) + ENC(KEY, ENCn(SERIAL), DATA) +
318 AUTH(ENCn(SERIAL) + ENC(KEY, ENCn(SERIAL), DATA))
321 Each transport message is indistinguishable from pseudo random noise.
323 @code{SERIAL} is message's serial number. Odds are reserved for
324 client(→server) messages, evens for server(→client) messages.
326 @code{ENCn} is XTEA block cipher algorithm used here as PRP (pseudo
327 random permutation) to randomize, obfuscate @code{SERIAL}. Plaintext
328 @code{SERIAL} state is kept in peers internal state, but encrypted
329 before transmission. XTEA is compact and fast enough. Salsa20 is PRF
330 function and requires much more code to create PRP from it. XTEA's
331 encryption key is the first 128-bit of Salsa20's output with established
332 common key and zero nonce (message nonces start from 1).
334 Encrypted @code{SERIAL} is used as a nonce for @code{DATA} encryption:
335 encryption key is different during each handshake, so (key, nonce) pair
336 is always used only once. @code{ENC} is Salsa20 cipher, with established
337 session @code{KEY} and encrypted @code{SERIAL} used as a nonce.
339 @code{AUTH} is Poly1305 authentication function. First 256 bits of
340 Salsa20 output are used as a one-time key for @code{AUTH}. Next 256 bits
341 of Salsa20 are ignored. All remaining output is XORed with the data,
344 To prevent replay attacks we remember latest @code{SERIAL} from the
345 remote peer. If received message's @code{SERIAL} is not greater that the
346 saved one, then drop it. Optionally, because some UDP packets can be
347 reordered during transmission, we can allow some window for valid
348 serials with the @code{-noncediff} option. @code{-noncediff 10} with
349 current saved serial state equals to 78 allows messages with 68…78
350 serials. That time window can be used by attacker to replay packets, so
351 by default it equals to 1. However it can improve performance because of
352 rearranged UDP packets.
354 @node Handshake protocol
355 @section Handshake protocol
357 @verbatiminclude handshake.utxt
361 client generates @code{CPubKey}, random 64bit @code{R} that is used as a
362 nonce for encryption, and an encrypted @code{R} with XTEA, where the key
363 equals to client's identity
365 @verb{|R + enc(PSK, R, CPubKey) + xtea(ID, R) + NULL + NULLs -> Server|} [65 bytes]
367 server remembers clients address, decrypt @code{CPubKey}, generates
368 @code{SPrivKey}/@code{SPubKey}, computes common shared key @code{K}
369 (based on @code{CPubKey} and @code{SPrivKey}), generates 64bit random
370 number @code{RS} and 256bit random @code{SS}. PSK-encryption uses
371 incremented @code{R} (from previous message) for nonce
373 @verb{|enc(PSK, SPubKey) + enc(K, RS + SS) + NULLs -> Client|} [88 bytes]
375 client decrypt @code{SPubKey}, computes @code{K}, decrypts @code{RS},
376 @code{SS} with key @code{K}, remembers @code{SS}, generates 64bit random
377 number @code{RC} and 256bit random @code{SC},
379 @verb{|enc(K, RS + RC + SC) + NULLs -> Server|} [64 bytes]
381 server decrypt @code{RS}, @code{RC}, @code{SC} with key @code{K},
382 compares @code{RS} with it's own one send before, computes final main
383 encryption key @code{S = SS XOR SC}
385 @verb{|ENC(K, RC) + NULLs -> Client|} [24 bytes]
387 server switches to the new client
389 client decrypts @code{RC} and compares with it's own generated one,
390 computes final main encryption key @code{S}
393 Where PSK is 256bit pre-shared key, @code{NULLs} are 16 null-bytes.
394 @code{R*} are required for handshake randomization and two-way
395 authentication. K key is used only during handshake. @code{NULLs} are
396 required to differentiate common transport protocol messages from
397 handshake ones. DH public keys can be trivially derived from private
401 @unnumbered Reporting bugs
403 Please send all your bug requests, patches and related questions to
404 @email{govpn-devel@@lists.cypherpunks.ru} mailing list.
405 Visit @url{https://lists.cypherpunks.ru/mailman/listinfo/govpn-devel}
406 for information about subscription options and archived messages access.
408 Development Git source code repository currently is located on:
409 @url{https://github.com/stargrave/govpn}.
411 @node Copying conditions
412 @unnumbered Copying conditions