@end quotation
@end copying
-@ifnottex
@node Top
@top GoVPN
-This manual is for GoVPN -- simple secure free software
-virtual private network (VPN) daemon.
-@end ifnottex
+This manual is for GoVPN -- simple secure free software virtual private
+network (VPN) daemon, written entirely on Go programming language.
@menu
* Overview::
* News::
-* Getting source code::
+* Installation::
+* Precautions::
* User manual::
* Developer manual::
* Reporting bugs::
@unnumbered Overview
GoVPN is simple secure virtual private network daemon. It uses
-Diffie-Hellman Encrypted Key Exchange (DH-EKE) for mutual zero-knowledge
-peers authentication and authenticated encrypted data transport.
+@url{https://en.wikipedia.org/wiki/Encrypted_key_exchange, Diffie-Hellman Encrypted Key Exchange}
+(DH-EKE) for mutual zero-knowledge peers authentication and
+authenticated encrypted data transport. It is written entirely on
+@url{http://golang.org/, Go programming language}.
All packets captured on network interface are encrypted, authenticated
and sent to remote server, that writes them to his interface, and vice
all of them independently. Identification key is not secret, but it is
encrypted (obfuscated) during transmission.
+The only platform specific requirement is TAP network interface support.
+API to that kind of device is different, OS dependent and non portable.
+So only a few operating systems is officially supported. Author has no
+proprietary software to work with, so currently there is lack of either
+popular Microsoft Windows or Apple OS X support.
+
@itemize @bullet
-@item GNU/Linux and FreeBSD support
+@item
+Works with @url{https://en.wikipedia.org/wiki/TAP_(network_driver), TAP}
+network interfaces on top of UDP entirely
+@item
+@url{https://www.gnu.org/, GNU}/Linux and
+@url{http://www.freebsd.org/, FreeBSD} support
@item IPv6 compatible
@item Encrypted and authenticated transport
@item Relatively fast handshake
-@item Replay attack protection
@item
-Perfect forward secrecy (if long-term pre-shared keys are compromised,
-no captured traffic can be decrypted anyway)
+@url{https://en.wikipedia.org/wiki/Replay_attack, Replay attack} protection
+@item
+@url{https://en.wikipedia.org/wiki/Forward_secrecy, Perfect forward secrecy}
+(if long-term pre-shared keys are compromised, no captured traffic can
+be decrypted anyway)
@item
Mutual two-side authentication (noone will send real network interface
data unless the other side is authenticated)
@item
-Zero knowledge authentication (pre-shared key is not transmitted in
-any form between the peers, not even it's hash value)
+@url{https://en.wikipedia.org/wiki/Zero-knowledge_password_proof, Zero knowledge}
+authentication (pre-shared key is not transmitted in any form between
+the peers, not even it's hash value)
@item Built-in rehandshake and heartbeat features
@item Several simultaneous clients support
@end itemize
@verbatiminclude ../NEWS
-@node Getting source code
-@unnumbered Getting source code
+@node Installation
+@unnumbered Installation
-GoVPN is written on Go programming language and depends on
-@code{golang.org/x/crypto} libraries.
+GoVPN is written on Go programming language, But
+@url{https://www.gnu.org/software/make/, Make} program is recommended
+also to be used. @url{https://www.gnu.org/software/texinfo/, Texinfo} is
+used for building documentation. Also it depends on
+@code{golang.org/x/crypto} Go libraries.
@include download.texi
trusted source. Alternatively check this page from other sources and
look for the mailing list announcements.
-@verbatim
-pub rsa2048/FFE2F4A1 2015-03-10
-uid [ultimate] Sergey Matveev (GoVPN release signing key) <stargrave@stargrave.org>
-sub rsa2048/8A6C750A 2015-03-10
-
------BEGIN PGP PUBLIC KEY BLOCK-----
-
-mQENBFT/H6cBCADTf/oqoTTBAA/CCQuYtzg8vrXxyjXj9yy4lTWqMSwgLXMm8br/
-kG0Jnk63oP3hggI3hm2mpuiNwpwrJiORLBZCe8JgZW71zG4LfhVpQeWd7fu8WxDx
-0uUZWByz5KcK8c/kNWNDpSkMmmqdE/8v0YDFbsz5U+ytp/Kki/gj3BCeIX3jYOL1
-fxczkv2okoU+aGYXt9z50VzheLUSRLzkkX8yNSpszqfB0LEEmUk8HO2fSS/bXwaY
-ZXX5//suH8V5hwq8vB8dHHCquZW6blyzcTa2KGIh6g2CmpypIQp/i5QAbzOCHKTM
-A1F7A1r0kYF2WfZOrycCfjUx3GA5B7sytuA3ABEBAAG0RFNlcmdleSBNYXR2ZWV2
-IChHb1ZQTiByZWxlYXNlIHNpZ25pbmcga2V5KSA8c3RhcmdyYXZlQHN0YXJncmF2
-ZS5vcmc+iQE8BBMBCAAmBQJU/x+nAhsDCAsKCQgHBAMCBxUKCQgLAwIFFgIBAwAC
-HgECF4AACgkQ8vWQRf/i9KEZ/AgAqYF/RRNwwhgLgFqTLfw3ha0FeiSso7H9ITDo
-cdJ/domLHaFvmwFIDQQKV8Zd1Rnj6xTCs2bq2O5hYMLrFZg85A9i5tLwkgFc9J5G
-+8K3K/dh9Y4pArbM+craO+xydrwLyg1zlXCezthWbL0iXO/CuGiuBBCZJqRJ9HV4
-cZr4TRA3Znm5nt96rRsR86XqOgr0iOEDtYKfKW/IzDqOEgXUN5o2bUwuQawe9Y8d
-CngXzJcfb2eJ/TqSP9CxVWscjz4sAmD3/ECrHSjX7xsusIs46F2+VMlEXFuST52r
-zamfiGKlol8XvimUjKhlMWjqfdcJ0+jvFftsa7HXQUwRoQ1vJYheBBARCAAGBQJU
-/x/VAAoJEK4agQnkmFfvqn8A/ReK2ZZrnI9s0rzTsF1jrTZ1o5YowuINOzVMmLbE
-aYuGAP4iGwPgwVbANu4dWaP2N03oL4xFtmdaeNn3sB9ZqJOOyrkBDQRU/x+nAQgA
-uYBRyJVwhlE2SRIEmMggwr4gq1JBM2Ge5O46usf+YPUjCJKWoAj+MpQoq7r+oA/s
-E/6kGvWgngwV9prCdNkvcdwEWbb+n9PcMc2ZuIGRV3iOKYlYEBFV0bfM9zEV2jar
-1YQ+J/48UX7R00cYJuXel7Dy77V9eNd+Ukyowm93fggFlBDBGBjVbNtfIorHNYjB
-01CCu3i/8yxrMyFRvMKyAVEGp3obgmlam4DNkNIhFMv3du0tFnDFBsZf7N0kbLWI
-xEEJoc/jxaezDytQpUr3RhlMsLV6N/jjIZuy36QO1sbFeOe2to0E7ixaFzNCWsqY
-cxUfnJ3wi7hOiOwE2PF3tQARAQABiQEfBBgBCAAJBQJU/x+nAhsMAAoJEPL1kEX/
-4vShrVcIAKLUwMn7WgK6thmwPjdwP5V/jTlsWLWk2O/LEN4W/R0mw2hRsgRG/8Sz
-qlAP6vfl7ERaWuyL+fp72rKnGTGU9CEvn6PKmaG7bi4tGEvWXscNc10r0leIAP63
-pkQOa6Nyx2axJlJdSuTsYetd1ZgNpHNng+lxSUBlkPMOhPd/P/Ok7DShZjd2jhQ1
-jUbjWn+P7ARGEvgdd5utNjy/RaSwrLG8NXj3I+XuksG0/TPeG0zu9NOPzWZq9sCc
-5VbDNJTYtsMFs1etHE95Efmx6yUquQyB+g/HgvkH/LzthBawVVHxZNzzHgc6KN5w
-E0itJPXMaQL+juUfiNM0i2R1O8nJo14=
-=LJzj
------END PGP PUBLIC KEY BLOCK-----
-@end verbatim
+You have to set up @code{$GOPATH} properly first. For example you can
+clone the repository or decompress tarball and set path like this:
+
+@example
+% mkdir -p govpn/src
+% git clone https://github.com/stargrave/govpn.git govpn/src/govpn
+or
+% tar xfC govpn-1.5.tar.xz govpn/src && mv govpn/src/govpn-1.5 govpn/src/govpn
+% export GOPATH=$(pwd)/govpn:$GOPATH
+@end example
+
+After that you can just type @code{make} and all necessary Go libraries
+will be installed and client/server binaries are built in the current
+directory:
+
+@example
+% cd govpn/src/govpn
+% make
+[or gmake under FreeBSD]
+@end example
+
+@include pubkey.texi
+
+@node Precautions
+@unnumbered Precautions
+
+The very important precaution is the @strong{cryptographically good}
+pseudo random number generator. GoVPN uses native operating system PRNG
+as entropy source. You have no way to check it's quality in closed
+source code operating systems, so it is recommended not to use them if
+you really needs security. Moreover it is possible that those OS leaks
+information about possible PRNG states. And at least Apple OS X and
+Microsoft Windows are already known to have weak CSPRNGs.
+
+GoVPN could use it's own PRNG implementation like
+@url{https://www.schneier.com/fortuna.html, Fortuna}, but it is
+much easier to use the right OS, to use free software.
+
+Also you should @strong{never} use one key for multiple clients. Salsa20
+encryption is randomized in each session, but it depends again on PRNG.
+If it fails, produces equal values at least once, then all you traffic
+related to that key could be decrypted.
@node User manual
@unnumbered User manual
MTU for the link is 1476, however it does not take in account TAP's
Ethernet frame header length, that in my case is 14 bytes long (1476 - 14).
+Do not forget about setting @code{GOMAXPROC} environment variable for
+using more than one CPU.
+
+At first you have to generate client's authentication key and client's
+unique identification. There is @code{utils/newclient.sh} script for
+convenience.
+
+@example
+% ./utils/newclient.sh Alice
+peers/9b40701bdaf522f2b291cb039490312/Alice
+@end example
+
+@code{9b40701bdaf522f2b291cb039490312} is client's identification.
+@code{Alice} is just an empty file that can help to search them like
+this: @verb{|find peers -name Alice|}. @code{key} file inside peer's
+directory contains authentication key.
+
GNU/Linux IPv4 client-server example:
@example
-server% mkdir -p peers/CLIENTID
-server% umask 066
-server% echo MYLONG64HEXKEY > peers/CLIENTID/key
server% echo "#!/bin/sh" > peers/CLIENTID/up.sh
-server% echo "echo tap10" > peers/CLIENTID/up.sh
+server% echo "echo tap10" >> peers/CLIENTID/up.sh
server% chmod 500 peers/CLIENTID/up.sh
server% ip addr add 192.168.0.1/24 dev wlan0
server% tunctl -t tap10
server% ip link set mtu 1462 dev tap10
server% ip addr add 172.16.0.1/24 dev tap10
server% ip link set up dev tap10
-server% govpn -bind 192.168.0.1:1194
+server% GOMAXPROC=4 govpn-server -bind 192.168.0.1:1194
@end example
@example
client% ip addr add 172.16.0.2/24 dev tap10
client% ip link set up dev tap10
client% ip route add default via 172.16.0.1
+client% export GOMAXPROC=4
client% while :; do
- govpn -key key.txt -id CLIENTID -iface tap10 -remote 192.168.0.1:1194
+ govpn-client -key key.txt -id CLIENTID -iface tap10 -remote 192.168.0.1:1194
done
@end example
FreeBSD IPv6 client-server example:
@example
-server% mkdir -p peers/CLIENTID
-server% umask 066
-server% echo MYLONG64HEXKEY > peers/CLIENTID/key
-server% echo "#!/bin/sh" >
server% cat > peers/CLIENTID/up.sh <<EOF
#!/bin/sh
$tap=$(ifconfig tap create)
EOF
server% chmod 500 peers/CLIENTID/up.sh
server% ifconfig em0 inet6 fe80::1/64
-server% govpn -bind fe80::1%em0
+server% GOMAXPROC=4 govpn-server -bind fe80::1%em0
@end example
@example
client% ifconfig tap10
client% ifconfig tap10 inet6 fc00::2/96 mtu 1462 up
client% route -6 add default fc00::1
+client% export GOMAXPROC=4
client% while :; do
- govpn -key key.txt -id CLIENTID -iface tap10 -remote [fe80::1%me0]:1194
+ govpn-client -key key.txt -id CLIENTID -iface tap10 -remote [fe80::1%me0]:1194
done
@end example
@table @asis
@item Nonce and identification encryption
-XTEA
+@url{http://143.53.36.235:8080/tea.htm, XTEA}
@item Data encryption
-Salsa20
+@url{http://cr.yp.to/snuffle.html, Salsa20}
@item Message authentication
-Poly1305
+@url{http://cr.yp.to/mac.html, Poly1305}
@item Password authenticated key agreement
-Curve25519 based DH-EKE
+DH-EKE powered by @url{http://cr.yp.to/ecdh.html, Curve25519}
@item Packet overhead
24 bytes per packet
@item Handshake overhead
Each transport message is indistinguishable from pseudo random noise.
-@code{SERIAL} is message's serial number. Odds are reserved for client(→server)
-messages, evens for server(→client) messages.
+@code{SERIAL} is message's serial number. Odds are reserved for
+client(→server) messages, evens for server(→client) messages.
@code{ENCn} is XTEA block cipher algorithm used here as PRP (pseudo
random permutation) to randomize, obfuscate @code{SERIAL}. Plaintext
number @code{RS} and 256bit random @code{SS}. PSK-encryption uses
incremented @code{R} (from previous message) for nonce
@item
-@verb{|enc(PSK, SPubKey) + enc(K, RS + SS) + NULLs -> Client|} [88 bytes]
+@verb{|enc(PSK, R+1, SPubKey) + enc(K, R, RS + SS) + NULLs -> Client|} [88 bytes]
@item
client decrypt @code{SPubKey}, computes @code{K}, decrypts @code{RS},
@code{SS} with key @code{K}, remembers @code{SS}, generates 64bit random
number @code{RC} and 256bit random @code{SC},
@item
-@verb{|enc(K, RS + RC + SC) + NULLs -> Server|} [64 bytes]
+@verb{|enc(K, R+1, RS + RC + SC) + NULLs -> Server|} [64 bytes]
@item
server decrypt @code{RS}, @code{RC}, @code{SC} with key @code{K},
compares @code{RS} with it's own one send before, computes final main
encryption key @code{S = SS XOR SC}
@item
-@verb{|ENC(K, RC) + NULLs -> Client|} [24 bytes]
+@verb{|ENC(K, 0, RC) + NULLs -> Client|} [24 bytes]
@item
server switches to the new client
@item
Please send all your bug requests, patches and related questions to
@email{govpn-devel@@lists.cypherpunks.ru} mailing list.
-Visit @url{https://lists.cypherpunks.ru/mailman/listinfo/govpn-devel}
-for information about subscription options and archived messages access.
-
-Development Git source code repository currently is located on:
-@url{https://github.com/stargrave/govpn}.
+Either visit @url{https://lists.cypherpunks.ru/mailman/listinfo/govpn-devel}
+for information about subscription options and archived messages access, or
+send email with the subject @code{subscribe} to
+@email{govpn-devel-request@@lists.cypherpunks.ru}.
+
+Official website is @url{http://www.cypherpunks.ru/govpn/}, also available
+as @url{https://www.torproject.org/, Tor} hidden service:
+@url{http://vabu56j2ep2rwv3b.onion/govpn/}.
+Development Git source code repository currently is located here:
+@url{https://github.com/stargrave/govpn.git}.
@node Copying conditions
@unnumbered Copying conditions