chiark / gitweb /
rsa: Do not crash with -j if key file does not exist
[secnet.git] / README
1 secnet - flexible VPN software
2
3 * Copying
4
5 secnet is
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
23
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.
28
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
32 for more details.
33
34 The file COPYING contains a copy of the GNU GPL v3.
35
36
37 * Introduction
38
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.
45
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.
50
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
54 VPN'.
55
56 * Mailing lists and bug reporting
57
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
62
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.
66
67 Bug reports should be sent to <steve@greenend.org.uk>; they will be
68 forwarded to the -discuss list by me.
69
70 * Creating a VPN
71
72 XXX TODO
73
74 * secnet configuration file format
75
76 By default secnet on linux reads /etc/secnet/secnet.conf.  The default
77 may be different on other platforms.
78
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.
84
85 The configuration file has a very simple syntax; keys are defined as
86 follows:
87
88 key definition;
89 or
90 key = definition;
91
92 (the "=" is optional)
93
94 Keys must match the following regular expression:
95 [[:alpha:]_][[:alnum:]\-_]*
96
97 i.e. the first character must be an alpha or an underscore, and the
98 remaining characters may be alphanumeric, '-' or '_'.
99
100 Keys can be defined to be a comma-separated list of any of the
101 following types:
102
103   a boolean
104   a string, in quotes
105   a number, in decimal
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
109
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).
115
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.
121
122 Example:
123
124 a=1;
125 b=2;
126 c={ d=3; e=a; };
127 f={ a=4; g=c; };
128
129 The following paths are valid:
130 a is 1
131 b is 2
132 c is a dictionary:
133  c/d is 3
134  c/e is 1
135 f is a dictionary:
136  f/a is 4
137  f/g is a dictionary:
138   f/g/d is 3
139   f/g/e is 1
140
141 Note that f/g/e is NOT 4.
142
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).
145
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.
150
151 closure { definitions } is short for closure({definitions}).
152
153 The main body of secnet, and all the additional modules, predefine
154 some keys in the root dictionary.  The main ones are:
155
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
159               (ignoring the keys)
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.
164
165 Keys defined by modules are described below, in the module
166 documentation.
167
168 Other configuration files can be included inline by writing "include
169 filename" at the start of a line.
170
171 After the configuration file is read, secnet looks for particular keys
172 in configuration space to tell it what to do:
173
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
178    
179  sites: a list of closures of type 'site', which define other tunnel
180         endpoints that secnet will attempt to communicate with
181
182 * secnet command line options
183
184 Usage: secnet [OPTION]...
185
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
195
196 * base91s
197
198 secnet defines a variant of the base91 encoding `basE91', from
199  http://base91.sourceforge.net/
200
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).
206
207 * secnet builtin modules
208
209 ** resolver
210
211 Defines:
212   adns (closure => resolver closure)
213
214 adns: dict argument
215   config (string): optional, a resolv.conf for ADNS to use
216
217 ** random
218
219 Defines:
220   randomsrc (closure => randomsrc closure)
221
222 randomsrc: string[,bool]
223   arg1: filename of random source
224   arg2: if True then source is blocking
225
226 ** udp
227
228 Defines:
229   udp (closure => comm closure)
230
231 udp: dict argument
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
239
240 ** polypath
241
242 Defines:
243   polypath (closure => comm closure)
244
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.
278
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
282 to do this.
283
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
288 address.
289
290 polypath takes site-specific informtion as passed to the `comm-info'
291 site closure parameter.  The entries understood in the dictionary
292 are:
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
296    is this address.
297
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.
303
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.
310
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.
317
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
320 adns).
321
322 ** log
323
324 Defines:
325   logfile (closure => log closure)
326   syslog (closure => log closure)
327
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 },
336     { "info", M_INFO },
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 },
344     { "quiet", M_FATAL }
345
346 logfile will close and reopen its file upon receipt of SIGHUP.
347
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 },
363     { "lpr", LOG_LPR },
364     { "mail", LOG_MAIL },
365     { "news", LOG_NEWS },
366     { "syslog", LOG_SYSLOG },
367     { "user", LOG_USER },
368     { "uucp", LOG_UUCP }
369
370 ** util
371
372 Defines:
373   sysbuffer (closure => buffer closure)
374
375 sysbuffer: integer[,dict]
376   arg1: buffer length
377   arg2: options:
378     lockdown (boolean): if True, mlock() the buffer
379
380 ** site
381
382 Defines:
383   site (closure => site closure)
384
385 site: dict argument
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
392    them.
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
400     to contact our peer
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
405   dh (dh closure)
406   key-lifetime (integer): max lifetime of a session key, in ms
407     [one hour; mobile: 2 days]
408   setup-retries (integer): max number of times to transmit a key negotiation
409     packet [5; mobile: 30]
410   setup-timeout (integer): time between retransmissions of key negotiation
411     packets, in ms [2000; mobile: 1000]
412   wait-time (integer): after failed key setup, wait roughly this long
413     (in ms) before allowing another attempt [20000; mobile: 10000]
414     Actual wait time is randomly chosen between ~0.5x and ~1.5x this.
415   renegotiate-time (integer): if we see traffic on the link after this time
416     then renegotiate another session key immediately (in ms)
417     [half key-lifetime, or key-lifetime minus 5 mins (mobile: 12 hours),
418      whichever is longer].
419   keepalive (bool): if True then attempt always to keep a valid session key.
420     [false]
421   log-events (string list): types of events to log for this site
422     unexpected: unexpected key setup packets (may be late retransmissions)
423     setup-init: start of attempt to setup a session key
424     setup-timeout: failure of attempt to setup a session key, through timeout
425     activate-key: activation of a new session key
426     timeout-key: deletion of current session key through age
427     security: anything potentially suspicious
428     state-change: steps in the key setup protocol
429     packet-drop: whenever we throw away an outgoing packet
430     dump-packets: every key setup packet we see
431     errors: failure of name resolution, internal errors
432     peer-addrs: changes to sets of peer addresses (interesting for mobile peers)
433     all: everything (too much!)
434   mobile (bool): if True then peer is "mobile" ie we assume it may
435     change its apparent IP address and port number without either it
436     or us being aware of the change; so, we remember the last several
437     port/addr pairs we've seen and send packets to all of them
438     (subject to a timeout).  We maintain one set of addresses for key
439     setup exchanges, and another for data traffic. Two communicating
440     peers must not each regard the other as mobile, or all the traffic
441     in each direction will be triplicated (strictly, transmitted
442     mobile-peers-max times) and anyway two peers whose public contact
443     address may suddenly change couldn't communicate reliably because
444     their contact addresses might both change at once. [false]
445   mobile-peers-max (integer): Maximum number of peer port/addr pairs we
446     remember and send to.  Must be at least 1 and no more than 5.
447     [4 if any address is configured, otherwise 3]
448   static-peers-max (integer): Maximum number of peer port/addr pairs
449     we can try for a static site.  Must be at least 1 and no more
450     than 5.  [4 or 3, as above]
451   mobile-peer-expiry (integer): For "mobile" peers only, the length
452     of time (in seconds) for which we will keep sending to multiple
453     address/ports from which we have not seen incoming traffic. [120]
454   local-mobile (bool): if True then other peers have been told we are
455     "mobile".  This should be True iff the peers' site configurations
456     for us have "mobile True" (and if we find a site configuration for
457     ourselves in the config, we insist on this).  The effect is to
458     check that there are no links both ends of which are allegedly
459     mobile (which is not supported, so those links are ignored) and
460     to change some of the tuning parameter defaults. [false]
461   mtu-target (integer): Desired value of the inter-site MTU for this
462     peering.  This value will be advertised to the peer (which ought
463     to affect incoming packets), and if the peer advertises an MTU its
464     value will be combined with this setting to compute the inter-site
465     MTU.  (secnet will still accept packets which exceed the
466     (negotiated or assumed) inter-site MTU.)  Setting a lower
467     inter-site MTU can be used to try to restrict the sizes of the
468     packets sent over the underlying public network (e.g. to work
469     around network braindamage).  It is not normally useful to set a
470     larger value for mtu-target than the VPN's general MTU (which
471     should be reflected in the local private interface MTU, ie the mtu
472     parameter to netlink).  If this parameter is not set, or is set
473     to 0, the default is to use the local private link mtu.
474   comm-info (dict): Information for the comm, used when this site
475     wants to transmit.  If the comm does not support this, it is
476     ignored.
477
478 Links involving mobile peers have some different tuning parameter
479 default values, which are generally more aggressive about retrying key
480 setup but more relaxed about using old keys.  These are noted with
481 "mobile:", above, and apply whether the mobile peer is local or
482 remote.
483
484 ** transform-eax
485
486 Defines:
487    eax-serpent (closure => transform closure)
488
489 ** transform-cbcmac
490
491 Defines:
492   serpent256-cbc (closure => transform closure)
493
494 ** netlink
495
496 Defines:
497   null-netlink (closure => closure or netlink closure)
498
499 null-netlink: dict argument
500   name (string): name for netlink device, used in log messages
501   networks (string list): networks on the host side of the netlink device
502   remote-networks (string list): networks that may be claimed
503     by the remote site using this netlink device
504   local-address (string): IP address of host's tunnel interface
505   secnet-address (string): IP address of this netlink device
506   ptp-address (string): IP address of the other end of a point-to-point link
507   mtu (integer): MTU of host's tunnel interface
508
509 Only one of secnet-address or ptp-address may be specified.  If
510 point-to-point mode is in use then the "routes" option must also be
511 specified, and netlink returns a netlink closure that should be used
512 directly with the "link" option to the site closure.  If
513 point-to-point mode is not in use then netlink returns a closure that
514 may be invoked using a dict argument with the following keys to yield
515 a netlink closure:
516   routes (string list): networks reachable down the tunnel attached to
517     this instance of netlink
518   options (string list):
519     allow-route: allow packets coming from this tunnel to be routed to
520       other tunnels as well as the host (used for mobile devices like laptops)
521     soft: remove these routes from the host's routing table when
522       the tunnel link quality is zero
523   mtu (integer): MTU of host's tunnel interface
524
525 Netlink will dump its current routing table to the system/log on
526 receipt of SIGUSR1.
527
528 ** slip
529
530 Defines:
531   userv-ipif (closure => netlink closure)
532
533 userv-ipif: dict argument
534   userv-path (string): optional, where to find userv ["userv"]
535   service-user (string): optional, username for userv-ipif service ["root"]
536   service-name (string): optional, name of userv-ipif service ["ipif"]
537   buffer (buffer closure): buffer for assembly of host->secnet packets
538  plus generic netlink options, as for 'null-netlink'
539
540 ** tun
541
542 Defines:
543   tun (closure => netlink closure) [only on linux-2.4]
544   tun-old (closure => netlink closure)
545
546 tun: dict argument
547   flavour (string): optional, type of TUN interface to use
548     ("guess","linux","bsd","streams")
549   device (string): optional, path of TUN/TAP device file ["/dev/net/tun"]
550   interface (string): optional, name of tunnel network interface
551   ifconfig-path (string): optional, path to ifconfig command
552   route-path (string): optional, path to route command
553   ifconfig-type (string): optional, how to perform ifconfig
554   route-type (string): optional, how to add and remove routes
555    types are: "guess", "ioctl", "bsd", "linux", "solaris-2.5"
556   buffer (buffer closure): buffer for host->secnet packets
557  plus generic netlink options, as for 'null-netlink'
558
559 I recommend you don't specify the 'interface' option unless you're
560 doing something that requires the interface name to be constant.
561
562 ** privcache
563
564 Cache of dynamically loaded private keys.
565
566 Defines:
567   priv-cache (closure => privcache closure)
568
569 priv-cache: dict argument
570   privkeys (string): path prefix for private keys.  Each key is
571     looked for at this path prefix followed by the 10-character 
572     hex key id.
573   privcache-size (integer): optional, maximum number of private
574     keys to retain at once. [5]
575   privkey-max (integer): optional, maximum size of private key
576     file in bytes. [4095]
577
578 ** pubkeys
579
580 Defines:
581   make-public (closure => sigpubkey closure)
582
583 make-public: (
584   arg1: sigscheme name
585   arg2: base91s encoded public key data, according to algorithm
586
587 ** rsa
588
589 Defines:
590   sigscheme algorithm 00 "rsa1"
591   rsa-private (closure => sigprivkey closure)
592   rsa-public (closure => sigpubkey closure)
593
594 rsa1 sigscheme algorithm:
595   private key: SSH private key file, version 1, no password
596   public key: SSH public key file, version 1
597     (length, restrictions, email, etc., ignored)
598
599 rsa-private: string[,bool]
600   arg1: filename of SSH private key file (version 1, no password)
601   arg2: whether to check that the key is usable [default True]
602
603 rsa-public: string,string
604   arg1: encryption key (decimal)
605   arg2: modulus (decimal)
606
607 The sigscheme is hardcoded to use sha1.  Both rsa-private and
608 rsa-public look for the following config key in their context:
609   hash (hash closure): hash function [sha1]
610
611
612 ** dh
613
614 Defines:
615   diffie-hellman (closure => dh closure)
616
617 diffie-hellman: string,string[,bool]
618   arg1: modulus (hex)
619   arg2: generator (hex)
620   arg3: whether to check that the modulus is prime [default True]
621
622 ** md5
623
624 Defines:
625   md5 (hash closure)
626
627 ** sha1
628
629 Defines:
630   sha1 (hash closure)
631
632 ** conffile
633
634 Defines:
635   makelist (dictionary => list of definitions)
636   readfile (string => string)
637   map (closure,list => list)
638
639 makelist: dictionary
640   returns a list consisting of the definitions in the dictionary. The keys
641   are discarded.
642
643 readfile: string
644   reads the named file and returns its contents as a string
645
646 map:
647   applies the closure specified as arg1 to each of the elements in the list.
648   Returns a list made up of the outputs of the closure.