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