X-Git-Url: https://git.distorted.org.uk/~mdw/secnet/blobdiff_plain/558fa3fbbb2e6fd1bed6dec54ef603ceb6c943ad..1fc8a4acb3ef658696038c9c4bd3c155fbc27ac3:/README diff --git a/README b/README index 14b7ad3..e56c444 100644 --- a/README +++ b/README @@ -1,5 +1,39 @@ secnet - flexible VPN software +* Copying + +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. + + * Introduction secnet allows large virtual private networks to be constructed @@ -19,6 +53,20 @@ providing complete links between multiple sites to a simple laptop-to-host link), read the section in this file on 'Creating a VPN'. +* Mailing lists and bug reporting + +There are two mailing lists associated with secnet: an 'announce' list +and a 'discuss' list. Their addresses are: +http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-announce +http://www.chiark.greenend.org.uk/mailman/listinfo/secnet-discuss + +The -announce list receives one message per secnet release. The +-discuss list is for general discussion, including help with +configuration, bug reports, feature requests, etc. + +Bug reports should be sent to ; they will be +forwarded to the -discuss list by me. + * Creating a VPN XXX TODO @@ -92,12 +140,6 @@ f is a dictionary: Note that f/g/e is NOT 4. -In a future version of secnet it will also be permissible to list -other dictionaries before a dictionary definition, -eg. {definitions}. These will be searched in -order for keys, before the lexical parent. (This is not yet -implemented) - Elements that are lists are inserted into lists in definitions, not referenced by them (i.e. you can't have lists of lists). @@ -111,11 +153,14 @@ closure { definitions } is short for closure({definitions}). The main body of secnet, and all the additional modules, predefine some keys in the root dictionary. The main ones are: - yes, true, True, TRUE: the boolean value True - no, false, False, FALSE: the boolean value False + yes, true, True, TRUE, on: the boolean value True + no, false, False, FALSE, off: the boolean value False makelist: turns a dictionary (arg1) into a list of definitions (ignoring the keys) readfile: reads a file (arg1) and returns it as a string + map: applies the closure specified as arg1 to each of the + remaining elements in the list in turn. Returns a list + made up of the outputs of the closure. Keys defined by modules are described below, in the module documentation. @@ -136,7 +181,17 @@ in configuration space to tell it what to do: * secnet command line options -XXX TODO +Usage: secnet [OPTION]... + + -f, --silent, --quiet suppress error messages + -w, --nowarnings suppress warnings + -v, --verbose output extra diagnostics + -c, --config=filename specify a configuration file + -j, --just-check-config stop after reading configfile + -n, --nodetach do not run in background + -d, --debug=item,... set debug options + --help display this help and exit + --version output version information and exit * secnet builtin modules @@ -145,28 +200,278 @@ XXX TODO Defines: adns (closure => resolver closure) +adns: dict argument + config (string): optional, a resolv.conf for ADNS to use + ** random Defines: randomsrc (closure => randomsrc closure) +randomsrc: string[,bool] + arg1: filename of random source + arg2: if True then source is blocking + ** udp Defines: udp (closure => comm closure) -** util +udp: dict argument + 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 `+|- 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. + +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 Defines: logfile (closure => log closure) + syslog (closure => log closure) + +logfile: dict argument + filename (string): where to log to + class (string list): what type of messages to log + { "debug-config", M_DEBUG_CONFIG }, + { "debug-phase", M_DEBUG_PHASE }, + { "debug", M_DEBUG }, + { "all-debug", M_DEBUG|M_DEBUG_PHASE|M_DEBUG_CONFIG }, + { "info", M_INFO }, + { "notice", M_NOTICE }, + { "warning", M_WARNING }, + { "error", M_ERROR }, + { "security", M_SECURITY }, + { "fatal", M_FATAL }, + { "default", M_WARNING|M_ERROR|M_SECURITY|M_FATAL }, + { "verbose", M_INFO|M_NOTICE|M_WARNING|M_ERROR|M_SECURITY|M_FATAL }, + { "quiet", M_FATAL } + +logfile will close and reopen its file upon receipt of SIGHUP. + +syslog: dict argument + ident (string): include this string in every log message + facility (string): facility to log as + { "authpriv", LOG_AUTHPRIV }, + { "cron", LOG_CRON }, + { "daemon", LOG_DAEMON }, + { "kern", LOG_KERN }, + { "local0", LOG_LOCAL0 }, + { "local1", LOG_LOCAL1 }, + { "local2", LOG_LOCAL2 }, + { "local3", LOG_LOCAL3 }, + { "local4", LOG_LOCAL4 }, + { "local5", LOG_LOCAL5 }, + { "local6", LOG_LOCAL6 }, + { "local7", LOG_LOCAL7 }, + { "lpr", LOG_LPR }, + { "mail", LOG_MAIL }, + { "news", LOG_NEWS }, + { "syslog", LOG_SYSLOG }, + { "user", LOG_USER }, + { "uucp", LOG_UUCP } + +** util + +Defines: sysbuffer (closure => buffer closure) +sysbuffer: integer[,dict] + arg1: buffer length + arg2: options: + lockdown (boolean): if True, mlock() the buffer + ** site Defines: site (closure => site closure) -** transform +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 (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 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; mobile: 2 days] + setup-retries (integer): max number of times to transmit a key negotiation + 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] + 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. + [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 + setup-timeout: failure of attempt to setup a session key, through timeout + activate-key: activation of a new session key + timeout-key: deletion of current session key through age + security: anything potentially suspicious + state-change: steps in the key setup protocol + 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. + 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 +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 + +Defines: + eax-serpent (closure => transform closure) + +** transform-cbcmac Defines: serpent256-cbc (closure => transform closure) @@ -174,10 +479,70 @@ Defines: ** netlink Defines: + null-netlink (closure => closure or netlink closure) + +null-netlink: dict argument + name (string): name for netlink device, used in log messages + networks (string list): networks on the host side of the netlink device + remote-networks (string list): networks that may be claimed + by the remote site using this netlink device + local-address (string): IP address of host's tunnel interface + secnet-address (string): IP address of this netlink device + ptp-address (string): IP address of the other end of a point-to-point link + mtu (integer): MTU of host's tunnel interface + +Only one of secnet-address or ptp-address may be specified. If +point-to-point mode is in use then the "routes" option must also be +specified, and netlink returns a netlink closure that should be used +directly with the "link" option to the site closure. If +point-to-point mode is not in use then netlink returns a closure that +may be invoked using a dict argument with the following keys to yield +a netlink closure: + routes (string list): networks reachable down the tunnel attached to + this instance of netlink + options (string list): + allow-route: allow packets coming from this tunnel to be routed to + 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): MTU of host's tunnel interface + +Netlink will dump its current routing table to the system/log on +receipt of SIGUSR1. + +** slip + +Defines: userv-ipif (closure => netlink closure) + +userv-ipif: dict argument + userv-path (string): optional, where to find userv ["userv"] + service-user (string): optional, username for userv-ipif service ["root"] + service-name (string): optional, name of userv-ipif service ["ipif"] + buffer (buffer closure): buffer for assembly of host->secnet packets + plus generic netlink options, as for 'null-netlink' + +** tun + +Defines: tun (closure => netlink closure) [only on linux-2.4] tun-old (closure => netlink closure) - null-netlink (closure => netlink closure) + +tun: dict argument + flavour (string): optional, type of TUN interface to use + ("guess","linux","bsd","streams") + device (string): optional, path of TUN/TAP device file ["/dev/net/tun"] + interface (string): optional, name of tunnel network interface + ifconfig-path (string): optional, path to ifconfig command + route-path (string): optional, path to route command + ifconfig-type (string): optional, how to perform ifconfig + route-type (string): optional, how to add and remove routes + types are: "guess", "ioctl", "bsd", "linux", "solaris-2.5" + buffer (buffer closure): buffer for host->secnet packets + plus generic netlink options, as for 'null-netlink' + +I recommend you don't specify the 'interface' option unless you're +doing something that requires the interface name to be constant. ** rsa @@ -185,12 +550,48 @@ Defines: rsa-private (closure => rsaprivkey closure) rsa-public (closure => rsapubkey closure) +rsa-private: string[,bool] + arg1: filename of SSH private key file (version 1, no password) + arg2: whether to check that the key is usable [default True] + +rsa-public: string,string + arg1: encryption key (decimal) + arg2: modulus (decimal) + ** dh Defines: diffie-hellman (closure => dh closure) +diffie-hellman: string,string[,bool] + arg1: modulus (hex) + arg2: generator (hex) + arg3: whether to check that the modulus is prime [default True] + ** md5 Defines: md5 (hash closure) + +** sha1 + +Defines: + sha1 (hash closure) + +** conffile + +Defines: + makelist (dictionary => list of definitions) + readfile (string => string) + map (closure,list => list) + +makelist: dictionary + returns a list consisting of the definitions in the dictionary. The keys + are discarded. + +readfile: string + reads the named file and returns its contents as a string + +map: + applies the closure specified as arg1 to each of the elements in the list. + Returns a list made up of the outputs of the closure.