| 1 | .\" Man page for secnet. |
| 2 | .\" |
| 3 | .\" See the secnet.git README, or the Debian copyright file, for full |
| 4 | .\" list of copyright holders. |
| 5 | .\" |
| 6 | .\" secnet is free software; you can redistribute it and/or modify it |
| 7 | .\" under the terms of the GNU General Public License as published by |
| 8 | .\" the Free Software Foundation; either version 3 of the License, or |
| 9 | .\" (at your option) any later version. |
| 10 | .\" |
| 11 | .\" secnet is distributed in the hope that it will be useful, but |
| 12 | .\" WITHOUT ANY WARRANTY; without even the implied warranty of |
| 13 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
| 14 | .\" General Public License for more details. |
| 15 | .\" |
| 16 | .\" You should have received a copy of the GNU General Public License |
| 17 | .\" version 3 along with secnet; if not, see |
| 18 | .\" https://www.gnu.org/licenses/gpl.html. |
| 19 | .TH secnet 8 |
| 20 | |
| 21 | .SH NAME |
| 22 | secnet \- VPN router daemon |
| 23 | |
| 24 | .SH SYNOPSIS |
| 25 | \fBsecnet\fR [\fIOPTIONS\fR] |
| 26 | |
| 27 | .SH DESCRIPTION |
| 28 | \fBsecnet\fR allows virtual private networks to be constructed |
| 29 | spanning multiple separate sites. |
| 30 | |
| 31 | .SH OPTIONS |
| 32 | .TP |
| 33 | .B --verbose\fR, \fB-v |
| 34 | Enable extra diagnostics. |
| 35 | .TP |
| 36 | .B --nowarnings\fR, \fB-w |
| 37 | Suppress warnings. |
| 38 | .TP |
| 39 | .B --help |
| 40 | Display usage message. |
| 41 | .TP |
| 42 | .B --version |
| 43 | Display version string. |
| 44 | .TP |
| 45 | .B --nodetach\fR, \fB-n |
| 46 | Don't go into background. |
| 47 | The default behaviour is to become a daemon during startup. |
| 48 | .TP |
| 49 | .B --silent\fR, \fB--quiet\fR, \fB-f |
| 50 | Suppress error messages. |
| 51 | .TP |
| 52 | .B --debug\fR, \fB-d |
| 53 | Enable debug messages. |
| 54 | .TP |
| 55 | .B --config\fR, \fB-c \fIPATH |
| 56 | Specify configuration file. |
| 57 | The default is \fI/etc/secnet/secnet.conf\fR. |
| 58 | .TP |
| 59 | .B --just-check-config\fR, \fB-j |
| 60 | Check configuration and exit. |
| 61 | .TP |
| 62 | .B --sites-key\fR, \fB-s \fIKEY |
| 63 | Configuration file key defining active sites. |
| 64 | The default is \fBsites\fR. |
| 65 | |
| 66 | .SH "CAPABILITY NEGOTIATION" |
| 67 | Sites negotiate with each other during key exchange |
| 68 | in order to determine which cryptographic algorithms and other features |
| 69 | \(en termed |
| 70 | .I capabilities |
| 71 | \(en |
| 72 | they each support. |
| 73 | Capabilities are assigned small integer numbers. |
| 74 | In many cases, |
| 75 | capability numbers can be assigned in the configuration file, |
| 76 | as described below; |
| 77 | but secnet's default assignments will often be satisfactory. |
| 78 | .PP |
| 79 | Capability numbers between 0 and 7 inclusive |
| 80 | are reserved for local use: |
| 81 | secnet will never make use of them without explicit configuration. |
| 82 | This may be useful to migrate from one set of parameters |
| 83 | for a particular cryptographic algorithm |
| 84 | to different, incompatible, parameters for the same algorithm. |
| 85 | Other capability numbers are assigned by default |
| 86 | by various kinds of closures. |
| 87 | See the descriptions below for details. |
| 88 | .PP |
| 89 | It is essential that a capability number mean the same thing |
| 90 | to each of a pair of peers. |
| 91 | It's possible to configure a site |
| 92 | so that it uses different capability numbers for the same feature |
| 93 | when it communicates with different peer sites, |
| 94 | but this is likely to be more confusing than useful. |
| 95 | |
| 96 | .SH "CONFIGURATION FILE" |
| 97 | .SS Overview |
| 98 | The default configuration file is \fI/etc/secnet/secnet.conf\fR. |
| 99 | This can be overridden with the \fB--config\fR option. |
| 100 | .PP |
| 101 | The configuration file defines a dictionary (a mapping from keys to |
| 102 | values) of configuration information for secnet. |
| 103 | It is recursive in nature, i.e. values may themselves include dictionaries. |
| 104 | Any node in the nested structure thus defined can be identified by a |
| 105 | \fIpath\fR, which is the sequence of keys necessary to reach it from |
| 106 | the root, separated by "/" characters. |
| 107 | See \fBPaths\fR below for how this is used. |
| 108 | .PP |
| 109 | Furthermore, when a key is looked up in a dictionary, if it cannot be |
| 110 | found, it is sought in the parent dictionary, and so on back to the |
| 111 | root. |
| 112 | For instance, each \fIsite\fR must contain the \fBresolver\fR key, but |
| 113 | in a typical configuration there is no value in having different |
| 114 | resolvers for each site. |
| 115 | Therefore \fBresolver\fR is defined at the root and thus automatically |
| 116 | incorporated into all sites. |
| 117 | .SS Whitespace |
| 118 | Whitespace, including newlines, is ignored except to the extent that |
| 119 | it bounds other symbols. |
| 120 | .PP |
| 121 | Comment begin with "#" and continues to the end of the line. |
| 122 | Comments are ignored. |
| 123 | .SS Inclusion |
| 124 | A file may be recursively included into the configuration file using a |
| 125 | line of the form: |
| 126 | .IP |
| 127 | \fBinclude \fIPATH |
| 128 | .PP |
| 129 | This is handled at a higher level than the main parser and so |
| 130 | precludes the possibility of using the string \fBinclude\fR for any |
| 131 | other purpose. |
| 132 | .\" check if this is true. it's probably a bug! |
| 133 | .SS Assignments |
| 134 | The configuration file contains one or more assigments. |
| 135 | Each assignment is written: |
| 136 | .IP |
| 137 | \fIkey\fR [\fB=\fR] \fIlist\fR\fB;\fR |
| 138 | .PP |
| 139 | i.e. the equals sign is optional. |
| 140 | The semicolon is mandatory in all contexts. |
| 141 | .PP |
| 142 | Keys start with a letter or "_" and continue with any numbers of |
| 143 | letters, digits, "_" and "-". |
| 144 | .PP |
| 145 | Each \fIkey\fR is a list of one or more \fIvalues\fR, separated by commas. |
| 146 | Possible values types are \fIboolean\fR, \fIstring\fR, \fInumber\fR, |
| 147 | \fIdictionary\fR, \fIpath\fR and \fIclosure evaluation\fR. |
| 148 | .\" This man page draws a distinction between a closure (the thing |
| 149 | .\" evaluated) and a closure evaluation (the closure plus is |
| 150 | .\" arguments). |
| 151 | .SS "Strings" |
| 152 | Strings are contained within "double quotes". |
| 153 | There is (currently) no escape syntax and no way to include quotes |
| 154 | inside strings. |
| 155 | .PP |
| 156 | Example: |
| 157 | .nf |
| 158 | filename "/var/log/secnet"; |
| 159 | .fi |
| 160 | .SS "Numbers" |
| 161 | Numbers are encoded in decimal and do not include a sign. |
| 162 | Numbers must lie in the range 0 to 4294967295. |
| 163 | .PP |
| 164 | Example: |
| 165 | .nf |
| 166 | mtu 1400; |
| 167 | .fi |
| 168 | .SS "Dictionaries" |
| 169 | .\" In conffile.y dictionaries can be preceded by a search path, but |
| 170 | .\" this is not implemented elsewhere, so not documented here. |
| 171 | Dictionaries consist of one or more assignments, in the same syntax as |
| 172 | given above, enclosed in "{" and "}". |
| 173 | .PP |
| 174 | Example: |
| 175 | .nf |
| 176 | system { |
| 177 | userid "secnet"; |
| 178 | pidfile "/var/run/secnet.pid"; |
| 179 | }; |
| 180 | .fi |
| 181 | .SS "Paths" |
| 182 | Paths allow a key already defined in the configuration to be aliased. |
| 183 | .PP |
| 184 | Paths consist of a sequence of keys separated by "/". |
| 185 | If the path starts with a "/" then it is an \fIabsolute path\fR and |
| 186 | the search starts at the root of the configuration. |
| 187 | Otherwise it is a \fIrelative path\fR and starts in the containing |
| 188 | dictionary or in any of its parents, down to and including the root. |
| 189 | If there is more than one match, the one furthest from the root "wins". |
| 190 | .PP |
| 191 | The value of a path is the list assigned to the key it refers to. |
| 192 | Lists are flattened; for example if a key is defined as a list of two |
| 193 | paths, and each of those refers to a list of two integers, the |
| 194 | original key is therefore defined to be a list of four integers, not |
| 195 | a list consisting of two lists. |
| 196 | .PP |
| 197 | It is not possible to refer to a \fIlater\fR key using a path. |
| 198 | .PP |
| 199 | Example: |
| 200 | .nf |
| 201 | vpn { |
| 202 | test { |
| 203 | kakajou vpn-data/test/kakajou/kakajou; |
| 204 | araminta vpn-data/test/araminta/araminta; |
| 205 | deodand vpn-data/test/deodand/deodand; |
| 206 | all-sites kakajou,araminta,deodand; |
| 207 | }; |
| 208 | }; |
| 209 | all-sites vpn/test/all-sites; |
| 210 | .fi |
| 211 | .PP |
| 212 | Here, each of \fBvpn/test/kakajou\fR, \fBvpn/test/araminta\fR and |
| 213 | \fBvpn/test/deodand\fR are defined as aliases to values defined |
| 214 | elsewhere. |
| 215 | \fBvpn/tests/all-sites\fR is defined as the list of all three of those |
| 216 | values, and \fBall-sites\fR is then defined to be an alias for that. |
| 217 | .SS "Booleans" |
| 218 | The (single-element) paths \fBfalse\fR, \fBno\fR and \fBnowise\fR are |
| 219 | predefined and refer to a boolean false value. |
| 220 | Similarly \fBtrue\fR, \fByes\fR and \fBverily\fR point at a boolean |
| 221 | true value. |
| 222 | .PP |
| 223 | In all six cases, variants with just the first letter capitalized, and |
| 224 | with all letters capitalized, are also provided. |
| 225 | .PP |
| 226 | Example: |
| 227 | .nf |
| 228 | random randomfile("/dev/urandom",no); |
| 229 | .fi |
| 230 | .SS "Closure Evaluation" |
| 231 | Closure evaluation uses the following syntax: |
| 232 | .IP |
| 233 | \fICLOSURE \fB( \fIARGUMENTS \fB) |
| 234 | .PP |
| 235 | \fICLOSURE\fR may be a path referring to a closure, or may itself be a |
| 236 | closure evaluation. |
| 237 | .PP |
| 238 | \fIARGUMENTS\fR is a list of zero or more values, separated by commas. |
| 239 | As a shortcut, if the arguments consist of a single dictionary, the |
| 240 | parentheses may be ommitted: |
| 241 | .IP |
| 242 | \fICLOSURE \fB{ \fR... \fB} |
| 243 | .PP |
| 244 | Example: |
| 245 | .nf |
| 246 | sites map(site, vpn/test/all-sites); |
| 247 | .fi |
| 248 | .PP |
| 249 | When a closure is evaluated it returns a value (a list, much as above) |
| 250 | and may also have side effects (which may be immediate or may be |
| 251 | deferred to some later phase of execution). |
| 252 | A list of built-in closures is given below. |
| 253 | .SS "Mandatory Keys" |
| 254 | Two keys are mandatory. |
| 255 | \fBsystem\fR must be a dictionary in which the following keys can be |
| 256 | looked up: |
| 257 | .TP |
| 258 | .B log |
| 259 | A \fIlog closure\fR; see the \fBlogfile\fR documentation below. |
| 260 | The destination for log messages. |
| 261 | Mandatory. |
| 262 | .TP |
| 263 | .B userid |
| 264 | A string. |
| 265 | The userid to run as after dropping privilege. |
| 266 | Optional. |
| 267 | .TP |
| 268 | .B pidfile |
| 269 | A string. |
| 270 | The path to write a pidfile. |
| 271 | Optional. |
| 272 | .PP |
| 273 | \fBsites\fR should be a list of \fIsite closures\fR; see the \fBsite\fR documentation below. |
| 274 | This defines the collection of tunnel endpoints that \fBsecnet\fR will |
| 275 | communicate with. |
| 276 | .PP |
| 277 | Recall the recursive lookup logic described in \fBOverview\fR above: |
| 278 | if (for instance) \fBlog\fR is defined in the top level dictionary but |
| 279 | not in \fBsystem\fR, it will nevertheless be found when looked up in |
| 280 | the latter. |
| 281 | |
| 282 | .SH CLOSURES |
| 283 | \fBsecnet\fR contains a collection of built-in closures |
| 284 | with names (i.e. single-element paths) given below. |
| 285 | .PP |
| 286 | Most of them return anonymous closures of various types, |
| 287 | which are described contextually. |
| 288 | |
| 289 | .SS adns |
| 290 | \fBadns(\fIDICT\fB)\fR => \fIresolver closure\fR |
| 291 | .TP |
| 292 | .I DICT |
| 293 | This either be empty or contain the single key \fBconfig\fR, with a |
| 294 | string value giving configuration to supply to ADNS. |
| 295 | This might be read from a file using \fBreadfile\fR. |
| 296 | .PP |
| 297 | A \fIresolver closure\fR is a means of converting hostnames into |
| 298 | network addresses. |
| 299 | |
| 300 | .SS diffie-hellman |
| 301 | .PP |
| 302 | \fBdiffie-hellman(\fIMODULUS\fB, \fIGENERATOR\fR[\fB, \fICHECK\fR]\fB)\fR => \fIdh closure\fR |
| 303 | .br |
| 304 | \fBdiffie-hellman(\fIDICT\fB)\fR => \fIdh closure\fR |
| 305 | Defines a Diffie\(enHellman group which uses |
| 306 | traditional Diffie\(enHellman modulo a large prime number. |
| 307 | Arguments may be provided |
| 308 | either as positional arguments |
| 309 | or in a dictionary. |
| 310 | Dictionary keys are described below; |
| 311 | those keys which correspond with positional arguments |
| 312 | are mentioned in the individual descriptions. |
| 313 | .TP |
| 314 | .B p |
| 315 | String. |
| 316 | The prime modulus \fIp\fR in hex. |
| 317 | Corresponds to the |
| 318 | .I MODULUS |
| 319 | argument. |
| 320 | .TP |
| 321 | .B g |
| 322 | String. |
| 323 | The generator \fIg\fR in hex. |
| 324 | Corresponds to the |
| 325 | .I GENERATOR |
| 326 | argument. |
| 327 | .TP |
| 328 | .B check |
| 329 | Boolean. |
| 330 | If \fBtrue\fR (the default) then check if \fIp\fR is prime. |
| 331 | Corresponds to the |
| 332 | .I CHECK |
| 333 | argument. |
| 334 | .TP |
| 335 | .B capab-num |
| 336 | The capability number to use when advertising |
| 337 | this Diffie\(enHellman group. |
| 338 | The default capability number is 10. |
| 339 | |
| 340 | .PP |
| 341 | A \fIdh closure\fR defines a group to be used for key exchange. |
| 342 | |
| 343 | .SS x25519 |
| 344 | .PP |
| 345 | \fBx25519 |
| 346 | .PP |
| 347 | A premade \fIdh closure\fR |
| 348 | which uses Daniel Bernstein's X25519 key-exchange function. |
| 349 | This uses an elliptic curve called Curve25519, |
| 350 | defined over a 255-bit field. |
| 351 | The function is fast and very well-studied. |
| 352 | .PP |
| 353 | A \fIdh closure\fR defines a group to be used for key exchange. |
| 354 | The |
| 355 | .B x25519 |
| 356 | Diffie\(enHellman group always uses capability number 24. |
| 357 | |
| 358 | .SS x448 |
| 359 | .PP |
| 360 | \fBx448 |
| 361 | .PP |
| 362 | A premade \fIdh closure\fR |
| 363 | which uses Mike Hamburg's X448 key-exchange function. |
| 364 | This uses an elliptic curve called Ed448-Goldilocks, |
| 365 | defined over a 448-bit field. |
| 366 | The function is unusually quick and fairly well studied. |
| 367 | .PP |
| 368 | A \fIdh closure\fR defines a group to be used for key exchange. |
| 369 | The |
| 370 | .B x448 |
| 371 | Diffie\(enHellman group always uses capability number 25. |
| 372 | |
| 373 | .SS logfile |
| 374 | \fBlogfile(\fIDICT\fB)\fR => \fIlog closure\fR |
| 375 | .PP |
| 376 | Valid keys in the \fIDICT\fR argument are: |
| 377 | .TP |
| 378 | .B filename |
| 379 | The path to log to. |
| 380 | .TP |
| 381 | .B class |
| 382 | A list of strings defining which classes of message to log. |
| 383 | The possible message classes are \fBdebug-config\fR, |
| 384 | \fBdebug-phase\fR, \fBdebug\fR, \fBinfo\fR, \fBnotice\fR, |
| 385 | \fBwarning\fR, \fBerror\fR, \fBsecurity\fR and \fBfatal\fR. |
| 386 | .IP |
| 387 | \fBall-debug\fR is the union of all the \fBdebug\fR... classes. |
| 388 | \fBdefault\fR is equivalent to \fBwarning, error, security, fatal\fR. |
| 389 | \fBverbose\fR is equivalent to \fBinfo, notice, warning, error, |
| 390 | security, fatal\fR. |
| 391 | \fBquiet\fR is equivalent to \fBfatal\fR. |
| 392 | .PP |
| 393 | A \fIlog closure\fR is a means of saving log messages. |
| 394 | See also \fBsyslog\fR below. |
| 395 | |
| 396 | .SS makelist |
| 397 | \fBmakelist(\fIDICT\fB)\fR => \fILIST\fR |
| 398 | .PP |
| 399 | Returns the (flattened) list of values from the dictionary, discarding |
| 400 | the keys. |
| 401 | |
| 402 | .SS map |
| 403 | \fBmap(\fICLOSURE\fB, \fIINPUT\fR...\fB)\fR => \fILIST\fR |
| 404 | .PP |
| 405 | Applies \fICLOSURE\fR to all its additional input arguments and |
| 406 | returns the resulting list. |
| 407 | |
| 408 | .SS md5 |
| 409 | \fBmd5\fR is a \fIhash closure\fR implementing the MD5 algorithm. |
| 410 | |
| 411 | .SS null-netlink |
| 412 | \fBnull-netlink(\fIDICT\fB)\fR => \fInetlink closure\fR |
| 413 | .br |
| 414 | \fBnull-netlink(\fIDICT\fB)\fR => \fIpure closure\fR |
| 415 | .\" TODO pure closure is what it's called internally but this is a |
| 416 | .\" very opaque name to use in docs |
| 417 | .PP |
| 418 | Valid keys in the \fIDICT\fR argument are: |
| 419 | .TP |
| 420 | .B name |
| 421 | String. |
| 422 | The name for the netlink device. |
| 423 | The default is \fBnull-netlink\fR. |
| 424 | .TP |
| 425 | .B networks |
| 426 | List of strings. |
| 427 | The networks on the host side of the netlink device. |
| 428 | .TP |
| 429 | .B remote-networks |
| 430 | List of strings. |
| 431 | Networks that may be claimed by remote sites using this netlink device. |
| 432 | .TP |
| 433 | .B secnet-address |
| 434 | String. |
| 435 | IP address of this netlink. |
| 436 | Incompatible with \fBptp-address\fR. |
| 437 | .TP |
| 438 | .B ptp-address |
| 439 | String. |
| 440 | IP address of the other end of a point-to-point link. |
| 441 | Incompatible with \fBsecnet-address\fR. |
| 442 | .TP |
| 443 | .B mtu |
| 444 | Number. |
| 445 | The MTU of the netlink device. |
| 446 | The default is 1000. |
| 447 | .PP |
| 448 | If \fBptp-address\fR is used then the result is a \fInetlink closure\fR. |
| 449 | This can be used directly with the \fBlink\fR key in the \fBsites\fR |
| 450 | closure (see below). |
| 451 | .PP |
| 452 | If \fBsecnet-address\fR is used then the result is a \fIpure |
| 453 | closure\fR. |
| 454 | This must be evaluated to yield a \fInetlink closure\fR, using a |
| 455 | dictionary argument with the following keys: |
| 456 | .TP |
| 457 | .B routes |
| 458 | String list. |
| 459 | networks reachable via this tunnel, in \fIaddress\fB/\fIbits\fR format. |
| 460 | .TP |
| 461 | .B options |
| 462 | String list. |
| 463 | A list of options: |
| 464 | .RS |
| 465 | .TP |
| 466 | .B allow-route |
| 467 | Allow packets received via this tunnel to be routed down other tunnels |
| 468 | (without this option only packets from the host will be routed). |
| 469 | .TP |
| 470 | .B soft |
| 471 | Remove these routes from the host routing table when the link quality |
| 472 | is 0. |
| 473 | .RE |
| 474 | .TP |
| 475 | .B mtu |
| 476 | Number. |
| 477 | Default MTU over this link. |
| 478 | The default is inherited from the \fIpure closure\fR. |
| 479 | .TP |
| 480 | .B priority |
| 481 | Number. |
| 482 | The priority of this link. |
| 483 | Higher values beat lower values. |
| 484 | The default is 0. |
| 485 | |
| 486 | .\" TODO ptp-address turns up in sites.conf, but why? I think this |
| 487 | .\" is a bug in make-secnet-sites; it is not used by |
| 488 | \" netlink_inst_create. |
| 489 | |
| 490 | .PP |
| 491 | A \fInetlink closure\fR is a virtual IP link, and is supplied to the |
| 492 | \fBlink\fR key of a \fIsite\fR closure. |
| 493 | .PP |
| 494 | The netlink created by \fBnull-netlink\fR has no connection to the |
| 495 | host. |
| 496 | See \fBtun\fR and \fBuserv-ipif\fR below for more useful alternatives. |
| 497 | |
| 498 | |
| 499 | |
| 500 | .SS randomfile |
| 501 | \fBrandomfile(\fIFILENAME\fR[\fB, \fIBLOCKING\fR]\fB)\fR => \fIrandomsource closure\fR |
| 502 | .TP |
| 503 | .I FILENAME |
| 504 | String. |
| 505 | Path to random device, e.g. \fI/dev/urandom\fR. |
| 506 | .TP |
| 507 | .I BLOCKING |
| 508 | Boolean. |
| 509 | \fBTrue\fR if this is a blocking device and \fBfalse\fR otherwise (the default). |
| 510 | Blocking device support is not implemented so this must always be |
| 511 | \fBFalse\fR or absent. |
| 512 | .PP |
| 513 | A \fIrandomsource closure\fR is a source of random numbers. |
| 514 | |
| 515 | .SS readfile |
| 516 | \fBreadfile(\fIPATH\fB)\fR => \fISTRING\fR |
| 517 | .PP |
| 518 | Read the contents of the file \fIPATH\fR (a string) and return it as a string. |
| 519 | |
| 520 | .SS eax-serpent |
| 521 | \fBeax-serpent(\fIDICT\fB)\fR => \fItransform closure\fR |
| 522 | .PP |
| 523 | Valid keys in the \fIDICT\fR argument are: |
| 524 | .TP |
| 525 | .B max-sequence-skew |
| 526 | The maximum acceptable difference between the sequence number in a |
| 527 | received, decrypted message and the previous one. |
| 528 | The default is 10. |
| 529 | It may be necessary to increase this is if connectivity is poor. |
| 530 | .TP |
| 531 | .B tag-length-bytes |
| 532 | The length of the message authentication tag. The default is 16, |
| 533 | for a 128-bit tag length. It must be no longer than the Serpent |
| 534 | blocksize, 16. Must be have the same value at both ends. |
| 535 | .TP |
| 536 | .B padding-rounding |
| 537 | Messages are padded to a multiple of this many bytes. This |
| 538 | serves to obscure the exact length of messages. The default is 16, |
| 539 | .TP |
| 540 | .B capab-num |
| 541 | The capability number to use when advertising this |
| 542 | transform. The default for serpent-eax is 9. |
| 543 | .PP |
| 544 | A \fItransform closure\fR is a reversible means of transforming |
| 545 | messages for transmission over a (presumably) insecure network. |
| 546 | It is responsible for both confidentiality and integrity. |
| 547 | |
| 548 | .SS serpent256-cbc |
| 549 | \fBserpent256-cbc(\fIDICT\fB)\fR => \fItransform closure\fR |
| 550 | .PP |
| 551 | This transform |
| 552 | is deprecated as its security properties are poor; it should be |
| 553 | specified only alongside a better transform such as eax-serpent. |
| 554 | .PP |
| 555 | Valid keys in the \fIDICT\fR argument are: |
| 556 | .TP |
| 557 | .B capab-num |
| 558 | As above. The default for serpent256-cbc is 8. |
| 559 | .TP |
| 560 | .B max-sequence-skew |
| 561 | As above. |
| 562 | .PP |
| 563 | Note that this uses a big-endian variant of the Serpent block cipher |
| 564 | (which is not compatible with most other Serpent implementations). |
| 565 | .SS rsa-private |
| 566 | \fBrsa-private(\fIPATH\fB\fR[, \fICHECK\fR]\fB)\fR => \fIrsaprivkey closure\fR |
| 567 | .TP |
| 568 | .I PATH |
| 569 | String. |
| 570 | The path to a file containing an RSA private key in SSH format |
| 571 | (version 1). |
| 572 | There must be no passphrase. |
| 573 | .TP |
| 574 | .I CHECK |
| 575 | Boolean. |
| 576 | If \fBtrue\fR (the default) then check that the key is valid. |
| 577 | |
| 578 | .SS rsa-public |
| 579 | \fBrsa-public(\fIKEY\fB, \fIMODULUS\fB)\fR => \fIrsapubkey closure\fR |
| 580 | .TP |
| 581 | .I KEY |
| 582 | String. |
| 583 | The public key exponent (\fIe\fR), in decimal. |
| 584 | .TP |
| 585 | .I MODULUS |
| 586 | String. |
| 587 | The modulus (\fIn\fR), in decimal. |
| 588 | |
| 589 | .SS sha1 |
| 590 | \fBsha1\fR is a \fIhash closure\fR implementing the SHA-1 algorithm. |
| 591 | |
| 592 | .SS sha512 |
| 593 | \fBsha512\fR is a \fIhash closure\fR implementing the SHA-512 algorithm. |
| 594 | |
| 595 | .SS site |
| 596 | \fBsite(\fIDICT\fB)\fR => \fIsite closure\fR |
| 597 | .PP |
| 598 | Valid keys in the \fIDICT\fR argument are: |
| 599 | .TP |
| 600 | .B local-name |
| 601 | String. |
| 602 | The site's name for itself. |
| 603 | .TP |
| 604 | .B name |
| 605 | String. |
| 606 | The name of the site's peer. |
| 607 | .TP |
| 608 | .B link |
| 609 | A \fInetlink closure\fR. |
| 610 | .TP |
| 611 | .B comm |
| 612 | A \fIcomm closure\fR. |
| 613 | .TP |
| 614 | .B resolver |
| 615 | A \fIresolver closure\fR. |
| 616 | .TP |
| 617 | .B random |
| 618 | A \fIrandomsource closure\fR. |
| 619 | .TP |
| 620 | .B local-key |
| 621 | An \fIrsaprivkey closure\fR. |
| 622 | The key used to prove our identity to the peer. |
| 623 | .TP |
| 624 | .B address |
| 625 | String. |
| 626 | The DNS name of the peer. |
| 627 | Optional, but if it is missing then it will not be possible to |
| 628 | initiate new connections to the peer. |
| 629 | .TP |
| 630 | .B port |
| 631 | Number. |
| 632 | The port to contact the peer. |
| 633 | .TP |
| 634 | .B key |
| 635 | An \fIrsapubkey closure\fR. |
| 636 | The key used to verify the peer's identity. |
| 637 | .TP |
| 638 | .B transform |
| 639 | One or more \fItransform closures\fR. |
| 640 | Used to protect packets exchanged with the peer. These should |
| 641 | all have distinct \fBcapab-num\fR values, and the same \fBcapab-num\fR |
| 642 | value should have the same (or a compatible) meaning at both |
| 643 | ends. The list should be in order of preference, most preferred |
| 644 | first. (The end which sends MSG1,MSG3 ends up choosing; the ordering |
| 645 | at the other end is irrelevant.) |
| 646 | .TP |
| 647 | .B dh |
| 648 | A list of one or more \fIdh closure\fRs. |
| 649 | The groups to use in key exchange. |
| 650 | These should all have distinct |
| 651 | .B capab-num |
| 652 | values, |
| 653 | and the same |
| 654 | .B capab-num |
| 655 | value should have the same (or a compatible) meaning at both ends. |
| 656 | The list should be in order of preference, |
| 657 | most preferred first. |
| 658 | (The end which sends MSG1,MSG3 ends up choosing; |
| 659 | the ordering at the other end is irrelevant.) |
| 660 | .TP |
| 661 | .B hash |
| 662 | The hash function used during setup. |
| 663 | .\" TODO clarify what we actually use it for! |
| 664 | .TP |
| 665 | .B key-lifetime |
| 666 | Number. |
| 667 | The maximum lifetime of a session key in milliseconds. |
| 668 | The default is one hour. |
| 669 | .TP |
| 670 | .B setup-retries |
| 671 | Number. |
| 672 | The maximum number of times a key negotiation packet will be |
| 673 | transmitted before giving up. |
| 674 | The default is 5. |
| 675 | .TP |
| 676 | .B setup-timeout |
| 677 | Number. |
| 678 | The time between retransmissions of key negotiation packets, in milliseconds. |
| 679 | The default is one second. |
| 680 | .TP |
| 681 | .B wait-time |
| 682 | Number. |
| 683 | The time to wait after a failed key setup before making another |
| 684 | attempt, in milliseconds. |
| 685 | The default is 20s. |
| 686 | .TP |
| 687 | .B renegotiate-time |
| 688 | Number. |
| 689 | The time after which a new session key will be negotiated, \fIif\fR |
| 690 | there is traffic on the link, in milliseconds. |
| 691 | It must not be greater than the \fBkey-lifetime\fR. |
| 692 | The default 5 minutes less than the key lifetime, unless the lifetime |
| 693 | is less than 10 minutes in which case the default is half the |
| 694 | lifetime. |
| 695 | .TP |
| 696 | .B keepalive |
| 697 | Boolean. |
| 698 | If \fBtrue\fR then attempt to always maintain a live session key. |
| 699 | Not implemented. |
| 700 | .TP |
| 701 | .B log-events |
| 702 | String list. |
| 703 | Types of event to log for this site. |
| 704 | .RS |
| 705 | .TP |
| 706 | .B unexpected |
| 707 | Unexpected key setup packets (including late retransmissions). |
| 708 | .TP |
| 709 | .B setup-init |
| 710 | Start of attempt to setup a session key. |
| 711 | .TP |
| 712 | .B setup-timeout |
| 713 | Failure of attempt to setup a session key, through timeout. |
| 714 | .TP |
| 715 | .B activate-key |
| 716 | Activation of a new session key. |
| 717 | .TP |
| 718 | .B timeout-key |
| 719 | Deletion of current session key through age. |
| 720 | .TP |
| 721 | .B security |
| 722 | Anything potentially suspicious. |
| 723 | .TP |
| 724 | .B state-change |
| 725 | Steps in the key setup protocol. |
| 726 | .TP |
| 727 | .B packet-drop |
| 728 | Whenever we throw away an outgoing packet. |
| 729 | .TP |
| 730 | .B dump-packets |
| 731 | Every key setup packet we see. |
| 732 | .TP |
| 733 | .B errors |
| 734 | Failure of name resolution, internal errors. |
| 735 | .TP |
| 736 | .B all |
| 737 | Everything (too much!) |
| 738 | .RE |
| 739 | .PP |
| 740 | A \fIsite closure\fR defines one site to communicate with. |
| 741 | \fBsecnet\fR expects the (root) key \fBsite\fR to be a list of site |
| 742 | closures. |
| 743 | |
| 744 | .SS sysbuffer |
| 745 | \fBsysbuffer(\fR[\fISIZE\fR[\fB, \fIOPTIONS\fR]]\fB)\fR => \fIbuffer closure\fR |
| 746 | .TP |
| 747 | .I SIZE |
| 748 | Number. |
| 749 | The size of the buffer in bytes. |
| 750 | This must be between 64 and 131072. |
| 751 | The default is 4096. |
| 752 | .TP |
| 753 | .I OPTIONS |
| 754 | Dictionary. |
| 755 | Optional and presently unused. |
| 756 | .\" lockdown is accepted but ignored. |
| 757 | .PP |
| 758 | A \fIbuffer closure\fR is a means of buffering packets to send or that |
| 759 | have been received. |
| 760 | |
| 761 | .SS syslog |
| 762 | \fBsyslog(\fIDICT\fB)\fR => \fIlog closure\fR |
| 763 | .PP |
| 764 | Valid keys in the \fIDICT\fR argument are: |
| 765 | .TP |
| 766 | .B ident |
| 767 | String. |
| 768 | The ident string to pass to \fBopenlog\fR(3); this value will appear |
| 769 | in each message. |
| 770 | .TP |
| 771 | .B facility |
| 772 | String. |
| 773 | The facility to log as. |
| 774 | The possible values are \fBauthpriv\fR, \fBcron\fR, \fBdaemon\fR, |
| 775 | \fBkern\fR, \fBlocal0\fR-\fB7\fR, \fBlpr\fR, \fBmail\fR, \fBnews\fR, |
| 776 | \fBsyslog\fR, \fBuser\fR and \fBuucp\fR. |
| 777 | .PP |
| 778 | See also \fBlogfile\fR above. |
| 779 | |
| 780 | .SS tun |
| 781 | \fBtun(\fIDICT\fB)\fR => \fInetlink closure\fR |
| 782 | .br |
| 783 | \fBtun(\fIDICT\fB)\fR => \fIpure closure\fR |
| 784 | .PP |
| 785 | Valid keys in the \fIDICT\fR argument are those documented for |
| 786 | \fBnull-netlink\fR above, plus: |
| 787 | .TP |
| 788 | .B flavour |
| 789 | String. |
| 790 | The type of TUN interface to use. |
| 791 | Possible values are \fBlinux\fR, \fBbsd\fR, \fBstreams\fR and \fBguess\fR. |
| 792 | The default is \fBguess\fR. |
| 793 | .TP |
| 794 | .B device |
| 795 | String. |
| 796 | The path to the TUN/TAP device file. |
| 797 | The default is \fI/dev/net/tun\fR for the \fBlinux\fR flavour and |
| 798 | \fI/dev/tun\fR for the others. |
| 799 | .TP |
| 800 | .B interface |
| 801 | String. |
| 802 | The interface to use. |
| 803 | The default is to pick one automatically. |
| 804 | This cannot be used with the \fBstreams\fR flavour. |
| 805 | .TP |
| 806 | .B local-address |
| 807 | String. |
| 808 | IP address of the host's tunnel interface. |
| 809 | .\" README says this belongs to netlink-null but actually it's |
| 810 | \" duplicated between slip & tun |
| 811 | .TP |
| 812 | .B ifconfig-path |
| 813 | String. |
| 814 | The name of the \fBifconfig\fR command. |
| 815 | The default is simply "ifconfig". |
| 816 | .TP |
| 817 | .B route-path |
| 818 | String. |
| 819 | The name of the \fBroute\fR command. |
| 820 | The default is simply "route". |
| 821 | .TP |
| 822 | .B ifconfig-type |
| 823 | String. |
| 824 | The syntax expected by the \fBifconfig\fR command. |
| 825 | Possible values are \fBlinux\fR, \fBbsd\fR, \fBioctl\fR, |
| 826 | \fBsolaris-2.5\fR and \fBguess\fR. |
| 827 | The default is \fBguess\fR. |
| 828 | .TP |
| 829 | .B route-type |
| 830 | String. |
| 831 | The syntax expected by the \fBifconfig\fR command. |
| 832 | Possible values are \fBlinux\fR, \fBbsd\fR, \fBioctl\fR, |
| 833 | \fBsolaris-2.5\fR and \fBguess\fR. |
| 834 | The default is \fBguess\fR. |
| 835 | .TP |
| 836 | .B buffer |
| 837 | A \fIbuffer closure\fR to use for packets transferred from the host to secnet. |
| 838 | The buffer size must be at least 60 greater than the MTU. |
| 839 | .\" TODO rumour has is that buffers are sometimes shareable between |
| 840 | .\" netlink devices - document that if the conditions are reasonable |
| 841 | .\" ones. |
| 842 | .PP |
| 843 | The \fBifconfig-type\fR and \fBroute-type\fR values determine how |
| 844 | those commands are executed. |
| 845 | If they are set to \fBioctl\fR then low-level system calls are used |
| 846 | directly instead of invoking the commands. |
| 847 | .PP |
| 848 | The netlink created by \fBtun\fR uses the \fBtun\fR device to |
| 849 | communicate with the host kernel. |
| 850 | |
| 851 | .SS udp |
| 852 | \fBudp(\fIDICT\fB)\fR => \fIcomm closure\fR |
| 853 | .PP |
| 854 | Valid keys in the \fIDICT\fR argument are: |
| 855 | .TP |
| 856 | .B address |
| 857 | String. |
| 858 | The IP address to bind on. |
| 859 | The default is 0.0.0.0, i.e. "any". |
| 860 | .TP |
| 861 | .B port |
| 862 | Number. |
| 863 | The port number to bind to. |
| 864 | The default is 0, i.e. the OS will choose one. |
| 865 | It is suggested that any given VPN agree a common port number. |
| 866 | .TP |
| 867 | .B buffer |
| 868 | A \fIbuffer closure\fR. |
| 869 | See the \fBsysbuffer\fR closure above. |
| 870 | .TP |
| 871 | .B authbind |
| 872 | String. |
| 873 | The path to a helper program to bind the socket. |
| 874 | Optional. |
| 875 | .IP |
| 876 | The program will be invoked with the address and port number as its |
| 877 | arguments, and with the socket to bind as file descriptor 0. |
| 878 | It should either bind the socket as requested, or exit with nonzero |
| 879 | status. |
| 880 | .PP |
| 881 | A \fIcomm closure\fR is a means of sending and receiving messages via |
| 882 | a network. |
| 883 | It does not provide confidentiality, reliablity or availability. |
| 884 | |
| 885 | .SS userv-ipif |
| 886 | \fBuserv-ipif(\fIDICT\fB)\fR => \fInetlink closure\fR |
| 887 | .br |
| 888 | \fBuserv-ipif(\fIDICT\fB)\fR => \fIpure closure\fR |
| 889 | .PP |
| 890 | Valid keys in the \fIDICT\fR argument are those documented for |
| 891 | \fBnull-netlink\fR above, plus: |
| 892 | .TP |
| 893 | .B local-address |
| 894 | String. |
| 895 | IP address of the host's SLIP interface. |
| 896 | .\" README says this belongs to netlink-null but actually it's |
| 897 | \" duplicated between SLIP & tun |
| 898 | .TP |
| 899 | .B userv-path |
| 900 | String. |
| 901 | Where to find \fBuserv\fR(1). |
| 902 | The default is \fB"userv"\fR. |
| 903 | .TP |
| 904 | .B service-user |
| 905 | String. |
| 906 | The name of the user that owns the service. |
| 907 | The default is \fB"root"\fR. |
| 908 | .TP |
| 909 | .B service-name |
| 910 | String. |
| 911 | The name of the service to request. |
| 912 | The default is \fB"ipif"\fR. |
| 913 | .TP |
| 914 | .B buffer |
| 915 | A \fIbuffer closure\fR to use for packets transferred from the host to secnet. |
| 916 | .PP |
| 917 | The netlink created by \fBuserv-ipif\fR invokes the specified \fBuserv\fR service with pipes connected to its standard input and output. |
| 918 | It uses SLIP to communicate with the host kernel via these pipes. |
| 919 | |
| 920 | .SH FILES |
| 921 | .TP |
| 922 | .I /etc/secnet/secnet.conf |
| 923 | Configuration file. |
| 924 | |
| 925 | .SH "SEE ALSO" |
| 926 | \fBuserv\fR(1) |