X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=secnet.git;a=blobdiff_plain;f=README;h=a01156c6d8a9491c12dfa7c946631c930d313f11;hp=73679c2acd3695fd0a4377ffa4c685736cccaca2;hb=ca53592227f187270bfd611e21e63f33d07a9f7e;hpb=b98e450dcb5dde31417880a2af601bd8372ad673 diff --git a/README b/README index 73679c2..a01156c 100644 --- a/README +++ b/README @@ -2,18 +2,37 @@ secnet - flexible VPN software * Copying -secnet is Copyright (C) 1995--2003 Stephen Early -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 + Copyright 2002-2014 Ian Jackson + 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 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 portable snprintf implementation in snprintf.c is Copyright (C) -1999 Mark Martinec and is distributed under the -terms of the Frontier Artistic License. You can find the standard -version of snprintf.c at http://www.ijs.si/software/snprintf/ - -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 @@ -199,10 +218,83 @@ Defines: udp (closure => comm closure) udp: dict argument - address (string): IP address 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 (string list): which interfaces to process; each entry is + optionally `!' or `+' followed by a glob pattern (which is applied to a + prospective interface using fnmatch with no flags). If no list is + specified, or the list ends with a `!' entry, a default list is + used/appended: "!tun*","!tap*","!sl*","!userv*","!lo","*". Patterns + which do not start with `*' or an alphanumeric need to be preceded + by `!' 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 `+|- 4|6 ' where 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. + +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 @@ -270,26 +362,33 @@ site: dict argument local-name (string): this site's name for itself name (string): the name of the site's peer link (netlink closure) - comm (comm closure) + comm (one or more comm closures): if there is more than one, the + first one will be used for any key setups initiated by us using the + configured address. Others are only used if our peer talks to + them. resolver (resolver closure) random (randomsrc closure) local-key (rsaprivkey closure) - address (string): optional, DNS name used to find our peer + address (string list): optional, DNS name(s) used to find our peer; + address literals are supported too if enclosed in `[' `]'. port (integer): mandatory if 'address' is specified: the port used to contact our peer key (rsapubkey closure): our peer's public key transform (transform closure): how to mangle packets sent between sites dh (dh closure) hash (hash closure) - key-lifetime (integer): max lifetime of a session key, in ms [one hour] + key-lifetime (integer): max lifetime of a session key, in ms + [one hour; mobile: 2 days] setup-retries (integer): max number of times to transmit a key negotiation - packet [5] + packet [5; mobile: 30] setup-timeout (integer): time between retransmissions of key negotiation - packets, in ms [1000] + packets, in ms [2000; mobile: 1000] wait-time (integer): after failed key setup, wait this long (in ms) before - allowing another attempt [20000] + allowing another attempt [20000; mobile: 10000] renegotiate-time (integer): if we see traffic on the link after this time - then renegotiate another session key immediately [depends on key-lifetime] + 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] log-events (string list): types of events to log for this site @@ -303,9 +402,61 @@ site: dict argument packet-drop: whenever we throw away an outgoing packet dump-packets: every key setup packet we see errors: failure of name resolution, internal errors + peer-addrs: changes to sets of peer addresses (interesting for mobile peers) all: everything (too much!) + mobile (bool): if True then peer is "mobile" ie we assume it may + change its apparent IP address and port number without either it + or us being aware of the change; so, we remember the last several + port/addr pairs we've seen and send packets to all of them + (subject to a timeout). We maintain one set of addresses for key + setup exchanges, and another for data traffic. Two communicating + peers must not each regard the other as mobile, or all the traffic + in each direction will be triplicated (strictly, transmitted + mobile-peers-max times) and anyway two peers whose public contact + address may suddenly change couldn't communicate reliably because + their contact addresses might both change at once. [false] + mobile-peers-max (integer): Maximum number of peer port/addr pairs we + remember and send to. Must be at least 1 and no more than 5. + [4 if any address is configured, otherwise 3] + static-peers-max (integer): Maximum number of peer port/addr pairs + we can try for a static site. Must be at least 1 and no more + than 5. [4 or 3, as above] + mobile-peer-expiry (integer): For "mobile" peers only, the length + of time (in seconds) for which we will keep sending to multiple + address/ports from which we have not seen incoming traffic. [120] + local-mobile (bool): if True then other peers have been told we are + "mobile". This should be True iff the peers' site configurations + for us have "mobile True" (and if we find a site configuration for + ourselves in the config, we insist on this). The effect is to + check that there are no links both ends of which are allegedly + mobile (which is not supported, so those links are ignored) and + to change some of the tuning parameter defaults. [false] + mtu-target (integer): Desired value of the inter-site MTU for this + peering. This value will be advertised to the peer (which ought + to affect incoming packets), and if the peer advertises an MTU its + value will be combined with this setting to compute the inter-site + MTU. (secnet will still accept packets which exceed the + (negotiated or assumed) inter-site MTU.) Setting a lower + inter-site MTU can be used to try to restrict the sizes of the + packets sent over the underlying public network (e.g. to work + around network braindamage). It is not normally useful to set a + larger value for mtu-target than the VPN's general MTU (which + 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. + +Links involving mobile peers have some different tuning parameter +default values, which are generally more aggressive about retrying key +setup but more relaxed about using old keys. These are noted with +"mobile:", above, and apply whether the mobile peer is local or +remote. + +** transform-eax -** transform +Defines: + eax-serpent (closure => transform closure) + +** transform-cbcmac Defines: serpent256-cbc (closure => transform closure) @@ -339,7 +490,7 @@ a netlink closure: other tunnels as well as the host (used for mobile devices like laptops) soft: remove these routes from the host's routing table when the tunnel link quality is zero - mtu (integer): default MTU over this link; may be updated by tunnel code + mtu (integer): MTU of host's tunnel interface Netlink will dump its current routing table to the system/log on receipt of SIGUSR1.