]>
Commit | Line | Data |
---|---|---|
997358a6 MW |
1 | Content-type: text/html |
2 | ||
3 | <HTML><HEAD><TITLE>Manpage of IPSEC_PLUTO</TITLE> | |
4 | </HEAD><BODY> | |
5 | <H1>IPSEC_PLUTO</H1> | |
6 | Section: Maintenance Commands (8)<BR>Updated: 28 March 1999<BR><A HREF="#index">Index</A> | |
7 | <A HREF="http://localhost/cgi-bin/man/man2html">Return to Main Contents</A><HR> | |
8 | ||
9 | <A NAME="lbAB"> </A> | |
10 | <H2>NAME</H2> | |
11 | ||
12 | ipsec pluto - IPsec IKE keying daemon | |
13 | <BR> | |
14 | ||
15 | ipsec whack - control interface for IPSEC keying daemon | |
16 | <A NAME="lbAC"> </A> | |
17 | <H2>SYNOPSIS</H2> | |
18 | ||
19 | ||
20 | ||
21 | <DL COMPACT> | |
22 | <DT> | |
23 | <B> | |
24 | <DD>ipsec pluto | |
25 | [--help] | |
26 | [--version] | |
27 | [--optionsfrom </B><I>filename</I>] | |
28 | [--nofork] | |
29 | [--stderrlog] | |
30 | [--noklips] | |
31 | [--uniqueids] | |
32 | [<B>--interface</B> <I>interfacename</I>] | |
33 | [--ikeport <I>portnumber</I>] | |
34 | [--ctlbase <I>path</I>] | |
35 | [--secretsfile <I>secrets-file</I>] | |
36 | [--adns <I>pathname</I>] | |
37 | [--lwdnsq <I>pathname</I>] | |
38 | [--perpeerlog] | |
39 | [--perpeerlogbase <I>dirname</I>] | |
40 | [--debug-none] | |
41 | [--debug-all] | |
42 | [--debug-raw] | |
43 | [--debug-crypt] | |
44 | [--debug-parsing] | |
45 | [--debug-emitting] | |
46 | [--debug-control] | |
47 | [--debug-lifecycle] | |
48 | [--debug-klips] | |
49 | [--debug-dns] | |
50 | [--debug-oppo] | |
51 | [--debug-private] | |
52 | <DT> | |
53 | <B> | |
54 | <DD>ipsec whack | |
55 | [--help] | |
56 | [--version] | |
57 | <DT> | |
58 | ||
59 | <DD>ipsec whack | |
60 | --name </B><I>connection-name</I> | |
61 | <BR> | |
62 | ||
63 | [--id <I>id</I>] [--host <I>ip-address</I>] | |
64 | [--ikeport <I>port-number</I>] | |
65 | [--nexthop <I>ip-address</I>] | |
66 | [--client <I>subnet</I>] | |
67 | [--dnskeyondemand] | |
68 | [--updown <I>updown</I>] | |
69 | <BR> | |
70 | ||
71 | --to | |
72 | <BR> | |
73 | ||
74 | [--id <I>id</I>] | |
75 | [--host <I>ip-address</I>] | |
76 | [--ikeport <I>port-number</I>] | |
77 | [--nexthop <I>ip-address</I>] | |
78 | [--client <I>subnet</I>] | |
79 | [--dnskeyondemand] | |
80 | [--updown <I>updown</I>] | |
81 | <BR> | |
82 | ||
83 | [--psk] | |
84 | [--rsasig] | |
85 | [--encrypt] | |
86 | [--authenticate] | |
87 | [--compress] | |
88 | [--tunnel] | |
89 | [--pfs] | |
90 | [--disablearrivalcheck] | |
91 | [--ipv4] | |
92 | [--ipv6] | |
93 | [--tunnelipv4] | |
94 | [--tunnelipv6] | |
95 | [--ikelifetime <I>seconds</I>] | |
96 | [--ipseclifetime <I>seconds</I>] | |
97 | [--rekeymargin <I>seconds</I>] | |
98 | [--rekeyfuzz <I>percentage</I>] | |
99 | [--keyingtries <I>count</I>] | |
100 | [--dontrekey] | |
101 | [--delete] | |
102 | [--ctlbase <I>path</I>] | |
103 | [--optionsfrom <I>filename</I>] | |
104 | [--label <I>string</I>] | |
105 | <DT> | |
106 | <B> | |
107 | <DD>ipsec whack | |
108 | --keyid </B><I>id</I> | |
109 | [--addkey] | |
110 | [--pubkeyrsa <I>key</I>] | |
111 | [--ctlbase <I>path</I>] | |
112 | [--optionsfrom <I>filename</I>] | |
113 | [--label <I>string</I>] | |
114 | <DT> | |
115 | <B> | |
116 | <DD>ipsec whack | |
117 | --myid </B><I>id</I> | |
118 | <DT> | |
119 | <B> | |
120 | <DD>ipsec whack | |
121 | --listen|--unlisten | |
122 | [--ctlbase </B><I>path</I>] | |
123 | [--optionsfrom <I>filename</I>] | |
124 | [--label <I>string</I>] | |
125 | <DT> | |
126 | <B> | |
127 | <DD>ipsec whack | |
128 | --route|--unroute | |
129 | --name </B><I>connection-name</I> | |
130 | [--ctlbase <I>path</I>] | |
131 | [--optionsfrom <I>filename</I>] | |
132 | [--label <I>string</I>] | |
133 | <DT> | |
134 | <B> | |
135 | <DD>ipsec whack | |
136 | --initiate|--terminate | |
137 | --name </B><I>connection-name</I> | |
138 | [--asynchronous] | |
139 | [--ctlbase <I>path</I>] | |
140 | [--optionsfrom <I>filename</I>] | |
141 | [--label <I>string</I>] | |
142 | <DT> | |
143 | <B> | |
144 | <DD>ipsec whack | |
145 | [--tunnelipv4] | |
146 | [--tunnelipv6] | |
147 | --oppohere </B><I>ip-address</I> | |
148 | --oppothere <I>ip-address</I> | |
149 | <DT> | |
150 | <B> | |
151 | <DD>ipsec whack | |
152 | --delete | |
153 | --name </B><I>connection-name</I> | |
154 | [--ctlbase <I>path</I>] | |
155 | [--optionsfrom <I>filename</I>] | |
156 | [--label <I>string</I>] | |
157 | <DT> | |
158 | <B> | |
159 | <DD>ipsec whack | |
160 | --deletestate </B><I>state-number</I> | |
161 | [--ctlbase <I>path</I>] | |
162 | [--optionsfrom <I>filename</I>] | |
163 | [--label <I>string</I>] | |
164 | <DT> | |
165 | <B> | |
166 | <DD>ipsec whack | |
167 | [--name </B><I>connection-name</I>] | |
168 | [--debug-none] | |
169 | [--debug-all] | |
170 | [--debug-raw] | |
171 | [--debug-crypt] | |
172 | [--debug-parsing] | |
173 | [--debug-emitting] | |
174 | [--debug-control] | |
175 | [--debug-lifecycle] | |
176 | [--debug-klips] | |
177 | [--debug-dns] | |
178 | [--debug-oppo] | |
179 | [--debug-private] | |
180 | [--ctlbase <I>path</I>] | |
181 | [--optionsfrom <I>filename</I>] | |
182 | [--label <I>string</I>] | |
183 | <DT> | |
184 | <B> | |
185 | <DD>ipsec whack | |
186 | --status | |
187 | [--ctlbase </B><I>path</I>] | |
188 | [--optionsfrom <I>filename</I>] | |
189 | [--label <I>string</I>] | |
190 | <DT> | |
191 | <B> | |
192 | <DD>ipsec whack | |
193 | --shutdown | |
194 | [--ctlbase </B><I>path</I>] | |
195 | [--optionsfrom <I>filename</I>] | |
196 | [--label <I>string</I>] | |
197 | ||
198 | ||
199 | ||
200 | </DL> | |
201 | <A NAME="lbAD"> </A> | |
202 | <H2>DESCRIPTION</H2> | |
203 | ||
204 | <B>pluto</B> | |
205 | ||
206 | is an IKE (``IPsec Key Exchange'') daemon. | |
207 | <B>whack</B> | |
208 | ||
209 | is an auxiliary program to allow requests to be made to a running | |
210 | <B>pluto</B>. | |
211 | ||
212 | <P> | |
213 | ||
214 | <B>pluto</B> | |
215 | ||
216 | is used to automatically build shared ``security associations'' on a | |
217 | system that has IPsec, the secure IP protocol. | |
218 | In other words, | |
219 | <B>pluto</B> | |
220 | ||
221 | can eliminate much of the work of manual keying. | |
222 | The actual | |
223 | secure transmission of packets is the responsibility of other parts of | |
224 | the system (see | |
225 | <B>KLIPS</B>, | |
226 | ||
227 | the companion implementation of IPsec). | |
228 | <I><A HREF="ipsec_auto.8.html">ipsec_auto</A></I>(8) provides a more convenient interface to | |
229 | <B>pluto</B> and <B>whack</B>. | |
230 | <A NAME="lbAE"> </A> | |
231 | <H3>IKE's Job</H3> | |
232 | ||
233 | <P> | |
234 | ||
235 | A <I>Security Association</I> (<I>SA</I>) is an agreement between two network nodes on | |
236 | how to process certain traffic between them. This processing involves | |
237 | encapsulation, authentication, encryption, or compression. | |
238 | <P> | |
239 | ||
240 | IKE can be deployed on a network node to negotiate Security | |
241 | Associations for that node. These IKE implementations can only | |
242 | negotiate with other IKE implementations, so IKE must be on each node | |
243 | that is to be an endpoint of an IKE-negotiated Security Association. | |
244 | No other nodes need to be running IKE. | |
245 | <P> | |
246 | ||
247 | An IKE instance (i.e. an IKE implementation on a particular network | |
248 | node) communicates with another IKE instance using UDP IP packets, so | |
249 | there must be a route between the nodes in each direction. | |
250 | <P> | |
251 | ||
252 | The negotiation of Security Associations requires a number of choices | |
253 | that involve tradeoffs between security, convenience, trust, and | |
254 | efficiency. These are policy issues and are normally specified to the | |
255 | IKE instance by the system administrator. | |
256 | <P> | |
257 | ||
258 | IKE deals with two kinds of Security Associations. The first part of | |
259 | a negotiation between IKE instances is to build an ISAKMP SA. An | |
260 | ISAKMP SA is used to protect communication between the two IKEs. | |
261 | IPsec SAs can then be built by the IKEs - these are used to carry | |
262 | protected IP traffic between the systems. | |
263 | <P> | |
264 | ||
265 | The negotiation of the ISAKMP SA is known as Phase 1. In theory, | |
266 | Phase 1 can be accomplished by a couple of different exchange types, | |
267 | but we only implement one called Main Mode (we don't implement | |
268 | Aggressive Mode). | |
269 | <P> | |
270 | ||
271 | Any negotiation under the protection of an ISAKMP SA, including the | |
272 | negotiation of IPsec SAs, is part of Phase 2. The exchange type | |
273 | that we use to negotiate an IPsec SA is called Quick Mode. | |
274 | <P> | |
275 | ||
276 | IKE instances must be able to authenticate each other as part of their | |
277 | negotiation of an ISAKMP SA. This can be done by several mechanisms | |
278 | described in the draft standards. | |
279 | <P> | |
280 | ||
281 | IKE negotiation can be initiated by any instance with any other. If | |
282 | both can find an agreeable set of characteristics for a Security | |
283 | Association, and both recognize each others authenticity, they can set | |
284 | up a Security Association. The standards do not specify what causes | |
285 | an IKE instance to initiate a negotiation. | |
286 | <P> | |
287 | ||
288 | In summary, an IKE instance is prepared to automate the management of | |
289 | Security Associations in an IPsec environment, but a number of issues | |
290 | are considered policy and are left in the system administrator's hands. | |
291 | <A NAME="lbAF"> </A> | |
292 | <H3>Pluto</H3> | |
293 | ||
294 | <P> | |
295 | ||
296 | <B>pluto</B> is an implementation of IKE. It runs as a daemon on a network | |
297 | node. Currently, this network node must be a LINUX system running the | |
298 | <B>KLIPS</B> implementation of IPsec. | |
299 | <P> | |
300 | ||
301 | <B>pluto</B> only implements a subset of IKE. This is enough for it to | |
302 | interoperate with other instances of <B>pluto</B>, and many other IKE | |
303 | implementations. We are working on implementing more of IKE. | |
304 | <P> | |
305 | ||
306 | The policy for acceptable characteristics for Security Associations is | |
307 | mostly hardwired into the code of <B>pluto</B> (spdb.c). Eventually | |
308 | this will be moved into a security policy database with reasonable | |
309 | expressive power and more convenience. | |
310 | <P> | |
311 | ||
312 | <B>pluto</B> uses shared secrets or RSA signatures to authenticate | |
313 | peers with whom it is negotiating. | |
314 | <P> | |
315 | ||
316 | <B>pluto</B> initiates negotiation of a Security Association when it is | |
317 | manually prodded: the program <B>whack</B> is run to trigger this. | |
318 | It will also initiate a negotiation when <B>KLIPS</B> traps an outbound packet | |
319 | for Opportunistic Encryption. | |
320 | <P> | |
321 | ||
322 | <B>pluto</B> implements ISAKMP SAs itself. After it has negotiated the | |
323 | characteristics of an IPsec SA, it directs <B>KLIPS</B> to implement it. | |
324 | It also invokes a script to adjust any firewall and issue <I><A HREF="route.8.html">route</A></I>(8) | |
325 | commands to direct IP packets through <B>KLIPS</B>. | |
326 | <P> | |
327 | ||
328 | When <B>pluto</B> shuts down, it closes all Security Associations. | |
329 | <A NAME="lbAG"> </A> | |
330 | <H3>Before Running Pluto</H3> | |
331 | ||
332 | <P> | |
333 | ||
334 | <B>pluto</B> runs as a daemon with userid root. Before running it, a few | |
335 | things must be set up. | |
336 | <P> | |
337 | ||
338 | <B>pluto</B> requires <B>KLIPS</B>, the FreeS/WAN implementation of IPsec. | |
339 | All of the components of <B>KLIPS</B> and <B>pluto</B> should be installed. | |
340 | <P> | |
341 | ||
342 | <B>pluto</B> supports multiple public networks (that is, networks | |
343 | that are considered insecure and thus need to have their traffic | |
344 | encrypted or authenticated). It discovers the | |
345 | public interfaces to use by looking at all interfaces that are | |
346 | configured (the <B>--interface</B> option can be used to limit | |
347 | the interfaces considered). | |
348 | It does this only when <B>whack</B> tells it to --listen, | |
349 | so the interfaces must be configured by then. Each interface with a name of the form | |
350 | <B>ipsec</B>[<B>0</B>-<B>9</B>] is taken as a <B>KLIPS</B> virtual public interface. | |
351 | Another network interface with the same IP address (there should be only | |
352 | one) is taken as the corresponding real public | |
353 | interface. <I><A HREF="ifconfig.8.html">ifconfig</A></I>(8) with the <B>-a</B> flag will show | |
354 | the name and status of each network interface. | |
355 | <P> | |
356 | ||
357 | <B>pluto</B> requires a database of preshared secrets and RSA private keys. | |
358 | This is described in the | |
359 | <I><A HREF="ipsec.secrets.5.html">ipsec.secrets</A></I>(5). | |
360 | ||
361 | <B>pluto</B> is told of RSA public keys via <B>whack</B> commands. | |
362 | If the connection is Opportunistic, and no RSA public key is known, | |
363 | <B>pluto</B> will attempt to fetch RSA keys using the Domain Name System. | |
364 | <A NAME="lbAH"> </A> | |
365 | <H3>Setting up <B>KLIPS</B> for <B>pluto</B></H3> | |
366 | ||
367 | <P> | |
368 | ||
369 | The most basic network topology that <B>pluto</B> supports has two security | |
370 | gateways negotiating on behalf of client subnets. The diagram of RGB's | |
371 | testbed is a good example (see <I>klips/doc/rgb_setup.txt</I>). | |
372 | <P> | |
373 | ||
374 | The file <I>INSTALL</I> in the base directory of this distribution | |
375 | explains how to start setting up the whole system, including <B>KLIPS</B>. | |
376 | <P> | |
377 | ||
378 | Make sure that the security gateways have routes to each other. This | |
379 | is usually covered by the default route, but may require issuing | |
380 | <I><A HREF="route.8.html">route</A></I>(8) | |
381 | ||
382 | commands. The route must go through a particular IP | |
383 | interface (we will assume it is <I>eth0</I>, but it need not be). The | |
384 | interface that connects the security gateway to its client must be a | |
385 | different one. | |
386 | <P> | |
387 | ||
388 | It is necessary to issue a | |
389 | <I><A HREF="ipsec_tncfg.8.html">ipsec_tncfg</A></I>(8) | |
390 | ||
391 | command on each gateway. The required command is: | |
392 | <P> | |
393 | ipsec tncfg --attach --virtual ipsec0 --physical eth0 | |
394 | <P> | |
395 | A command to set up the ipsec0 virtual interface will also need to be | |
396 | run. It will have the same parameters as the command used to set up | |
397 | the physical interface to which it has just been connected using | |
398 | <I><A HREF="ipsec_tncfg.8.html">ipsec_tncfg</A></I>(8). | |
399 | ||
400 | <A NAME="lbAI"> </A> | |
401 | <H3>ipsec.secrets file</H3> | |
402 | ||
403 | <P> | |
404 | ||
405 | A <B>pluto</B> daemon and another IKE daemon (for example, another instance | |
406 | of <B>pluto</B>) must convince each other that they are who they are supposed | |
407 | to be before any negotiation can succeed. This authentication is | |
408 | accomplished by using either secrets that have been shared beforehand | |
409 | (manually) or by using RSA signatures. There are other techniques, | |
410 | but they have not been implemented in <B>pluto</B>. | |
411 | <P> | |
412 | ||
413 | The file <I>/etc/ipsec.secrets</I> is used to keep preshared secret keys | |
414 | and RSA private keys for | |
415 | authentication with other IKE daemons. For debugging, there is an | |
416 | argument to the <B>pluto</B> command to use a different file. | |
417 | This file is described in | |
418 | <I><A HREF="ipsec.secrets.5.html">ipsec.secrets</A></I>(5). | |
419 | ||
420 | <A NAME="lbAJ"> </A> | |
421 | <H3>Running Pluto</H3> | |
422 | ||
423 | <P> | |
424 | ||
425 | To fire up the daemon, just type <B>pluto</B> (be sure to be running as | |
426 | the superuser). | |
427 | The default IKE port number is 500, the UDP port assigned by IANA for IKE Daemons. | |
428 | <B>pluto</B> must be run by the superuser to be able to use the UDP 500 port. | |
429 | <P> | |
430 | ||
431 | <B>pluto</B> attempts to create a lockfile with the name | |
432 | <I>/var/run/pluto.pid</I>. If the lockfile cannot be created, | |
433 | <B>pluto</B> exits - this prevents multiple <B>pluto</B>s from | |
434 | competing Any ``leftover'' lockfile must be removed before | |
435 | <B>pluto</B> will run. <B>pluto</B> writes its pid into this file so | |
436 | that scripts can find it. This lock will not function properly if it | |
437 | is on an NFS volume (but sharing locks on multiple machines doesn't | |
438 | make sense anyway). | |
439 | <P> | |
440 | ||
441 | <B>pluto</B> then forks and the parent exits. This is the conventional | |
442 | ``daemon fork''. It can make debugging awkward, so there is an option | |
443 | to suppress this fork. | |
444 | <P> | |
445 | ||
446 | All logging, including diagnostics, is sent to | |
447 | <I><A HREF="syslog.3.html">syslog</A></I>(3) | |
448 | ||
449 | with facility=authpriv; | |
450 | it decides where to put these messages (possibly in /var/log/secure). | |
451 | Since this too can make debugging awkward, there is an option to | |
452 | steer logging to stderr. | |
453 | <P> | |
454 | ||
455 | If the <B>--perpeerlog</B> option is given, then pluto will open | |
456 | a log file per connection. By default, this is in /var/log/pluto/peer, | |
457 | in a subdirectory formed by turning all dot (.) [IPv4} or colon (:) | |
458 | [IPv6] into slashes (/). | |
459 | <P> | |
460 | ||
461 | The base directory can be changed with the <B>--perpeerlogbase</B>. | |
462 | <P> | |
463 | ||
464 | Once <B>pluto</B> is started, it waits for requests from <B>whack</B>. | |
465 | <A NAME="lbAK"> </A> | |
466 | <H3>Pluto's Internal State</H3> | |
467 | ||
468 | <P> | |
469 | ||
470 | To understand how to use <B>pluto</B>, it is helpful to understand a little | |
471 | about its internal state. Furthermore, the terminology is needed to decipher | |
472 | some of the diagnostic messages. | |
473 | <P> | |
474 | ||
475 | The <I>(potential) connection</I> database describes attributes of a | |
476 | connection. These include the IP addresses of the hosts and client | |
477 | subnets and the security characteristics desired. <B>pluto</B> | |
478 | requires this information (simply called a connection) before it can | |
479 | respond to a request to build an SA. Each connection is given a name | |
480 | when it is created, and all references are made using this name. | |
481 | <P> | |
482 | ||
483 | During the IKE exchange to build an SA, the information about the | |
484 | negotiation is represented in a <I>state object</I>. Each state object | |
485 | reflects how far the negotiation has reached. Once the negotiation is | |
486 | complete and the SA established, the state object remains to represent | |
487 | the SA. When the SA is terminated, the state object is discarded. | |
488 | Each State object is given a serial number and this is used to refer | |
489 | to the state objects in logged messages. | |
490 | <P> | |
491 | ||
492 | Each state object corresponds to a connection and can be thought of | |
493 | as an instantiation of that connection. | |
494 | At any particular time, there may be any number of state objects | |
495 | corresponding to a particular connection. | |
496 | Often there is one representing an ISAKMP SA and another representing | |
497 | an IPsec SA. | |
498 | <P> | |
499 | ||
500 | <B>KLIPS</B> hooks into the routing code in a LINUX kernel. | |
501 | Traffic to be processed by an IPsec SA must be directed through | |
502 | <B>KLIPS</B> by routing commands. Furthermore, the processing to be | |
503 | done is specified by <I>ipsec <A HREF="eroute.8.html">eroute</A>(8)</I> commands. | |
504 | <B>pluto</B> takes the responsibility of managing both of these special | |
505 | kinds of routes. | |
506 | <P> | |
507 | ||
508 | Each connection may be routed, and must be while it has an IPsec SA. | |
509 | The connection specifies the characteristics of the route: the | |
510 | interface on this machine, the ``gateway'' (the nexthop), | |
511 | and the peer's client subnet. Two | |
512 | connections may not be simultaneously routed if they are for the same | |
513 | peer's client subnet but use different interfaces or gateways | |
514 | (<B>pluto</B>'s logic does not reflect any advanced routing capabilities). | |
515 | <P> | |
516 | ||
517 | Each eroute is associated with the state object for an IPsec SA | |
518 | because it has the particular characteristics of the SA. | |
519 | Two eroutes conflict if they specify the identical local | |
520 | and remote clients (unlike for routes, the local clients are | |
521 | taken into account). | |
522 | <P> | |
523 | ||
524 | When <B>pluto</B> needs to install a route for a connection, | |
525 | it must make sure that no conflicting route is in use. If another | |
526 | connection has a conflicting route, that route will be taken down, as long | |
527 | as there is no IPsec SA instantiating that connection. | |
528 | If there is such an IPsec SA, the attempt to install a route will fail. | |
529 | <P> | |
530 | ||
531 | There is an exception. If <B>pluto</B>, as Responder, needs to install | |
532 | a route to a fixed client subnet for a connection, and there is | |
533 | already a conflicting route, then the SAs using the route are deleted | |
534 | to make room for the new SAs. The rationale is that the new | |
535 | connection is probably more current. The need for this usually is a | |
536 | product of Road Warrior connections (these are explained later; they | |
537 | cannot be used to initiate). | |
538 | <P> | |
539 | ||
540 | When <B>pluto</B> needs to install an eroute for an IPsec SA (for a | |
541 | state object), first the state object's connection must be routed (if | |
542 | this cannot be done, the eroute and SA will not be installed). | |
543 | If a conflicting eroute is already in place for another connection, | |
544 | the eroute and SA will not be installed (but note that the routing | |
545 | exception mentioned above may have already deleted potentially conflicting SAs). | |
546 | If another IPsec | |
547 | SA for the same connection already has an eroute, all its outgoing traffic | |
548 | is taken over by the new eroute. The incoming traffic will still be | |
549 | processed. This characteristic is exploited during rekeying. | |
550 | <P> | |
551 | ||
552 | All of these routing characteristics are expected change when | |
553 | <B>KLIPS</B> is modified to use the firewall hooks in the LINUX 2.4.x | |
554 | kernel. | |
555 | <A NAME="lbAL"> </A> | |
556 | <H3>Using Whack</H3> | |
557 | ||
558 | <P> | |
559 | ||
560 | <B>whack</B> is used to command a running <B>pluto</B>. | |
561 | <B>whack</B> uses a UNIX domain socket to speak to <B>pluto</B> | |
562 | (by default, <I>/var/pluto.ctl</I>). | |
563 | <P> | |
564 | ||
565 | <B>whack</B> has an intricate argument syntax. | |
566 | This syntax allows many different functions to be specified. | |
567 | The help form shows the usage or version information. | |
568 | The connection form gives <B>pluto</B> a description of a potential connection. | |
569 | The public key form informs <B>pluto</B> of the RSA public key for a potential peer. | |
570 | The delete form deletes a connection description and all SAs corresponding | |
571 | to it. | |
572 | The listen form tells <B>pluto</B> to start or stop listening on the public interfaces | |
573 | for IKE requests from peers. | |
574 | The route form tells <B>pluto</B> to set up routing for a connection; | |
575 | the unroute form undoes this. | |
576 | The initiate form tells <B>pluto</B> to negotiate an SA corresponding to a connection. | |
577 | The terminate form tells <B>pluto</B> to remove all SAs corresponding to a connection, | |
578 | including those being negotiated. | |
579 | The status form displays the <B>pluto</B>'s internal state. | |
580 | The debug form tells <B>pluto</B> to change the selection of debugging output | |
581 | ``on the fly''. The shutdown form tells | |
582 | <B>pluto</B> to shut down, deleting all SAs. | |
583 | <P> | |
584 | ||
585 | Most options are specific to one of the forms, and will be described | |
586 | with that form. There are three options that apply to all forms. | |
587 | <DL COMPACT> | |
588 | <DT><B>--ctlbase</B> <I>path</I><DD> | |
589 | <I>path</I>.ctl is used as the UNIX domain socket for talking | |
590 | to <B>pluto</B>. | |
591 | This option facilitates debugging. | |
592 | <DT><B>--optionsfrom</B> <I>filename</I><DD> | |
593 | adds the contents of the file to the argument list. | |
594 | <DT><B>--label</B> <I>string</I><DD> | |
595 | adds the string to all error messages generated by <B>whack</B>. | |
596 | </DL> | |
597 | <P> | |
598 | ||
599 | The help form of <B>whack</B> is self-explanatory. | |
600 | <DL COMPACT> | |
601 | <DT><B>--help</B><DD> | |
602 | display the usage message. | |
603 | <DT><B>--version</B><DD> | |
604 | display the version of <B>whack</B>. | |
605 | </DL> | |
606 | <P> | |
607 | ||
608 | The connection form describes a potential connection to <B>pluto</B>. | |
609 | <B>pluto</B> needs to know what connections can and should be negotiated. | |
610 | When <B>pluto</B> is the initiator, it needs to know what to propose. | |
611 | When <B>pluto</B> is the responder, it needs to know enough to decide whether | |
612 | is is willing to set up the proposed connection. | |
613 | <P> | |
614 | ||
615 | The description of a potential connection can specify a large number | |
616 | of details. Each connection has a unique name. This name will appear | |
617 | in a updown shell command, so it should not contain punctuation | |
618 | that would make the command ill-formed. | |
619 | <DL COMPACT> | |
620 | <DT><B>--name</B> <I>connection-name</I><DD> | |
621 | </DL> | |
622 | <P> | |
623 | ||
624 | The topology of | |
625 | a connection is symmetric, so to save space here is half a picture: | |
626 | <P> | |
627 | client_subnet<-->host:ikeport<-->nexthop<--- | |
628 | <P> | |
629 | A similar trick is used in the flags. The same flag names are used for | |
630 | both ends. Those before the <B>--to</B> flag describe the left side | |
631 | and those afterwards describe the right side. When <B>pluto</B> attempts | |
632 | to use the connection, it decides whether it is the left side or the right | |
633 | side of the connection, based on the IP numbers of its interfaces. | |
634 | <DL COMPACT> | |
635 | <DT><B>--id</B> <I>id</I><DD> | |
636 | the identity of the end. Currently, this can be an IP address (specified | |
637 | as dotted quad or as a Fully Qualified Domain Name, which will be resolved | |
638 | immediately) or as a Fully Qualified Domain Name itself (prefixed by ``@'' | |
639 | to signify that it should not be resolved), or as <A HREF="mailto:user@FQDN">user@FQDN</A>, or as the | |
640 | magic value <B>%myid</B>. | |
641 | <B>Pluto</B> only authenticates the identity, and does not use it for | |
642 | addressing, so, for example, an IP address need not be the one to which | |
643 | packets are to be sent. If the option is absent, the | |
644 | identity defaults to the IP address specified by <B>--host</B>. | |
645 | <B>%myid</B> allows the identity to be separately specified (by the <B>pluto</B> or <B>whack</B> option <B>--myid</B> | |
646 | or by the <B><A HREF="ipsec.conf.5.html">ipsec.conf</A></B>(5) <B>config setup</B> parameter myid). | |
647 | Otherwise, <B>pluto</B> tries to guess what <B>%myid</B> should stand for: | |
648 | the IP address of <B>%defaultroute</B>, if it is supported by a suitable TXT record in the reverse domain for that IP address, | |
649 | or the system's hostname, if it is supported by a suitable TXT record in its forward domain. | |
650 | ||
651 | <DT><B>--host</B> <I>ip-address</I><DD> | |
652 | <DT><B>--host</B> <B>%any</B><DD> | |
653 | <DT><B>--host</B> <B>%opportunistic</B><DD> | |
654 | the IP address of the end (generally the public interface). | |
655 | If <B>pluto</B> is to act as a responder | |
656 | for IKE negotiations initiated from unknown IP addresses (the | |
657 | ``Road Warrior'' case), the | |
658 | IP address should be specified as <B>%any</B> (currently, | |
659 | the obsolete notation <B>0.0.0.0</B> is also accepted for this). | |
660 | If <B>pluto</B> is to opportunistically initiate the connection, | |
661 | use <B>%opportunistic</B> | |
662 | <DT><B>--ikeport</B> <I>port-number</I><DD> | |
663 | the UDP port that IKE listens to on that host. The default is 500. | |
664 | (<B>pluto</B> on this machine uses the port specified by its own command | |
665 | line argument, so this only affects where <B>pluto</B> sends messages.) | |
666 | <DT><B>--nexthop</B> <I>ip-address</I><DD> | |
667 | where to route packets for the peer's client (presumably for the peer too, | |
668 | but it will not be used for this). | |
669 | When <B>pluto</B> installs an IPsec SA, it issues a route command. | |
670 | It uses the nexthop as the gateway. | |
671 | The default is the peer's IP address (this can be explicitly written as | |
672 | <B>%direct</B>; the obsolete notation <B>0.0.0.0</B> is accepted). | |
673 | This option is necessary if <B>pluto</B>'s host's interface used for sending | |
674 | packets to the peer is neither point-to-point nor directly connected to the | |
675 | peer. | |
676 | <DT><B>--client</B> <I>subnet</I><DD> | |
677 | the subnet for which the IPsec traffic will be destined. If not specified, | |
678 | the host will be the client. | |
679 | The subnet can be specified in any of the forms supported by <I><A HREF="ipsec_atosubnet.3.html">ipsec_atosubnet</A></I>(3). | |
680 | The general form is <I>address</I>/<I>mask</I>. The <I>address</I> can be either | |
681 | a domain name or four decimal numbers (specifying octets) separated by dots. | |
682 | The most convenient form of the <I>mask</I> is a decimal integer, specifying | |
683 | the number of leading one bits in the mask. So, for example, 10.0.0.0/8 | |
684 | would specify the class A network ``Net 10''. | |
685 | <DT><B>--dnskeyondemand]</B><DD> | |
686 | specifies that when an RSA public key is needed to authenticate this | |
687 | host, and it isn't already known, fetch it from DNS. | |
688 | <DT><B>--updown</B> <I>updown</I><DD> | |
689 | specifies an external shell command to be run whenever <B>pluto</B> | |
690 | brings up or down a connection. | |
691 | The script is used to build a shell command, so it may contain positional | |
692 | parameters, but ought not to have punctuation that would cause the | |
693 | resulting command to be ill-formed. | |
694 | The default is <I>ipsec _updown</I>. | |
695 | <DT><B>--to</B><DD> | |
696 | separates the specification of the left and right ends of the connection. | |
697 | </DL> | |
698 | <P> | |
699 | ||
700 | The potential connection description also specifies characteristics of | |
701 | rekeying and security. | |
702 | <DL COMPACT> | |
703 | <DT><B>--psk</B><DD> | |
704 | Propose and allow preshared secret authentication for IKE peers. This authentication | |
705 | requires that each side use the same secret. May be combined with <B>--rsasig</B>; | |
706 | at least one must be specified. | |
707 | <DT><B>--rsasig</B><DD> | |
708 | Propose and allow RSA signatures for authentication of IKE peers. This authentication | |
709 | requires that each side have have a private key of its own and know the | |
710 | public key of its peer. May be combined with <B>--psk</B>; | |
711 | at least one must be specified. | |
712 | <DT><B>--encrypt</B><DD> | |
713 | All proposed or accepted IPsec SAs will include non-null ESP. | |
714 | The actual choices of transforms are wired into <B>pluto</B>. | |
715 | <DT><B>--authenticate</B><DD> | |
716 | All proposed IPsec SAs will include AH. | |
717 | All accepted IPsec SAs will include AH or ESP with authentication. | |
718 | The actual choices of transforms are wired into <B>pluto</B>. | |
719 | Note that this has nothing to do with IKE authentication. | |
720 | <DT><B>--compress</B><DD> | |
721 | All proposed IPsec SAs will include IPCOMP (compression). | |
722 | This will be ignored if KLIPS is not configured with IPCOMP support. | |
723 | <DT><B>--tunnel</B><DD> | |
724 | the IPsec SA should use tunneling. Implicit if the SA is for clients. | |
725 | Must only be used with <B>--authenticate</B> or <B>--encrypt</B>. | |
726 | <DT><B>--ipv4</B><DD> | |
727 | The host addresses will be interpreted as IPv4 addresses. This is the | |
728 | default. Note that for a connection, all host addresses must be of | |
729 | the same Address Family (IPv4 and IPv6 use different Address Families). | |
730 | <DT><B>--ipv6</B><DD> | |
731 | The host addresses (including nexthop) will be interpreted as IPv6 addresses. | |
732 | Note that for a connection, all host addresses must be of | |
733 | the same Address Family (IPv4 and IPv6 use different Address Families). | |
734 | <DT><B>--tunnelipv4</B><DD> | |
735 | The client addresses will be interpreted as IPv4 addresses. The default is | |
736 | to match what the host will be. This does not imply <B>--tunnel</B> so the | |
737 | flag can be safely used when no tunnel is actually specified. | |
738 | Note that for a connection, all tunnel addresses must be of the same | |
739 | Address Family. | |
740 | <DT><B>--tunnelipv6</B><DD> | |
741 | The client addresses will be interpreted as IPv6 addresses. The default is | |
742 | to match what the host will be. This does not imply <B>--tunnel</B> so the | |
743 | flag can be safely used when no tunnel is actually specified. | |
744 | Note that for a connection, all tunnel addresses must be of the same | |
745 | Address Family. | |
746 | <DT><B>--pfs</B><DD> | |
747 | There should be Perfect Forward Secrecy - new keying material will | |
748 | be generated for each IPsec SA rather than being derived from the ISAKMP | |
749 | SA keying material. | |
750 | Since the group to be used cannot be negotiated (a dubious feature of the | |
751 | standard), <B>pluto</B> will propose the same group that was used during Phase 1. | |
752 | We don't implement a stronger form of PFS which would require that the | |
753 | ISAKMP SA be deleted after the IPSEC SA is negotiated. | |
754 | <DT><B>--disablearrivalcheck</B><DD> | |
755 | If the connection is a tunnel, allow packets arriving through the tunnel | |
756 | to have any source and destination addresses. | |
757 | </DL> | |
758 | <P> | |
759 | ||
760 | If none of the <B>--encrypt</B>, <B>--authenticate</B>, <B>--compress</B>, | |
761 | or <B>--pfs</B> flags is given, the initiating the connection will | |
762 | only build an ISAKMP SA. For such a connection, client subnets have | |
763 | no meaning and must not be specified. | |
764 | <P> | |
765 | ||
766 | More work is needed to allow for flexible policies. Currently | |
767 | policy is hardwired in the source file spdb.c. The ISAKMP SAs may use | |
768 | Oakley groups MODP1024 and MODP1536; 3DES encryption; SHA1-96 | |
769 | and MD5-96 authentication. The IPsec SAs may use 3DES and | |
770 | MD5-96 or SHA1-96 for ESP, or just MD5-96 or SHA1-96 for AH. | |
771 | IPCOMP Compression is always Deflate. | |
772 | <DL COMPACT> | |
773 | <DT><B>--ikelifetime</B> <I>seconds</I><DD> | |
774 | how long <B>pluto</B> will propose that an ISAKMP SA be allowed to live. | |
775 | The default is 3600 (one hour) and the maximum is 28800 (8 hours). | |
776 | This option will not affect what is accepted. | |
777 | <B>pluto</B> will reject proposals that exceed the maximum. | |
778 | <DT><B>--ipseclifetime</B> <I>seconds</I><DD> | |
779 | how long <B>pluto</B> will propose that an IPsec SA be allowed to live. | |
780 | The default is 28800 (eight hours) and the maximum is 86400 (one day). | |
781 | This option will not affect what is accepted. | |
782 | <B>pluto</B> will reject proposals that exceed the maximum. | |
783 | <DT><B>--rekeymargin</B> <I>seconds</I><DD> | |
784 | how long before an SA's expiration should <B>pluto</B> try to negotiate | |
785 | a replacement SA. This will only happen if <B>pluto</B> was the initiator. | |
786 | The default is 540 (nine minutes). | |
787 | <DT><B>--rekeyfuzz</B> <I>percentage</I><DD> | |
788 | maximum size of random component to add to rekeymargin, expressed as | |
789 | a percentage of rekeymargin. <B>pluto</B> will select a delay uniformly | |
790 | distributed within this range. By default, the percentage will be 100. | |
791 | If greater determinism is desired, specify 0. It may be appropriate | |
792 | for the percentage to be much larger than 100. | |
793 | <DT><B>--keyingtries</B> <I>count</I><DD> | |
794 | how many times <B>pluto</B> should try to negotiate an SA, | |
795 | either for the first time or for rekeying. | |
796 | A value of 0 is interpreted as a very large number: never give up. | |
797 | The default is three. | |
798 | <DT><B>--dontrekey</B><DD> | |
799 | A misnomer. | |
800 | Only rekey a connection if we were the Initiator and there was recent | |
801 | traffic on the existing connection. | |
802 | This applies to Phase 1 and Phase 2. | |
803 | This is currently the only automatic way for a connection to terminate. | |
804 | It may be useful with Road Warrior or Opportunistic connections. | |
805 | <BR> | |
806 | ||
807 | Since SA lifetime negotiation is take-it-or-leave it, a Responder | |
808 | normally uses the shorter of the negotiated or the configured lifetime. | |
809 | This only works because if the lifetime is shorter than negotiated, | |
810 | the Responder will rekey in time so that everything works. | |
811 | This interacts badly with <B>--dontrekey</B>. In this case, | |
812 | the Responder will end up rekeying to rectify a shortfall in an IPsec SA | |
813 | lifetime; for an ISAKMP SA, the Responder will accept the negotiated | |
814 | lifetime. | |
815 | <DT><B>--delete</B><DD> | |
816 | when used in the connection form, it causes any previous connection | |
817 | with this name to be deleted before this one is added. Unlike a | |
818 | normal delete, no diagnostic is produced if there was no previous | |
819 | connection to delete. Any routing in place for the connection is undone. | |
820 | </DL> | |
821 | <P> | |
822 | ||
823 | The delete form deletes a named connection description and any | |
824 | SAs established or negotiations initiated using this connection. | |
825 | Any routing in place for the connection is undone. | |
826 | <DL COMPACT> | |
827 | <DT><B>--delete</B><DD> | |
828 | <DT><B>--name</B> <I>connection-name</I><DD> | |
829 | </DL> | |
830 | <P> | |
831 | ||
832 | The deletestate form deletes the state object with the specified serial number. | |
833 | This is useful for selectively deleting instances of connections. | |
834 | <DL COMPACT> | |
835 | <DT><B>--deletestate</B> <I>state-number</I><DD> | |
836 | </DL> | |
837 | <P> | |
838 | ||
839 | The route form of the <B>whack</B> command tells <B>pluto</B> to set up | |
840 | routing for a connection. | |
841 | Although like a traditional route, it uses an ipsec device as a | |
842 | virtual interface. | |
843 | Once routing is set up, no packets will be | |
844 | sent ``in the clear'' to the peer's client specified in the connection. | |
845 | A TRAP shunt eroute will be installed; if outbound traffic is caught, | |
846 | Pluto will initiate the connection. | |
847 | An explicit <B>whack</B> route is not always needed: if it hasn't been | |
848 | done when an IPsec SA is being installed, one will be automatically attempted. | |
849 | <P> | |
850 | ||
851 | When a routing is attempted for a connection, there must not already | |
852 | be a routing for a different connection with the same subnet but different | |
853 | interface or destination, or if | |
854 | there is, it must not be being used by an IPsec SA. Otherwise the | |
855 | attempt will fail. | |
856 | <DL COMPACT> | |
857 | <DT><B>--route</B><DD> | |
858 | <DT><B>--name</B> <I>connection-name</I><DD> | |
859 | </DL> | |
860 | <P> | |
861 | ||
862 | The unroute form of the <B>whack</B> command tells <B>pluto</B> to undo | |
863 | a routing. <B>pluto</B> will refuse if an IPsec SA is using the connection. | |
864 | If another connection is sharing the same routing, it will be left in place. | |
865 | Without a routing, packets will be sent without encryption or authentication. | |
866 | <DL COMPACT> | |
867 | <DT><B>--unroute</B><DD> | |
868 | <DT><B>--name</B> <I>connection-name</I><DD> | |
869 | </DL> | |
870 | <P> | |
871 | ||
872 | The initiate form tells <B>pluto</B> to initiate a negotiation with another | |
873 | <B>pluto</B> (or other IKE daemon) according to the named connection. | |
874 | Initiation requires a route that <B>--route</B> would provide; | |
875 | if none is in place at the time an IPsec SA is being installed, | |
876 | <B>pluto</B> attempts to set one up. | |
877 | <DL COMPACT> | |
878 | <DT><B>--initiate</B><DD> | |
879 | <DT><B>--name</B> <I>connection-name</I><DD> | |
880 | <DT><B>--asynchronous<DD> | |
881 | </DL> | |
882 | <P> | |
883 | ||
884 | The initiate form of the whack</B> command will relay back from | |
885 | <B>pluto</B> status information via the UNIX domain socket (unless | |
886 | --asynchronous is specified). The status information is meant to | |
887 | look a bit like that from <B>FTP</B>. Currently <B>whack</B> simply | |
888 | copies this to stderr. When the request is finished (eg. the SAs are | |
889 | established or <B>pluto</B> gives up), <B>pluto</B> closes the channel, | |
890 | causing <B>whack</B> to terminate. | |
891 | <P> | |
892 | ||
893 | The opportunistic initiate form is mainly used for debugging. | |
894 | <DL COMPACT> | |
895 | <DT><B>--tunnelipv4</B><DD> | |
896 | <DT><B>--tunnelipv6</B><DD> | |
897 | <DT><B>--oppohere</B> <I>ip-address</I><DD> | |
898 | <DT><B>--oppothere</B> <I>ip-address</I><DD> | |
899 | </DL> | |
900 | <P> | |
901 | ||
902 | This will cause <B>pluto</B> to attempt to opportunistically initiate a | |
903 | connection from here to the there, even if a previous attempt | |
904 | had been made. | |
905 | The whack log will show the progress of this attempt. | |
906 | <P> | |
907 | ||
908 | The terminate form tells <B>pluto</B> to delete any SAs that use the specified | |
909 | connection and to stop any negotiations in process. | |
910 | It does not prevent new negotiations from starting (the delete form | |
911 | has this effect). | |
912 | <DL COMPACT> | |
913 | <DT><B>--terminate</B><DD> | |
914 | <DT><B>--name</B> <I>connection-name</I><DD> | |
915 | </DL> | |
916 | <P> | |
917 | ||
918 | The public key for informs <B>pluto</B> of the RSA public key for a potential peer. | |
919 | Private keys must be kept secret, so they are kept in | |
920 | <I><A HREF="ipsec.secrets.5.html">ipsec.secrets</A></I>(5). | |
921 | ||
922 | <DL COMPACT> | |
923 | <DT><B>--keyid </B><I>id</I><DD> | |
924 | specififies the identity of the peer for which a public key should be used. | |
925 | Its form is identical to the identity in the connection. | |
926 | If no public key is specified, <B>pluto</B> attempts to find KEY records | |
927 | from DNS for the id (if a FQDN) or through reverse lookup (if an IP address). | |
928 | Note that there several interesting ways in which this is not secure. | |
929 | <DT><B>--addkey</B><DD> | |
930 | specifies that the new key is added to the collection; otherwise the | |
931 | new key replaces any old ones. | |
932 | <DT><B>--pubkeyrsa </B><I>key</I><DD> | |
933 | specifies the value of the RSA public key. It is a sequence of bytes | |
934 | as described in RFC 2537 ``RSA/MD5 KEYs and SIGs in the Domain Name System (DNS)''. | |
935 | It is denoted in a way suitable for <I><A HREF="ipsec_ttodata.3.html">ipsec_ttodata</A></I>(3). | |
936 | For example, a base 64 numeral starts with 0s. | |
937 | </DL> | |
938 | <P> | |
939 | ||
940 | The listen form tells <B>pluto</B> to start listening for IKE requests | |
941 | on its public interfaces. To avoid race conditions, it is normal to | |
942 | load the appropriate connections into <B>pluto</B> before allowing it | |
943 | to listen. If <B>pluto</B> isn't listening, it is pointless to | |
944 | initiate negotiations, so it will refuse requests to do so. Whenever | |
945 | the listen form is used, <B>pluto</B> looks for public interfaces and | |
946 | will notice when new ones have been added and when old ones have been | |
947 | removed. This is also the trigger for <B>pluto</B> to read the | |
948 | <I>ipsec.secrets</I> file. So listen may useful more than once. | |
949 | <DL COMPACT> | |
950 | <DT><B>--listen</B><DD> | |
951 | start listening for IKE traffic on public interfaces. | |
952 | <DT><B>--unlisten</B><DD> | |
953 | stop listening for IKE traffic on public interfaces. | |
954 | </DL> | |
955 | <P> | |
956 | ||
957 | The status form will display information about the internal state of | |
958 | <B>pluto</B>: information about each potential connection, about | |
959 | each state object, and about each shunt that <B>pluto</B> is managing | |
960 | without an associated connection. | |
961 | <DL COMPACT> | |
962 | <DT><B>--status</B><DD> | |
963 | </DL> | |
964 | <P> | |
965 | ||
966 | The shutdown form is the proper way to shut down <B>pluto</B>. | |
967 | It will tear down the SAs on this machine that <B>pluto</B> has negotiated. | |
968 | It does not inform its peers, so the SAs on their machines remain. | |
969 | <DL COMPACT> | |
970 | <DT><B>--shutdown</B><DD> | |
971 | </DL> | |
972 | <A NAME="lbAM"> </A> | |
973 | <H3>Examples</H3> | |
974 | ||
975 | <P> | |
976 | ||
977 | It would be normal to start <B>pluto</B> in one of the system initialization | |
978 | scripts. It needs to be run by the superuser. Generally, no arguments are needed. | |
979 | To run in manually, the superuser can simply type | |
980 | <P> | |
981 | ipsec pluto | |
982 | <P> | |
983 | The command will immediately return, but a <B>pluto</B> process will be left | |
984 | running, waiting for requests from <B>whack</B> or a peer. | |
985 | <P> | |
986 | ||
987 | Using <B>whack</B>, several potential connections would be described: | |
988 | <DL COMPACT> | |
989 | <DT> | |
990 | ||
991 | ipsec whack --name silly | |
992 | --host 127.0.0.1 --to --host 127.0.0.2 | |
993 | --ikelifetime 900 --ipseclifetime 800 --keyingtries 3 | |
994 | ||
995 | </DL> | |
996 | <P> | |
997 | ||
998 | <DD>Since this silly connection description specifies neither encryption, | |
999 | authentication, nor tunneling, it could only be used to establish | |
1000 | an ISAKMP SA. | |
1001 | <DL COMPACT> | |
1002 | <DT> | |
1003 | ||
1004 | ipsec whack --name secret --host 10.0.0.1 --client 10.0.1.0/24 | |
1005 | --to --host 10.0.0.2 --client 10.0.2.0/24 | |
1006 | --encrypt | |
1007 | ||
1008 | </DL> | |
1009 | <P> | |
1010 | ||
1011 | <DD>This is something that must be done on both sides. If the other | |
1012 | side is <B>pluto</B>, the same <B>whack</B> command could be used on it | |
1013 | (the command syntax is designed to not distinguish which end is ours). | |
1014 | <P> | |
1015 | ||
1016 | Now that the connections are specified, <B>pluto</B> is ready to handle | |
1017 | requests and replies via the public interfaces. We must tell it to discover | |
1018 | those interfaces and start accepting messages from peers: | |
1019 | <P> | |
1020 | ipsec whack --listen | |
1021 | <P> | |
1022 | ||
1023 | If we don't immediately wish to bring up a secure connection between | |
1024 | the two clients, we might wish to prevent insecure traffic. | |
1025 | The routing form asks <B>pluto</B> to cause the packets sent from | |
1026 | our client to the peer's client to be routed through the ipsec0 | |
1027 | device; if there is no SA, they will be discarded: | |
1028 | <P> | |
1029 | ipsec whack --route secret | |
1030 | <P> | |
1031 | ||
1032 | Finally, we are ready to get <B>pluto</B> to initiate negotiation | |
1033 | for an IPsec SA (and implicitly, an ISAKMP SA): | |
1034 | <P> | |
1035 | ipsec whack --initiate --name secret | |
1036 | <P> | |
1037 | A small log of interesting events will appear on standard output | |
1038 | (other logging is sent to syslog). | |
1039 | <P> | |
1040 | ||
1041 | <B>whack</B> can also be used to terminate <B>pluto</B> cleanly, tearing down | |
1042 | all SAs that it has negotiated. | |
1043 | <P> | |
1044 | ipsec whack --shutdown | |
1045 | <P> | |
1046 | Notification of any IPSEC SA deletion, but not ISAKMP SA deletion | |
1047 | is sent to the peer. Unfortunately, such Notification is not reliable. | |
1048 | Furthermore, <B>pluto</B> itself ignores Notifications. | |
1049 | <A NAME="lbAN"> </A> | |
1050 | <H3>The updown command</H3> | |
1051 | ||
1052 | <P> | |
1053 | ||
1054 | Whenever <B>pluto</B> brings a connection up or down, it invokes | |
1055 | the updown command. This command is specified using the <B>--updown</B> | |
1056 | option. This allows for customized control over routing and firewall manipulation. | |
1057 | <P> | |
1058 | ||
1059 | The updown is invoked for five different operations. Each of | |
1060 | these operations can be for our client subnet or for our host itself. | |
1061 | <DL COMPACT> | |
1062 | <DT><B>prepare-host</B> or <B>prepare-client</B><DD> | |
1063 | is run before bringing up a new connection if no other connection | |
1064 | with the same clients is up. Generally, this is useful for deleting a | |
1065 | route that might have been set up before <B>pluto</B> was run or | |
1066 | perhaps by some agent not known to <B>pluto</B>. | |
1067 | <DT><B>route-host</B> or <B>route-client</B><DD> | |
1068 | is run when bringing up a connection for a new peer client subnet | |
1069 | (even if <B>prepare-host</B> or <B>prepare-client</B> was run). The | |
1070 | command should install a suitable route. Routing decisions are based | |
1071 | only on the destination (peer's client) subnet address, unlike eroutes | |
1072 | which discriminate based on source too. | |
1073 | <DT><B>unroute-host</B> or <B>unroute-client</B><DD> | |
1074 | is run when bringing down the last connection for a particular peer | |
1075 | client subnet. It should undo what the <B>route-host</B> or <B>route-client</B> | |
1076 | did. | |
1077 | <DT><B>up-host</B> or <B>up-client</B><DD> | |
1078 | is run when bringing up a tunnel eroute with a pair of client subnets | |
1079 | that does not already have a tunnel eroute. | |
1080 | This command should install firewall rules as appropriate. | |
1081 | It is generally a good idea to allow IKE messages (UDP port 500) | |
1082 | travel between the hosts. | |
1083 | <DT><B>down-host</B> or <B>down-client</B><DD> | |
1084 | is run when bringing down the eroute for a pair of client subnets. | |
1085 | This command should delete firewall rules as appropriate. Note that | |
1086 | there may remain some inbound IPsec SAs with these client subnets. | |
1087 | </DL> | |
1088 | <P> | |
1089 | ||
1090 | The script is passed a large number of environment variables to specify | |
1091 | what needs to be done. | |
1092 | <DL COMPACT> | |
1093 | <DT><B>PLUTO_VERSION</B><DD> | |
1094 | indicates what version of this interface is being used. This document | |
1095 | describes version 1.1. This is upwardly compatible with version 1.0. | |
1096 | <DT><B>PLUTO_VERB</B><DD> | |
1097 | specifies the name of the operation to be performed | |
1098 | (<B>prepare-host</B>,r <B>prepare-client</B>, | |
1099 | <B>up-host</B>, <B>up-client</B>, | |
1100 | <B>down-host</B>, or <B>down-client</B>). If the address family for | |
1101 | security gateway to security gateway communications is IPv6, then | |
1102 | a suffix of -v6 is added to the verb. | |
1103 | <DT><B>PLUTO_CONNECTION</B><DD> | |
1104 | is the name of the connection for which we are routing. | |
1105 | <DT><B>PLUTO_NEXT_HOP</B><DD> | |
1106 | is the next hop to which packets bound for the peer must be sent. | |
1107 | <DT><B>PLUTO_INTERFACE</B><DD> | |
1108 | is the name of the ipsec interface to be used. | |
1109 | <DT><B>PLUTO_ME</B><DD> | |
1110 | is the IP address of our host. | |
1111 | <DT><B>PLUTO_MY_CLIENT</B><DD> | |
1112 | is the IP address / count of our client subnet. | |
1113 | If the client is just the host, this will be the host's own IP address / max | |
1114 | (where max is 32 for IPv4 and 128 for IPv6). | |
1115 | <DT><B>PLUTO_MY_CLIENT_NET</B><DD> | |
1116 | is the IP address of our client net. | |
1117 | If the client is just the host, this will be the host's own IP address. | |
1118 | <DT><B>PLUTO_MY_CLIENT_MASK</B><DD> | |
1119 | is the mask for our client net. | |
1120 | If the client is just the host, this will be 255.255.255.255. | |
1121 | <DT><B>PLUTO_PEER</B><DD> | |
1122 | is the IP address of our peer. | |
1123 | <DT><B>PLUTO_PEER_CLIENT</B><DD> | |
1124 | is the IP address / count of the peer's client subnet. | |
1125 | If the client is just the peer, this will be the peer's own IP address / max | |
1126 | (where max is 32 for IPv4 and 128 for IPv6). | |
1127 | <DT><B>PLUTO_PEER_CLIENT_NET</B><DD> | |
1128 | is the IP address of the peer's client net. | |
1129 | If the client is just the peer, this will be the peer's own IP address. | |
1130 | <DT><B>PLUTO_PEER_CLIENT_MASK</B><DD> | |
1131 | is the mask for the peer's client net. | |
1132 | If the client is just the peer, this will be 255.255.255.255. | |
1133 | </DL> | |
1134 | <P> | |
1135 | ||
1136 | All output sent by the script to stderr or stdout is logged. The | |
1137 | script should return an exit status of 0 if and only if it succeeds. | |
1138 | <P> | |
1139 | ||
1140 | <B>Pluto</B> waits for the script to finish and will not do any other | |
1141 | processing while it is waiting. | |
1142 | The script may assume that <B>pluto</B> will not change anything | |
1143 | while the script runs. | |
1144 | The script should avoid doing anything that takes much time and it | |
1145 | should not issue any command that requires processing by <B>pluto</B>. | |
1146 | Either of these activities could be performed by a background | |
1147 | subprocess of the script. | |
1148 | <A NAME="lbAO"> </A> | |
1149 | <H3>Rekeying</H3> | |
1150 | ||
1151 | <P> | |
1152 | ||
1153 | When an SA that was initiated by <B>pluto</B> has only a bit of | |
1154 | lifetime left, | |
1155 | <B>pluto</B> will initiate the creation of a new SA. This applies to | |
1156 | ISAKMP and IPsec SAs. | |
1157 | The rekeying will be initiated when the SA's remaining lifetime is | |
1158 | less than the rekeymargin plus a random percentage, between 0 and | |
1159 | rekeyfuzz, of the rekeymargin. | |
1160 | <P> | |
1161 | ||
1162 | Similarly, when an SA that was initiated by the peer has only a bit of | |
1163 | lifetime left, <B>pluto</B> will try to initiate the creation of a | |
1164 | replacement. | |
1165 | To give preference to the initiator, this rekeying will only be initiated | |
1166 | when the SA's remaining lifetime is half of rekeymargin. | |
1167 | If rekeying is done by the responder, the roles will be reversed: the | |
1168 | responder for the old SA will be the initiator for the replacement. | |
1169 | The former initiator might also initiate rekeying, so there may | |
1170 | be redundant SAs created. | |
1171 | To avoid these complications, make sure that rekeymargin is generous. | |
1172 | <P> | |
1173 | ||
1174 | One risk of having the former responder initiate is that perhaps | |
1175 | none of its proposals is acceptable to the former initiator | |
1176 | (they have not been used in a successful negotiation). | |
1177 | To reduce the chances of this happening, and to prevent loss of security, | |
1178 | the policy settings are taken from the old SA (this is the case even if | |
1179 | the former initiator is initiating). | |
1180 | These may be stricter than those of the connection. | |
1181 | <P> | |
1182 | ||
1183 | <B>pluto</B> will not rekey an SA if that SA is not the most recent of its | |
1184 | type (IPsec or ISAKMP) for its potential connection. | |
1185 | This avoids creating redundant SAs. | |
1186 | <P> | |
1187 | ||
1188 | The random component in the rekeying time (rekeyfuzz) is intended to | |
1189 | make certain pathological patterns of rekeying unstable. If both | |
1190 | sides decide to rekey at the same time, twice as many SAs as necessary | |
1191 | are created. This could become a stable pattern without the | |
1192 | randomness. | |
1193 | <P> | |
1194 | ||
1195 | Another more important case occurs when a security gateway has SAs | |
1196 | with many other security gateways. Each of these connections might | |
1197 | need to be rekeyed at the same time. This would cause a high peek | |
1198 | requirement for resources (network bandwidth, CPU time, entropy for | |
1199 | random numbers). The rekeyfuzz can be used to stagger the rekeying | |
1200 | times. | |
1201 | <P> | |
1202 | ||
1203 | Once a new set of SAs has been negotiated, <B>pluto</B> will never send | |
1204 | traffic on a superseded one. Traffic will be accepted on an old SA | |
1205 | until it expires. | |
1206 | <A NAME="lbAP"> </A> | |
1207 | <H3>Selecting a Connection When Responding: Road Warrior Support</H3> | |
1208 | ||
1209 | <P> | |
1210 | ||
1211 | When <B>pluto</B> receives an initial Main Mode message, it needs to | |
1212 | decide which connection this message is for. It picks based solely on | |
1213 | the source and destination IP addresses of the message. There might | |
1214 | be several connections with suitable IP addresses, in which case one | |
1215 | of them is arbitrarily chosen. (The ISAKMP SA proposal contained in | |
1216 | the message could be taken into account, but it is not.) | |
1217 | <P> | |
1218 | ||
1219 | The ISAKMP SA is negotiated before the parties pass further | |
1220 | identifying information, so all ISAKMP SA characteristics specified in | |
1221 | the connection description should be the same for every connection | |
1222 | with the same two host IP addresses. At the moment, the only | |
1223 | characteristic that might differ is authentication method. | |
1224 | <P> | |
1225 | ||
1226 | Up to this point, | |
1227 | all configuring has presumed that the IP addresses | |
1228 | are known to all parties ahead of time. This will not work | |
1229 | when either end is mobile (or assigned a dynamic IP address for other | |
1230 | reasons). We call this situation ``Road Warrior''. It is fairly tricky | |
1231 | and has some important limitations, most of which are features of | |
1232 | the IKE protocol. | |
1233 | <P> | |
1234 | ||
1235 | Only the initiator may be mobile: | |
1236 | the initiator may have an IP number unknown to the responder. When | |
1237 | the responder doesn't recognize the IP address on the first Main Mode | |
1238 | packet, it looks for a connection with itself as one end and <B>%any</B> | |
1239 | as the other. | |
1240 | If it cannot find one, it refuses to negotiate. If it | |
1241 | does find one, it creates a temporary connection that is a duplicate | |
1242 | except with the <B>%any</B> replaced by the source IP address from the | |
1243 | packet; if there was no identity specified for the peer, the new IP | |
1244 | address will be used. | |
1245 | <P> | |
1246 | ||
1247 | When <B>pluto</B> is using one of these temporary connections and | |
1248 | needs to find the preshared secret or RSA private key in <I>ipsec.secrets</I>, | |
1249 | and and the connection specified no identity for the peer, <B>%any</B> | |
1250 | is used as its identity. After all, the real IP address was apparently | |
1251 | unknown to the configuration, so it is unreasonable to require that | |
1252 | it be used in this table. | |
1253 | <P> | |
1254 | ||
1255 | Part way into the Phase 1 (Main Mode) negotiation using one of these | |
1256 | temporary connection descriptions, <B>pluto</B> will be receive an | |
1257 | Identity Payload. At this point, <B>pluto</B> checks for a more | |
1258 | appropriate connection, one with an identity for the peer that matches | |
1259 | the payload but which would use the same keys so-far used for | |
1260 | authentication. If it finds one, it will switch to using this better | |
1261 | connection (or a temporary derived from this, if it has <B>%any</B> | |
1262 | for the peer's IP address). It may even turn out that no connection | |
1263 | matches the newly discovered identity, including the current connection; | |
1264 | if so, <B>pluto</B> terminates negotiation. | |
1265 | <P> | |
1266 | ||
1267 | Unfortunately, if preshared secret authentication is being used, the | |
1268 | Identity Payload is encrypted using this secret, so the secret must be | |
1269 | selected by the responder without knowing this payload. This | |
1270 | limits there to being at most one preshared secret for all Road Warrior | |
1271 | systems connecting to a host. RSA Signature authentications does not | |
1272 | require that the responder know how to select the initiator's public key | |
1273 | until after the initiator's Identity Payload is decoded (using the | |
1274 | responder's private key, so that must be preselected). | |
1275 | <P> | |
1276 | ||
1277 | When <B>pluto</B> is responding to a Quick Mode negotiation via one of these | |
1278 | temporary connection descriptions, it may well find that the subnets | |
1279 | specified by the initiator don't match those in the temporary | |
1280 | connection description. If so, it will look for a connection with | |
1281 | matching subnets, its own host address, a peer address of <B>%any</B> | |
1282 | and matching identities. | |
1283 | If it finds one, a new temporary connection is derived from this one | |
1284 | and used for the Quick Mode negotiation of IPsec SAs. If it does not | |
1285 | find one, <B>pluto</B> terminates negotiation. | |
1286 | <P> | |
1287 | ||
1288 | Be sure to specify an appropriate nexthop for the responder | |
1289 | to send a message to the initiator: <B>pluto</B> has no way of guessing | |
1290 | it (if forwarding isn't required, use an explicit <B>%direct</B> as the nexthop | |
1291 | and the IP address of the initiator will be filled in; the obsolete | |
1292 | notation <B>0.0.0.0</B> is still accepted). | |
1293 | <P> | |
1294 | ||
1295 | <B>pluto</B> has no special provision for the initiator side. The current | |
1296 | (possibly dynamic) IP address and nexthop must be used in defining | |
1297 | connections. These must be | |
1298 | properly configured each time the initiator's IP address changes. | |
1299 | <B>pluto</B> has no mechanism to do this automatically. | |
1300 | <P> | |
1301 | ||
1302 | Although we call this Road Warrior Support, it could also be used to | |
1303 | support encrypted connections with anonymous initiators. The | |
1304 | responder's organization could announce the preshared secret that would be used | |
1305 | with unrecognized initiators and let anyone connect. Of course the initiator's | |
1306 | identity would not be authenticated. | |
1307 | <P> | |
1308 | ||
1309 | If any Road Warrior connections are supported, <B>pluto</B> cannot | |
1310 | reject an exchange initiated by an unknown host until it has | |
1311 | determined that the secret is not shared or the signature is invalid. | |
1312 | This must await the | |
1313 | third Main Mode message from the initiator. If no Road Warrior | |
1314 | connection is supported, the first message from an unknown source | |
1315 | would be rejected. This has implications for ease of debugging | |
1316 | configurations and for denial of service attacks. | |
1317 | <P> | |
1318 | ||
1319 | Although a Road Warrior connection must be initiated by the mobile | |
1320 | side, the other side can and will rekey using the temporary connection | |
1321 | it has created. If the Road Warrior wishes to be able to disconnect, | |
1322 | it is probably wise to set <B>--keyingtries</B> to 1 in the | |
1323 | connection on the non-mobile side to prevent it trying to rekey the | |
1324 | connection. Unfortunately, there is no mechanism to unroute the | |
1325 | connection automatically. | |
1326 | <A NAME="lbAQ"> </A> | |
1327 | <H3>Debugging</H3> | |
1328 | ||
1329 | <P> | |
1330 | ||
1331 | <B>pluto</B> accepts several optional arguments, useful mostly for debugging. | |
1332 | Except for <B>--interface</B>, each should appear at most once. | |
1333 | <DL COMPACT> | |
1334 | <DT><B>--interface</B> <I>interfacename</I><DD> | |
1335 | specifies that the named real public network interface should be considered. | |
1336 | The interface name specified should not be <B>ipsec</B><I>N</I>. | |
1337 | If the option doesn't appear, all interfaces are considered. | |
1338 | To specify several interfaces, use the option once for each. | |
1339 | One use of this option is to specify which interface should be used | |
1340 | when two or more share the same IP address. | |
1341 | <DT><B>--ikeport</B> <I>port-number</I><DD> | |
1342 | changes the UDP port that <B>pluto</B> will use | |
1343 | (default, specified by IANA: 500) | |
1344 | <DT><B>--ctlbase</B> <I>path</I><DD> | |
1345 | basename for control files. | |
1346 | <I>path</I>.ctl is the socket through which <B>whack</B> communicates with | |
1347 | <B>pluto</B>. | |
1348 | <I>path</I>.pid is the lockfile to prevent multiple <B>pluto</B> instances. | |
1349 | The default is <I>/var/run/pluto</I>). | |
1350 | <DT><B>--secretsfile</B> <I>file</I><DD> | |
1351 | specifies the file for authentication secrets | |
1352 | (default: <I>/etc/ipsec.secrets</I>). | |
1353 | This name is subject to ``globbing'' as in <I><A HREF="sh.1.html">sh</A></I>(1), | |
1354 | so every file with a matching name is processed. | |
1355 | Quoting is generally needed to prevent the shell from doing the globbing. | |
1356 | <DT><B>--adns</B> <I>pathname</I><DD> | |
1357 | <DT><B>--lwdnsq</B> <I>pathname</I><DD> | |
1358 | specifies where to find <B>pluto</B>'s helper program for asynchronous DNS lookup. | |
1359 | <B>pluto</B> can be built to use one of two helper programs: <B>_pluto_adns</B> | |
1360 | or <B>lwdnsq</B>. You must use the program for which it was built. | |
1361 | By default, <B>pluto</B> will look for the program in | |
1362 | <B>$IPSEC_DIR</B> (if that environment variable is defined) or, failing that, | |
1363 | in the same directory as <B>pluto</B>. | |
1364 | <DT><B>--nofork</B><DD> | |
1365 | disable ``daemon fork'' (default is to fork). In addition, after the | |
1366 | lock file and control socket are created, print the line ``Pluto | |
1367 | initialized'' to standard out. | |
1368 | <DT><B>--noklips</B><DD> | |
1369 | don't actually implement negotiated IPsec SAs | |
1370 | <DT><B>--uniqueids</B><DD> | |
1371 | if this option has been selected, whenever a new ISAKMP SA is | |
1372 | established, any connection with the same Peer ID but a different | |
1373 | Peer IP address is unoriented (causing all its SAs to be deleted). | |
1374 | This helps clean up dangling SAs when a connection is lost and | |
1375 | then regained at another IP address. | |
1376 | <DT><B>--stderrlog</B><DD> | |
1377 | log goes to standard out {default is to use <I><A HREF="syslogd.8.html">syslogd</A></I>(8)) | |
1378 | </DL> | |
1379 | <P> | |
1380 | ||
1381 | For example | |
1382 | <DL COMPACT> | |
1383 | <DT>pluto --secretsfile ipsec.secrets --ctlbase pluto.base --ikeport 8500 --nofork --noklips --stderrlog<DD> | |
1384 | </DL> | |
1385 | <P> | |
1386 | ||
1387 | lets one test <B>pluto</B> without using the superuser account. | |
1388 | <P> | |
1389 | ||
1390 | <B>pluto</B> is willing to produce a prodigious amount of debugging | |
1391 | information. To do so, it must be compiled with -DDEBUG. There are | |
1392 | several classes of debugging output, and <B>pluto</B> may be directed to | |
1393 | produce a selection of them. All lines of | |
1394 | debugging output are prefixed with ``| '' to distinguish them from error | |
1395 | messages. | |
1396 | <P> | |
1397 | ||
1398 | When <B>pluto</B> is invoked, it may be given arguments to specify | |
1399 | which classes to output. The current options are: | |
1400 | <DL COMPACT> | |
1401 | <DT><B>--debug-raw</B><DD> | |
1402 | show the raw bytes of messages | |
1403 | <DT><B>--debug-crypt</B><DD> | |
1404 | show the encryption and decryption of messages | |
1405 | <DT><B>--debug-parsing</B><DD> | |
1406 | show the structure of input messages | |
1407 | <DT><B>--debug-emitting</B><DD> | |
1408 | show the structure of output messages | |
1409 | <DT><B>--debug-control</B><DD> | |
1410 | show <B>pluto</B>'s decision making | |
1411 | <DT><B>--debug-lifecycle</B><DD> | |
1412 | [this option is temporary] log more detail of lifecycle of SAs | |
1413 | <DT><B>--debug-klips</B><DD> | |
1414 | show <B>pluto</B>'s interaction with <B>KLIPS</B> | |
1415 | <DT><B>--debug-dns</B><DD> | |
1416 | show <B>pluto</B>'s interaction with <B>DNS</B> for KEY and TXT records | |
1417 | <DT><B>--debug-oppo</B><DD> | |
1418 | show why <B>pluto</B> didn't find a suitable DNS TXT record to authorize opportunistic initiation | |
1419 | <DT><B>--debug-all</B><DD> | |
1420 | all of the above | |
1421 | <DT><B>--debug-private</B><DD> | |
1422 | allow debugging output with private keys. | |
1423 | <DT><B>--debug-none</B><DD> | |
1424 | none of the above | |
1425 | </DL> | |
1426 | <P> | |
1427 | ||
1428 | The debug form of the | |
1429 | <B>whack</B> command will change the selection in a running | |
1430 | <B>pluto</B>. | |
1431 | If a connection name is specified, the flags are added whenever | |
1432 | <B>pluto</B> has identified that it is dealing with that connection. | |
1433 | Unfortunately, this is often part way into the operation being observed. | |
1434 | <P> | |
1435 | ||
1436 | For example, to start a <B>pluto</B> with a display of the structure of input | |
1437 | and output: | |
1438 | <DL COMPACT> | |
1439 | <DT><DD> | |
1440 | pluto --debug-emitting --debug-parsing | |
1441 | </DL> | |
1442 | <P> | |
1443 | ||
1444 | To later change this <B>pluto</B> to only display raw bytes: | |
1445 | <DL COMPACT> | |
1446 | <DT><DD> | |
1447 | whack --debug-raw | |
1448 | </DL> | |
1449 | <P> | |
1450 | ||
1451 | For testing, SSH's IKE test page is quite useful: | |
1452 | <DL COMPACT> | |
1453 | <DT><DD> | |
1454 | <I><A HREF="http://isakmp-test.ssh.fi/">http://isakmp-test.ssh.fi/</A></I> | |
1455 | </DL> | |
1456 | <P> | |
1457 | ||
1458 | Hint: ISAKMP SAs are often kept alive by IKEs even after the IPsec SA | |
1459 | is established. This allows future IPsec SA's to be negotiated | |
1460 | directly. If one of the IKEs is restarted, the other may try to use | |
1461 | the ISAKMP SA but the new IKE won't know about it. This can lead to | |
1462 | much confusion. <B>pluto</B> is not yet smart enough to get out of such a | |
1463 | mess. | |
1464 | <A NAME="lbAR"> </A> | |
1465 | <H3>Pluto's Behaviour When Things Go Wrong</H3> | |
1466 | ||
1467 | <P> | |
1468 | ||
1469 | When <B>pluto</B> doesn't understand or accept a message, it just | |
1470 | ignores the message. It is not yet capable of communicating the | |
1471 | problem to the other IKE daemon (in the future it might use | |
1472 | Notifications to accomplish this in many cases). It does log a diagnostic. | |
1473 | <P> | |
1474 | ||
1475 | When <B>pluto</B> gets no response from a message, it resends the same | |
1476 | message (a message will be sent at most three times). This is | |
1477 | appropriate: UDP is unreliable. | |
1478 | <P> | |
1479 | ||
1480 | When pluto gets a message that it has already seen, there are many | |
1481 | cases when it notices and discards it. This too is appropriate for UDP. | |
1482 | <P> | |
1483 | ||
1484 | Combine these three rules, and you can explain many apparently | |
1485 | mysterious behaviours. In a <B>pluto</B> log, retrying isn't usually the | |
1486 | interesting event. The critical thing is either earlier (<B>pluto</B> | |
1487 | got a message which it didn't like and so ignored, so it was still | |
1488 | awaiting an acceptable message and got impatient) or on the other | |
1489 | system (<B>pluto</B> didn't send a reply because it wasn't happy with | |
1490 | the previous message). | |
1491 | <A NAME="lbAS"> </A> | |
1492 | <H3>Notes</H3> | |
1493 | ||
1494 | <P> | |
1495 | ||
1496 | If <B>pluto</B> is compiled without -DKLIPS, it negotiates Security | |
1497 | Associations but never ask the kernel to put them in place and never | |
1498 | makes routing changes. This allows <B>pluto</B> to be tested on systems | |
1499 | without <B>KLIPS</B>, but makes it rather useless. | |
1500 | <P> | |
1501 | ||
1502 | Each IPsec SA is assigned an SPI, a 32-bit number used to refer to the SA. | |
1503 | The IKE protocol lets the destination of the SA choose the SPI. | |
1504 | The range 0 to 0xFF is reserved for IANA. | |
1505 | <B>Pluto</B> also avoids choosing an SPI in the range 0x100 to 0xFFF, | |
1506 | leaving these SPIs free for manual keying. | |
1507 | Remember that the peer, if not <B>pluto</B>, may well chose | |
1508 | SPIs in this range. | |
1509 | <A NAME="lbAT"> </A> | |
1510 | <H3>Policies</H3> | |
1511 | ||
1512 | <P> | |
1513 | ||
1514 | This catalogue of policies may be of use when trying to configure | |
1515 | <B>Pluto</B> and another IKE implementation to interoperate. | |
1516 | <P> | |
1517 | ||
1518 | In Phase 1, only Main Mode is supported. We are not sure that | |
1519 | Aggressive Mode is secure. For one thing, it does not support | |
1520 | identity protection. It may allow more severe Denial Of Service | |
1521 | attacks. | |
1522 | <P> | |
1523 | ||
1524 | No Informational Exchanges are supported. These are optional and | |
1525 | since their delivery is not assured, they must not matter. | |
1526 | It is the case that some IKE implementations won't interoperate | |
1527 | without Informational Exchanges, but we feel they are broken. | |
1528 | <P> | |
1529 | ||
1530 | No Informational Payloads are supported. These are optional, but | |
1531 | useful. It is of concern that these payloads are not authenticated in | |
1532 | Phase 1, nor in those Phase 2 messages authenticated with <A HREF="HASH.3.html">HASH</A>(3). | |
1533 | <DL COMPACT> | |
1534 | <DT>*<DD> | |
1535 | Diffie Hellman Groups MODP 1024 and MODP 1536 (2 and 5) | |
1536 | are supported. | |
1537 | Group MODP768 (1) is not supported because it is too weak. | |
1538 | <DT>*<DD> | |
1539 | Host authetication can be done by RSA Signatures or Pre-Shared | |
1540 | Secrets. | |
1541 | <DT>*<DD> | |
1542 | 3DES CBC (Cypher Block Chaining mode) is the only encryption | |
1543 | supported, both for ISAKMP SAs and IPSEC SAs. | |
1544 | <DT>*<DD> | |
1545 | MD5 and SHA1 hashing are supported for packet authentication in both | |
1546 | kinds of SAs. | |
1547 | <DT>*<DD> | |
1548 | The ESP, AH, or AH plus ESP are supported. If, and only if, AH and | |
1549 | ESP are combined, the ESP need not have its own authentication | |
1550 | component. The selection is controlled by the --encrypt and | |
1551 | --authenticate flags. | |
1552 | <DT>*<DD> | |
1553 | Each of these may be combined with IPCOMP Deflate compression, | |
1554 | but only if the potential connection specifies compression and only | |
1555 | if KLIPS is configured with IPCOMP support. | |
1556 | <DT>*<DD> | |
1557 | The IPSEC SAs may be tunnel or transport mode, where appropriate. | |
1558 | The --tunnel flag controls this when <B>pluto</B> is initiating. | |
1559 | <DT>*<DD> | |
1560 | When responding to an ISAKMP SA proposal, the maximum acceptable | |
1561 | lifetime is eight hours. The default is one hour. There is no | |
1562 | minimum. The --ikelifetime flag controls this when <B>pluto</B> | |
1563 | is initiating. | |
1564 | <DT>*<DD> | |
1565 | When responding to an IPSEC SA proposal, the maximum acceptable | |
1566 | lifetime is one day. The default is eight hours. There is no | |
1567 | minimum. The --ipseclifetime flag controls this when <B>pluto</B> | |
1568 | is initiating. | |
1569 | <DT>*<DD> | |
1570 | PFS is acceptable, and will be proposed if the --pfs flag was | |
1571 | specified. The DH group proposed will be the same as negotiated for | |
1572 | Phase 1. | |
1573 | </DL> | |
1574 | <A NAME="lbAU"> </A> | |
1575 | <H2>SIGNALS</H2> | |
1576 | ||
1577 | <P> | |
1578 | ||
1579 | <B>Pluto</B> responds to <B>SIGHUP</B> by issuing a suggestion that ``<B>whack</B> | |
1580 | --listen'' might have been intended. | |
1581 | <P> | |
1582 | ||
1583 | <B>Pluto</B> exits when it recieves <B>SIGTERM</B>. | |
1584 | <A NAME="lbAV"> </A> | |
1585 | <H2>EXIT STATUS</H2> | |
1586 | ||
1587 | <P> | |
1588 | ||
1589 | <B>pluto</B> normally forks a daemon process, so the exit status is | |
1590 | normally a very preliminary result. | |
1591 | <DL COMPACT> | |
1592 | <DT>0<DD> | |
1593 | means that all is OK so far. | |
1594 | <DT>1<DD> | |
1595 | means that something was wrong. | |
1596 | <DT>10<DD> | |
1597 | means that the lock file already exists. | |
1598 | </DL> | |
1599 | <P> | |
1600 | ||
1601 | If <B>whack</B> detects a problem, it will return an exit status of 1. | |
1602 | If it received progress messages from <B>pluto</B>, it returns as status | |
1603 | the value of the numeric prefix from the last such message | |
1604 | that was not a message sent to syslog or a comment | |
1605 | (but the prefix for success is treated as 0). | |
1606 | Otherwise, the exit status is 0. | |
1607 | <A NAME="lbAW"> </A> | |
1608 | <H2>FILES</H2> | |
1609 | ||
1610 | <I>/var/run/pluto.pid</I> | |
1611 | <BR> | |
1612 | ||
1613 | <I>/var/run/pluto.ctl</I> | |
1614 | <BR> | |
1615 | ||
1616 | <I>/etc/ipsec.secrets</I> | |
1617 | <BR> | |
1618 | ||
1619 | <I>$IPSEC_LIBDIR/_pluto_adns</I> | |
1620 | <BR> | |
1621 | ||
1622 | <I>$IPSEC_EXECDIR/lwdnsq</I> | |
1623 | <BR> | |
1624 | ||
1625 | <I>/dev/urandom</I> | |
1626 | <A NAME="lbAX"> </A> | |
1627 | <H2>ENVIRONMENT</H2> | |
1628 | ||
1629 | <I>IPSEC_LIBDIR</I> | |
1630 | <BR> | |
1631 | ||
1632 | <I>IPSEC_EXECDIR</I> | |
1633 | <BR> | |
1634 | ||
1635 | <I>IPSECmyid</I> | |
1636 | <A NAME="lbAY"> </A> | |
1637 | <H2>SEE ALSO</H2> | |
1638 | ||
1639 | <P> | |
1640 | ||
1641 | The rest of the FreeS/WAN distribution, in particular <I><A HREF="ipsec.8.html">ipsec</A></I>(8). | |
1642 | <P> | |
1643 | ||
1644 | <I><A HREF="ipsec_auto.8.html">ipsec_auto</A></I>(8) is designed to make using <B>pluto</B> more pleasant. | |
1645 | Use it! | |
1646 | <P> | |
1647 | ||
1648 | <I><A HREF="ipsec.secrets.5.html">ipsec.secrets</A></I>(5) | |
1649 | ||
1650 | describes the format of the secrets file. | |
1651 | <P> | |
1652 | ||
1653 | <I><A HREF="ipsec_atoaddr.3.html">ipsec_atoaddr</A></I>(3), part of the FreeS/WAN distribution, describes the | |
1654 | forms that IP addresses may take. | |
1655 | <I><A HREF="ipsec_atosubnet.3.html">ipsec_atosubnet</A></I>(3), part of the FreeS/WAN distribution, describes the | |
1656 | forms that subnet specifications. | |
1657 | <P> | |
1658 | ||
1659 | For more information on IPsec, the mailing list, and the relevant | |
1660 | documents, see: | |
1661 | <DL COMPACT> | |
1662 | <DT><DD> | |
1663 | ||
1664 | <I><A HREF="http://www.ietf.cnri.reston.va.us/html.charters/ipsec-charter.html">http://www.ietf.cnri.reston.va.us/html.charters/ipsec-charter.html</A></I> | |
1665 | ||
1666 | </DL> | |
1667 | <P> | |
1668 | ||
1669 | At the time of writing, the most relevant IETF RFCs are: | |
1670 | <DL COMPACT> | |
1671 | <DT><DD> | |
1672 | RFC2409 The Internet Key Exchange (IKE) | |
1673 | <DT><DD> | |
1674 | RFC2408 Internet Security Association and Key Management Protocol (ISAKMP) | |
1675 | <DT><DD> | |
1676 | RFC2407 The Internet IP Security Domain of Interpretation for ISAKMP | |
1677 | </DL> | |
1678 | <P> | |
1679 | ||
1680 | The FreeS/WAN web site <<A HREF="htp://www.freeswan.org">htp://www.freeswan.org</A>> | |
1681 | and the mailing lists described there. | |
1682 | <A NAME="lbAZ"> </A> | |
1683 | <H2>HISTORY</H2> | |
1684 | ||
1685 | This code is released under the GPL terms. | |
1686 | See the accompanying file COPYING-2.0 for more details. | |
1687 | The GPL does NOT apply to those pieces of code written by others | |
1688 | which are included in this distribution, except as noted by the | |
1689 | individual authors. | |
1690 | <P> | |
1691 | ||
1692 | This software was originally written | |
1693 | for the FreeS/WAN project | |
1694 | <<A HREF="http://www.freeswan.org">http://www.freeswan.org</A>> | |
1695 | by Angelos D. Keromytis | |
1696 | (<A HREF="mailto:angelos@dsl.cis.upenn.edu">angelos@dsl.cis.upenn.edu</A>), in May/June 1997, in Athens, Greece. | |
1697 | Thanks go to John Ioannidis for his help. | |
1698 | <P> | |
1699 | ||
1700 | It is currently (2000) | |
1701 | being developed and maintained by D. Hugh Redelmeier | |
1702 | (<A HREF="mailto:hugh@mimosa.com">hugh@mimosa.com</A>), in Canada. The regulations of Greece and Canada | |
1703 | allow us to make the code freely redistributable. | |
1704 | <P> | |
1705 | ||
1706 | Kai Martius (<A HREF="mailto:admin@imib.med.tu-dresden.de">admin@imib.med.tu-dresden.de</A>) contributed the initial | |
1707 | version of the code supporting PFS. | |
1708 | <P> | |
1709 | ||
1710 | Richard Guy Briggs <<A HREF="mailto:rgb@conscoop.ottawa.on.ca">rgb@conscoop.ottawa.on.ca</A>> and Peter Onion | |
1711 | <<A HREF="mailto:ponion@srd.bt.co.uk">ponion@srd.bt.co.uk</A>> added the PFKEY2 support. | |
1712 | <P> | |
1713 | ||
1714 | We gratefully acknowledge that we use parts of Eric Young's <I>libdes</I> | |
1715 | package; see <I>../libdes/COPYRIGHT</I>. | |
1716 | <A NAME="lbBA"> </A> | |
1717 | <H2>BUGS</H2> | |
1718 | ||
1719 | <B>pluto</B> | |
1720 | ||
1721 | is a work-in-progress. It currently has many limitations. | |
1722 | For example, it ignores notification messages that it receives, and | |
1723 | it generates only Delete Notifications and those only for IPSEC SAs. | |
1724 | <P> | |
1725 | ||
1726 | <B>pluto</B> does not support the Commit Flag. | |
1727 | The Commit Flag is a bad feature of the IKE protocol. | |
1728 | It isn't protected -- neither encrypted nor authenticated. | |
1729 | A man in the middle could turn it on, leading to DoS. | |
1730 | We just ignore it, with a warning. | |
1731 | This should let us interoperate with | |
1732 | implementations that insist on it, with minor damage. | |
1733 | <P> | |
1734 | ||
1735 | <B>pluto</B> does not check that the SA returned by the Responder | |
1736 | is actually one that was proposed. It only checks that the SA is | |
1737 | acceptable. The difference is not large, but can show up in attributes | |
1738 | such as SA lifetime. | |
1739 | <P> | |
1740 | ||
1741 | There is no good way for a connection to be automatically terminated. | |
1742 | This is a problem for Road Warrior and Opportunistic connections. | |
1743 | The <B>--dontrekey</B> option does prevent the SAs from | |
1744 | being rekeyed on expiry. | |
1745 | Additonally, if a Road Warrior connection has a client subnet with a fixed IP | |
1746 | address, a negotiation with that subnet will cause any other | |
1747 | connection instantiations with that same subnet to be unoriented | |
1748 | (deleted, in effect). | |
1749 | See also the --uniqueids option for an extension of this. | |
1750 | <P> | |
1751 | ||
1752 | When <B>pluto</B> sends a message to a peer that has disappeared, | |
1753 | <B>pluto</B> receives incomplete information from the kernel, so it | |
1754 | logs the unsatisfactory message ``some IKE message we sent has been | |
1755 | rejected with ECONNREFUSED (kernel supplied no details)''. John | |
1756 | Denker suggests that this command is useful for tracking down the | |
1757 | source of these problems: | |
1758 | <BR> | |
1759 | ||
1760 | <TT> </TT>tcpdump -i eth0 icmp[0] != 8 and icmp[0] != 0<BR> | |
1761 | <BR> | |
1762 | ||
1763 | Substitute your public interface for eth0 if it is different. | |
1764 | <P> | |
1765 | ||
1766 | The word ``authenticate'' is used for two different features. We must | |
1767 | authenticate each IKE peer to the other. This is an important task of | |
1768 | Phase 1. Each packet must be authenticated, both in IKE and in IPsec, | |
1769 | and the method for IPsec is negotiated as an AH SA or part of an ESP SA. | |
1770 | Unfortunately, the protocol has no mechanism for authenticating the Phase 2 | |
1771 | identities. | |
1772 | <P> | |
1773 | ||
1774 | Bugs should be reported to the <<A HREF="mailto:users@lists.freeswan.org">users@lists.freeswan.org</A>> mailing list. | |
1775 | Caution: we cannot accept | |
1776 | actual code from US residents, or even US citizens living outside the | |
1777 | US, because that would bring FreeS/WAN under US export law. Some | |
1778 | other countries cause similar problems. In general, we would prefer | |
1779 | that you send detailed problem reports rather than code: we want | |
1780 | FreeS/WAN to be unquestionably freely exportable, which means being | |
1781 | very careful about where the code comes from, and for a small bug fix, | |
1782 | that is often more time-consuming than just reinventing the fix | |
1783 | ourselves. | |
1784 | <P> | |
1785 | ||
1786 | <HR> | |
1787 | <A NAME="index"> </A><H2>Index</H2> | |
1788 | <DL> | |
1789 | <DT><A HREF="#lbAB">NAME</A><DD> | |
1790 | <DT><A HREF="#lbAC">SYNOPSIS</A><DD> | |
1791 | <DT><A HREF="#lbAD">DESCRIPTION</A><DD> | |
1792 | <DL> | |
1793 | <DT><A HREF="#lbAE">IKE's Job</A><DD> | |
1794 | <DT><A HREF="#lbAF">Pluto</A><DD> | |
1795 | <DT><A HREF="#lbAG">Before Running Pluto</A><DD> | |
1796 | <DT><A HREF="#lbAH">Setting up <B>KLIPS</B> for <B>pluto</B></A><DD> | |
1797 | <DT><A HREF="#lbAI">ipsec.secrets file</A><DD> | |
1798 | <DT><A HREF="#lbAJ">Running Pluto</A><DD> | |
1799 | <DT><A HREF="#lbAK">Pluto's Internal State</A><DD> | |
1800 | <DT><A HREF="#lbAL">Using Whack</A><DD> | |
1801 | <DT><A HREF="#lbAM">Examples</A><DD> | |
1802 | <DT><A HREF="#lbAN">The updown command</A><DD> | |
1803 | <DT><A HREF="#lbAO">Rekeying</A><DD> | |
1804 | <DT><A HREF="#lbAP">Selecting a Connection When Responding: Road Warrior Support</A><DD> | |
1805 | <DT><A HREF="#lbAQ">Debugging</A><DD> | |
1806 | <DT><A HREF="#lbAR">Pluto's Behaviour When Things Go Wrong</A><DD> | |
1807 | <DT><A HREF="#lbAS">Notes</A><DD> | |
1808 | <DT><A HREF="#lbAT">Policies</A><DD> | |
1809 | </DL> | |
1810 | <DT><A HREF="#lbAU">SIGNALS</A><DD> | |
1811 | <DT><A HREF="#lbAV">EXIT STATUS</A><DD> | |
1812 | <DT><A HREF="#lbAW">FILES</A><DD> | |
1813 | <DT><A HREF="#lbAX">ENVIRONMENT</A><DD> | |
1814 | <DT><A HREF="#lbAY">SEE ALSO</A><DD> | |
1815 | <DT><A HREF="#lbAZ">HISTORY</A><DD> | |
1816 | <DT><A HREF="#lbBA">BUGS</A><DD> | |
1817 | </DL> | |
1818 | <HR> | |
1819 | This document was created by | |
1820 | <A HREF="http://localhost/cgi-bin/man/man2html">man2html</A>, | |
1821 | using the manual pages.<BR> | |
1822 | Time: 21:40:18 GMT, November 11, 2003 | |
1823 | </BODY> | |
1824 | </HTML> |