* 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 portable snprintf implementation in snprintf.c is Copyright (C)
-1999 Mark Martinec <mark.martinec@ijs.si> 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
--help display this help and exit
--version output version information and exit
+* base91s
+
+secnet defines a variant of the base91 encoding `basE91', from
+ http://base91.sourceforge.net/
+
+base91s is the same as baseE91 except that:
+ - in the encoded charset, `"' is replaced with `-'
+ - spaces, newlines etc. and other characters outside the charset
+ are not permitted (although in some places they may be ignored,
+ this is not guaranteed).
+
* secnet builtin modules
** resolver
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 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
syslog (closure => log closure)
logfile: dict argument
- filename (string): where to log to
+ filename (string): where to log to; default is stderr
+ prefix (string): added to messages [""]
class (string list): what type of messages to log
{ "debug-config", M_DEBUG_CONFIG },
{ "debug-phase", M_DEBUG_PHASE },
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
+ key-cache (privcache closure)
+ local-key (sigprivkey closure): Deprecated; use key-cache instead.
+ 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
+ peer-keys (string): path (prefix) for peer public key set file(s);
+ see README.make-secnet-sites re `pub' etc. and NOTES.peer-keys.
+ key (sigpubkey closure): our peer's public key (obsolete)
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 [2000]
- wait-time (integer): after failed key setup, wait this long (in ms) before
- allowing another attempt [20000]
+ packets, in ms [2000; mobile: 1000]
+ 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, whichever is longer].
+ [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
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. [3]
+ 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]
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). [false]
+ 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
-** transform
+Defines:
+ eax-serpent (closure => transform closure)
+
+** transform-cbcmac
Defines:
serpent256-cbc (closure => transform 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.
I recommend you don't specify the 'interface' option unless you're
doing something that requires the interface name to be constant.
+** privcache
+
+Cache of dynamically loaded private keys.
+
+Defines:
+ priv-cache (closure => privcache closure)
+
+priv-cache: dict argument
+ privkeys (string): path prefix for private keys. Each key is
+ looked for at this path prefix followed by the 10-character
+ hex key id.
+ privcache-size (integer): optional, maximum number of private
+ keys to retain at once. [5]
+ privkey-max (integer): optional, maximum size of private key
+ file in bytes. [4095]
+
+** pubkeys
+
+Defines:
+ make-public (closure => sigpubkey closure)
+
+make-public: (
+ arg1: sigscheme name
+ arg2: base91s encoded public key data, according to algorithm
+
** rsa
Defines:
- rsa-private (closure => rsaprivkey closure)
- rsa-public (closure => rsapubkey closure)
+ sigscheme algorithm 00 "rsa1"
+ rsa-private (closure => sigprivkey closure)
+ rsa-public (closure => sigpubkey closure)
+
+rsa1 sigscheme algorithm:
+ private key: SSH private key file, version 1, no password
+ public key: SSH public key file, version 1
+ (length, restrictions, email, etc., ignored)
rsa-private: string[,bool]
arg1: filename of SSH private key file (version 1, no password)
arg1: encryption key (decimal)
arg2: modulus (decimal)
+The sigscheme is hardcoded to use sha1. Both rsa-private and
+rsa-public look for the following config key in their context:
+ hash (hash closure): hash function [sha1]
+
+
** dh
Defines:
~ian / secnet.git / blobdiff