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 virtual private
25 network (VPN) daemon, written entirely on Go programming language.
31 * Getting and building source code::
35 * Copying conditions::
41 GoVPN is simple secure virtual private network daemon. It uses
42 @url{https://en.wikipedia.org/wiki/Encrypted_key_exchange, Diffie-Hellman Encrypted Key Exchange}
43 (DH-EKE) for mutual zero-knowledge peers authentication and
44 authenticated encrypted data transport. It is written entirely on
45 @url{http://golang.org/, Go programming language}.
47 All packets captured on network interface are encrypted, authenticated
48 and sent to remote server, that writes them to his interface, and vice
49 versa. Client and server use pre-shared authentication key (PSK) and
50 128-bit identification key.
52 Because of stateless UDP nature, after some timeout of inactivity peers
53 forget about each other and have to retry handshake process again,
54 therefore background heartbeat process will be ran.
56 Handshake is used to mutually authenticate peers, exchange common secret
57 per-session encryption key and check UDP transport availability.
59 Because of UDP and authentication overhead: each packet grows in size
60 during transmission, so you have to lower you maximum transmission unit
61 (MTU) on virtual network interface.
63 High security is the goal for that daemon. It uses fast cryptography
64 algorithms with 128bit security margin, strong mutual zero-knowledge
65 authentication and perfect-forward secrecy property. An attacker can not
66 know anything about payload (except it's size and time) from captured
67 traffic, even if pre-shared key is compromised. Rehandshake is performed
68 by client every 4 GiB of transfered data.
70 Each client also has it's own identification key and server works with
71 all of them independently. Identification key is not secret, but it is
72 encrypted (obfuscated) during transmission.
76 Works with @url{https://en.wikipedia.org/wiki/TAP_(network_driver), TAP}
77 network interfaces on top of UDP entirely
79 @url{https://www.gnu.org/, GNU}/Linux and
80 @url{http://www.freebsd.org/, FreeBSD} support
82 @item Encrypted and authenticated transport
83 @item Relatively fast handshake
85 @url{https://en.wikipedia.org/wiki/Replay_attack, Replay attack} protection
87 @url{https://en.wikipedia.org/wiki/Forward_secrecy, Perfect forward secrecy}
88 (if long-term pre-shared keys are compromised, no captured traffic can
91 Mutual two-side authentication (noone will send real network interface
92 data unless the other side is authenticated)
94 @url{https://en.wikipedia.org/wiki/Zero-knowledge_password_proof, Zero knowledge}
95 authentication (pre-shared key is not transmitted in any form between
96 the peers, not even it's hash value)
97 @item Built-in rehandshake and heartbeat features
98 @item Several simultaneous clients support
104 @verbatiminclude ../NEWS
106 @node Getting and building source code
107 @unnumbered Getting and building source code
109 GoVPN is written on Go programming language, But
110 @url{https://www.gnu.org/software/make/, Make} program is recommended
111 also to be used. @url{https://www.gnu.org/software/texinfo/, Texinfo} is
112 used for building documentation. Also it depends on
113 @code{golang.org/x/crypto} Go libraries.
115 @include download.texi
117 You @strong{have to} verify downloaded archives integrity and check
118 their signature to be sure that you have got trusted, untampered
119 software. For integrity and authentication of downloaded binaries
120 @url{https://www.gnupg.org/, The GNU Privacy Guard} is used. You must
121 download signature provided with the tarball and run for example:
124 gpg --verify govpn-1.5.tar.xz.sig govpn-1.5.tar.xz
127 For the very first time you must also import signing public keys. They
128 are provided below, but be sure that you are reading them from the
129 trusted source. Alternatively check this page from other sources and
130 look for the mailing list announcements.
132 You have to set up @code{$GOPATH} properly first. For example you can
133 clone the repository or decompress tarball and set path like this:
137 % git clone https://github.com/stargrave/govpn govpn/src/govpn
139 % tar xfC govpn-1.5.tar.xz govpn/src && mv govpn/src/govpn-1.5 govpn/src/govpn
140 % export GOPATH=$(pwd)/govpn:$GOPATH
143 After that you can just type @code{make} and all necessary Go libraries
144 will be installed and client/server binaries are built in the current
150 [or gmake under FreeBSD]
156 @unnumbered User manual
158 GoVPN is split into two pieces: client and server. Each of them work on
159 top of UDP and TAP virtual network interfaces. Client and server have
160 several common configuration command line options:
164 Because of stateless UDP nature there is no way to know if
165 remote peer is dead, but after some timeout. Client and server
166 heartbeats each other every third part of heartbeat. Also this timeout
167 is the time when server purge his obsolete handshake and peers states.
168 @item Allowable nonce difference
169 To prevent replay attacks we just remembers
170 latest received nonce number from the remote peer and drops those who
171 has lower ones. Because UDP packets can be reordered during: that
172 behaviour can lead to dropping of not replayed ones. This options gives
173 ability to create some window of allows difference. That opens the door
174 for replay attacks for narrow time interval.
176 Maximum transmission unit.
179 Client needs to know his identification, path to the authentication key,
180 remote server's address, TAP interface name, and optional path to up and
181 down scripts, that will be executed after connection is either initiated
184 Server needs to know only the address to listen on and path to directory
185 containing peers information. This directory must contain subdirectories
186 with the names equal to client's identifications. Each of them must have
187 key file with corresponding authentication key, up.sh script that has to
188 print interface's name on the first line and optional down.sh.
195 @section Example usage
197 Let's assume that there is some insecure link between your computer and
198 WiFi-reachable gateway. You have got preconfigured @code{wlan0} network
199 interface with 192.168.0/24 network. You want to create virtual
200 encrypted and authenticated 172.16.0/24 network and use it as a default
201 transport. MTU for that wlan0 is 1500 bytes. GoVPN will say that maximum
202 MTU for the link is 1476, however it does not take in account TAP's
203 Ethernet frame header length, that in my case is 14 bytes long (1476 - 14).
205 GNU/Linux IPv4 client-server example:
208 server% mkdir -p peers/CLIENTID
210 server% echo MYLONG64HEXKEY > peers/CLIENTID/key
211 server% echo "#!/bin/sh" > peers/CLIENTID/up.sh
212 server% echo "echo tap10" > peers/CLIENTID/up.sh
213 server% chmod 500 peers/CLIENTID/up.sh
214 server% ip addr add 192.168.0.1/24 dev wlan0
215 server% tunctl -t tap10
216 server% ip link set mtu 1462 dev tap10
217 server% ip addr add 172.16.0.1/24 dev tap10
218 server% ip link set up dev tap10
219 server% govpn -bind 192.168.0.1:1194
224 client% echo MYLONG64HEXKEY > key.txt
225 client% ip addr add 192.168.0.2/24 dev wlan0
226 client% tunctl -t tap10
227 client% ip link set mtu 1462 dev tap10
228 client% ip addr add 172.16.0.2/24 dev tap10
229 client% ip link set up dev tap10
230 client% ip route add default via 172.16.0.1
232 govpn -key key.txt -id CLIENTID -iface tap10 -remote 192.168.0.1:1194
236 FreeBSD IPv6 client-server example:
239 server% mkdir -p peers/CLIENTID
241 server% echo MYLONG64HEXKEY > peers/CLIENTID/key
242 server% echo "#!/bin/sh" >
243 server% cat > peers/CLIENTID/up.sh <<EOF
245 $tap=$(ifconfig tap create)
246 ifconfig $tap inet6 fc00::1/96 mtu 1462 up
249 server% chmod 500 peers/CLIENTID/up.sh
250 server% ifconfig em0 inet6 fe80::1/64
251 server% govpn -bind fe80::1%em0
255 client% ifconfig me0 inet6 -ifdisabled auto_linklocal
256 client% ifconfig tap10
257 client% ifconfig tap10 inet6 fc00::2/96 mtu 1462 up
258 client% route -6 add default fc00::1
260 govpn -key key.txt -id CLIENTID -iface tap10 -remote [fe80::1%me0]:1194
267 client% cat > up.sh <<EOF
272 client% chmod +x up.sh
273 client% govpn -id CLIENTID -key key.txt -iface tap10 -remote [fe80::1%me0]:1194 -up ./up.sh
276 Client will exit if won't finish handshake during @code{-timeout}.
277 If no packets are received from remote side during timeout, then daemon
278 will stop sending packets to the client and client will exit. In all
279 cases you have to rehandshake again.
281 @node Developer manual
282 @unnumbered Developer manual
285 @item Nonce and identification encryption
286 @url{http://143.53.36.235:8080/tea.htm, XTEA}
287 @item Data encryption
288 @url{http://cr.yp.to/snuffle.html, Salsa20}
289 @item Message authentication
290 @url{http://cr.yp.to/mac.html, Poly1305}
291 @item Password authenticated key agreement
292 @url{http://cr.yp.to/ecdh.html, Curve25519} based DH-EKE
293 @item Packet overhead
295 @item Handshake overhead
296 4 UDP (2 from client, 2 from server) packets, 240 bytes total payload
300 * Transport protocol::
301 * Handshake protocol::
304 @node Transport protocol
305 @section Transport protocol
308 ENCn(SERIAL) + ENC(KEY, ENCn(SERIAL), DATA) +
309 AUTH(ENCn(SERIAL) + ENC(KEY, ENCn(SERIAL), DATA))
312 Each transport message is indistinguishable from pseudo random noise.
314 @code{SERIAL} is message's serial number. Odds are reserved for
315 client(→server) messages, evens for server(→client) messages.
317 @code{ENCn} is XTEA block cipher algorithm used here as PRP (pseudo
318 random permutation) to randomize, obfuscate @code{SERIAL}. Plaintext
319 @code{SERIAL} state is kept in peers internal state, but encrypted
320 before transmission. XTEA is compact and fast enough. Salsa20 is PRF
321 function and requires much more code to create PRP from it. XTEA's
322 encryption key is the first 128-bit of Salsa20's output with established
323 common key and zero nonce (message nonces start from 1).
325 Encrypted @code{SERIAL} is used as a nonce for @code{DATA} encryption:
326 encryption key is different during each handshake, so (key, nonce) pair
327 is always used only once. @code{ENC} is Salsa20 cipher, with established
328 session @code{KEY} and encrypted @code{SERIAL} used as a nonce.
330 @code{AUTH} is Poly1305 authentication function. First 256 bits of
331 Salsa20 output are used as a one-time key for @code{AUTH}. Next 256 bits
332 of Salsa20 are ignored. All remaining output is XORed with the data,
335 To prevent replay attacks we remember latest @code{SERIAL} from the
336 remote peer. If received message's @code{SERIAL} is not greater that the
337 saved one, then drop it. Optionally, because some UDP packets can be
338 reordered during transmission, we can allow some window for valid
339 serials with the @code{-noncediff} option. @code{-noncediff 10} with
340 current saved serial state equals to 78 allows messages with 68…78
341 serials. That time window can be used by attacker to replay packets, so
342 by default it equals to 1. However it can improve performance because of
343 rearranged UDP packets.
345 @node Handshake protocol
346 @section Handshake protocol
348 @verbatiminclude handshake.utxt
352 client generates @code{CPubKey}, random 64bit @code{R} that is used as a
353 nonce for encryption, and an encrypted @code{R} with XTEA, where the key
354 equals to client's identity
356 @verb{|R + enc(PSK, R, CPubKey) + xtea(ID, R) + NULL + NULLs -> Server|} [65 bytes]
358 server remembers clients address, decrypt @code{CPubKey}, generates
359 @code{SPrivKey}/@code{SPubKey}, computes common shared key @code{K}
360 (based on @code{CPubKey} and @code{SPrivKey}), generates 64bit random
361 number @code{RS} and 256bit random @code{SS}. PSK-encryption uses
362 incremented @code{R} (from previous message) for nonce
364 @verb{|enc(PSK, SPubKey) + enc(K, RS + SS) + NULLs -> Client|} [88 bytes]
366 client decrypt @code{SPubKey}, computes @code{K}, decrypts @code{RS},
367 @code{SS} with key @code{K}, remembers @code{SS}, generates 64bit random
368 number @code{RC} and 256bit random @code{SC},
370 @verb{|enc(K, RS + RC + SC) + NULLs -> Server|} [64 bytes]
372 server decrypt @code{RS}, @code{RC}, @code{SC} with key @code{K},
373 compares @code{RS} with it's own one send before, computes final main
374 encryption key @code{S = SS XOR SC}
376 @verb{|ENC(K, RC) + NULLs -> Client|} [24 bytes]
378 server switches to the new client
380 client decrypts @code{RC} and compares with it's own generated one,
381 computes final main encryption key @code{S}
384 Where PSK is 256bit pre-shared key, @code{NULLs} are 16 null-bytes.
385 @code{R*} are required for handshake randomization and two-way
386 authentication. K key is used only during handshake. @code{NULLs} are
387 required to differentiate common transport protocol messages from
388 handshake ones. DH public keys can be trivially derived from private
392 @unnumbered Reporting bugs
394 Please send all your bug requests, patches and related questions to
395 @email{govpn-devel@@lists.cypherpunks.ru} mailing list.
396 Visit @url{https://lists.cypherpunks.ru/mailman/listinfo/govpn-devel}
397 for information about subscription options and archived messages access.
399 Development Git source code repository currently is located on:
400 @url{https://github.com/stargrave/govpn}.
402 @node Copying conditions
403 @unnumbered Copying conditions