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