1 secnet - flexible VPN software
6 Copyright 1995-2003 Stephen Early <steve@greenend.org.uk>
7 Copyright 2002-2014 Ian Jackson <ijackson@chiark.greenend.org.uk>
8 Copyright 1991 Massachusetts Institute of Technology
9 Copyright 1998 Ross Anderson, Eli Biham, Lars Knudsen
10 Copyright 1993 Colin Plumb
11 Copyright 1998 James H. Brown, Steve Reid
12 Copyright 2000 Vincent Rijmen, Antoon Bosselaers, Paulo Barreto
13 Copyright 2001 Saul Kravitz
14 Copyright 2004 Fabrice Bellard
15 Copyright 2002 Guido Draheim
16 Copyright 2005-2010 Free Software Foundation, Inc.
17 Copyright 1995-2001 Jonathan Amery
18 Copyright 1995-2003 Peter Benie
19 Copyright 2011 Richard Kettlewell
20 Copyright 2012 Matthew Vernon
21 Copyright 2013-2019 Mark Wooding
22 Copyright 1995-2013 Simon Tatham
24 secnet is distributed under the terms of the GNU General Public
25 License, version 3 or later. Some individual files have more
26 permissive licences; where this is the case, it is documented in the
27 header comment for the files in question.
29 secnet is distributed in the hope that it will be useful, but WITHOUT
30 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
31 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
34 The file COPYING contains a copy of the GNU GPL v3.
39 secnet allows large virtual private networks to be constructed
40 spanning multiple separate sites. It is designed for the case where a
41 private network connecting many hosts is 'hidden' behind a single
42 globally-routable IP address, but can also be applied in other
43 circumstances. It communicates entirely using UDP, and works well
44 with gateways that implement network address translation.
46 If you are installing secnet to join an existing VPN, you should read
47 the 'INSTALL' file and your particular VPN's documentation now. You
48 may need to refer back to this file for information on the netlink and
49 comm sections of the configuration file.
51 If you are thinking about setting up a new VPN of any size (from one
52 providing complete links between multiple sites to a simple
53 laptop-to-host link), read the section in this file on 'Creating a
56 * Mailing lists and bug reporting
58 There are two mailing lists associated with secnet: an 'announce' list
59 and a 'discuss' list. Their addresses are:
60 http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-announce
61 http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-discuss
63 The -announce list receives one message per secnet release. The
64 -discuss list is for general discussion, including help with
65 configuration, bug reports, feature requests, etc.
67 Bug reports should be sent to <steve@greenend.org.uk>; they will be
68 forwarded to the -discuss list by me.
74 * secnet configuration file format
76 By default secnet on linux reads /etc/secnet/secnet.conf. The default
77 may be different on other platforms.
79 This file defines a dictionary (a mapping from keys to values) full of
80 configuration information for secnet. Two keys must be defined in
81 this file for secnet to start. One is "system", a dictionary
82 containing systemwide control parameters. The other is "sites", a
83 list of all the sites that you intend to communicate with.
85 The configuration file has a very simple syntax; keys are defined as
94 Keys must match the following regular expression:
95 [[:alpha:]_][[:alnum:]\-_]*
97 i.e. the first character must be an alpha or an underscore, and the
98 remaining characters may be alphanumeric, '-' or '_'.
100 Keys can be defined to be a comma-separated list of any of the
106 a dictionary of definitions, enclosed in { }
107 a "closure", followed by arguments
108 a path to a key that already exists, to reference that definition
110 Note that dictionaries can be nested: a key in one dictionary can
111 refer to another dictionary. When secnet looks for a key in a
112 particular directory and can't find it, it looks in the dictionary's
113 lexical 'parents' in turn until it finds it (or fails to find it at
114 all and stops with an error).
116 Definitions can refer to previous definitions by naming them with a
117 path. Paths are key1/key2/key3... (starting from wherever we find
118 key1, i.e. in the current dictionary or any of its parents), or
119 alternatively /key1/key2/key3... (to start from the root).
120 Definitions cannot refer to future definitions.
129 The following paths are valid:
141 Note that f/g/e is NOT 4.
143 Elements that are lists are inserted into lists in definitions, not
144 referenced by them (i.e. you can't have lists of lists).
146 Some closures may be followed by an argument list in ( ), and may
147 return any number of whatever type they like (including other
148 closures). Some types of closure (typically those returned from
149 invokations of other closures) cannot be invoked.
151 closure { definitions } is short for closure({definitions}).
153 The main body of secnet, and all the additional modules, predefine
154 some keys in the root dictionary. The main ones are:
156 yes, true, True, TRUE, on: the boolean value True
157 no, false, False, FALSE, off: the boolean value False
158 makelist: turns a dictionary (arg1) into a list of definitions
160 readfile: reads a file (arg1) and returns it as a string
161 map: applies the closure specified as arg1 to each of the
162 remaining elements in the list in turn. Returns a list
163 made up of the outputs of the closure.
165 Keys defined by modules are described below, in the module
168 Other configuration files can be included inline by writing "include
169 filename" at the start of a line.
171 After the configuration file is read, secnet looks for particular keys
172 in configuration space to tell it what to do:
174 system: a dictionary which can contain the following keys:
175 log (log closure): a destination for system messages
176 userid (string): the userid for secnet to run as once it drops privileges
177 pidfile (string): where to store its PID
179 sites: a list of closures of type 'site', which define other tunnel
180 endpoints that secnet will attempt to communicate with
182 * secnet command line options
184 Usage: secnet [OPTION]...
186 -f, --silent, --quiet suppress error messages
187 -w, --nowarnings suppress warnings
188 -v, --verbose output extra diagnostics
189 -c, --config=filename specify a configuration file
190 -j, --just-check-config stop after reading configfile
191 -n, --nodetach do not run in background
192 -d, --debug=item,... set debug options
193 --help display this help and exit
194 --version output version information and exit
198 secnet defines a variant of the base91 encoding `basE91', from
199 http://base91.sourceforge.net/
201 base91s is the same as baseE91 except that:
202 - in the encoded charset, `"' is replaced with `-'
203 - spaces, newlines etc. and other characters outside the charset
204 are not permitted (although in some places they may be ignored,
205 this is not guaranteed).
207 * secnet builtin modules
212 adns (closure => resolver closure)
215 config (string): optional, a resolv.conf for ADNS to use
220 randomsrc (closure => randomsrc closure)
222 randomsrc: string[,bool]
223 arg1: filename of random source
224 arg2: if True then source is blocking
229 udp (closure => comm closure)
232 address (string list): IPv6 or IPv4 addresses to listen and send on;
233 default is all local addresses
234 port (integer): UDP port to listen and send on; optional if you
235 don't need to have a stable address for your peers to talk to
236 (in which case your site ought probably to have `local-mobile true').
237 buffer (buffer closure): buffer for incoming packets
238 authbind (string): optional, path to authbind-helper program
243 polypath (closure => comm closure)
245 polypath: dict argument
246 port (integer): UDP port to listen and send on
247 buffer (buffer closure): buffer for incoming packets
248 authbind (string): optional, path to authbind-helper program
249 max-interfaces (number): optional, max number of different interfaces to
250 use (also, maximum steady-state amount of packet multiplication);
251 interfaces marked with `@' do not count.
252 interfaces (string list): which interfaces to process; each entry is
253 optionally `!' or `+' or `@' followed by a glob pattern (which is
254 applied to a prospective interface using fnmatch with no flags).
255 `+' or nothing means to process normally. `!' means to ignore;
256 `@' means to use only in conjunction with dedicated-interface-addr.
257 If no list is specified, or the list ends with a `!' entry, a
258 default list is used/appended:
259 "!tun*","!tap*","!sl*","!userv*","!lo","@hippo*","*".
260 Patterns which do not start with `*' or an alphanumeric need to be
261 preceded by `!' or `+' or `@'.
262 monitor-command (string list): Program to use to monitor appearance
263 and disappearance of addresses on local network interfaces. Should
264 produce lines of the form `+|-<ifname> 4|6 <addr>' where <addr> is
265 an address literal. Each - line should relate to a previously
266 printed + line. On startup, should produce a + line for each
267 currently existing address. secnet does filtering so there is no
268 need to strip out tun interfaces, multicast addresses, and so on.
269 The command is run as the user secnet is started as (not the one
270 which secnet may drop privilege to due to the configured `userid').
271 The default depends on the operating system.
272 permit-loopback (boolean): Normally, loopback IPv6 and IPv4
273 addresses on local interfaces are disregarded, because such
274 interfaces are not interesting for communicating with distant
275 hosts. Setting this option will ignore that check, which can be
276 useful for testing. Setting this option also removes "!lo*" from
277 the default interface pattern list.
279 When using this comm, packets are sent out of every active interface
280 on the host (where possible). It is important that interfaces created
281 by secnet itself are not included! secnet's default filter list tries
284 This comm only makes sense for sites which are mobile. That is, the
285 site closures used with this comm should all have the `local-mobile'
286 parameter set to `true'. When the local site site is not marked
287 mobile the address selection machinery might fixate on an unsuitable
290 polypath takes site-specific informtion as passed to the `comm-info'
291 site closure parameter. The entries understood in the dictionary
293 dedicated-interface-addr (string): IPv4 or IPv6 address
294 literal. Interfaces specified with `@' in `interfaces' will be
295 used for the corresponding site iff the interface local address
298 For an interface to work with polypath, it must either have a suitable
299 default route, or be a point-to-point interface. In the general case
300 this might mean that the host would have to have multiple default
301 routes. However in practice the most useful configuration is two
302 interfaces being (1) wifi (2) mobile internet.
304 I have had success on Linux by using network-manager for wifi and
305 invoking ppp directly for mobile internet. ppp sets up a
306 point-to-point link, and does not add a default route if there already
307 is one. network-manager always sets up a default route. The result
308 is that the wifi always has a default route (so is useable); ppp
309 (being a point-to-point link) does not need one.
311 The use of polypath requires that secnet be started with root
312 privilege, to make the setsockopt(,,SO_BINDTODEVICE,) calls. If the
313 configuration specifies that secnet should drop privilege (see
314 `userid' above), secnet will keep a special process around for this
315 purpose; that process will handle local network interface changes but
316 does not deal with any packets, key exchange, etc.
318 polypath support is only available when secnet is built against an
319 IPv6-capable version of adns (because it wants features in the newer
325 logfile (closure => log closure)
326 syslog (closure => log closure)
328 logfile: dict argument
329 filename (string): where to log to; default is stderr
330 prefix (string): added to messages [""]
331 class (string list): what type of messages to log
332 { "debug-config", M_DEBUG_CONFIG },
333 { "debug-phase", M_DEBUG_PHASE },
334 { "debug", M_DEBUG },
335 { "all-debug", M_DEBUG|M_DEBUG_PHASE|M_DEBUG_CONFIG },
337 { "notice", M_NOTICE },
338 { "warning", M_WARNING },
339 { "error", M_ERROR },
340 { "security", M_SECURITY },
341 { "fatal", M_FATAL },
342 { "default", M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
343 { "verbose", M_INFO|M_NOTICE|M_WARNING|M_ERROR|M_SECURITY|M_FATAL },
346 logfile will close and reopen its file upon receipt of SIGHUP.
348 syslog: dict argument
349 ident (string): include this string in every log message
350 facility (string): facility to log as
351 { "authpriv", LOG_AUTHPRIV },
352 { "cron", LOG_CRON },
353 { "daemon", LOG_DAEMON },
354 { "kern", LOG_KERN },
355 { "local0", LOG_LOCAL0 },
356 { "local1", LOG_LOCAL1 },
357 { "local2", LOG_LOCAL2 },
358 { "local3", LOG_LOCAL3 },
359 { "local4", LOG_LOCAL4 },
360 { "local5", LOG_LOCAL5 },
361 { "local6", LOG_LOCAL6 },
362 { "local7", LOG_LOCAL7 },
364 { "mail", LOG_MAIL },
365 { "news", LOG_NEWS },
366 { "syslog", LOG_SYSLOG },
367 { "user", LOG_USER },
373 sysbuffer (closure => buffer closure)
375 sysbuffer: integer[,dict]
378 lockdown (boolean): if True, mlock() the buffer
383 site (closure => site closure)
386 local-name (string): this site's name for itself
387 name (string): the name of the site's peer
388 link (netlink closure)
389 comm (one or more comm closures): if there is more than one, the
390 first one will be used for any key setups initiated by us using the
391 configured address. Others are only used if our peer talks to
393 resolver (resolver closure)
394 random (randomsrc closure)
395 key-cache (privcache closure)
396 local-key (sigprivkey closure): Deprecated; use key-cache instead.
397 address (string list): optional, DNS name(s) used to find our peer;
398 address literals are supported too if enclosed in `[' `]'.
399 port (integer): mandatory if 'address' is specified: the port used
401 peer-keys (string): path (prefix) for peer public key set file(s);
402 see README.make-secnet-sites re `pub' etc. and NOTES.peer-keys.
403 key (sigpubkey closure): our peer's public key (obsolete)
404 transform (transform closure): how to mangle packets sent between sites
406 hash (hash closure): used for keys whose algorithm (or public
407 or private key file) does not imply the hash function
408 key-lifetime (integer): max lifetime of a session key, in ms
409 [one hour; mobile: 2 days]
410 setup-retries (integer): max number of times to transmit a key negotiation
411 packet [5; mobile: 30]
412 setup-timeout (integer): time between retransmissions of key negotiation
413 packets, in ms [2000; mobile: 1000]
414 wait-time (integer): after failed key setup, wait roughly this long
415 (in ms) before allowing another attempt [20000; mobile: 10000]
416 Actual wait time is randomly chosen between ~0.5x and ~1.5x this.
417 renegotiate-time (integer): if we see traffic on the link after this time
418 then renegotiate another session key immediately (in ms)
419 [half key-lifetime, or key-lifetime minus 5 mins (mobile: 12 hours),
420 whichever is longer].
421 keepalive (bool): if True then attempt always to keep a valid session key.
423 log-events (string list): types of events to log for this site
424 unexpected: unexpected key setup packets (may be late retransmissions)
425 setup-init: start of attempt to setup a session key
426 setup-timeout: failure of attempt to setup a session key, through timeout
427 activate-key: activation of a new session key
428 timeout-key: deletion of current session key through age
429 security: anything potentially suspicious
430 state-change: steps in the key setup protocol
431 packet-drop: whenever we throw away an outgoing packet
432 dump-packets: every key setup packet we see
433 errors: failure of name resolution, internal errors
434 peer-addrs: changes to sets of peer addresses (interesting for mobile peers)
435 all: everything (too much!)
436 mobile (bool): if True then peer is "mobile" ie we assume it may
437 change its apparent IP address and port number without either it
438 or us being aware of the change; so, we remember the last several
439 port/addr pairs we've seen and send packets to all of them
440 (subject to a timeout). We maintain one set of addresses for key
441 setup exchanges, and another for data traffic. Two communicating
442 peers must not each regard the other as mobile, or all the traffic
443 in each direction will be triplicated (strictly, transmitted
444 mobile-peers-max times) and anyway two peers whose public contact
445 address may suddenly change couldn't communicate reliably because
446 their contact addresses might both change at once. [false]
447 mobile-peers-max (integer): Maximum number of peer port/addr pairs we
448 remember and send to. Must be at least 1 and no more than 5.
449 [4 if any address is configured, otherwise 3]
450 static-peers-max (integer): Maximum number of peer port/addr pairs
451 we can try for a static site. Must be at least 1 and no more
452 than 5. [4 or 3, as above]
453 mobile-peer-expiry (integer): For "mobile" peers only, the length
454 of time (in seconds) for which we will keep sending to multiple
455 address/ports from which we have not seen incoming traffic. [120]
456 local-mobile (bool): if True then other peers have been told we are
457 "mobile". This should be True iff the peers' site configurations
458 for us have "mobile True" (and if we find a site configuration for
459 ourselves in the config, we insist on this). The effect is to
460 check that there are no links both ends of which are allegedly
461 mobile (which is not supported, so those links are ignored) and
462 to change some of the tuning parameter defaults. [false]
463 mtu-target (integer): Desired value of the inter-site MTU for this
464 peering. This value will be advertised to the peer (which ought
465 to affect incoming packets), and if the peer advertises an MTU its
466 value will be combined with this setting to compute the inter-site
467 MTU. (secnet will still accept packets which exceed the
468 (negotiated or assumed) inter-site MTU.) Setting a lower
469 inter-site MTU can be used to try to restrict the sizes of the
470 packets sent over the underlying public network (e.g. to work
471 around network braindamage). It is not normally useful to set a
472 larger value for mtu-target than the VPN's general MTU (which
473 should be reflected in the local private interface MTU, ie the mtu
474 parameter to netlink). If this parameter is not set, or is set
475 to 0, the default is to use the local private link mtu.
476 comm-info (dict): Information for the comm, used when this site
477 wants to transmit. If the comm does not support this, it is
480 Links involving mobile peers have some different tuning parameter
481 default values, which are generally more aggressive about retrying key
482 setup but more relaxed about using old keys. These are noted with
483 "mobile:", above, and apply whether the mobile peer is local or
489 eax-serpent (closure => transform closure)
494 serpent256-cbc (closure => transform closure)
499 null-netlink (closure => closure or netlink closure)
501 null-netlink: dict argument
502 name (string): name for netlink device, used in log messages
503 networks (string list): networks on the host side of the netlink device
504 remote-networks (string list): networks that may be claimed
505 by the remote site using this netlink device
506 local-address (string): IP address of host's tunnel interface
507 secnet-address (string): IP address of this netlink device
508 ptp-address (string): IP address of the other end of a point-to-point link
509 mtu (integer): MTU of host's tunnel interface
511 Only one of secnet-address or ptp-address may be specified. If
512 point-to-point mode is in use then the "routes" option must also be
513 specified, and netlink returns a netlink closure that should be used
514 directly with the "link" option to the site closure. If
515 point-to-point mode is not in use then netlink returns a closure that
516 may be invoked using a dict argument with the following keys to yield
518 routes (string list): networks reachable down the tunnel attached to
519 this instance of netlink
520 options (string list):
521 allow-route: allow packets coming from this tunnel to be routed to
522 other tunnels as well as the host (used for mobile devices like laptops)
523 soft: remove these routes from the host's routing table when
524 the tunnel link quality is zero
525 mtu (integer): MTU of host's tunnel interface
527 Netlink will dump its current routing table to the system/log on
533 userv-ipif (closure => netlink closure)
535 userv-ipif: dict argument
536 userv-path (string): optional, where to find userv ["userv"]
537 service-user (string): optional, username for userv-ipif service ["root"]
538 service-name (string): optional, name of userv-ipif service ["ipif"]
539 buffer (buffer closure): buffer for assembly of host->secnet packets
540 plus generic netlink options, as for 'null-netlink'
545 tun (closure => netlink closure) [only on linux-2.4]
546 tun-old (closure => netlink closure)
549 flavour (string): optional, type of TUN interface to use
550 ("guess","linux","bsd","streams")
551 device (string): optional, path of TUN/TAP device file ["/dev/net/tun"]
552 interface (string): optional, name of tunnel network interface
553 ifconfig-path (string): optional, path to ifconfig command
554 route-path (string): optional, path to route command
555 ifconfig-type (string): optional, how to perform ifconfig
556 route-type (string): optional, how to add and remove routes
557 types are: "guess", "ioctl", "bsd", "linux", "solaris-2.5"
558 buffer (buffer closure): buffer for host->secnet packets
559 plus generic netlink options, as for 'null-netlink'
561 I recommend you don't specify the 'interface' option unless you're
562 doing something that requires the interface name to be constant.
566 Cache of dynamically loaded private keys.
569 priv-cache (closure => privcache closure)
571 priv-cache: dict argument
572 privkeys (string): path prefix for private keys. Each key is
573 looked for at this path prefix followed by the 10-character
575 privcache-size (integer): optional, maximum number of private
576 keys to retain at once. [5]
577 privkey-max (integer): optional, maximum size of private key
578 file in bytes. [4095]
583 make-public (closure => sigpubkey closure)
587 arg2: base91s encoded public key data, according to algorithm
592 sigscheme algorithm 00 "rsa1"
593 rsa-private (closure => sigprivkey closure)
594 rsa-public (closure => sigpubkey closure)
596 rsa1 sigscheme algorithm:
597 private key: SSH private key file, version 1, no password
598 public key: SSH public key file, version 1
599 (length, restrictions, email, etc., ignored)
601 rsa-private: string[,bool]
602 arg1: filename of SSH private key file (version 1, no password)
603 arg2: whether to check that the key is usable [default True]
605 rsa-public: string,string
606 arg1: encryption key (decimal)
607 arg2: modulus (decimal)
612 diffie-hellman (closure => dh closure)
614 diffie-hellman: string,string[,bool]
616 arg2: generator (hex)
617 arg3: whether to check that the modulus is prime [default True]
632 makelist (dictionary => list of definitions)
633 readfile (string => string)
634 map (closure,list => list)
637 returns a list consisting of the definitions in the dictionary. The keys
641 reads the named file and returns its contents as a string
644 applies the closure specified as arg1 to each of the elements in the list.
645 Returns a list made up of the outputs of the closure.