| 1 | secnet - flexible VPN software |
| 2 | |
| 3 | * Introduction |
| 4 | |
| 5 | secnet allows large virtual private networks to be constructed |
| 6 | spanning multiple separate sites. It is designed for the case where a |
| 7 | private network connecting many hosts is 'hidden' behind a single |
| 8 | globally-routable IP address, but can also be applied in other |
| 9 | circumstances. It communicates entirely using UDP, and works well |
| 10 | with gateways that implement network address translation. |
| 11 | |
| 12 | If you are installing secnet to join an existing VPN, you should read |
| 13 | the 'INSTALL' file and your particular VPN's documentation now. You |
| 14 | may need to refer back to this file for information on the netlink and |
| 15 | comm sections of the configuration file. |
| 16 | |
| 17 | If you are thinking about setting up a new VPN of any size (from one |
| 18 | providing complete links between multiple sites to a simple |
| 19 | laptop-to-host link), read the section in this file on 'Creating a |
| 20 | VPN'. |
| 21 | |
| 22 | * Creating a VPN |
| 23 | |
| 24 | XXX TODO |
| 25 | |
| 26 | * secnet configuration file format |
| 27 | |
| 28 | By default secnet on linux reads /etc/secnet/secnet.conf. The default |
| 29 | may be different on other platforms. |
| 30 | |
| 31 | This file defines a dictionary (a mapping from keys to values) full of |
| 32 | configuration information for secnet. Two keys must be defined in |
| 33 | this file for secnet to start. One is "system", a dictionary |
| 34 | containing systemwide control parameters. The other is "sites", a |
| 35 | list of all the sites that you intend to communicate with. |
| 36 | |
| 37 | The configuration file has a very simple syntax; keys are defined as |
| 38 | follows: |
| 39 | |
| 40 | key definition; |
| 41 | or |
| 42 | key = definition; |
| 43 | |
| 44 | (the "=" is optional) |
| 45 | |
| 46 | Keys must match the following regular expression: |
| 47 | [[:alpha:]_][[:alnum:]\-_]* |
| 48 | |
| 49 | i.e. the first character must be an alpha or an underscore, and the |
| 50 | remaining characters may be alphanumeric, '-' or '_'. |
| 51 | |
| 52 | Keys can be defined to be a comma-separated list of any of the |
| 53 | following types: |
| 54 | |
| 55 | a boolean |
| 56 | a string, in quotes |
| 57 | a number, in decimal |
| 58 | a dictionary of definitions, enclosed in { } |
| 59 | a "closure", followed by arguments |
| 60 | a path to a key that already exists, to reference that definition |
| 61 | |
| 62 | Note that dictionaries can be nested: a key in one dictionary can |
| 63 | refer to another dictionary. When secnet looks for a key in a |
| 64 | particular directory and can't find it, it looks in the dictionary's |
| 65 | lexical 'parents' in turn until it finds it (or fails to find it at |
| 66 | all and stops with an error). |
| 67 | |
| 68 | Definitions can refer to previous definitions by naming them with a |
| 69 | path. Paths are key1/key2/key3... (starting from wherever we find |
| 70 | key1, i.e. in the current dictionary or any of its parents), or |
| 71 | alternatively /key1/key2/key3... (to start from the root). |
| 72 | Definitions cannot refer to future definitions. |
| 73 | |
| 74 | Example: |
| 75 | |
| 76 | a=1; |
| 77 | b=2; |
| 78 | c={ d=3; e=a; }; |
| 79 | f={ a=4; g=c; }; |
| 80 | |
| 81 | The following paths are valid: |
| 82 | a is 1 |
| 83 | b is 2 |
| 84 | c is a dictionary: |
| 85 | c/d is 3 |
| 86 | c/e is 1 |
| 87 | f is a dictionary: |
| 88 | f/a is 4 |
| 89 | f/g is a dictionary: |
| 90 | f/g/d is 3 |
| 91 | f/g/e is 1 |
| 92 | |
| 93 | Note that f/g/e is NOT 4. |
| 94 | |
| 95 | In a future version of secnet it will also be permissible to list |
| 96 | other dictionaries before a dictionary definition, |
| 97 | eg. <defaults,otherdefaults>{definitions}. These will be searched in |
| 98 | order for keys, before the lexical parent. (This is not yet |
| 99 | implemented) |
| 100 | |
| 101 | Elements that are lists are inserted into lists in definitions, not |
| 102 | referenced by them (i.e. you can't have lists of lists). |
| 103 | |
| 104 | Some closures may be followed by an argument list in ( ), and may |
| 105 | return any number of whatever type they like (including other |
| 106 | closures). Some types of closure (typically those returned from |
| 107 | invokations of other closures) cannot be invoked. |
| 108 | |
| 109 | closure { definitions } is short for closure({definitions}). |
| 110 | |
| 111 | The main body of secnet, and all the additional modules, predefine |
| 112 | some keys in the root dictionary. The main ones are: |
| 113 | |
| 114 | yes, true, True, TRUE: the boolean value True |
| 115 | no, false, False, FALSE: the boolean value False |
| 116 | makelist: turns a dictionary (arg1) into a list of definitions |
| 117 | (ignoring the keys) |
| 118 | readfile: reads a file (arg1) and returns it as a string |
| 119 | |
| 120 | Keys defined by modules are described below, in the module |
| 121 | documentation. |
| 122 | |
| 123 | Other configuration files can be included inline by writing "include |
| 124 | filename" at the start of a line. |
| 125 | |
| 126 | After the configuration file is read, secnet looks for particular keys |
| 127 | in configuration space to tell it what to do: |
| 128 | |
| 129 | system: a dictionary which can contain the following keys: |
| 130 | log (log closure): a destination for system messages |
| 131 | userid (string): the userid for secnet to run as once it drops privileges |
| 132 | pidfile (string): where to store its PID |
| 133 | |
| 134 | sites: a list of closures of type 'site', which define other tunnel |
| 135 | endpoints that secnet will attempt to communicate with |
| 136 | |
| 137 | * secnet command line options |
| 138 | |
| 139 | XXX TODO |
| 140 | |
| 141 | * secnet builtin modules |
| 142 | |
| 143 | ** resolver |
| 144 | |
| 145 | Defines: |
| 146 | adns (closure => resolver closure) |
| 147 | |
| 148 | adns: dict argument |
| 149 | config (string): optional, a resolv.conf for ADNS to use |
| 150 | |
| 151 | ** random |
| 152 | |
| 153 | Defines: |
| 154 | randomsrc (closure => randomsrc closure) |
| 155 | |
| 156 | randomsrc: string[,bool] |
| 157 | arg1: filename of random source |
| 158 | arg2: if True then source is blocking |
| 159 | |
| 160 | ** udp |
| 161 | |
| 162 | Defines: |
| 163 | udp (closure => comm closure) |
| 164 | |
| 165 | udp: dict argument |
| 166 | port (integer): UDP port to listen and send on |
| 167 | buffer (buffer closure): buffer for incoming packets |
| 168 | |
| 169 | ** util |
| 170 | |
| 171 | Defines: |
| 172 | logfile (closure => log closure) |
| 173 | sysbuffer (closure => buffer closure) |
| 174 | |
| 175 | ** site |
| 176 | |
| 177 | Defines: |
| 178 | site (closure => site closure) |
| 179 | |
| 180 | site: dict argument |
| 181 | local-name (string): this site's name for itself |
| 182 | name (string): the name of the site's peer |
| 183 | netlink (netlink closure) |
| 184 | comm (comm closure) |
| 185 | resolver (resolver closure) |
| 186 | random (randomsrc closure) |
| 187 | local-key (rsaprivkey closure) |
| 188 | address (string): optional, DNS name used to find our peer |
| 189 | port (integer): mandatory if 'address' is specified: the port used |
| 190 | to contact our peer |
| 191 | networks (string list): networks that our peer may claim traffic for |
| 192 | key (rsapubkey closure): our peer's public key |
| 193 | transform (transform closure): how to mangle packets sent between sites |
| 194 | dh (dh closure) |
| 195 | hash (hash closure) |
| 196 | key-lifetime (integer): max lifetime of a session key, in ms [one hour] |
| 197 | setup-retries (integer): max number of times to transmit a key negotiation |
| 198 | packet [5] |
| 199 | setup-timeout (integer): time between retransmissions of key negotiation |
| 200 | packets, in ms [1000] |
| 201 | wait-time (integer): after failed key setup, wait this long (in ms) before |
| 202 | allowing another attempt [20000] |
| 203 | renegotiate-time (integer): if we see traffic on the link after this time |
| 204 | then renegotiate another session key immediately [depends on key-lifetime] |
| 205 | keepalive (bool): if True then attempt always to keep a valid session key |
| 206 | log-events (string list): types of events to log for this site |
| 207 | unexpected: unexpected key setup packets (may be late retransmissions) |
| 208 | setup-init: start of attempt to setup a session key |
| 209 | setup-timeout: failure of attempt to setup a session key, through timeout |
| 210 | activate-key: activation of a new session key |
| 211 | timeout-key: deletion of current session key through age |
| 212 | security: anything potentially suspicious |
| 213 | state-change: steps in the key setup protocol |
| 214 | packet-drop: whenever we throw away an outgoing packet |
| 215 | dump-packets: every key setup packet we see |
| 216 | errors: failure of name resolution, internal errors |
| 217 | all: everything (too much!) |
| 218 | netlink-options (string list): options to pass to netlink device when |
| 219 | registering remote networks |
| 220 | soft: create 'soft' routes that go away when there's no key established |
| 221 | with the peer |
| 222 | allow-route: allow packets from our peer to be sent down other tunnels, |
| 223 | as well as to the host |
| 224 | |
| 225 | ** transform |
| 226 | |
| 227 | Defines: |
| 228 | serpent256-cbc (closure => transform closure) |
| 229 | |
| 230 | ** netlink |
| 231 | |
| 232 | Defines: |
| 233 | null-netlink (closure => netlink closure) |
| 234 | |
| 235 | null-netlink: dict argument |
| 236 | name (string): name for netlink device, used in log messages |
| 237 | networks (string list): networks on the host side of the netlink device |
| 238 | exclude-remote-networks (string list): networks that may never be claimed |
| 239 | by any remote site using this netlink device |
| 240 | local-address (string): IP address of host's tunnel interface |
| 241 | secnet-address (string): IP address of this netlink device |
| 242 | mtu (integer): MTU of host's tunnel interface |
| 243 | |
| 244 | ** slip |
| 245 | |
| 246 | Defines: |
| 247 | userv-ipif (closure => netlink closure) |
| 248 | |
| 249 | userv-ipif: dict argument |
| 250 | userv-path (string): optional, where to find userv ["userv"] |
| 251 | service-user (string): optional, username for userv-ipif service ["root"] |
| 252 | service-name (string): optional, name of userv-ipif service ["ipif"] |
| 253 | buffer (buffer closure): buffer for assembly of host->secnet packets |
| 254 | plus generic netlink options, as for 'null-netlink' |
| 255 | |
| 256 | ** tun |
| 257 | |
| 258 | Defines: |
| 259 | tun (closure => netlink closure) [only on linux-2.4] |
| 260 | tun-old (closure => netlink closure) |
| 261 | |
| 262 | tun: dict argument |
| 263 | device (string): optional, path of TUN/TAP device file ["/dev/net/tun"] |
| 264 | interface (string): optional, name of tunnel network interface |
| 265 | ifconfig-path (string): optional, path to ifconfig command |
| 266 | route-path (string): optional, path to route command |
| 267 | buffer (buffer closure): buffer for host->secnet packets |
| 268 | plus generic netlink options, as for 'null-netlink' |
| 269 | |
| 270 | tun-old: dict argument |
| 271 | device (string): optional, path of TUN/TAP device file ["/dev/tun*"] |
| 272 | interface (string): optional, name of tunnel network interface |
| 273 | interface-search (bool): optional, whether to search for a free tunnel |
| 274 | interface (True if 'device' not specified, otherwise False) |
| 275 | ifconfig-path (string): optional, path to ifconfig command |
| 276 | route-path (string): optional, path to route command |
| 277 | plus generic netlink options, as for 'null-netlink' |
| 278 | |
| 279 | ** rsa |
| 280 | |
| 281 | Defines: |
| 282 | rsa-private (closure => rsaprivkey closure) |
| 283 | rsa-public (closure => rsapubkey closure) |
| 284 | |
| 285 | rsa-private: string[,bool] |
| 286 | arg1: filename of SSH private key file (version 1, no password) |
| 287 | arg2: whether to check that the key is usable [default True] |
| 288 | |
| 289 | rsa-public: string,string |
| 290 | arg1: encryption key (decimal) |
| 291 | arg2: modulus (decimal) |
| 292 | |
| 293 | ** dh |
| 294 | |
| 295 | Defines: |
| 296 | diffie-hellman (closure => dh closure) |
| 297 | |
| 298 | diffie-hellman: string,string[,bool] |
| 299 | arg1: modulus (hex) |
| 300 | arg2: generator (hex) |
| 301 | arg3: whether to check that the modulus is prime [default True] |
| 302 | |
| 303 | ** md5 |
| 304 | |
| 305 | Defines: |
| 306 | md5 (hash closure) |
| 307 | |
| 308 | ** sha1 |
| 309 | |
| 310 | Defines: |
| 311 | sha1 (hash closure) |