| 1 | secnet - flexible VPN software |
| 2 | |
| 3 | * Copying |
| 4 | |
| 5 | secnet is Copyright (C) 1995--2003 Stephen Early <steve@greenend.org.uk> |
| 6 | It is distributed under the terms of the GNU General Public License, |
| 7 | version 2 or later. See the file COPYING for more information. |
| 8 | |
| 9 | The portable snprintf implementation in snprintf.c is Copyright (C) |
| 10 | 1999 Mark Martinec <mark.martinec@ijs.si> and is distributed under the |
| 11 | terms of the Frontier Artistic License. You can find the standard |
| 12 | version of snprintf.c at http://www.ijs.si/software/snprintf/ |
| 13 | |
| 14 | The IP address handling library in ipaddr.py is Copyright (C) |
| 15 | 1996--2000 Cendio Systems AB, and is distributed under the terms of |
| 16 | the GPL. |
| 17 | |
| 18 | * Introduction |
| 19 | |
| 20 | secnet allows large virtual private networks to be constructed |
| 21 | spanning multiple separate sites. It is designed for the case where a |
| 22 | private network connecting many hosts is 'hidden' behind a single |
| 23 | globally-routable IP address, but can also be applied in other |
| 24 | circumstances. It communicates entirely using UDP, and works well |
| 25 | with gateways that implement network address translation. |
| 26 | |
| 27 | If you are installing secnet to join an existing VPN, you should read |
| 28 | the 'INSTALL' file and your particular VPN's documentation now. You |
| 29 | may need to refer back to this file for information on the netlink and |
| 30 | comm sections of the configuration file. |
| 31 | |
| 32 | If you are thinking about setting up a new VPN of any size (from one |
| 33 | providing complete links between multiple sites to a simple |
| 34 | laptop-to-host link), read the section in this file on 'Creating a |
| 35 | VPN'. |
| 36 | |
| 37 | * Mailing lists and bug reporting |
| 38 | |
| 39 | There are two mailing lists associated with secnet: an 'announce' list |
| 40 | and a 'discuss' list. Their addresses are: |
| 41 | http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-announce |
| 42 | http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-discuss |
| 43 | |
| 44 | The -announce list receives one message per secnet release. The |
| 45 | -discuss list is for general discussion, including help with |
| 46 | configuration, bug reports, feature requests, etc. |
| 47 | |
| 48 | Bug reports should be sent to <steve@greenend.org.uk>; they will be |
| 49 | forwarded to the -discuss list by me. |
| 50 | |
| 51 | * Creating a VPN |
| 52 | |
| 53 | XXX TODO |
| 54 | |
| 55 | * secnet configuration file format |
| 56 | |
| 57 | By default secnet on linux reads /etc/secnet/secnet.conf. The default |
| 58 | may be different on other platforms. |
| 59 | |
| 60 | This file defines a dictionary (a mapping from keys to values) full of |
| 61 | configuration information for secnet. Two keys must be defined in |
| 62 | this file for secnet to start. One is "system", a dictionary |
| 63 | containing systemwide control parameters. The other is "sites", a |
| 64 | list of all the sites that you intend to communicate with. |
| 65 | |
| 66 | The configuration file has a very simple syntax; keys are defined as |
| 67 | follows: |
| 68 | |
| 69 | key definition; |
| 70 | or |
| 71 | key = definition; |
| 72 | |
| 73 | (the "=" is optional) |
| 74 | |
| 75 | Keys must match the following regular expression: |
| 76 | [[:alpha:]_][[:alnum:]\-_]* |
| 77 | |
| 78 | i.e. the first character must be an alpha or an underscore, and the |
| 79 | remaining characters may be alphanumeric, '-' or '_'. |
| 80 | |
| 81 | Keys can be defined to be a comma-separated list of any of the |
| 82 | following types: |
| 83 | |
| 84 | a boolean |
| 85 | a string, in quotes |
| 86 | a number, in decimal |
| 87 | a dictionary of definitions, enclosed in { } |
| 88 | a "closure", followed by arguments |
| 89 | a path to a key that already exists, to reference that definition |
| 90 | |
| 91 | Note that dictionaries can be nested: a key in one dictionary can |
| 92 | refer to another dictionary. When secnet looks for a key in a |
| 93 | particular directory and can't find it, it looks in the dictionary's |
| 94 | lexical 'parents' in turn until it finds it (or fails to find it at |
| 95 | all and stops with an error). |
| 96 | |
| 97 | Definitions can refer to previous definitions by naming them with a |
| 98 | path. Paths are key1/key2/key3... (starting from wherever we find |
| 99 | key1, i.e. in the current dictionary or any of its parents), or |
| 100 | alternatively /key1/key2/key3... (to start from the root). |
| 101 | Definitions cannot refer to future definitions. |
| 102 | |
| 103 | Example: |
| 104 | |
| 105 | a=1; |
| 106 | b=2; |
| 107 | c={ d=3; e=a; }; |
| 108 | f={ a=4; g=c; }; |
| 109 | |
| 110 | The following paths are valid: |
| 111 | a is 1 |
| 112 | b is 2 |
| 113 | c is a dictionary: |
| 114 | c/d is 3 |
| 115 | c/e is 1 |
| 116 | f is a dictionary: |
| 117 | f/a is 4 |
| 118 | f/g is a dictionary: |
| 119 | f/g/d is 3 |
| 120 | f/g/e is 1 |
| 121 | |
| 122 | Note that f/g/e is NOT 4. |
| 123 | |
| 124 | Elements that are lists are inserted into lists in definitions, not |
| 125 | referenced by them (i.e. you can't have lists of lists). |
| 126 | |
| 127 | Some closures may be followed by an argument list in ( ), and may |
| 128 | return any number of whatever type they like (including other |
| 129 | closures). Some types of closure (typically those returned from |
| 130 | invokations of other closures) cannot be invoked. |
| 131 | |
| 132 | closure { definitions } is short for closure({definitions}). |
| 133 | |
| 134 | The main body of secnet, and all the additional modules, predefine |
| 135 | some keys in the root dictionary. The main ones are: |
| 136 | |
| 137 | yes, true, True, TRUE, on: the boolean value True |
| 138 | no, false, False, FALSE, off: the boolean value False |
| 139 | makelist: turns a dictionary (arg1) into a list of definitions |
| 140 | (ignoring the keys) |
| 141 | readfile: reads a file (arg1) and returns it as a string |
| 142 | map: applies the closure specified as arg1 to each of the |
| 143 | remaining elements in the list in turn. Returns a list |
| 144 | made up of the outputs of the closure. |
| 145 | |
| 146 | Keys defined by modules are described below, in the module |
| 147 | documentation. |
| 148 | |
| 149 | Other configuration files can be included inline by writing "include |
| 150 | filename" at the start of a line. |
| 151 | |
| 152 | After the configuration file is read, secnet looks for particular keys |
| 153 | in configuration space to tell it what to do: |
| 154 | |
| 155 | system: a dictionary which can contain the following keys: |
| 156 | log (log closure): a destination for system messages |
| 157 | userid (string): the userid for secnet to run as once it drops privileges |
| 158 | pidfile (string): where to store its PID |
| 159 | |
| 160 | sites: a list of closures of type 'site', which define other tunnel |
| 161 | endpoints that secnet will attempt to communicate with |
| 162 | |
| 163 | * secnet command line options |
| 164 | |
| 165 | Usage: secnet [OPTION]... |
| 166 | |
| 167 | -f, --silent, --quiet suppress error messages |
| 168 | -w, --nowarnings suppress warnings |
| 169 | -v, --verbose output extra diagnostics |
| 170 | -c, --config=filename specify a configuration file |
| 171 | -j, --just-check-config stop after reading configfile |
| 172 | -n, --nodetach do not run in background |
| 173 | -d, --debug=item,... set debug options |
| 174 | --help display this help and exit |
| 175 | --version output version information and exit |
| 176 | |
| 177 | * secnet builtin modules |
| 178 | |
| 179 | ** resolver |
| 180 | |
| 181 | Defines: |
| 182 | adns (closure => resolver closure) |
| 183 | |
| 184 | adns: dict argument |
| 185 | config (string): optional, a resolv.conf for ADNS to use |
| 186 | |
| 187 | ** random |
| 188 | |
| 189 | Defines: |
| 190 | randomsrc (closure => randomsrc closure) |
| 191 | |
| 192 | randomsrc: string[,bool] |
| 193 | arg1: filename of random source |
| 194 | arg2: if True then source is blocking |
| 195 | |
| 196 | ** udp |
| 197 | |
| 198 | Defines: |
| 199 | udp (closure => comm closure) |
| 200 | |
| 201 | udp: dict argument |
| 202 | address (string): IP address to listen and send on |
| 203 | port (integer): UDP port to listen and send on |
| 204 | buffer (buffer closure): buffer for incoming packets |
| 205 | authbind (string): optional, path to authbind-helper program |
| 206 | |
| 207 | ** log |
| 208 | |
| 209 | Defines: |
| 210 | logfile (closure => log closure) |
| 211 | syslog (closure => log closure) |
| 212 | |
| 213 | logfile: dict argument |
| 214 | filename (string): where to log to |
| 215 | class (string list): what type of messages to log |
| 216 | { "debug-config", M_DEBUG_CONFIG }, |
| 217 | { "debug-phase", M_DEBUG_PHASE }, |
| 218 | { "debug", M_DEBUG }, |
| 219 | { "all-debug", M_DEBUG|M_DEBUG_PHASE|M_DEBUG_CONFIG }, |
| 220 | { "info", M_INFO }, |
| 221 | { "notice", M_NOTICE }, |
| 222 | { "warning", M_WARNING }, |
| 223 | { "error", M_ERROR }, |
| 224 | { "security", M_SECURITY }, |
| 225 | { "fatal", M_FATAL }, |
| 226 | { "default", M_WARNING|M_ERROR|M_SECURITY|M_FATAL }, |
| 227 | { "verbose", M_INFO|M_NOTICE|M_WARNING|M_ERROR|M_SECURITY|M_FATAL }, |
| 228 | { "quiet", M_FATAL } |
| 229 | |
| 230 | logfile will close and reopen its file upon receipt of SIGHUP. |
| 231 | |
| 232 | syslog: dict argument |
| 233 | ident (string): include this string in every log message |
| 234 | facility (string): facility to log as |
| 235 | { "authpriv", LOG_AUTHPRIV }, |
| 236 | { "cron", LOG_CRON }, |
| 237 | { "daemon", LOG_DAEMON }, |
| 238 | { "kern", LOG_KERN }, |
| 239 | { "local0", LOG_LOCAL0 }, |
| 240 | { "local1", LOG_LOCAL1 }, |
| 241 | { "local2", LOG_LOCAL2 }, |
| 242 | { "local3", LOG_LOCAL3 }, |
| 243 | { "local4", LOG_LOCAL4 }, |
| 244 | { "local5", LOG_LOCAL5 }, |
| 245 | { "local6", LOG_LOCAL6 }, |
| 246 | { "local7", LOG_LOCAL7 }, |
| 247 | { "lpr", LOG_LPR }, |
| 248 | { "mail", LOG_MAIL }, |
| 249 | { "news", LOG_NEWS }, |
| 250 | { "syslog", LOG_SYSLOG }, |
| 251 | { "user", LOG_USER }, |
| 252 | { "uucp", LOG_UUCP } |
| 253 | |
| 254 | ** util |
| 255 | |
| 256 | Defines: |
| 257 | sysbuffer (closure => buffer closure) |
| 258 | |
| 259 | sysbuffer: integer[,dict] |
| 260 | arg1: buffer length |
| 261 | arg2: options: |
| 262 | lockdown (boolean): if True, mlock() the buffer |
| 263 | |
| 264 | ** site |
| 265 | |
| 266 | Defines: |
| 267 | site (closure => site closure) |
| 268 | |
| 269 | site: dict argument |
| 270 | local-name (string): this site's name for itself |
| 271 | name (string): the name of the site's peer |
| 272 | link (netlink closure) |
| 273 | comm (comm closure) |
| 274 | resolver (resolver closure) |
| 275 | random (randomsrc closure) |
| 276 | local-key (rsaprivkey closure) |
| 277 | address (string): optional, DNS name used to find our peer |
| 278 | port (integer): mandatory if 'address' is specified: the port used |
| 279 | to contact our peer |
| 280 | key (rsapubkey closure): our peer's public key |
| 281 | transform (transform closure): how to mangle packets sent between sites |
| 282 | dh (dh closure) |
| 283 | hash (hash closure) |
| 284 | key-lifetime (integer): max lifetime of a session key, in ms [one hour] |
| 285 | setup-retries (integer): max number of times to transmit a key negotiation |
| 286 | packet [5] |
| 287 | setup-timeout (integer): time between retransmissions of key negotiation |
| 288 | packets, in ms [1000] |
| 289 | wait-time (integer): after failed key setup, wait this long (in ms) before |
| 290 | allowing another attempt [20000] |
| 291 | renegotiate-time (integer): if we see traffic on the link after this time |
| 292 | then renegotiate another session key immediately [depends on key-lifetime] |
| 293 | keepalive (bool): if True then attempt always to keep a valid session key |
| 294 | log-events (string list): types of events to log for this site |
| 295 | unexpected: unexpected key setup packets (may be late retransmissions) |
| 296 | setup-init: start of attempt to setup a session key |
| 297 | setup-timeout: failure of attempt to setup a session key, through timeout |
| 298 | activate-key: activation of a new session key |
| 299 | timeout-key: deletion of current session key through age |
| 300 | security: anything potentially suspicious |
| 301 | state-change: steps in the key setup protocol |
| 302 | packet-drop: whenever we throw away an outgoing packet |
| 303 | dump-packets: every key setup packet we see |
| 304 | errors: failure of name resolution, internal errors |
| 305 | all: everything (too much!) |
| 306 | |
| 307 | ** transform |
| 308 | |
| 309 | Defines: |
| 310 | serpent256-cbc (closure => transform closure) |
| 311 | |
| 312 | ** netlink |
| 313 | |
| 314 | Defines: |
| 315 | null-netlink (closure => closure or netlink closure) |
| 316 | |
| 317 | null-netlink: dict argument |
| 318 | name (string): name for netlink device, used in log messages |
| 319 | networks (string list): networks on the host side of the netlink device |
| 320 | exclude-remote-networks (string list): networks that may never be claimed |
| 321 | by any remote site using this netlink device |
| 322 | local-address (string): IP address of host's tunnel interface |
| 323 | secnet-address (string): IP address of this netlink device |
| 324 | ptp-address (string): IP address of the other end of a point-to-point link |
| 325 | mtu (integer): MTU of host's tunnel interface |
| 326 | |
| 327 | Only one of secnet-address or ptp-address may be specified. If |
| 328 | point-to-point mode is in use then the "routes" option must also be |
| 329 | specified, and netlink returns a netlink closure that should be used |
| 330 | directly with the "link" option to the site closure. If |
| 331 | point-to-point mode is not in use then netlink returns a closure that |
| 332 | may be invoked using a dict argument with the following keys to yield |
| 333 | a netlink closure: |
| 334 | routes (string list): networks reachable down the tunnel attached to |
| 335 | this instance of netlink |
| 336 | options (string list): |
| 337 | allow-route: allow packets coming from this tunnel to be routed to |
| 338 | other tunnels as well as the host (used for mobile devices like laptops) |
| 339 | soft-route: remove these routes from the host's routing table when |
| 340 | the tunnel link quality is zero |
| 341 | mtu (integer): default MTU over this link; may be updated by tunnel code |
| 342 | |
| 343 | Netlink will dump its current routing table to the system/log on |
| 344 | receipt of SIGUSR1. |
| 345 | |
| 346 | ** slip |
| 347 | |
| 348 | Defines: |
| 349 | userv-ipif (closure => netlink closure) |
| 350 | |
| 351 | userv-ipif: dict argument |
| 352 | userv-path (string): optional, where to find userv ["userv"] |
| 353 | service-user (string): optional, username for userv-ipif service ["root"] |
| 354 | service-name (string): optional, name of userv-ipif service ["ipif"] |
| 355 | buffer (buffer closure): buffer for assembly of host->secnet packets |
| 356 | plus generic netlink options, as for 'null-netlink' |
| 357 | |
| 358 | ** tun |
| 359 | |
| 360 | Defines: |
| 361 | tun (closure => netlink closure) [only on linux-2.4] |
| 362 | tun-old (closure => netlink closure) |
| 363 | |
| 364 | tun: dict argument |
| 365 | flavour (string): optional, type of TUN interface to use |
| 366 | ("guess","linux","bsd","streams") |
| 367 | device (string): optional, path of TUN/TAP device file ["/dev/net/tun"] |
| 368 | interface (string): optional, name of tunnel network interface |
| 369 | ifconfig-path (string): optional, path to ifconfig command |
| 370 | route-path (string): optional, path to route command |
| 371 | ifconfig-type (string): optional, how to perform ifconfig |
| 372 | route-type (string): optional, how to add and remove routes |
| 373 | types are: "guess", "ioctl", "bsd", "linux", "solaris-2.5" |
| 374 | buffer (buffer closure): buffer for host->secnet packets |
| 375 | plus generic netlink options, as for 'null-netlink' |
| 376 | |
| 377 | I recommend you don't specify the 'interface' option unless you're |
| 378 | doing something that requires the interface name to be constant. |
| 379 | |
| 380 | ** rsa |
| 381 | |
| 382 | Defines: |
| 383 | rsa-private (closure => rsaprivkey closure) |
| 384 | rsa-public (closure => rsapubkey closure) |
| 385 | |
| 386 | rsa-private: string[,bool] |
| 387 | arg1: filename of SSH private key file (version 1, no password) |
| 388 | arg2: whether to check that the key is usable [default True] |
| 389 | |
| 390 | rsa-public: string,string |
| 391 | arg1: encryption key (decimal) |
| 392 | arg2: modulus (decimal) |
| 393 | |
| 394 | ** dh |
| 395 | |
| 396 | Defines: |
| 397 | diffie-hellman (closure => dh closure) |
| 398 | |
| 399 | diffie-hellman: string,string[,bool] |
| 400 | arg1: modulus (hex) |
| 401 | arg2: generator (hex) |
| 402 | arg3: whether to check that the modulus is prime [default True] |
| 403 | |
| 404 | ** md5 |
| 405 | |
| 406 | Defines: |
| 407 | md5 (hash closure) |
| 408 | |
| 409 | ** sha1 |
| 410 | |
| 411 | Defines: |
| 412 | sha1 (hash closure) |
| 413 | |
| 414 | ** conffile |
| 415 | |
| 416 | Defines: |
| 417 | makelist (dictionary => list of definitions) |
| 418 | readfile (string => string) |
| 419 | map (closure,list => list) |
| 420 | |
| 421 | makelist: dictionary |
| 422 | returns a list consisting of the definitions in the dictionary. The keys |
| 423 | are discarded. |
| 424 | |
| 425 | readfile: string |
| 426 | reads the named file and returns its contents as a string |
| 427 | |
| 428 | map: |
| 429 | applies the closure specified as arg1 to each of the elements in the list. |
| 430 | Returns a list made up of the outputs of the closure. |