README

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