README

   1                                  GoVPN
   2                                  =====
   3 SYNOPSIS
   4
   5 govpn is simple high-performance secure virtual private network daemon.
   6 It uses DH-EKE for mutual zero-knowledge authentication and
   7 authenticated encrypted transport. It runs under GNU/Linux and FreeBSD.
   8
   9 DESCRIPTION
  10
  11 All packets captured on network interface are encrypted, authenticated
  12 and sent to remote server, that writes them to his interface, and vice
  13 versa. Client and server use pre-shared authentication key (PSK).
  14 Because of stateless UDP nature, after some timeout of inactivity peers
  15 forget about each other and have to retry handshake process again,
  16 therefore background heartbeat process will be ran.
  17
  18 Handshake is used to mutually authenticate peers, exchange common secret
  19 per-session encryption key and checks UDP transport availability.
  20
  21 Because of UDP and authentication overhead: each packet grows in size
  22 during transmission, so you have to lower you maximum transmission unit
  23 (MTU) on network interface.
  24
  25 High security and high performance are the goals for that daemon. It
  26 uses fast cryptography algorithms with 128bit security margin, strong
  27 mutual zero-knowledge authentication and perfect-forward secrecy
  28 property. An attacker can not know anything from captured traffic, even
  29 if pre-shared key is compromised. Rehandshake is performed by client
  30 every 4 GiB of transfered data.
  31
  32 Also you can provide up and down scripts that will be executed after
  33 either connection is initiated (up-script in background), or is went
  34 down. The first argument for them is an interface name.
  35
  36 COMPARISON TO OpenVPN
  37
  38 * Faster handshake
  39 * Perfect-forward secrecy (if long-term pre-shared keys are compromised,
  40   no captured traffic can be decrypted anyway)
  41 * Mutual two-side authentication (noone will send real network interface
  42   data unless the other side is authenticated)
  43 * Zero-knowledge authentication (pre-shared key is not transmitted in
  44   any form between the peers, not even it's hash value)
  45 * Higher performance in some cases
  46 * Fully IPv6 compatible
  47
  48 CONSOLE OUTPUT LEGEND
  49
  50 B -- bad or timeouted UDP packet (maybe network is inactive)
  51 T -- bad tag on packet (MiTM, unordered packet)
  52 R -- invalid sequence number (MiTM, unordered packet)
  53 [HS?] -- unknown handshake message
  54 w -- successful write to remote peer
  55 r -- successful read from remote peer
  56 [HS1], [HS2], [HS3], [HS4] -- handshake packet stage
  57 [rS?] -- invalid server's random authentication number received (MiTM, bad PSK)
  58 [rC?] -- invalid client's random authentication number received (MiTM, bad PSK)
  59 [S?] -- invalid handshake stage is trying to perform (MiTM, duplicate packet)
  60 [OK] -- handshake's stage passed
  61
  62 EXAMPLE USAGE
  63
  64 Let's assume that there is some insecure link between your computer and
  65 WiFi-reachable gateway. You have got preconfigured wlan0 network
  66 interface with 192.168.0/24 network. You want to create virtual
  67 encrypted and authenticated 172.16.0/24 network and use it as a default
  68 transport. MTU for that wlan0 is 1500 bytes. GoVPN will say that maximum
  69 MTU for the link is 1476, however it does not take in account TAP's
  70 Ethernet frame header length, that in my case is 14 bytes long (1476 - 14).
  71
  72     common% umask 066
  73     common% echo MYLONG64HEXKEY > key.txt
  74
  75 GNU/Linux IPv4 client-server example:
  76
  77     server% ip addr add 192.168.0.1/24 dev wlan0
  78     server% tunctl -t tap10
  79     server% ip link set mtu 1462 dev tap10
  80     server% ip addr add 172.16.0.1/24 dev tap10
  81     server% ip link set up dev tap10
  82     server% govpn -key key.txt -iface tap10 -bind 192.168.0.1:1194
  83
  84     client% ip addr add 192.168.0.2/24 dev wlan0
  85     client% tunctl -t tap10
  86     client% ip link set mtu 1462 dev tap10
  87     client% ip addr add 172.16.0.2/24 dev tap10
  88     client% ip link set up dev tap10
  89     client% ip route add default via 172.16.0.1
  90     client% while :; do govpn -key key.txt -iface tap10 -remote 192.168.0.1:1194; done
  91
  92 FreeBSD IPv6 client-server example:
  93
  94     server% ifconfig em0 inet6 fe80::1/64
  95     server% ifconfig tap10 create
  96     server% ifconfig tap10 inet6 fc00::1/96 mtu 1462 up
  97     server% govpn -key key.txt -face tap10 -bind fe80::1%em0
  98
  99     client% ifconfig me0 inet6 -ifdisabled auto_linklocal
 100     client% ifconfig tap10
 101     client% ifconfig tap10 inet6 fc00::2/96 mtu 1462 up
 102     client% route -6 add default fc00::1
 103     client% while :; do govpn -key key.txt -iface tap10 -remote [fe80::1%me0]:1194; done
 104
 105 Example up-script:
 106
 107     client% cat > up.sh <<EOF
 108     #!/bin/sh
 109     dhclient $1
 110     rtsol $1
 111     EOF
 112     client% chmod +x up.sh
 113     client% govpn -key key.txt -iface tap10 -remote [fe80::1%me0]:1194 -up ./up.sh
 114
 115 If client won't finish handshake during -timeout, then it will exit.
 116 If no packets are received from remote side during timeout, then daemon
 117 will stop sending packets to the client and client will exit. In all
 118 cases you have to rehandshake again.
 119
 120 TECHNICAL INTERNALS
 121
 122 Encryption: Salsa20
 123 Message authentication: Poly1305
 124 Password authenticated key agreement: Curve25519 based DH-EKE
 125 Packet overhead: 24 bytes per packet
 126 Handshake overhead: 4 UDP (2 from client, 2 from server) packets,
 127                     232 bytes total payload
 128
 129                            Transport protocol
 130
 131     SERIAL + ENC(KEY, SERIAL, DATA) + AUTH(SERIAL + ENC_DATA)
 132
 133 where SERIAL is message serial number. Odds are reserved for
 134 client->server, evens are for server->client. SERIAL is used as a nonce
 135 for DATA encryption: encryption key is different during each handshake,
 136 so (key, nonce) pair is always used once.
 137
 138 We generate Salsa20's output using this key and nonce for each message:
 139 * first 256 bits are used as a one-time key for Poly1305 authentication
 140 * next 256 bits of output are ignored
 141 * and all remaining ones XORed with the data, encrypting it
 142
 143                            Handshake protocol
 144      ┌──────┐                                  ┌──────┐
 145      │Client│                                  │Server│
 146      └──┬───┘                                  └──┬───┘
 147         │────┐
 148         │    │ R=rand(64bit); CPrivKey=rand(256bit)
 149         │<───┘
 150         │                                         │
 151         │         R, enc(PSK, R, CPubKey)         │
 152         │ ────────────────────────────────────────>
 153         │                                         │
 154         │                                         │────┐
 155         │                                         │    │ SPrivKey=rand(256bit)
 156         │                                         │<───┘
 157         │                                         │
 158         │                                         │────┐
 159         │                                         │    │ K=DH(SPrivKey, CPubKey)
 160         │                                         │<───┘
 161         │                                         │
 162         │                                         │────┐
 163         │                                         │    │ RS=rand(64bit); SS=rand(256bit)
 164         │                                         │<───┘
 165         │                                         │
 166         │ enc(PSK, R+1, SPubKey); enc(K, R, RS+SS)│
 167         │ <────────────────────────────────────────
 168         │                                         │
 169         │────┐                                    │
 170         │    │ K=DH(CPrivKey, SPubKey)            │
 171         │<───┘                                    │
 172         │                                         │
 173         │────┐                                    │
 174         │    │ RC=rand(64bit); SC=rand(256bit)    │
 175         │<───┘                                    │
 176         │                                         │
 177         │          enc(K, R+1, RS+RC+SC)          │
 178         │ ────────────────────────────────────────>
 179         │                                         │
 180         │                                         │────┐
 181         │                                         │    │ compare(RS)
 182         │                                         │<───┘
 183         │                                         │
 184         │                                         │────┐
 185         │                                         │    │ MasterKey=SS XOR SC
 186         │                                         │<───┘
 187         │                                         │
 188         │             enc(K, 0x00, RC)            │
 189         │ <────────────────────────────────────────
 190         │                                         │
 191         │────┐                                    │
 192         │    │ compare(RC)                        │
 193         │<───┘                                    │
 194         │                                         │
 195         │────┐                                    │
 196         │    │ MasterKey=SS XOR SC                │
 197         │<───┘                                    │
 198      ┌──┴───┐                                  ┌──┴───┐
 199      │Client│                                  │Server│
 200      └──────┘                                  └──────┘
 201
 202 * client generates CPubKey, random 64bit R that is used as a nonce
 203   for encryption
 204 * R + enc(PSK, R, CPubKey) + NULLs -> Server [56 bytes]
 205 * server remembers clients address, decrypt CPubKey, generates
 206   SPrivKey/SPubKey, computes common shared key K (based on
 207   CPubKey and SPrivKey), generates 64bit random number RS and
 208   256bit random SS. PSK-encryption uses incremented R (from previous
 209   message) for nonce
 210 * enc(PSK, SPubKey) + enc(K, RS + SS) + NULLs -> Client [88 bytes]
 211 * client decrypt SPubKey, computes K, decrypts RS, SS with key K,
 212   remembers SS, generates 64bit random number RC and 256bit random SC,
 213 * enc(K, RS + RC + SC) + NULLs -> Server [64 bytes]
 214 * server decrypt RS, RC, SC with key K, compares RS with it's own one
 215   send before, computes final main encryption key S = SS XOR SC
 216 * ENC(K, RC) + NULLs -> Client [24 bytes]
 217 * server switches to the new client
 218 * client decrypts RC and compares with it's own generated one, computes
 219   final main encryption key S
 220
 221 Where PSK is 256bit pre-shared key, NULLs are 16 null-bytes. R* are
 222 required for handshake randomization and two-way authentication. K key
 223 is used only during handshake. NULLs are required to differentiate
 224 common transport protocol messages from handshake ones. DH public keys
 225 can be trivially derived from private ones.
 226
 227
 228 RELATED DOCUMENTS
 229
 230 * http://cr.yp.to/ecdh.html
 231 * http://cr.yp.to/snuffle.html
 232 * http://cr.yp.to/mac.html
 233 * http://grouper.ieee.org/groups/1363/passwdPK/contributions/jablon.pdf
 234 * Applied Cryptography (C) 1996 Bruce Schneier
 235
 236 TODO
 237
 238 * Move decryption and encryption processes into goroutines
 239 * Add identity management (client can send it's identification, server has
 240   on-disk id↔key plaintext database)
 241 * Implement alternative Secure Remote Password protocol (it is much slower,
 242   technically has more code, but human memorized passwords can be used
 243   instead of keys)
 244
 245 LICENCE
 246
 247 This program is free software: you can redistribute it and/or modify
 248 it under the terms of the GNU General Public License as published by
 249 the Free Software Foundation, either version 3 of the License, or
 250 any later version.
 251
 252 This program is distributed in the hope that it will be useful,
 253 but WITHOUT ANY WARRANTY; without even the implied warranty of
 254 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 255 GNU General Public License for more details.