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. After that you can
133 just type @code{make} and all necessary Go libraries will be installed
134 and client/server binaries are built in the current directory.
139 @unnumbered User manual
141 GoVPN is split into two pieces: client and server. Each of them work on
142 top of UDP and TAP virtual network interfaces. Client and server have
143 several common configuration command line options:
147 Because of stateless UDP nature there is no way to know if
148 remote peer is dead, but after some timeout. Client and server
149 heartbeats each other every third part of heartbeat. Also this timeout
150 is the time when server purge his obsolete handshake and peers states.
151 @item Allowable nonce difference
152 To prevent replay attacks we just remembers
153 latest received nonce number from the remote peer and drops those who
154 has lower ones. Because UDP packets can be reordered during: that
155 behaviour can lead to dropping of not replayed ones. This options gives
156 ability to create some window of allows difference. That opens the door
157 for replay attacks for narrow time interval.
159 Maximum transmission unit.
162 Client needs to know his identification, path to the authentication key,
163 remote server's address, TAP interface name, and optional path to up and
164 down scripts, that will be executed after connection is either initiated
167 Server needs to know only the address to listen on and path to directory
168 containing peers information. This directory must contain subdirectories
169 with the names equal to client's identifications. Each of them must have
170 key file with corresponding authentication key, up.sh script that has to
171 print interface's name on the first line and optional down.sh.
178 @section Example usage
180 Let's assume that there is some insecure link between your computer and
181 WiFi-reachable gateway. You have got preconfigured @code{wlan0} network
182 interface with 192.168.0/24 network. You want to create virtual
183 encrypted and authenticated 172.16.0/24 network and use it as a default
184 transport. MTU for that wlan0 is 1500 bytes. GoVPN will say that maximum
185 MTU for the link is 1476, however it does not take in account TAP's
186 Ethernet frame header length, that in my case is 14 bytes long (1476 - 14).
188 GNU/Linux IPv4 client-server example:
191 server% mkdir -p peers/CLIENTID
193 server% echo MYLONG64HEXKEY > peers/CLIENTID/key
194 server% echo "#!/bin/sh" > peers/CLIENTID/up.sh
195 server% echo "echo tap10" > peers/CLIENTID/up.sh
196 server% chmod 500 peers/CLIENTID/up.sh
197 server% ip addr add 192.168.0.1/24 dev wlan0
198 server% tunctl -t tap10
199 server% ip link set mtu 1462 dev tap10
200 server% ip addr add 172.16.0.1/24 dev tap10
201 server% ip link set up dev tap10
202 server% govpn -bind 192.168.0.1:1194
207 client% echo MYLONG64HEXKEY > key.txt
208 client% ip addr add 192.168.0.2/24 dev wlan0
209 client% tunctl -t tap10
210 client% ip link set mtu 1462 dev tap10
211 client% ip addr add 172.16.0.2/24 dev tap10
212 client% ip link set up dev tap10
213 client% ip route add default via 172.16.0.1
215 govpn -key key.txt -id CLIENTID -iface tap10 -remote 192.168.0.1:1194
219 FreeBSD IPv6 client-server example:
222 server% mkdir -p peers/CLIENTID
224 server% echo MYLONG64HEXKEY > peers/CLIENTID/key
225 server% echo "#!/bin/sh" >
226 server% cat > peers/CLIENTID/up.sh <<EOF
228 $tap=$(ifconfig tap create)
229 ifconfig $tap inet6 fc00::1/96 mtu 1462 up
232 server% chmod 500 peers/CLIENTID/up.sh
233 server% ifconfig em0 inet6 fe80::1/64
234 server% govpn -bind fe80::1%em0
238 client% ifconfig me0 inet6 -ifdisabled auto_linklocal
239 client% ifconfig tap10
240 client% ifconfig tap10 inet6 fc00::2/96 mtu 1462 up
241 client% route -6 add default fc00::1
243 govpn -key key.txt -id CLIENTID -iface tap10 -remote [fe80::1%me0]:1194
250 client% cat > up.sh <<EOF
255 client% chmod +x up.sh
256 client% govpn -id CLIENTID -key key.txt -iface tap10 -remote [fe80::1%me0]:1194 -up ./up.sh
259 Client will exit if won't finish handshake during @code{-timeout}.
260 If no packets are received from remote side during timeout, then daemon
261 will stop sending packets to the client and client will exit. In all
262 cases you have to rehandshake again.
264 @node Developer manual
265 @unnumbered Developer manual
268 @item Nonce and identification encryption
269 @url{http://143.53.36.235:8080/tea.htm, XTEA}
270 @item Data encryption
271 @url{http://cr.yp.to/snuffle.html, Salsa20}
272 @item Message authentication
273 @url{http://cr.yp.to/mac.html, Poly1305}
274 @item Password authenticated key agreement
275 @url{http://cr.yp.to/ecdh.html, Curve25519} based DH-EKE
276 @item Packet overhead
278 @item Handshake overhead
279 4 UDP (2 from client, 2 from server) packets, 240 bytes total payload
283 * Transport protocol::
284 * Handshake protocol::
287 @node Transport protocol
288 @section Transport protocol
291 ENCn(SERIAL) + ENC(KEY, ENCn(SERIAL), DATA) +
292 AUTH(ENCn(SERIAL) + ENC(KEY, ENCn(SERIAL), DATA))
295 Each transport message is indistinguishable from pseudo random noise.
297 @code{SERIAL} is message's serial number. Odds are reserved for
298 client(→server) messages, evens for server(→client) messages.
300 @code{ENCn} is XTEA block cipher algorithm used here as PRP (pseudo
301 random permutation) to randomize, obfuscate @code{SERIAL}. Plaintext
302 @code{SERIAL} state is kept in peers internal state, but encrypted
303 before transmission. XTEA is compact and fast enough. Salsa20 is PRF
304 function and requires much more code to create PRP from it. XTEA's
305 encryption key is the first 128-bit of Salsa20's output with established
306 common key and zero nonce (message nonces start from 1).
308 Encrypted @code{SERIAL} is used as a nonce for @code{DATA} encryption:
309 encryption key is different during each handshake, so (key, nonce) pair
310 is always used only once. @code{ENC} is Salsa20 cipher, with established
311 session @code{KEY} and encrypted @code{SERIAL} used as a nonce.
313 @code{AUTH} is Poly1305 authentication function. First 256 bits of
314 Salsa20 output are used as a one-time key for @code{AUTH}. Next 256 bits
315 of Salsa20 are ignored. All remaining output is XORed with the data,
318 To prevent replay attacks we remember latest @code{SERIAL} from the
319 remote peer. If received message's @code{SERIAL} is not greater that the
320 saved one, then drop it. Optionally, because some UDP packets can be
321 reordered during transmission, we can allow some window for valid
322 serials with the @code{-noncediff} option. @code{-noncediff 10} with
323 current saved serial state equals to 78 allows messages with 68…78
324 serials. That time window can be used by attacker to replay packets, so
325 by default it equals to 1. However it can improve performance because of
326 rearranged UDP packets.
328 @node Handshake protocol
329 @section Handshake protocol
331 @verbatiminclude handshake.utxt
335 client generates @code{CPubKey}, random 64bit @code{R} that is used as a
336 nonce for encryption, and an encrypted @code{R} with XTEA, where the key
337 equals to client's identity
339 @verb{|R + enc(PSK, R, CPubKey) + xtea(ID, R) + NULL + NULLs -> Server|} [65 bytes]
341 server remembers clients address, decrypt @code{CPubKey}, generates
342 @code{SPrivKey}/@code{SPubKey}, computes common shared key @code{K}
343 (based on @code{CPubKey} and @code{SPrivKey}), generates 64bit random
344 number @code{RS} and 256bit random @code{SS}. PSK-encryption uses
345 incremented @code{R} (from previous message) for nonce
347 @verb{|enc(PSK, SPubKey) + enc(K, RS + SS) + NULLs -> Client|} [88 bytes]
349 client decrypt @code{SPubKey}, computes @code{K}, decrypts @code{RS},
350 @code{SS} with key @code{K}, remembers @code{SS}, generates 64bit random
351 number @code{RC} and 256bit random @code{SC},
353 @verb{|enc(K, RS + RC + SC) + NULLs -> Server|} [64 bytes]
355 server decrypt @code{RS}, @code{RC}, @code{SC} with key @code{K},
356 compares @code{RS} with it's own one send before, computes final main
357 encryption key @code{S = SS XOR SC}
359 @verb{|ENC(K, RC) + NULLs -> Client|} [24 bytes]
361 server switches to the new client
363 client decrypts @code{RC} and compares with it's own generated one,
364 computes final main encryption key @code{S}
367 Where PSK is 256bit pre-shared key, @code{NULLs} are 16 null-bytes.
368 @code{R*} are required for handshake randomization and two-way
369 authentication. K key is used only during handshake. @code{NULLs} are
370 required to differentiate common transport protocol messages from
371 handshake ones. DH public keys can be trivially derived from private
375 @unnumbered Reporting bugs
377 Please send all your bug requests, patches and related questions to
378 @email{govpn-devel@@lists.cypherpunks.ru} mailing list.
379 Visit @url{https://lists.cypherpunks.ru/mailman/listinfo/govpn-devel}
380 for information about subscription options and archived messages access.
382 Development Git source code repository currently is located on:
383 @url{https://github.com/stargrave/govpn}.
385 @node Copying conditions
386 @unnumbered Copying conditions