1IPSEC_PLUTO(8) IPSEC_PLUTO(8)
2
6 ipsec pluto - ipsec whack : IPsec IKE keying daemon and control inter‐
7 face
8
10 ipsec pluto [--help] [--version] [--optionsfrom filename] [--nofork]
11 [--stderrlog] [--use-auto] [--use-klips] [--use-netkey]
12 [--use-nostack] [--uniqueids] [--nat_traversal]
13 [--virtual_private network_list] [--keep_alive delay_sec]
14 [--force_keepalive] [--disable_port_floating] [--nocrsend]
15 [--strictcrlpolicy] [--crlcheckinterval] [--ocspuri]
16 [--interface interfacename] [--ikeport portnumber]
17 [--ctlbase path] [--secretsfile secrets-file] [--adns pathname]
18 [--nhelpers number] [--lwdnsq pathname] [--perpeerlog]
19 [--perpeerlogbase dirname] [--ipsecdir dirname]
20 [--coredir dirname] [--noretransmits]
21 ipsec whack [--help] [--version]
23 ipsec whack [--debug-none] [--debug-all] [--debug-raw] [--debug-crypt]
25 [--debug-parsing] [--debug-emitting] [--debug-control]
26 [--debug-lifecycle] [--debug-klips] [--debug-pfkey]
27 [--debug-nat-t] [--debug-dpd] [--debug-dns] [--debug-oppo]
28 [--debug-private]
29 ipsec whack --name connection-name [--ipv4 | --ipv6] [--tunnelipv4 |
31 --tunnelipv6]
32 [--id identity] [--host ip-address] [--cert path]
34 [--ca distinguished name] [--groups access control groups]
35 [--sendcert yes | forced | always | ifasked | no | never]
36 [--certtype number] [--ikeport portnumber] [--nexthop ip-address]
37 [--client subnet | --clientwithin subnet]
38 [--clientprotoport protocol/port] [--srcip ip-address]
39 [--xauthserver] [--xauthclient] [--modecfgserver]
40 [--modecfgclient] [--dnskeyondemand] [--updown updown]
41 --to
43 [--id identity] [--host ip-address] [--cert path]
45 [--ca distinguished name] [--groups access control groups]
46 [--sendcert yes | always | ifasked | no | never]
47 [--certtype number] [--ikeport port-number]
48 [--nexthop ip-address] [--client subnet] [--clientwithin subnet]
49 [--clientprotoport protocol/port] [--srcip ip-address]
50 [--xauthserver] [--xauthclient] [--modecfgserver]
51 [--modecfgclient] [--dnskeyondemand] [--updown updown]
52 [--tunnel] [--psk] [--rsasig] [--encrypt] [--authenticate]
54 [--compress] [--pfs]
55 [--pfsgroup modp1024 | modp1536 | modp2048 | modp3072 | modp4096 | modp6144 | modp8192]
56 [--disablearrivalcheck] [--ikelifetime seconds]
57 [--ipseclifetime seconds] [--rekeymargin seconds]
58 [--rekeyfuzz percentage] [--keyingtries count] [--esp esp-algos]
59 [--dontrekey] [--aggrmode] [--modecfgpull] [--dpddelay seconds |
60 --dpdtimeout seconds] [--dpdaction clear | hold | restart]
61 [--forceencaps]
62 [--initiateontraffic | --pass | --drop | --reject]
63 [--failnone | --failpass | --faildrop | --failreject]
64 [--ctlbase path] [--optionsfrom filename] [--label string]
65 ipsec whack --keyid id [--addkey] [--pubkeyrsa key] [--ctlbase path]
67 [--optionsfrom filename] [--label string]
68 ipsec whack --myid id
70 ipsec whack --listen | --unlisten [--ctlbase path]
72 [--optionsfrom filename] [--label string]
73 ipsec whack --route | --unroute --name connection-name
75 [--ctlbase path] [--optionsfrom filename] [--label string]
76 ipsec whack --initiate | --terminate --name connection-name
78 [--xauthuser user] [--xauthpass pass] [--asynchronous]
79 [--ctlbase path] [--optionsfrom filename] [--label string]
80 ipsec whack [--tunnelipv4 | --tunnelipv6] --oppohere ip-address
82 --oppothere ip-address
83 ipsec whack --crash [ipaddress]
85 ipsec whack --delete --name connection-name [--ctlbase path]
87 [--optionsfrom filename] [--label string]
88 ipsec whack --deletestate state-number [--ctlbase path]
90 [--optionsfrom filename] [--label string]
91 ipsec whack [--name connection-name] [--debug-none] [--debug-all]
93 [--debug-raw] [--debug-crypt] [--debug-parsing]
94 [--debug-emitting] [--debug-control] [--debug-controlmore]
95 [--debug-lifecycle] [--debug-klips] [--debug-pfkey] [--debug-dns]
96 [--debug-dpd] [--debug-natt] [--debug-oppo] [--debug-private]
97 [--impair-delay-adns-key-answer] [--impair-delay-adns-txt-answer]
98 [--impair-bust-mi2] [--impair-bust-mr2] [--impair-sa-fail]
99 [--impair-die-oninfo] [--impair-jacob-two-two]
100 ipsec whack [--utc] [--listall] [--listpubkeys] [--listcerts]
102 [--listcacerts] [--listacerts] [--listaacerts] [--listocspcerts]
103 [--listgroups] [--listcrls] [--listocsp] [--listcards]
104 ipsec whack [--utc] [--rereadsecrets] [--rereadall] [--rereadcacerts]
106 [--rereadacerts] [--rereadaacerts] [--rereadocspcerts]
107 [--rereadcrls]
108 ipsec whack --purgeocsp
110 ipsec whack --listevents
112 ipsec whack --status [--ctlbase path] [--optionsfrom filename]
114 [--label string]
115 ipsec whack --shutdown [--ctlbase path] [--optionsfrom filename]
117 [--label string]
118
121 pluto is an IKE (“IPsec Key Exchange”) daemon. whack is an auxiliary
122 program to allow requests to be made to a running pluto.
123 pluto is used to automatically build shared “security associations” on
126 a system that has IPsec, the secure IP protocol. In other words, pluto
127 can eliminate much of the work of manual keying. The actual secure
128 transmission of packets is the responsibility of other parts of the
129 system - the kernel. Pluto can talk to various kernel implementations,
130 such as KLIPS, such as NETKEY, and such as KAME IPsec stacks. ipsec_au‐
131 to(8) provides a more convenient interface to pluto and whack.
132 IKE's Job
135 A Security Association (SA) is an agreement between two network nodes
136 on how to process certain traffic between them. This processing in‐
137 volves encapsulation, authentication, encryption, or compression.
138 IKE can be deployed on a network node to negotiate Security Associa‐
141 tions for that node. These IKE implementations can only negotiate with
142 other IKE implementations, so IKE must be on each node that is to be an
143 endpoint of an IKE-negotiated Security Association. No other nodes need
144 to be running IKE.
145 An IKE instance (i.e. an IKE implementation on a particular network
148 node) communicates with another IKE instance using UDP IP packets, so
149 there must be a route between the nodes in each direction.
150 The negotiation of Security Associations requires a number of choices
153 that involve tradeoffs between security, convenience, trust, and effi‐
154 ciency. These are policy issues and are normally specified to the IKE
155 instance by the system administrator.
156 IKE deals with two kinds of Security Associations. The first part of a
159 negotiation between IKE instances is to build an ISAKMP SA. An ISAKMP
160 SA is used to protect communication between the two IKEs. IPsec SAs can
161 then be built by the IKEs - these are used to carry protected IP traf‐
162 fic between the systems.
163 The negotiation of the ISAKMP SA is known as Phase 1. In theory, Phase
166 1 can be accomplished by a couple of different exchange types. Current‐
167 ly, Main Mode and Aggressive Mode are implemented.
168 Any negotiation under the protection of an ISAKMP SA, including the ne‐
171 gotiation of IPsec SAs, is part of Phase 2. The exchange type that we
172 use to negotiate an IPsec SA is called Quick Mode.
173 IKE instances must be able to authenticate each other as part of their
176 negotiation of an ISAKMP SA. This can be done by several mechanisms de‐
177 scribed in the draft standards.
178 IKE negotiation can be initiated by any instance with any other. If
181 both can find an agreeable set of characteristics for a Security Asso‐
182 ciation, and both recognize each others authenticity, they can set up a
183 Security Association. The standards do not specify what causes an IKE
184 instance to initiate a negotiation.
185 In summary, an IKE instance is prepared to automate the management of
188 Security Associations in an IPsec environment, but a number of issues
189 are considered policy and are left in the system administrator's hands.
190 Pluto
193 pluto is an implementation of IKE. It runs as a daemon on a network
194 node. Currently, this network node must be a LINUX system running the
195 KLIPS or NETKEY implementation of IPsec, or a FreeBSD/NetBSD/Mac OSX
196 system running the KAME implementation of IPsec.
197 pluto implements a large subset of IKE. This is enough for it to inter‐
200 operate with other instances of pluto, and many other IKE implementa‐
201 tions. It currently supports XAUTH, ModeConfig, X.509, Dead Peer Detec‐
202 tion, Opportunistic Encryption and all the NAT Traversal standards.
203 The policy for acceptable characteristics for Security Associations is
206 mostly hardwired into the code of pluto (spdb.c). Eventually this will
207 be moved into a security policy database with reasonable expressive
208 power and more convenience.
209 pluto uses shared secrets or RSA signatures to authenticate peers with
212 whom it is negotiating. These RSA signatures can come from DNS(SEC), a
213 configuration file, or from X.509 and CA certificates.
214 pluto initiates negotiation of a Security Association when it is manu‐
217 ally prodded: the program whack is run to trigger this. It will also
218 initiate a negotiation when KLIPS traps an outbound packet for Oppor‐
219 tunistic Encryption.
220 pluto implements ISAKMP SAs itself. After it has negotiated the charac‐
223 teristics of an IPsec SA, it directs the kernel to implement it. If
224 necessary, it also invokes a script to adjust any firewall and issue
225 route(8) commands to direct IP packets.
226 When pluto shuts down, it closes all Security Associations.
229 Before Running Pluto
232 pluto runs as a daemon with userid root. Before running it, a few
233 things must be set up.
234 pluto requires a working IPsec stack.
237 pluto supports multiple public networks (that is, networks that are
240 considered insecure and thus need to have their traffic encrypted or
241 authenticated). It discovers the public interfaces to use by looking at
242 all interfaces that are configured (the --interface option can be used
243 to limit the interfaces considered). It does this only when whack tells
244 it to --listen, so the interfaces must be configured by then. Each in‐
245 terface with a name of the form ipsec[0-9] is taken as a KLIPS virtual
246 public interface. Another network interface with the same IP address
247 (the first one found will be used) is taken as the corresponding real
248 public interface. ifconfig(8) or ip(8) with the -a flag will show the
249 name and status of each network interface.
250 pluto requires a database of preshared secrets and RSA private keys.
253 This is described in the ipsec.secrets(5). pluto is told of RSA public
254 keys via whack commands. If the connection is Opportunistic, and no RSA
255 public key is known, pluto will attempt to fetch RSA keys using the Do‐
256 main Name System.
257 Setting up KLIPS for pluto
260 The most basic network topology that pluto supports has two security
261 gateways negotiating on behalf of client subnets. The diagram of RGB's
262 testbed is a good example (see klips/doc/rgb_setup.txt).
263 The file INSTALL in the base directory of this distribution explains
266 how to start setting up the whole system, including KLIPS.
267 Make sure that the security gateways have routes to each other. This is
270 usually covered by the default route, but may require issuing route(8)
271 commands. The route must go through a particular IP interface (we will
272 assume it is eth0, but it need not be). The interface that connects the
273 security gateway to its client must be a different one.
274 It is necessary to issue a ipsec_tncfg(8) command on each gateway. The
277 required command is:
278 ipsec tncfg --attach --virtual ipsec0 --physical eth0
281 A command to set up the ipsec0 virtual interface will also need to be
284 run. It will have the same parameters as the command used to set up the
285 physical interface to which it has just been connected using
286 ipsec_tncfg(8).
287 Setting up NETKEY for pluto
290 No special requirements are necessary to use NETKEY - it ships with all
291 modern versions of Linux 2.4 and 2.6. however, note that certain ven‐
292 dors or older distributions use old versions or backports of NETKEY
293 which are broken. If possible use a NETKEY version that is at least
294 based on, or backported from Linux 2.6.11 or newer.
295 ipsec.secrets file
298 A pluto daemon and another IKE daemon (for example, another instance of
299 pluto) must convince each other that they are who they are supposed to
300 be before any negotiation can succeed. This authentication is accom‐
301 plished by using either secrets that have been shared beforehand (manu‐
302 ally) or by using RSA signatures. There are other techniques, but they
303 have not been implemented in pluto.
304 The file /etc/ipsec.secrets is used to keep preshared secret keys, RSA
307 private keys, X.509 encoded keyfiles and smartcard PIN's for authenti‐
308 cation with other IKE daemons. For debugging, there is an argument to
309 the pluto command to use a different file. This file is described in
310 ipsec.secrets(5).
311 Running Pluto
314 To fire up the daemon, just type pluto (be sure to be running as the
315 superuser). The default IKE port number is 500, the UDP port assigned
316 by IANA for IKE Daemons. pluto must be run by the superuser to be able
317 to use the UDP 500 port. If pluto is told to enable NAT-Traversal, then
318 UDP port 4500 is also taken by pluto to listen on.
319 Pluto supports different IPstacks on different operating systems. The
322 option --use-auto, which is also the default, lets pluto find a stack
323 automatically. This behaviour can be changed by explicitely setting the
324 stack using --use-klips, --use-netkey or --use-nostack. The latter is
325 meant for testing only - no actual IPsec connections will be loaded in‐
326 to the kernel.
327 Pluto supports the NAT-Traversal drafts and the final standard, RFC
330 3947, if the --nat_traversal is specified. The allowed range behind the
331 NAT routers is submitted using the --virtual_private option. See
332 ipsec.conf(5) for the syntax. The option --force_keepalive forces the
333 sending of the keep-alive packets, which are send to prevent the NAT
334 router from closing its port when there is not enough traffic on the
335 IPsec connection. The --keep_alive sets the delay (in seconds) of these
336 keep-alive packets. The newer NAT-T standards support port floating,
337 and Openswan enables this per default. It can be disabled using the
338 --disable_port_floating option.
339 Pluto supports the use of X.509 certificates and sends it certificate
342 when needed. This can confuse IKE implementations that do not implement
343 this, such as the old FreeS/WAN implementation. The --nocrsend prevents
344 pluto from sending these. At startup, pluto loads all the X.509 related
345 files from the directories /etc/ipsec.d/certs, /etc/ipsec.d/cacerts,
346 /etc/ipsec.d/aacerts, /etc/ipsec.d/ocspcerts, /etc/ipsec.d/private and
347 /etc/ipsec.d/crls. The Certificate Revocation Lists can also be re‐
348 trieved from an URL. The option --crlcheckinterval sets the time be‐
349 tween checking for CRL expiration and issuing new fetch commands. The
350 first attempt to update a CRL is started at 2*crlcheckinterval before
351 the next update time. Pluto logs a warning if no valid CRL was loaded
352 or obtained for a connection. If --strictcrlpolicy is given, the con‐
353 nection will be rejected until a valid CRL has been loaded. Pluto also
354 has support for the Online Certificate Store Protocol (OSCP) as defined
355 in RFC 2560. The URL to the OSCP store can be given to pluto via the
356 --ocspuri option.
357 Pluto can use the BIND9 secure resolver, which means it has support for
360 DNSSEC, using the BIND9 lwres {} interface, see named.conf(5). Pluto
361 can also use the old adns interface if there is no BIND9 running with
362 lwres {} on the host, but then pluto cannot do any DNSSEC processing.
363 Pluto forks and starts these DNS helpers in seperate children. The op‐
364 tions --lwdnsq and --adns invoke these resolvers.
365 Pluto can also use helper children to off-load cryptographic opera‐
368 tions. This behavior can be fine tuned using the --nhelpers. Pluto will
369 start (n-1) of them, where n is the number of CPU’s you have (including
370 hypherthreaded CPU’s). A value of 0 forces pluto to do all operations
371 in the main process. A value of -1 tells pluto to perform the above
372 calculation. Any other value forces the number to that amount.
373 pluto attempts to create a lockfile with the name /var/run/pluto/plu‐
376 to.pid. If the lockfile cannot be created, pluto exits - this prevents
377 multiple plutos from competing Any “leftover” lockfile must be removed
378 before pluto will run. pluto writes its pid into this file so that
379 scripts can find it. This lock will not function properly if it is on
380 an NFS volume (but sharing locks on multiple machines doesn't make
381 sense anyway).
382 pluto then forks and the parent exits. This is the conventional “daemon
385 fork”. It can make debugging awkward, so there is an option to suppress
386 this fork. In certain configurations, pluto might also launch helper
387 programs to assist with DNS queries or to offload cryptographic opera‐
388 tions.
389 All logging, including diagnostics, is sent to syslog(3) with facili‐
392 ty=authpriv; it decides where to put these messages (possibly in
393 /var/log/secure). Since this too can make debugging awkward, the option
394 --stderrlog is used to steer logging to stderr.
395 If the --perpeerlog option is given, then pluto will open a log file
398 per connection. By default, this is in /var/log/pluto/peer, in a subdi‐
399 rectory formed by turning all dot (.) [IPv4} or colon (:) [IPv6] into
400 slashes (/).
401 The base directory can be changed with the --perpeerlogbase.
404 Once pluto is started, it waits for requests from whack.
407 Pluto's Internal State
410 To understand how to use pluto, it is helpful to understand a little
411 about its internal state. Furthermore, the terminology is needed to de‐
412 cipher some of the diagnostic messages.
413 Pluto supports food groups, and X.509 certificates. These are located
416 in /etc/ipsec.d, or another directory as specified by --ipsecdir.
417 Pluto may core dump. It will normally do so into the current working
420 directory. The standard scripts have an option dumpdir=, which can set
421 the current directory to determine where the core dump will go. In some
422 cases, it may be more convenient to specify it on the command line us‐
423 ing --coredir. A third method is to set the environment variable PLU‐
424 TO_CORE_DIR. The command line argument takes precedence over the envi‐
425 ronment variable. The option plutorestartoncrash can be set to no to
426 prevent multiple core files and a looping pluto process. Normally, when
427 pluto crashes, another pluto process is started.
428 At times it may be desireable to turn off all timed events in pluto,
431 this can be done with --noretransmits.
432 The (potential) connection database describes attributes of a connec‐
435 tion. These include the IP addresses of the hosts and client subnets
436 and the security characteristics desired. pluto requires this informa‐
437 tion (simply called a connection) before it can respond to a request to
438 build an SA. Each connection is given a name when it is created, and
439 all references are made using this name.
440 During the IKE exchange to build an SA, the information about the nego‐
443 tiation is represented in a state object. Each state object reflects
444 how far the negotiation has reached. Once the negotiation is complete
445 and the SA established, the state object remains to represent the SA.
446 When the SA is terminated, the state object is discarded. Each State
447 object is given a serial number and this is used to refer to the state
448 objects in logged messages.
449 Each state object corresponds to a connection and can be thought of as
452 an instantiation of that connection. At any particular time, there may
453 be any number of state objects corresponding to a particular connec‐
454 tion. Often there is one representing an ISAKMP SA and another repre‐
455 senting an IPsec SA.
456 KLIPS hooks into the routing code in a LINUX kernel. Traffic to be pro‐
459 cessed by an IPsec SA must be directed through KLIPS by routing com‐
460 mands. Furthermore, the processing to be done is specified by ipsec er‐
461 oute(8) commands. pluto takes the responsibility of managing both of
462 these special kinds of routes.
463 NETKEY requires no special routing.
466 Each connection may be routed, and must be while it has an IPsec SA.
469 The connection specifies the characteristics of the route: the inter‐
470 face on this machine, the “gateway” (the nexthop), and the peer's
471 client subnet. Two connections may not be simultaneously routed if they
472 are for the same peer's client subnet but use different interfaces or
473 gateways (pluto's logic does not reflect any advanced routing capabili‐
474 ties).
475 On KLIPS, each eroute is associated with the state object for an IPsec
478 SA because it has the particular characteristics of the SA. Two eroutes
479 conflict if they specify the identical local and remote clients (unlike
480 for routes, the local clients are taken into account).
481 When pluto needs to install a route for a connection, it must make sure
484 that no conflicting route is in use. If another connection has a con‐
485 flicting route, that route will be taken down, as long as there is no
486 IPsec SA instantiating that connection. If there is such an IPsec SA,
487 the attempt to install a route will fail.
488 There is an exception. If pluto, as Responder, needs to install a route
491 to a fixed client subnet for a connection, and there is already a con‐
492 flicting route, then the SAs using the route are deleted to make room
493 for the new SAs. The rationale is that the new connection is probably
494 more current. The need for this usually is a product of Road Warrior
495 connections (these are explained later; they cannot be used to initi‐
496 ate).
497 When pluto needs to install an eroute for an IPsec SA (for a state ob‐
500 ject), first the state object's connection must be routed (if this can‐
501 not be done, the eroute and SA will not be installed). If a conflicting
502 eroute is already in place for another connection, the eroute and SA
503 will not be installed (but note that the routing exception mentioned
504 above may have already deleted potentially conflicting SAs). If another
505 IPsec SA for the same connection already has an eroute, all its outgo‐
506 ing traffic is taken over by the new eroute. The incoming traffic will
507 still be processed. This characteristic is exploited during rekeying.
508 All of these routing characteristics are expected change when KLIPS and
511 NETKEY merge into a single new stack.
512 Using Whack
515 whack is used to command a running pluto. whack uses a UNIX domain
516 socket to speak to pluto (by default, /var/pluto.ctl).
517 whack has an intricate argument syntax. This syntax allows many differ‐
520 ent functions to be specified. The help form shows the usage or version
521 information. The connection form gives pluto a description of a poten‐
522 tial connection. The public key form informs pluto of the RSA public
523 key for a potential peer. The delete form deletes a connection descrip‐
524 tion and all SAs corresponding to it. The listen form tells pluto to
525 start or stop listening on the public interfaces for IKE requests from
526 peers. The route form tells pluto to set up routing for a connection;
527 the unroute form undoes this. The initiate form tells pluto to negoti‐
528 ate an SA corresponding to a connection. The terminate form tells pluto
529 to remove all SAs corresponding to a connection, including those being
530 negotiated. The status form displays the pluto's internal state. The
531 debug form tells pluto to change the selection of debugging output “on
532 the fly”. The shutdown form tells pluto to shut down, deleting all SAs.
533 The crash option asks pluto to consider a particularly target IP to
536 have crashed, and to attempt to restart all connections with that IP
537 address as a gateway. In general, you should use Dead Peer Detection to
538 detect this kind of situation automatically, but this is not always
539 possible.
540 Most options are specific to one of the forms, and will be described
543 with that form. There are three options that apply to all forms.
544 --ctlbase path
547 path.ctl is used as the UNIX domain socket for talking to pluto.
548 This option facilitates debugging.
549 --optionsfrom filename
552 adds the contents of the file to the argument list.
553 --label string
556 adds the string to all error messages generated by whack.
557 The help form of whack is self-explanatory.
560 --help display the usage message.
563 --version
566 display the version of whack.
567 The connection form describes a potential connection to pluto. pluto
570 needs to know what connections can and should be negotiated. When pluto
571 is the initiator, it needs to know what to propose. When pluto is the
572 responder, it needs to know enough to decide whether is is willing to
573 set up the proposed connection.
574 The description of a potential connection can specify a large number of
577 details. Each connection has a unique name. This name will appear in a
578 updown shell command, so it should not contain punctuation that would
579 make the command ill-formed.
580 --name connection-name
583 sets the name of the connection
584 The topology of a connection is symmetric, so to save space here is
587 half a picture:
588 client_subnet<-->host:ikeport<-->nexthop<---
591 A similar trick is used in the flags. The same flag names are used for
594 both ends. Those before the --to flag describe the left side and those
595 afterwards describe the right side. When pluto attempts to use the con‐
596 nection, it decides whether it is the left side or the right side of
597 the connection, based on the IP numbers of its interfaces.
598 --id id
601 the identity of the end. Currently, this can be an IP address
602 (specified as dotted quad or as a Fully Qualified Domain Name,
603 which will be resolved immediately) or as a Fully Qualified Do‐
604 main Name itself (prefixed by “@” to signify that it should not
605 be resolved), or as user@FQDN, or an X.509 DN, or as the magic
606 value %myid. Pluto only authenticates the identity, and does not
607 use it for addressing, so, for example, an IP address need not
608 be the one to which packets are to be sent. If the option is ab‐
609 sent, the identity defaults to the IP address specified by
610 --host. %myid allows the identity to be separately specified (by
611 the pluto or whack option --myid or by the ipsec.conf(5) config
612 setup parameter myid). Otherwise, pluto tries to guess what
613 %myid should stand for: the IP address of %defaultroute, if it
614 is supported by a suitable TXT record in the reverse domain for
615 that IP address, or the system's hostname, if it is supported by
616 a suitable TXT record in its forward domain.
617 --host ip-address, --host %any, --host %opportunistic
620 the IP address of the end (generally the public interface). If
621 pluto is to act as a responder for IKE negotiations initiated
622 from unknown IP addresses (the “Road Warrior” case), the IP ad‐
623 dress should be specified as %any (currently, the obsolete nota‐
624 tion 0.0.0.0 is also accepted for this). If pluto is to oppor‐
625 tunistically initiate the connection, use %opportunistic
626 --cert filename
629 The filename of the X.509 certificate. This must be the public
630 key certificate only, and cannot be the PKCS#12 certificate
631 file. See ipsec.conf(5) on how to extrac this from the PKCS#12
632 file.
633 --ca distinguished name
636 the X.509 Certificate Authority's Distinguished Name (DN) used
637 as trust anchor for this connection. This is the CA certificate
638 that signed the host certificate, as well as the certificate of
639 the incoming client.
640 --groups access control groups
643 the access control groups used.
644 --sendcert yes|forced|always|ifasked|no|never
647 Wether or not to send our X.509 certificate credentials. This
648 could potentially give an attacker too much information about
649 which identities are allowed to connect to this host. The de‐
650 fault is to use ifasked when we are a Responder, and to use yes
651 (which is the same as forced and always if we are an Initiator.
652 The values no and never are equivalent. NOTE: "forced" does not
653 seem to be actually implemented - do not use it.
654 --certtype number
657 The X.509 certificate type number.
658 --ikeport port-number
661 the UDP port that IKE listens to on that host. The default is
662 500. (pluto on this machine uses the port specified by its own
663 command line argument, so this only affects where pluto sends
664 messages.)
665 --nexthop ip-address
668 where to route packets for the peer's client (presumably for the
669 peer too, but it will not be used for this). When pluto installs
670 an IPsec SA, it issues a route command. It uses the nexthop as
671 the gateway. The default is the peer's IP address (this can be
672 explicitly written as %direct; the obsolete notation 0.0.0.0 is
673 accepted). This option is necessary if pluto's host's interface
674 used for sending packets to the peer is neither point-to-point
675 nor directly connected to the peer.
676 --client subnet
679 the subnet for which the IPsec traffic will be destined. If not
680 specified, the host will be the client. The subnet can be speci‐
681 fied in any of the forms supported by ipsec_atosubnet(3). The
682 general form is address/mask. The address can be either a domain
683 name or four decimal numbers (specifying octets) separated by
684 dots. The most convenient form of the mask is a decimal integer,
685 specifying the number of leading one bits in the mask. So, for
686 example, 10.0.0.0/8 would specify the class A network “Net 10”.
687 --clientwithin subnet
690 This option is obsolete and will be removed. Do not use this op‐
691 tion anymore.
692 --clientprotoport protocol/port
695 specify the Port Selectors (filters) to be used on this connec‐
696 tion. The general form is protocol/port. This is most commonly
697 used to limit the connection to L2TP traffic only by specifying
698 a value of 17/1701 for UDP (protocol 17) and port 1701. The no‐
699 tation 17/%any can be used to allow all UDP traffic and is need‐
700 ed for L2TP connections with Windows XP machines before Service
701 Pack 2.
702 --srcip ip-address
705 the IP address for this host to use when transmitting a packet
706 to the remote IPsec gateway itself. This option is used to make
707 the gateway itself use its internal IP, which is part of the
708 --client subnet. Otherwise it will use its nearest IP address,
709 which is its public IP address, which is not part of the sub‐
710 net-subnet IPsec tunnel, and would therefor not get encrypted.
711 --xauthserver
714 this end is an xauthserver. It will lookup the xauth user name
715 and password and verify this before allowing the connection to
716 get established.
717 --xauthclient
720 this end is an xauthclient. To bring this connection up with the
721 --initiate also requires the client to specify --xauthuser user‐
722 name and --xauthpass password
723 --xauthuser
726 The username for the xauth authentication.This option is normal‐
727 ly passed along by ipsec_auto(8) when an xauth connection is
728 started using ipsec auto --up conn
729 --xauthpass
732 The password for the xauth authentication. This option is nor‐
733 mally passed along by ipsec_auto(8) when an xauth connection is
734 started using ipsec auto --up conn
735 --modecfgserver
738 this end is an Mode Config server
739 --modecfgclient
742 this end is an Mode Config client
743 --dnskeyondemand
746 specifies that when an RSA public key is needed to authenticate
747 this host, and it isn't already known, fetch it from DNS.
748 --updown updown
751 specifies an external shell command to be run whenever pluto
752 brings up or down a connection. The script is used to build a
753 shell command, so it may contain positional parameters, but
754 ought not to have punctuation that would cause the resulting
755 command to be ill-formed. The default is ipsec _updown. Pluto
756 passes a dozen environment variables to the script about the
757 connection involved.
758 --to separates the specification of the left and right ends of the
761 connection. Pluto tries to decide wether it is left or right
762 based on the information provided on both sides of this option.
763 The potential connection description also specifies characteristics of
766 rekeying and security.
767 --psk Propose and allow preshared secret authentication for IKE peers.
770 This authentication requires that each side use the same secret.
771 May be combined with --rsasig; at least one must be specified.
772 --rsasig
775 Propose and allow RSA signatures for authentication of IKE
776 peers. This authentication requires that each side have have a
777 private key of its own and know the public key of its peer. May
778 be combined with --psk; at least one must be specified.
779 --encrypt
782 All proposed or accepted IPsec SAs will include non-null ESP.
783 The actual choices of transforms are wired into pluto.
784 --authenticate
787 All proposed IPsec SAs will include AH. All accepted IPsec SAs
788 will include AH or ESP with authentication. The actual choices
789 of transforms are wired into pluto. Note that this has nothing
790 to do with IKE authentication.
791 --compress
794 All proposed IPsec SAs will include IPCOMP (compression). This
795 will be ignored if KLIPS is not configured with IPCOMP support.
796 --tunnel
799 the IPsec SA should use tunneling. Implicit if the SA is for
800 clients. Must only be used with --authenticate or --encrypt.
801 --ipv4 The host addresses will be interpreted as IPv4 addresses. This
804 is the default. Note that for a connection, all host addresses
805 must be of the same Address Family (IPv4 and IPv6 use different
806 Address Families).
807 --ipv6 The host addresses (including nexthop) will be interpreted as
810 IPv6 addresses. Note that for a connection, all host addresses
811 must be of the same Address Family (IPv4 and IPv6 use different
812 Address Families).
813 --tunnelipv4
816 The client addresses will be interpreted as IPv4 addresses. The
817 default is to match what the host will be. This does not imply
818 --tunnel so the flag can be safely used when no tunnel is actu‐
819 ally specified. Note that for a connection, all tunnel addresses
820 must be of the same Address Family.
821 --tunnelipv6
824 The client addresses will be interpreted as IPv6 addresses. The
825 default is to match what the host will be. This does not imply
826 --tunnel so the flag can be safely used when no tunnel is actu‐
827 ally specified. Note that for a connection, all tunnel addresses
828 must be of the same Address Family.
829 --pfs There should be Perfect Forward Secrecy - new keying material
832 will be generated for each IPsec SA rather than being derived
833 from the ISAKMP SA keying material. Since the group to be used
834 cannot be negotiated (a dubious feature of the standard), pluto
835 will propose the same group that was used during Phase 1. We
836 don't implement a stronger form of PFS which would require that
837 the ISAKMP SA be deleted after the IPSEC SA is negotiated.
838 --pfsgroup modp-group
841 Sets the Diffie-Hellman group used. Currently the following val‐
842 ues are supported: modp1024 (DHgroup 2), modp1536 (DHgroup 5),
843 modp2048 (DHgroup 14), modp3072 (DHgroup 15), modp4096 (DHgroup
844 16), modp6144 (DHgroup 17), and modp8192 (DHgroup 18). It is
845 possible to support the weak and broken modp768 (DHgroup 1), but
846 this requires a manual recompile and is strongly discouraged.
847 --disablearrivalcheck
850 If the connection is a tunnel, allow packets arriving through
851 the tunnel to have any source and destination addresses.
852 --esp esp-algos
855 ESP encryption/authentication algorithm to be used for the con‐
856 nection (phase2 aka IPsec SA). The options must be suitable as a
857 value of ipsec_spi(8). See ipsec.conf(5) for a detailed descrip‐
858 tion of the algorithm format.
859 --aggrmode
862 This tunnel is using aggressive mode ISAKMP negotiation. The de‐
863 fault is main mode. Aggressive mode is less secure than main
864 mode as it reveals your identity to an eavesdropper, but is
865 needed to support road warriors using PSK keys or to interoper‐
866 ate with other buggy implementations insisting on using aggres‐
867 sive mode.
868 --modecfgpull
871 Pull the Mode Config network information from the peer.
872 --dpddelay seconds
875 Set the delay (in seconds) between Dead Peer Dectection (RFC
876 3706) keepalives (R_U_THERE, R_U_THERE_ACK) that are sent for
877 this connection (default 30 seconds).
878 --timeout seconds
881 Set the length of time (in seconds) we will idle without hearing
882 either an R_U_THERE poll from our peer, or an R_U_THERE_ACK re‐
883 ply. After this period has elapsed with no response and no traf‐
884 fic, we will declare the peer dead, and remove the SA (default
885 120 seconds).
886 --dpdaction action
889 When a DPD enabled peer is declared dead, what action should be
890 taken. hold(default) means the eroute will be put into %hold
891 status, while clearmeans the eroute and SA with both be cleared.
892 Clear is really only usefull on the server of a Road Warrior
893 config. The action restart is used on tunnels that need to be
894 permanently up, and have static IP addresses.
895 --forceencaps
898 In some cases, for example when ESP packets are filtered or when
899 a broken IPsec peer does not properly recognise NAT, it can be
900 useful to force RFC-3948 encapsulation using this option. It
901 causes pluto lie and tell the remote peer that RFC-3948 encapsu‐
902 lation (ESP in UDP port 4500 packets) is required. For this op‐
903 tion to have any effect, pluto must have been started with the
904 --nat_traversal option.
905 If none of the --encrypt, --authenticate, --compress, or --pfs flags is
908 given, the initiating the connection will only build an ISAKMP SA. For
909 such a connection, client subnets have no meaning and must not be spec‐
910 ified.
911 Apart from initiating directly using the --initiate option, a tunnel
914 can be loaded with a different policy
915 --initiateontraffic
918 Only initiate the connection when we have traffic to send over
919 the connection
920 --pass Allow unencrypted traffic to flow until the tunnel is initiated.
923 --drop Drop unencrypted traffic silently.
926 --reject
929 Drop unencrypted traffic silently, but send an ICMP message no‐
930 tifying the other end.
931 These options need to be documented
934 --failnone
937 to be documented
938 --failpass
941 to be documented
942 --faildrop
945 to be documented
946 --failreject
949 to be documented
950 pluto supports various X.509 Certificate related options.
953 --utc display all times in UTC.
956 --listall
959 lists all of the X.509 information known to pluto.
960 --listpubkeys
963 list all the public keys that have been successfully loaded.
964 --listcerts
967 list all the X.509 certificates that are currently loaded.
968 --listcacerts
971 list all the X.509 Certificate Agency (CA) certificates that are
972 currently loaded.
973 --listacerts
976 list all the X.509 Attribute certificates that are currently
977 loaded
978 --listaacerts
981 --ocspcerts
985 list all of the X.509 certificates obtained via the Online Cer‐
986 tificate Store Protocol (OCSP)
987 --listgroups
990 --listcrls
994 list all the loaded Certificate Revocation Lists (CRLs)
995 --listcards
998 list all the smartcard and USB token devices.
999 The corresponding options --rereadsecrets, --rereadall, --rereadcac‐
1002 erts, --rereadacerts, --rereadaacerts, --rereadocspcerts --rereadcrls,
1003 and --purgeocsp, options reread this information from their respective
1004 sources, and purge all the online obtained information. The option
1005 --listevents lists all pending CRL fetch commands.
1006 More work is needed to allow for flexible policies. Currently policy is
1009 hardwired in the source file spdb.c. The ISAKMP SAs may use Oakley
1010 groups MODP1024 and MODP1536; AES or 3DES encryption; SHA1-96 and
1011 MD5-96 authentication. The IPsec SAs may use AES or 3DES and MD5-96 or
1012 SHA1-96 for ESP, or just MD5-96 or SHA1-96 for AH. IPCOMP Compression
1013 is always Deflate.
1014 --ikelifetime seconds
1017 how long pluto will propose that an ISAKMP SA be allowed to
1018 live. The default is 3600 (one hour) and the maximum is 86400 (1
1019 day). This option will not affect what is accepted. pluto will
1020 reject proposals that exceed the maximum.
1021 --ipseclifetime seconds
1024 how long pluto will propose that an IPsec SA be allowed to live.
1025 The default is 28800 (eight hours) and the maximum is 86400 (one
1026 day). This option will not affect what is accepted. pluto will
1027 reject proposals that exceed the maximum.
1028 --rekeymargin seconds
1031 how long before an SA's expiration should pluto try to negotiate
1032 a replacement SA. This will only happen if pluto was the initia‐
1033 tor. The default is 540 (nine minutes).
1034 --rekeyfuzz percentage
1037 maximum size of random component to add to rekeymargin, ex‐
1038 pressed as a percentage of rekeymargin. pluto will select a de‐
1039 lay uniformly distributed within this range. By default, the
1040 percentage will be 100. If greater determinism is desired, spec‐
1041 ify 0. It may be appropriate for the percentage to be much larg‐
1042 er than 100.
1043 --keyingtries count
1046 how many times pluto should try to negotiate an SA, either for
1047 the first time or for rekeying. A value of 0 is interpreted as a
1048 very large number: never give up. The default is three.
1049 --dontrekey
1052 A misnomer. Only rekey a connection if we were the Initiator and
1053 there was recent traffic on the existing connection. This ap‐
1054 plies to Phase 1 and Phase 2. This is currently the only auto‐
1055 matic way for a connection to terminate. It may be useful with
1056 Road Warrior or Opportunistic connections. Since SA lifetime ne‐
1057 gotiation is take-it-or-leave it, a Responder normally uses the
1058 shorter of the negotiated or the configured lifetime. This only
1059 works because if the lifetime is shorter than negotiated, the
1060 Responder will rekey in time so that everything works. This in‐
1061 teracts badly with --dontrekey. In this case, the Responder will
1062 end up rekeying to rectify a shortfall in an IPsec SA lifetime;
1063 for an ISAKMP SA, the Responder will accept the negotiated life‐
1064 time.
1065 --delete
1068 when used in the connection form, it causes any previous connec‐
1069 tion with this name to be deleted before this one is added. Un‐
1070 like a normal delete, no diagnostic is produced if there was no
1071 previous connection to delete. Any routing in place for the con‐
1072 nection is undone.
1073 --delete, --name connection-name
1076 The delete form deletes a named connection description and any
1077 SAs established or negotiations initiated using this connection.
1078 Any routing in place for the connection is undone.
1079 --deletestate state-number
1082 The deletestate form deletes the state object with the specified
1083 serial number. This is useful for selectively deleting instances
1084 of connections.
1085 The route form of the whack command tells pluto to set up routing for a
1088 connection. Although like a traditional route, it uses an ipsec device
1089 as a virtual interface. Once routing is set up, no packets will be sent
1090 “in the clear” to the peer's client specified in the connection. A TRAP
1091 shunt eroute will be installed; if outbound traffic is caught, Pluto
1092 will initiate the connection. An explicit whack route is not always
1093 needed: if it hasn't been done when an IPsec SA is being installed, one
1094 will be automatically attempted.
1095 --route, --name connection-name
1098 When a routing is attempted for a connection, there must not al‐
1099 ready be a routing for a different connection with the same sub‐
1100 net but different interface or destination, or if there is, it
1101 must not be being used by an IPsec SA. Otherwise the attempt
1102 will fail.
1103 --unroute, --name connection-name
1106 The unroute form of the whack command tells pluto to undo a
1107 routing. pluto will refuse if an IPsec SA is using the connec‐
1108 tion. If another connection is sharing the same routing, it will
1109 be left in place. Without a routing, packets will be sent with‐
1110 out encryption or authentication.
1111 The initiate form tells pluto to initiate a negotiation with another
1114 pluto (or other IKE daemon) according to the named connection. Initia‐
1115 tion requires a route that --route would provide; if none is in place
1116 at the time an IPsec SA is being installed, pluto attempts to set one
1117 up.
1118 --initiate, --name connection-name, --asynchronous
1121 The initiate form of the whack command will relay back from plu‐
1122 to status information via the UNIX domain socket (unless --asyn‐
1123 chronous is specified). The status information is meant to look
1124 a bit like that from FTP. Currently whack simply copies this to
1125 stderr. When the request is finished (eg. the SAs are estab‐
1126 lished or pluto gives up), pluto closes the channel, causing
1127 whack to terminate.
1128 The opportunistic initiate form is mainly used for debugging.
1131 --tunnelipv4, --tunnelipv6, --oppohere ip-address, --oppothere ip-ad‐
1134 dress
1135 This will cause pluto to attempt to opportunistically initiate a
1136 connection from here to the there, even if a previous attempt
1137 had been made. The whack log will show the progress of this at‐
1138 tempt.
1139 Ending an connection
1142 --terminate, --name connection-name
1145 the terminate form tells pluto to delete any sas that use the
1146 specified connection and to stop any negotiations in process. it
1147 does not prevent new negotiations from starting (the delete form
1148 has this effect).
1149 --crash ip-address
1152 If the remote peer has crashed, and therefor did not notify us,
1153 we keep sending encrypted traffic, and rejecting all plaintext
1154 (non-IKE) traffic from that remote peer. The --crash brings our
1155 end down as well for all the known connections to the specified
1156 ip-address
1157 The public key for informs pluto of the RSA public key for a potential
1160 peer. Private keys must be kept secret, so they are kept in ipsec.se‐
1161 crets(5).
1162 --keyid id
1165 specififies the identity of the peer for which a public key
1166 should be used. Its form is identical to the identity in the
1167 connection. If no public key is specified, pluto attempts to
1168 find KEY records from DNS for the id (if a FQDN) or through re‐
1169 verse lookup (if an IP address). Note that there several inter‐
1170 esting ways in which this is not secure.
1171 --addkey
1174 specifies that the new key is added to the collection; otherwise
1175 the new key replaces any old ones.
1176 --pubkeyrsa key
1179 specifies the value of the RSA public key. It is a sequence of
1180 bytes as described in RFC 2537 “RSA/MD5 KEYs and SIGs in the Do‐
1181 main Name System (DNS)”. It is denoted in a way suitable for
1182 ipsec_ttodata(3). For example, a base 64 numeral starts with 0s.
1183 The listen form tells pluto to start listening for IKE requests on its
1186 public interfaces. To avoid race conditions, it is normal to load the
1187 appropriate connections into pluto before allowing it to listen. If
1188 pluto isn't listening, it is pointless to initiate negotiations, so it
1189 will refuse requests to do so. Whenever the listen form is used, pluto
1190 looks for public interfaces and will notice when new ones have been
1191 added and when old ones have been removed. This is also the trigger for
1192 pluto to read the ipsec.secrets file. So listen may useful more than
1193 once.
1194 --listen
1197 start listening for IKE traffic on public interfaces.
1198 --unlisten
1201 stop listening for IKE traffic on public interfaces.
1202 The status form will display information about the internal state of
1205 pluto: information about each potential connection, about each state
1206 object, and about each shunt that pluto is managing without an associ‐
1207 ated connection.
1208 --status
1211 The shutdown form is the proper way to shut down pluto. It will tear
1215 down the SAs on this machine that pluto has negotiated. It does not in‐
1216 form its peers, so the SAs on their machines remain.
1217 --shutdown
1220 Examples
1224 It would be normal to start pluto in one of the system initialization
1225 scripts. It needs to be run by the superuser. Generally, no arguments
1226 are needed. To run in manually, the superuser can simply type
1227 ipsec pluto
1230 The command will immediately return, but a pluto process will be left
1233 running, waiting for requests from whack or a peer.
1234 Using whack, several potential connections would be described:
1237 ipsec whack --name silly --host 127.0.0.1 --to --host 127.0.0.2
1240 --ikelifetime 900 --ipseclifetime 800 --keyingtries 3
1241 Since this silly connection description specifies neither encryption,
1244 authentication, nor tunneling, it could only be used to establish an
1245 ISAKMP SA.
1246 ipsec whack --name secret --host 10.0.0.1 --client 10.0.1.0/24 --to
1249 --host 10.0.0.2 --client 10.0.2.0/24 --encrypt
1250 This is something that must be done on both sides. If the other side is
1253 pluto, the same whack command could be used on it (the command syntax
1254 is designed to not distinguish which end is ours).
1255 Now that the connections are specified, pluto is ready to handle re‐
1258 quests and replies via the public interfaces. We must tell it to dis‐
1259 cover those interfaces and start accepting messages from peers:
1260 ipsec whack --listen
1263 If we don't immediately wish to bring up a secure connection between
1266 the two clients, we might wish to prevent insecure traffic. The routing
1267 form asks pluto to cause the packets sent from our client to the peer's
1268 client to be routed through the ipsec0 device; if there is no SA, they
1269 will be discarded:
1270 ipsec whack --route secret
1273 Finally, we are ready to get pluto to initiate negotiation for an IPsec
1276 SA (and implicitly, an ISAKMP SA):
1277 ipsec whack --initiate --name secret
1280 A small log of interesting events will appear on standard output (other
1283 logging is sent to syslog).
1284 whack can also be used to terminate pluto cleanly, tearing down all SAs
1287 that it has negotiated.
1288 ipsec whack --shutdown
1291 Notification of any IPSEC SA deletion, but not ISAKMP SA deletion is
1294 sent to the peer. Unfortunately, such Notification is not reliable.
1295 Furthermore, pluto itself ignores Notifications.
1296 XAUTH
1299 If pluto needs additional authentication, such as defined by the XAUTH
1300 specifications, then it may ask whack to prompt the operator for user‐
1301 name or passwords. Typically, these will be entered interactively. A
1302 GUI that wraps around whack may look for the 041 (username) or 040
1303 (password) prompts, and display them to the user.
1304 For testing purposes, the options --xauthuser user --xauthpass pass
1307 may be be given prior to the --initiate to provide responses to the
1308 username and password prompts.
1309 The updown command
1312 Whenever pluto brings a connection up or down, it invokes the updown
1313 command. This command is specified using the --updown option. This al‐
1314 lows for customized control over routing and firewall manipulation.
1315 The updown is invoked for five different operations. Each of these op‐
1318 erations can be for our client subnet or for our host itself.
1319 prepare-host or prepare-client
1322 is run before bringing up a new connection if no other connec‐
1323 tion with the same clients is up. Generally, this is useful for
1324 deleting a route that might have been set up before pluto was
1325 run or perhaps by some agent not known to pluto.
1326 route-host or route-client
1329 is run when bringing up a connection for a new peer client sub‐
1330 net (even if prepare-host or prepare-client was run). The com‐
1331 mand should install a suitable route. Routing decisions are
1332 based only on the destination (peer's client) subnet address,
1333 unlike eroutes which discriminate based on source too.
1334 unroute-host or unroute-client
1337 is run when bringing down the last connection for a particular
1338 peer client subnet. It should undo what the route-host or
1339 route-client did.
1340 up-host or up-client
1343 is run when bringing up a tunnel eroute with a pair of client
1344 subnets that does not already have a tunnel eroute. This command
1345 should install firewall rules as appropriate. It is generally a
1346 good idea to allow IKE messages (UDP port 500) travel between
1347 the hosts.
1348 down-host or down-client
1351 is run when bringing down the eroute for a pair of client sub‐
1352 nets. This command should delete firewall rules as appropriate.
1353 Note that there may remain some inbound IPsec SAs with these
1354 client subnets.
1355 The script is passed a large number of environment variables to specify
1358 what needs to be done.
1359 PLUTO_VERSION
1362 indicates what version of this interface is being used. This
1363 document describes version 1.1. This is upwardly compatible with
1364 version 1.0.
1365 PLUTO_VERB
1368 specifies the name of the operation to be performed (pre‐
1369 pare-host,r prepare-client, up-host, up-client, down-host, or
1370 down-client). If the address family for security gateway to se‐
1371 curity gateway communications is IPv6, then a suffix of -v6 is
1372 added to the verb.
1373 PLUTO_CONNECTION
1376 is the name of the connection for which we are routing.
1377 PLUTO_NEXT_HOP
1380 is the next hop to which packets bound for the peer must be
1381 sent.
1382 PLUTO_INTERFACE
1385 is the name of the ipsec interface to be used.
1386 PLUTO_ME
1389 is the IP address of our host.
1390 PLUTO_MY_CLIENT
1393 is the IP address / count of our client subnet. If the client is
1394 just the host, this will be the host's own IP address / max
1395 (where max is 32 for IPv4 and 128 for IPv6).
1396 PLUTO_MY_CLIENT_NET
1399 is the IP address of our client net. If the client is just the
1400 host, this will be the host's own IP address.
1401 PLUTO_MY_CLIENT_MASK
1404 is the mask for our client net. If the client is just the host,
1405 this will be 255.255.255.255.
1406 PLUTO_PEER
1409 is the IP address of our peer.
1410 PLUTO_PEER_CLIENT
1413 is the IP address / count of the peer's client subnet. If the
1414 client is just the peer, this will be the peer's own IP address
1415 / max (where max is 32 for IPv4 and 128 for IPv6).
1416 PLUTO_PEER_CLIENT_NET
1419 is the IP address of the peer's client net. If the client is
1420 just the peer, this will be the peer's own IP address.
1421 PLUTO_PEER_CLIENT_MASK
1424 is the mask for the peer's client net. If the client is just the
1425 peer, this will be 255.255.255.255.
1426 PLUTO_MY_PROTOCOL
1429 lists the protocols allowed over this IPsec SA.
1430 PLUTO_PEER_PROTOCOL
1433 lists the protocols the peer allows over this IPsec SA.
1434 PLUTO_MY_PORT
1437 lists the ports allowed over this IPsec SA.
1438 PLUTO_PEER_PORT
1441 lists the ports the peer allows over this IPsec SA.
1442 PLUTO_MY_ID
1445 lists our id.
1446 PLUTO_PEER_ID
1449 Dlists our peer's id.
1450 PLUTO_PEER_CA
1453 lists the peer's CA.
1454 All output sent by the script to stderr or stdout is logged. The script
1457 should return an exit status of 0 if and only if it succeeds.
1458 Pluto waits for the script to finish and will not do any other process‐
1461 ing while it is waiting. The script may assume that pluto will not
1462 change anything while the script runs. The script should avoid doing
1463 anything that takes much time and it should not issue any command that
1464 requires processing by pluto. Either of these activities could be per‐
1465 formed by a background subprocess of the script.
1466 Rekeying
1469 When an SA that was initiated by pluto has only a bit of lifetime left,
1470 pluto will initiate the creation of a new SA. This applies to ISAKMP
1471 and IPsec SAs. The rekeying will be initiated when the SA's remaining
1472 lifetime is less than the rekeymargin plus a random percentage, between
1473 0 and rekeyfuzz, of the rekeymargin.
1474 Similarly, when an SA that was initiated by the peer has only a bit of
1477 lifetime left, pluto will try to initiate the creation of a replace‐
1478 ment. To give preference to the initiator, this rekeying will only be
1479 initiated when the SA's remaining lifetime is half of rekeymargin. If
1480 rekeying is done by the responder, the roles will be reversed: the re‐
1481 sponder for the old SA will be the initiator for the replacement. The
1482 former initiator might also initiate rekeying, so there may be redun‐
1483 dant SAs created. To avoid these complications, make sure that rekey‐
1484 margin is generous.
1485 One risk of having the former responder initiate is that perhaps none
1488 of its proposals is acceptable to the former initiator (they have not
1489 been used in a successful negotiation). To reduce the chances of this
1490 happening, and to prevent loss of security, the policy settings are
1491 taken from the old SA (this is the case even if the former initiator is
1492 initiating). These may be stricter than those of the connection.
1493 pluto will not rekey an SA if that SA is not the most recent of its
1496 type (IPsec or ISAKMP) for its potential connection. This avoids creat‐
1497 ing redundant SAs.
1498 The random component in the rekeying time (rekeyfuzz) is intended to
1501 make certain pathological patterns of rekeying unstable. If both sides
1502 decide to rekey at the same time, twice as many SAs as necessary are
1503 created. This could become a stable pattern without the randomness.
1504 Another more important case occurs when a security gateway has SAs with
1507 many other security gateways. Each of these connections might need to
1508 be rekeyed at the same time. This would cause a high peek requirement
1509 for resources (network bandwidth, CPU time, entropy for random num‐
1510 bers). The rekeyfuzz can be used to stagger the rekeying times.
1511 Once a new set of SAs has been negotiated, pluto will never send traf‐
1514 fic on a superseded one. Traffic will be accepted on an old SA until it
1515 expires.
1516 Selecting a Connection When Responding: Road Warrior Support
1519 When pluto receives an initial Main Mode message, it needs to decide
1520 which connection this message is for. It picks based solely on the
1521 source and destination IP addresses of the message. There might be sev‐
1522 eral connections with suitable IP addresses, in which case one of them
1523 is arbitrarily chosen. (The ISAKMP SA proposal contained in the message
1524 could be taken into account, but it is not.)
1525 The ISAKMP SA is negotiated before the parties pass further identifying
1528 information, so all ISAKMP SA characteristics specified in the connec‐
1529 tion description should be the same for every connection with the same
1530 two host IP addresses. At the moment, the only characteristic that
1531 might differ is authentication method.
1532 Up to this point, all configuring has presumed that the IP addresses
1535 are known to all parties ahead of time. This will not work when either
1536 end is mobile (or assigned a dynamic IP address for other reasons). We
1537 call this situation “Road Warrior”. It is fairly tricky and has some
1538 important limitations, most of which are features of the IKE protocol.
1539 Only the initiator may be mobile: the initiator may have an IP number
1542 unknown to the responder. When the responder doesn't recognize the IP
1543 address on the first Main Mode packet, it looks for a connection with
1544 itself as one end and %any as the other. If it cannot find one, it re‐
1545 fuses to negotiate. If it does find one, it creates a temporary connec‐
1546 tion that is a duplicate except with the %any replaced by the source IP
1547 address from the packet; if there was no identity specified for the
1548 peer, the new IP address will be used.
1549 When pluto is using one of these temporary connections and needs to
1552 find the preshared secret or RSA private key in ipsec.secrets, and and
1553 the connection specified no identity for the peer, %any is used as its
1554 identity. After all, the real IP address was apparently unknown to the
1555 configuration, so it is unreasonable to require that it be used in this
1556 table.
1557 Part way into the Phase 1 (Main Mode) negotiation using one of these
1560 temporary connection descriptions, pluto will be receive an Identity
1561 Payload. At this point, pluto checks for a more appropriate connection,
1562 one with an identity for the peer that matches the payload but which
1563 would use the same keys so-far used for authentication. If it finds
1564 one, it will switch to using this better connection (or a temporary de‐
1565 rived from this, if it has %any for the peer's IP address). It may even
1566 turn out that no connection matches the newly discovered identity, in‐
1567 cluding the current connection; if so, pluto terminates negotiation.
1568 Unfortunately, if preshared secret authentication is being used, the
1571 Identity Payload is encrypted using this secret, so the secret must be
1572 selected by the responder without knowing this payload. This limits
1573 there to being at most one preshared secret for all Road Warrior sys‐
1574 tems connecting to a host. RSA Signature authentications does not re‐
1575 quire that the responder know how to select the initiator's public key
1576 until after the initiator's Identity Payload is decoded (using the re‐
1577 sponder's private key, so that must be preselected).
1578 When pluto is responding to a Quick Mode negotiation via one of these
1581 temporary connection descriptions, it may well find that the subnets
1582 specified by the initiator don't match those in the temporary connec‐
1583 tion description. If so, it will look for a connection with matching
1584 subnets, its own host address, a peer address of %any and matching
1585 identities. If it finds one, a new temporary connection is derived from
1586 this one and used for the Quick Mode negotiation of IPsec SAs. If it
1587 does not find one, pluto terminates negotiation.
1588 Be sure to specify an appropriate nexthop for the responder to send a
1591 message to the initiator: pluto has no way of guessing it (if forward‐
1592 ing isn't required, use an explicit %direct as the nexthop and the IP
1593 address of the initiator will be filled in; the obsolete notation
1594 0.0.0.0 is still accepted).
1595 pluto has no special provision for the initiator side. The current
1598 (possibly dynamic) IP address and nexthop must be used in defining con‐
1599 nections. These must be properly configured each time the initiator's
1600 IP address changes. pluto has no mechanism to do this automatically.
1601 Although we call this Road Warrior Support, it could also be used to
1604 support encrypted connections with anonymous initiators. The respon‐
1605 der's organization could announce the preshared secret that would be
1606 used with unrecognized initiators and let anyone connect. Of course the
1607 initiator's identity would not be authenticated.
1608 If any Road Warrior connections are supported, pluto cannot reject an
1611 exchange initiated by an unknown host until it has determined that the
1612 secret is not shared or the signature is invalid. This must await the
1613 third Main Mode message from the initiator. If no Road Warrior connec‐
1614 tion is supported, the first message from an unknown source would be
1615 rejected. This has implications for ease of debugging configurations
1616 and for denial of service attacks.
1617 Although a Road Warrior connection must be initiated by the mobile
1620 side, the other side can and will rekey using the temporary connection
1621 it has created. If the Road Warrior wishes to be able to disconnect, it
1622 is probably wise to set --keyingtries to 1 in the connection on the
1623 non-mobile side to prevent it trying to rekey the connection. Unfortu‐
1624 nately, there is no mechanism to unroute the connection automatically.
1625 Debugging
1628 pluto accepts several optional arguments, useful mostly for debugging.
1629 Except for --interface, each should appear at most once.
1630 --interface interfacename
1633 specifies that the named real public network interface should be
1634 considered. The interface name specified should not be ipsecN.
1635 If the option doesn't appear, all interfaces are considered. To
1636 specify several interfaces, use the option once for each. One
1637 use of this option is to specify which interface should be used
1638 when two or more share the same IP address.
1639 --ikeport port-number
1642 changes the UDP port that pluto will use (default, specified by
1643 IANA: 500)
1644 --ctlbase path
1647 basename for control files. path.ctl is the socket through which
1648 whack communicates with pluto. path.pid is the lockfile to pre‐
1649 vent multiple pluto instances. The default is /var/run/plu‐
1650 to/pluto).
1651 --secretsfile file
1654 specifies the file for authentication secrets (default:
1655 /etc/ipsec.secrets). This name is subject to “globbing” as in
1656 sh(1), so every file with a matching name is processed. Quoting
1657 is generally needed to prevent the shell from doing the glob‐
1658 bing.
1659 --adns path to adns, --lwdnsq path to lwdnsq
1662 specifies where to find pluto's helper program for asynchronous
1663 DNS lookup. pluto can be built to use one of two helper pro‐
1664 grams: _pluto_adns or lwdnsq. You must use the program for which
1665 it was built. By default, pluto will look for the program in
1666 $IPSEC_DIR (if that environment variable is defined) or, failing
1667 that, in the same directory as pluto.
1668 --nofork
1671 disable “daemon fork” (default is to fork). In addition, after
1672 the lock file and control socket are created, print the line
1673 “Pluto initialized” to standard out.
1674 --uniqueids
1677 if this option has been selected, whenever a new ISAKMP SA is
1678 established, any connection with the same Peer ID but a differ‐
1679 ent Peer IP address is unoriented (causing all its SAs to be
1680 deleted). This helps clean up dangling SAs when a connection is
1681 lost and then regained at another IP address.
1682 --stderrlog
1685 log goes to standard out {default is to use syslogd(8))
1686 For example
1689 pluto --secretsfile ipsec.secrets --ctlbase pluto.base --ikeport 8500
1692 --nofork --use-nostack --stderrlog
1693 lets one test pluto without using the superuser account.
1697 pluto is willing to produce a prodigious amount of debugging informa‐
1700 tion. To do so, it must be compiled with -DDEBUG. There are several
1701 classes of debugging output, and pluto may be directed to produce a se‐
1702 lection of them. All lines of debugging output are prefixed with “| ”
1703 to distinguish them from error messages.
1704 When pluto is invoked, it may be given arguments to specify which
1707 classes to output. The current options are:
1708 --debug-none
1711 disable all debugging
1712 --debug-all
1715 enable all debugging
1716 --debug-raw
1719 show the raw bytes of messages
1720 --debug-crypt
1723 show the encryption and decryption of messages
1724 --debug-parsing
1727 show the structure of input messages
1728 --debug-emitting
1731 show the structure of output messages
1732 --debug-control
1735 show pluto's decision making
1736 --debug-controlmore
1739 show even more detailed pluto decision making
1740 --debug-lifecycle
1743 [this option is temporary] log more detail of lifecycle of SAs
1744 --debug-klips
1747 show pluto's interaction with KLIPS
1748 --debug-pfkey
1751 show pluto's PFKEYinterface communication
1752 --debug-dns
1755 show pluto's interaction with DNS for KEY and TXT records
1756 --debug-dpd
1759 show pluto's Dead Peer Detection handling
1760 --debug-natt
1763 show pluto's NAT Traversal handling
1764 --debug-oppo
1767 show why pluto didn't find a suitable DNS TXT record to autho‐
1768 rize opportunistic initiation
1769 --debug-private
1772 allow debugging output with private keys.
1773 The debug form of the whack command will change the selection in a run‐
1776 ning pluto. If a connection name is specified, the flags are added
1777 whenever pluto has identified that it is dealing with that connection.
1778 Unfortunately, this is often part way into the operation being ob‐
1779 served.
1780 For example, to start a pluto with a display of the structure of input
1783 and output:
1784 pluto --debug-emitting --debug-parsing
1787 To later change this pluto to only display raw bytes:
1790 whack --debug-raw
1793 For testing, SSH's IKE test page is quite useful:
1796 http://isakmp-test.ssh.fi/: http://isakmp-test.ssh.fi/
1799 Hint: ISAKMP SAs are often kept alive by IKEs even after the IPsec SA
1802 is established. This allows future IPsec SA's to be negotiated direct‐
1803 ly. If one of the IKEs is restarted, the other may try to use the
1804 ISAKMP SA but the new IKE won't know about it. This can lead to much
1805 confusion. pluto is not yet smart enough to get out of such a mess.
1806 Pluto's Behaviour When Things Go Wrong
1809 When pluto doesn't understand or accept a message, it just ignores the
1810 message. It is not yet capable of communicating the problem to the oth‐
1811 er IKE daemon (in the future it might use Notifications to accomplish
1812 this in many cases). It does log a diagnostic.
1813 When pluto gets no response from a message, it resends the same message
1816 (a message will be sent at most three times). This is appropriate: UDP
1817 is unreliable.
1818 When pluto gets a message that it has already seen, there are many cas‐
1821 es when it notices and discards it. This too is appropriate for UDP.
1822 Combine these three rules, and you can explain many apparently mysteri‐
1825 ous behaviours. In a pluto log, retrying isn't usually the interesting
1826 event. The critical thing is either earlier (pluto got a message which
1827 it didn't like and so ignored, so it was still awaiting an acceptable
1828 message and got impatient) or on the other system (pluto didn't send a
1829 reply because it wasn't happy with the previous message).
1830 Notes
1833 If pluto is compiled without -DKLIPS, it negotiates Security Associa‐
1834 tions but never ask the kernel to put them in place and never makes
1835 routing changes. This allows pluto to be tested on systems without
1836 KLIPS, but makes it rather useless.
1837 Each IPsec SA is assigned an SPI, a 32-bit number used to refer to the
1840 SA. The IKE protocol lets the destination of the SA choose the SPI. The
1841 range 0 to 0xFF is reserved for IANA. Pluto also avoids choosing an SPI
1842 in the range 0x100 to 0xFFF, leaving these SPIs free for manual keying.
1843 Remember that the peer, if not pluto, may well chose SPIs in this
1844 range.
1845 Policies
1848 This catalogue of policies may be of use when trying to configure Pluto
1849 and another IKE implementation to interoperate.
1850 In Phase 1, only Main Mode is supported. We are not sure that Aggres‐
1853 sive Mode is secure. For one thing, it does not support identity pro‐
1854 tection. It may allow more severe Denial Of Service attacks.
1855 No Informational Exchanges are supported. These are optional and since
1858 their delivery is not assured, they must not matter. It is the case
1859 that some IKE implementations won't interoperate without Informational
1860 Exchanges, but we feel they are broken.
1861 No Informational Payloads are supported. These are optional, but use‐
1864 ful. It is of concern that these payloads are not authenticated in
1865 Phase 1, nor in those Phase 2 messages authenticated with HASH(3).
1866 · Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5) are sup‐
1869 ported. Group MODP768 (1) is not supported because it is too
1870 weak.
1871 · Host authetication can be done by RSA Signatures or Pre-Shared
1874 Secrets.
1875 · 3DES CBC (Cypher Block Chaining mode) is the only encryption
1878 supported, both for ISAKMP SAs and IPSEC SAs.
1879 · MD5 and SHA1 hashing are supported for packet authentication in
1882 both kinds of SAs.
1883 · The ESP, AH, or AH plus ESP are supported. If, and only if, AH
1886 and ESP are combined, the ESP need not have its own authentica‐
1887 tion component. The selection is controlled by the --encrypt and
1888 --authenticate flags.
1889 · Each of these may be combined with IPCOMP Deflate compression,
1892 but only if the potential connection specifies compression and
1893 only if KLIPS is configured with IPCOMP support.
1894 · The IPSEC SAs may be tunnel or transport mode, where appropri‐
1897 ate. The --tunnel flag controls this when pluto is initiating.
1898 · When responding to an ISAKMP SA proposal, the maximum acceptable
1901 lifetime is eight hours. The default is one hour. There is no
1902 minimum. The --ikelifetime flag controls this when pluto is ini‐
1903 tiating.
1904 · When responding to an IPSEC SA proposal, the maximum acceptable
1907 lifetime is one day. The default is eight hours. There is no
1908 minimum. The --ipseclifetime flag controls this when pluto is
1909 initiating.
1910 · PFS is acceptable, and will be proposed if the --pfs flag was
1913 specified. The DH group proposed will be the same as negotiated
1914 for Phase 1.
1915
1918 Pluto responds to SIGHUP by issuing a suggestion that ``whack --lis‐
1919 ten'' might have been intended.
1920 Pluto exits when it recieves SIGTERM.
1923
1926 pluto normally forks a daemon process, so the exit status is normally a
1927 very preliminary result.
1928 0 means that all is OK so far.
1931 1 means that something was wrong.
1934 10 means that the lock file already exists.
1937 If whack detects a problem, it will return an exit status of 1. If it
1940 received progress messages from pluto, it returns as status the value
1941 of the numeric prefix from the last such message that was not a message
1942 sent to syslog or a comment (but the prefix for success is treated as
1943 0). Otherwise, the exit status is 0.
1944
1947 /var/run/pluto/pluto.pid /var/run/pluto/pluto.ctl /etc/ipsec.se‐
1948 crets $IPSEC_LIBDIR/_pluto_adns $IPSEC_EXECDIR/lwdnsq
1949 /dev/urandom
1950
1953 IPSEC_LIBDIR IPSEC_EXECDIR IPSECmyid PLUTO_CORE_DIR
1954
1957 The rest of the Openswan distribution, in particular ipsec(8).
1958 ipsec_auto(8) is designed to make using pluto more pleasant. Use it!
1961 ipsec.secrets(5) describes the format of the secrets file.
1964 ipsec_atoaddr(3), part of the Openswan distribution, describes the
1967 forms that IP addresses may take. ipsec_atosubnet(3), part of the
1968 Openswan distribution, describes the forms that subnet specifications.
1969 For more information on IPsec, the mailing list, and the relevant docu‐
1972 ments, see:
1973 http://www.ietf.cnri.reston.va.us/html.charters/ipsec-charter.html:
1976 http://www.ietf.cnri.reston.va.us/html.charters/ipsec-charter.html
1977 At the time of writing, the most relevant IETF RFCs are:
1980 RFC2409 The Internet Key Exchange (IKE)
1983 RFC2408 Internet Security Association and Key Management Protocol
1986 (ISAKMP)
1987 RFC2407 The Internet IP Security Domain of Interpretation for ISAKMP
1990 The Openswan web site <htp://www.openswan.org> and the mailing lists
1993 described there.
1994
1997 This code is released under the GPL terms. See the accompanying files
1998 COPYING and CREDITS for more details. The GPL does NOT apply to those
1999 pieces of code written by others which are included in this distribu‐
2000 tion, except as noted by the individual authors.
2001 This software was originally written for the FreeS/WAN project
2004 <http://www.freeswan.org: http://www.freeswan.org>, founded by John
2005 Gilmore and managed by Hugh Daniel. It was written by Angelos D.
2006 Keromytis (angelos@dsl.cis.upenn.edu), in May/June 1997, in Athens,
2007 Greece. Thanks go to John Ioannidis for his help.
2008 It is currently maintained and extended by Xelerance Corporation, in
2011 Canada under the Openswan name. See CHANGES for details.
2012 FreeS/WAN was developed/maintained from 2000-2004 by D. Hugh Redelmeier
2015 (hugh@mimosa.com), in Canada. The regulations of Greece and Canada al‐
2016 low the code to be freely redistributable.
2017 Kai Martius (admin@imib.med.tu-dresden.de) contributed the initial ver‐
2020 sion of the code supporting PFS.
2021 Richard Guy Briggs <rgb@conscoop.ottawa.on.ca> and Peter Onion
2024 <ponion@srd.bt.co.uk> added the PFKEY2 support.
2025 We gratefully acknowledge that we use parts of Eric Young's libdes
2028 package; see ../libdes/COPYRIGHT.
2029
2032 pluto is a work-in-progress. It currently has many limitations. For ex‐
2033 ample, it ignores notification messages that it receives, and it gener‐
2034 ates only Delete Notifications and those only for IPSEC SAs.
2035 pluto does not support the Commit Flag. The Commit Flag is a bad fea‐
2038 ture of the IKE protocol. It isn't protected -- neither encrypted nor
2039 authenticated. A man in the middle could turn it on, leading to DoS. We
2040 just ignore it, with a warning. This should let us interoperate with
2041 implementations that insist on it, with minor damage.
2042 pluto does not check that the SA returned by the Responder is actually
2045 one that was proposed. It only checks that the SA is acceptable. The
2046 difference is not large, but can show up in attributes such as SA life‐
2047 time.
2048 There is no good way for a connection to be automatically terminated.
2051 This is a problem for Road Warrior and Opportunistic connections. The
2052 --dontrekey option does prevent the SAs from being rekeyed on expiry.
2053 Additonally, if a Road Warrior connection has a client subnet with a
2054 fixed IP address, a negotiation with that subnet will cause any other
2055 connection instantiations with that same subnet to be unoriented
2056 (deleted, in effect). See also the --uniqueids option for an extension
2057 of this.
2058 When pluto sends a message to a peer that has disappeared, pluto re‐
2061 ceives incomplete information from the kernel, so it logs the unsatis‐
2062 factory message “some IKE message we sent has been rejected with ECON‐
2063 NREFUSED (kernel supplied no details)”. John Denker suggests that this
2064 command is useful for tracking down the source of these problems: tcp‐
2065 dump -i eth0 icmp[0] != 8 and icmp[0] != 0 Substitute your public in‐
2066 terface for eth0 if it is different.
2067 The word “authenticate” is used for two different features. We must au‐
2070 thenticate each IKE peer to the other. This is an important task of
2071 Phase 1. Each packet must be authenticated, both in IKE and in IPsec,
2072 and the method for IPsec is negotiated as an AH SA or part of an ESP
2073 SA. Unfortunately, the protocol has no mechanism for authenticating the
2074 Phase 2 identities.
2075 Bugs should be reported to the <users@lists.openswan.org> mailing list.
2078 26 October 2006 IPSEC_PLUTO(8)