* Copying
-secnet is Copyright (C) 1995--2003 Stephen Early <steve@greenend.org.uk>
-It is distributed under the terms of the GNU General Public License,
-version 2 or later. See the file COPYING for more information.
+secnet is
+ Copyright 1995-2003 Stephen Early <steve@greenend.org.uk>
+ Copyright 2002-2014 Ian Jackson <ijackson@chiark.greenend.org.uk>
+ Copyright 1991 Massachusetts Institute of Technology
+ Copyright 1998 Ross Anderson, Eli Biham, Lars Knudsen
+ Copyright 1993 Colin Plumb
+ Copyright 1998 James H. Brown, Steve Reid
+ Copyright 2000 Vincent Rijmen, Antoon Bosselaers, Paulo Barreto
+ Copyright 2001 Saul Kravitz
+ Copyright 2004 Fabrice Bellard
+ Copyright 2002 Guido Draheim
+ Copyright 2005-2010 Free Software Foundation, Inc.
+ Copyright 1995-2001 Jonathan Amery
+ Copyright 1995-2003 Peter Benie
+ Copyright 2011 Richard Kettlewell
+ Copyright 2012 Matthew Vernon
+ Copyright 2013-2019 Mark Wooding
+ Copyright 1995-2013 Simon Tatham
+
+secnet is distributed under the terms of the GNU General Public
+License, version 3 or later. Some individual files have more
+permissive licences; where this is the case, it is documented in the
+header comment for the files in question.
+
+secnet is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+for more details.
+
+The file COPYING contains a copy of the GNU GPL v3.
-The IP address handling library in ipaddr.py is Copyright (C)
-1996--2000 Cendio Systems AB, and is distributed under the terms of
-the GPL.
* Introduction
udp (closure => comm closure)
udp: dict argument
- address (string list): IPv6 or IPv4 addresses to listen and send on
+ address (string list): IPv6 or IPv4 addresses to listen and send on;
+ default is all local addresses
+ port (integer): UDP port to listen and send on; optional if you
+ don't need to have a stable address for your peers to talk to
+ (in which case your site ought probably to have `local-mobile true').
+ buffer (buffer closure): buffer for incoming packets
+ authbind (string): optional, path to authbind-helper program
+
+** polypath
+
+Defines:
+ polypath (closure => comm closure)
+
+polypath: dict argument
port (integer): UDP port to listen and send on
buffer (buffer closure): buffer for incoming packets
authbind (string): optional, path to authbind-helper program
+ max-interfaces (number): optional, max number of different interfaces to
+ use (also, maximum steady-state amount of packet multiplication);
+ interfaces marked with `@' do not count.
+ interfaces (string list): which interfaces to process; each entry is
+ optionally `!' or `+' or `@' followed by a glob pattern (which is
+ applied to a prospective interface using fnmatch with no flags).
+ `+' or nothing means to process normally. `!' means to ignore;
+ `@' means to use only in conjunction with dedicated-interface-addr.
+ If no list is specified, or the list ends with a `!' entry, a
+ default list is used/appended:
+ "!tun*","!tap*","!sl*","!userv*","!lo","@hippo*","*".
+ Patterns which do not start with `*' or an alphanumeric need to be
+ preceded by `!' or `+' or `@'.
+ monitor-command (string list): Program to use to monitor appearance
+ and disappearance of addresses on local network interfaces. Should
+ produce lines of the form `+|-<ifname> 4|6 <addr>' where <addr> is
+ an address literal. Each - line should relate to a previously
+ printed + line. On startup, should produce a + line for each
+ currently existing address. secnet does filtering so there is no
+ need to strip out tun interfaces, multicast addresses, and so on.
+ The command is run as the user secnet is started as (not the one
+ which secnet may drop privilege to due to the configured `userid').
+ The default depends on the operating system.
+ permit-loopback (boolean): Normally, loopback IPv6 and IPv4
+ addresses on local interfaces are disregarded, because such
+ interfaces are not interesting for communicating with distant
+ hosts. Setting this option will ignore that check, which can be
+ useful for testing. Setting this option also removes "!lo*" from
+ the default interface pattern list.
+
+When using this comm, packets are sent out of every active interface
+on the host (where possible). It is important that interfaces created
+by secnet itself are not included! secnet's default filter list tries
+to do this.
+
+This comm only makes sense for sites which are mobile. That is, the
+site closures used with this comm should all have the `local-mobile'
+parameter set to `true'. When the local site site is not marked
+mobile the address selection machinery might fixate on an unsuitable
+address.
+
+polypath takes site-specific informtion as passed to the `comm-info'
+site closure parameter. The entries understood in the dictionary
+are:
+ dedicated-interface-addr (string): IPv4 or IPv6 address
+ literal. Interfaces specified with `@' in `interfaces' will be
+ used for the corresponding site iff the interface local address
+ is this address.
+
+For an interface to work with polypath, it must either have a suitable
+default route, or be a point-to-point interface. In the general case
+this might mean that the host would have to have multiple default
+routes. However in practice the most useful configuration is two
+interfaces being (1) wifi (2) mobile internet.
+
+I have had success on Linux by using network-manager for wifi and
+invoking ppp directly for mobile internet. ppp sets up a
+point-to-point link, and does not add a default route if there already
+is one. network-manager always sets up a default route. The result
+is that the wifi always has a default route (so is useable); ppp
+(being a point-to-point link) does not need one.
+
+The use of polypath requires that secnet be started with root
+privilege, to make the setsockopt(,,SO_BINDTODEVICE,) calls. If the
+configuration specifies that secnet should drop privilege (see
+`userid' above), secnet will keep a special process around for this
+purpose; that process will handle local network interface changes but
+does not deal with any packets, key exchange, etc.
+
+polypath support is only available when secnet is built against an
+IPv6-capable version of adns (because it wants features in the newer
+adns).
** log
packet [5; mobile: 30]
setup-timeout (integer): time between retransmissions of key negotiation
packets, in ms [2000; mobile: 1000]
- wait-time (integer): after failed key setup, wait this long (in ms) before
- allowing another attempt [20000; mobile: 10000]
+ wait-time (integer): after failed key setup, wait roughly this long
+ (in ms) before allowing another attempt [20000; mobile: 10000]
+ Actual wait time is randomly chosen between ~0.5x and ~1.5x this.
renegotiate-time (integer): if we see traffic on the link after this time
then renegotiate another session key immediately (in ms)
[half key-lifetime, or key-lifetime minus 5 mins (mobile: 12 hours),
whichever is longer].
keepalive (bool): if True then attempt always to keep a valid session key.
- Not actually currently implemented. [false]
+ [false]
log-events (string list): types of events to log for this site
unexpected: unexpected key setup packets (may be late retransmissions)
setup-init: start of attempt to setup a session key
should be reflected in the local private interface MTU, ie the mtu
parameter to netlink). If this parameter is not set, or is set
to 0, the default is to use the local private link mtu.
+ comm-info (dict): Information for the comm, used when this site
+ wants to transmit. If the comm does not support this, it is
+ ignored.
Links involving mobile peers have some different tuning parameter
default values, which are generally more aggressive about retrying key
~ianmdlvl / secnet.git / blobdiff