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