X-Git-Url: https://git.distorted.org.uk/~mdw/secnet/blobdiff_plain/558fa3fbbb2e6fd1bed6dec54ef603ceb6c943ad..c6f79b178fe27ee315055dccb371b63ca1a6183a:/README diff --git a/README b/README index 14b7ad3..79b5447 100644 --- a/README +++ b/README @@ -145,27 +145,135 @@ 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 + port (integer): UDP port to listen and send on + buffer (buffer closure): buffer for incoming packets + authbind (string): optional, path to authbind-helper program + +** 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) +site: dict argument + local-name (string): this site's name for itself + name (string): the name of the site's peer + netlink (netlink closure) + comm (comm closure) + resolver (resolver closure) + random (randomsrc closure) + local-key (rsaprivkey closure) + address (string): optional, DNS name used to find our peer + port (integer): mandatory if 'address' is specified: the port used + to contact our peer + networks (string list): networks that our peer may claim traffic for + 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] + setup-retries (integer): max number of times to transmit a key negotiation + packet [5] + setup-timeout (integer): time between retransmissions of key negotiation + packets, in ms [1000] + wait-time (integer): after failed key setup, wait this long (in ms) before + allowing another attempt [20000] + renegotiate-time (integer): if we see traffic on the link after this time + then renegotiate another session key immediately [depends on key-lifetime] + keepalive (bool): if True then attempt always to keep a valid session key + 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 + all: everything (too much!) + netlink-options (string list): options to pass to netlink device when + registering remote networks + soft: create 'soft' routes that go away when there's no key established + with the peer + allow-route: allow packets from our peer to be sent down other tunnels, + as well as to the host + ** transform Defines: @@ -174,10 +282,62 @@ Defines: ** netlink Defines: + null-netlink (closure => 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 + exclude-remote-networks (string list): networks that may never be claimed + by any 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 precisely one tunnel must register +with the netlink device. + +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 + 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 + buffer (buffer closure): buffer for host->secnet packets + plus generic netlink options, as for 'null-netlink' + +tun-old: dict argument + device (string): optional, path of TUN/TAP device file ["/dev/tun*"] + interface (string): optional, name of tunnel network interface + interface-search (bool): optional, whether to search for a free tunnel + interface (True if 'device' not specified, otherwise False) + ifconfig-path (string): optional, path to ifconfig command + route-path (string): optional, path to route command + 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 +345,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.