aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.xml
blob: 568cc8ba353f83feace2c06eb81d0859ba3938be (plain) (blame)
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
<?xml version="1.0" encoding="iso-8859-1"?>
<!--
     The FreeBSD Documentation Project

     $FreeBSD$
-->
<chapter xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:id="ipv6">
  <title>IPv6 Internals</title>

  <sect1 xml:id="ipv6-implementation">
    <info>
      <title>IPv6/IPsec Implementation</title>

      <authorgroup>
	<author>
	  <personname>
	    <firstname>Yoshinobu</firstname>
	    <surname>Inoue</surname>
	  </personname>
	  <contrib>Contributed by </contrib>
	</author>
      </authorgroup>
    </info>

    <para>This section should explain IPv6 and IPsec related
      implementation internals.  These functionalities are derived
      from <link xlink:href="http://www.kame.net/">KAME
	project</link></para>

    <sect2 xml:id="ipv6details">
      <title>IPv6</title>

      <sect3>
	<title>Conformance</title>

	<para>The IPv6 related functions conforms, or tries to conform
	  to the latest set of IPv6 specifications.  For future
	  reference we list some of the relevant documents below
	  (<emphasis>NOTE</emphasis>: this is not a complete list -
	  this is too hard to maintain...).</para>

	<para>For details please refer to specific chapter in the
	  document, RFCs, manual pages, or comments in the source
	  code.</para>

	<para>Conformance tests have been performed on the KAME STABLE
	  kit at TAHI project.  Results can be viewed at <uri
	    xlink:href="http://www.tahi.org/report/KAME/">http://www.tahi.org/report/KAME/</uri>.
	  We also attended University of New Hampshire IOL tests (<uri
	    xlink:href="http://www.iol.unh.edu/">http://www.iol.unh.edu/</uri>)
	  in the past, with our past snapshots.</para>

	<itemizedlist>
	  <listitem>
	    <para>RFC1639: FTP Operation Over Big Address Records
	      (FOOBAR)</para>
	    <itemizedlist>
	      <listitem>
		<para>RFC2428 is preferred over RFC1639.  FTP clients
		  will first try RFC2428, then RFC1639 if
		  failed.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>RFC1886: DNS Extensions to support IPv6</para>
	  </listitem>

	  <listitem>
	    <para>RFC1933: Transition Mechanisms for IPv6 Hosts and
	      Routers</para>
	    <itemizedlist>
	      <listitem>
		<para>IPv4 compatible address is not supported.</para>
	      </listitem>
	      <listitem>
		<para>automatic tunneling (described in 4.3 of this
		  RFC) is not supported.</para>
	      </listitem>
	      <listitem>
		<para>&man.gif.4; interface implements
		  IPv[46]-over-IPv[46] tunnel in a generic way, and it
		  covers "configured tunnel" described in the spec.
		  See <link linkend="gif">23.5.1.5</link> in this
		  document for details.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>RFC1981: Path MTU Discovery for IPv6</para>
	  </listitem>

	  <listitem>
	    <para>RFC2080: RIPng for IPv6</para>
	    <itemizedlist>
	      <listitem>
		<para>usr.sbin/route6d support this.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>RFC2292: Advanced Sockets API for IPv6</para>
	    <itemizedlist>
	      <listitem>
		<para>For supported library functions/kernel APIs, see
		  <filename>sys/netinet6/ADVAPI</filename>.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>RFC2362: Protocol Independent Multicast-Sparse Mode
	      (PIM-SM)</para>
	    <itemizedlist>
	      <listitem>
		<para>RFC2362 defines packet formats for PIM-SM.
		  <filename>draft-ietf-pim-ipv6-01.txt</filename> is
		  written based on this.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>RFC2373: IPv6 Addressing Architecture</para>
	    <itemizedlist>
	      <listitem>
		<para>supports node required addresses, and conforms
		  to the scope requirement.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>RFC2374: An IPv6 Aggregatable Global Unicast Address
	      Format</para>
	    <itemizedlist>
	      <listitem>
		<para>supports 64-bit length of Interface ID.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>RFC2375: IPv6 Multicast Address Assignments</para>
	    <itemizedlist>
	      <listitem>
		<para>Userland applications use the well-known
		  addresses assigned in the RFC.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>RFC2428: FTP Extensions for IPv6 and NATs</para>
	    <itemizedlist>
	      <listitem>
		<para>RFC2428 is preferred over RFC1639.  FTP clients
		  will first try RFC2428, then RFC1639 if
		  failed.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>RFC2460: IPv6 specification</para>
	  </listitem>

	  <listitem>
	    <para>RFC2461: Neighbor discovery for IPv6</para>
	    <itemizedlist>
	      <listitem>
		<para>See <link
		    linkend="neighbor-discovery">23.5.1.2</link> in
		  this document for details.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>RFC2462: IPv6 Stateless Address
	      Autoconfiguration</para>
	    <itemizedlist>
	      <listitem>
		<para>See <link linkend="ipv6-pnp">23.5.1.4</link> in
		  this document for details.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>RFC2463: ICMPv6 for IPv6 specification</para>
	    <itemizedlist>
	      <listitem>
		<para>See <link linkend="icmpv6">23.5.1.9</link> in
		  this document for details.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>RFC2464: Transmission of IPv6 Packets over Ethernet
	      Networks</para>
	  </listitem>

	  <listitem>
	    <para>RFC2465: MIB for IPv6: Textual Conventions and
	      General Group</para>
	    <itemizedlist>
	      <listitem>
		<para>Necessary statistics are gathered by the kernel.
		  Actual IPv6 MIB support is provided as a patchkit
		  for ucd-snmp.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>RFC2466: MIB for IPv6: ICMPv6 group</para>
	    <itemizedlist>
	      <listitem>
		<para>Necessary statistics are gathered by the kernel.
		  Actual IPv6 MIB support is provided as patchkit for
		  ucd-snmp.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>RFC2467: Transmission of IPv6 Packets over FDDI
	      Networks</para>
	  </listitem>

	  <listitem>
	    <para>RFC2497: Transmission of IPv6 packet over ARCnet
	      Networks</para>
	  </listitem>

	  <listitem>
	    <para>RFC2553: Basic Socket Interface Extensions for
	      IPv6</para>
	    <itemizedlist>
	      <listitem>
		<para>IPv4 mapped address (3.7) and special behavior
		  of IPv6 wildcard bind socket (3.8) are supported.
		  See <link
		    linkend="ipv6-wildcard-socket">23.5.1.12</link> in
		  this document for details.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>RFC2675: IPv6 Jumbograms</para>
	    <itemizedlist>
	      <listitem>
		<para>See <link linkend="ipv6-jumbo">23.5.1.7</link>
		  in this document for details.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>RFC2710: Multicast Listener Discovery for
	      IPv6</para>
	  </listitem>

	  <listitem>
	    <para>RFC2711: IPv6 router alert option</para>
	  </listitem>

	  <listitem>
	    <para><filename>draft-ietf-ipngwg-router-renum-08</filename>:
	      Router renumbering for IPv6</para>
	  </listitem>

	  <listitem>
	    <para><filename>draft-ietf-ipngwg-icmp-namelookups-02</filename>:
	      IPv6 Name Lookups Through ICMP</para>
	  </listitem>

	  <listitem>
	    <para><filename>draft-ietf-ipngwg-icmp-name-lookups-03</filename>:
	      IPv6 Name Lookups Through ICMP</para>
	  </listitem>

	  <listitem>
	    <para><filename>draft-ietf-pim-ipv6-01.txt</filename>: PIM
	      for IPv6</para>
	    <itemizedlist>
	      <listitem>
		<para>&man.pim6dd.8; implements dense mode.
		  &man.pim6sd.8; implements sparse mode.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para><filename>draft-itojun-ipv6-tcp-to-anycast-00</filename>:
	      Disconnecting TCP connection toward IPv6 anycast
	      address</para>
	  </listitem>

	  <listitem>
	    <para><filename>draft-yamamoto-wideipv6-comm-model-00</filename></para>
	    <itemizedlist>
	      <listitem>
		<para>See <link linkend="ipv6-sas">23.5.1.6</link> in
		  this document for details.</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para><filename>draft-ietf-ipngwg-scopedaddr-format-00.txt</filename>:
	      An Extension of Format for IPv6 Scoped Addresses</para>
	  </listitem>
	</itemizedlist>
      </sect3>

      <sect3 xml:id="neighbor-discovery">
	<title>Neighbor Discovery</title>

	<para>Neighbor Discovery is fairly stable.  Currently Address
	  Resolution, Duplicated Address Detection, and Neighbor
	  Unreachability Detection are supported.  In the near future
	  we will be adding Proxy Neighbor Advertisement support in
	  the kernel and Unsolicited Neighbor Advertisement
	  transmission command as admin tool.</para>

	<para>If DAD fails, the address will be marked "duplicated"
	  and message will be generated to syslog (and usually to
	  console).  The "duplicated" mark can be checked with
	  &man.ifconfig.8;.  It is administrators' responsibility to
	  check for and recover from DAD failures.  The behavior
	  should be improved in the near future.</para>

	<para>Some of the network driver loops multicast packets back
	  to itself, even if instructed not to do so (especially in
	  promiscuous mode).  In such cases DAD may fail, because DAD
	  engine sees inbound NS packet (actually from the node
	  itself) and considers it as a sign of duplicate.  You may
	  want to look at #if condition marked "heuristics" in
	  sys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note
	  that the code fragment in "heuristics" section is not spec
	  conformant).</para>

	<para>Neighbor Discovery specification (RFC2461) does not talk
	  about neighbor cache handling in the following cases:</para>

	<orderedlist>
	  <listitem>
	    <para>when there was no neighbor cache entry, node
	      received unsolicited RS/NS/NA/redirect packet without
	      link-layer address</para>
	  </listitem>
	  <listitem>
	    <para>neighbor cache handling on medium without link-layer
	      address (we need a neighbor cache entry for IsRouter
	      bit)</para>
	  </listitem>
	</orderedlist>

	<para>For first case, we implemented workaround based on
	  discussions on IETF ipngwg mailing list.  For more details,
	  see the comments in the source code and email thread started
	  from (IPng 7155), dated Feb 6 1999.</para>

	<para>IPv6 on-link determination rule (RFC2461) is quite
	  different from assumptions in BSD network code.  At this
	  moment, no on-link determination rule is supported where
	  default router list is empty (RFC2461, section 5.2, last
	  sentence in 2nd paragraph - note that the spec misuse the
	  word "host" and "node" in several places in the
	  section).</para>

	<para>To avoid possible DoS attacks and infinite loops, only
	  10 options on ND packet is accepted now.  Therefore, if you
	  have 20 prefix options attached to RA, only the first 10
	  prefixes will be recognized.  If this troubles you, please
	  ask it on FREEBSD-CURRENT mailing list and/or modify
	  nd6_maxndopt in <filename>sys/netinet6/nd6.c</filename>.  If
	  there are high demands we may provide sysctl knob for the
	  variable.</para>
      </sect3>

      <sect3 xml:id="ipv6-scope-index">
	<title>Scope Index</title>

	<para>IPv6 uses scoped addresses.  Therefore, it is very
	  important to specify scope index (interface index for
	  link-local address, or site index for site-local address)
	  with an IPv6 address.  Without scope index, scoped IPv6
	  address is ambiguous to the kernel, and kernel will not be
	  able to determine the outbound interface for a
	  packet.</para>

	<para>Ordinary userland applications should use advanced API
	  (RFC2292) to specify scope index, or interface index.  For
	  similar purpose, sin6_scope_id member in sockaddr_in6
	  structure is defined in RFC2553.  However, the semantics for
	  sin6_scope_id is rather vague.  If you care about
	  portability of your application, we suggest you to use
	  advanced API rather than sin6_scope_id.</para>

	<para>In the kernel, an interface index for link-local scoped
	  address is embedded into 2nd 16bit-word (3rd and 4th byte)
	  in IPv6 address.  For example, you may see something
	  like:</para>

	<screen>	fe80:1::200:f8ff:fe01:6317</screen>

	<para>in the routing table and interface address structure
	  (struct in6_ifaddr).  The address above is a link-local
	  unicast address which belongs to a network interface whose
	  interface identifier is 1.  The embedded index enables us to
	  identify IPv6 link local addresses over multiple interfaces
	  effectively and with only a little code change.</para>

	<para>Routing daemons and configuration programs, like
	  &man.route6d.8; and &man.ifconfig.8;, will need to
	  manipulate the "embedded" scope index.  These programs use
	  routing sockets and ioctls (like SIOCGIFADDR_IN6) and the
	  kernel API will return IPv6 addresses with 2nd 16bit-word
	  filled in.  The APIs are for manipulating kernel internal
	  structure.  Programs that use these APIs have to be prepared
	  about differences in kernels anyway.</para>

	<para>When you specify scoped address to the command line,
	  NEVER write the embedded form (such as ff02:1::1 or
	  fe80:2::fedc).  This is not supposed to work.  Always use
	  standard form, like ff02::1 or fe80::fedc, with command line
	  option for specifying interface (like <command>ping6 -I ne0
	    ff02::1</command>).  In general, if a command does not
	  have command line option to specify outgoing interface, that
	  command is not ready to accept scoped address.  This may
	  seem to be opposite from IPv6's premise to support "dentist
	  office" situation.  We believe that specifications need some
	  improvements for this.</para>

	<para>Some of the userland tools support extended numeric IPv6
	  syntax, as documented in
	  <filename>draft-ietf-ipngwg-scopedaddr-format-00.txt</filename>.
	  You can specify outgoing link, by using name of the outgoing
	  interface like "fe80::1%ne0".  This way you will be able to
	  specify link-local scoped address without much
	  trouble.</para>

	<para>To use this extension in your program, you will need to
	  use &man.getaddrinfo.3;, and &man.getnameinfo.3; with
	  NI_WITHSCOPEID.  The implementation currently assumes 1-to-1
	  relationship between a link and an interface, which is
	  stronger than what specs say.</para>
      </sect3>

      <sect3 xml:id="ipv6-pnp">
	<title>Plug and Play</title>

	<para>Most of the IPv6 stateless address autoconfiguration is
	  implemented in the kernel.  Neighbor Discovery functions are
	  implemented in the kernel as a whole.  Router Advertisement
	  (RA) input for hosts is implemented in the kernel.  Router
	  Solicitation (RS) output for endhosts, RS input for routers,
	  and RA output for routers are implemented in the
	  userland.</para>

	<sect4>
	  <title>Assignment of link-local, and special
	    addresses</title>

	  <para>IPv6 link-local address is generated from IEEE802
	    address (Ethernet MAC address).  Each of interface is
	    assigned an IPv6 link-local address automatically, when
	    the interface becomes up (IFF_UP).  Also, direct route for
	    the link-local address is added to routing table.</para>

	  <para>Here is an output of netstat command:</para>

	  <screen>Internet6:
Destination                   Gateway                   Flags      Netif Expire
fe80:1::%ed0/64               link#1                    UC          ed0
fe80:2::%ep0/64               link#2                    UC          ep0</screen>

	  <para>Interfaces that has no IEEE802 address (pseudo
	    interfaces like tunnel interfaces, or ppp interfaces) will
	    borrow IEEE802 address from other interfaces, such as
	    Ethernet interfaces, whenever possible.  If there is no
	    IEEE802 hardware attached, a last resort pseudo-random
	    value, MD5(hostname), will be used as source of link-local
	    address.  If it is not suitable for your usage, you will
	    need to configure the link-local address manually.</para>

	  <para>If an interface is not capable of handling IPv6 (such
	    as lack of multicast support), link-local address will not
	    be assigned to that interface.  See section 2 for
	    details.</para>

	  <para>Each interface joins the solicited multicast address
	    and the link-local all-nodes multicast addresses (e.g.,
	    fe80::1:ff01:6317 and ff02::1, respectively, on the link
	    the interface is attached).  In addition to a link-local
	    address, the loopback address (::1) will be assigned to
	    the loopback interface.  Also, ::1/128 and ff01::/32 are
	    automatically added to routing table, and loopback
	    interface joins node-local multicast group ff01::1.</para>
	</sect4>

	<sect4>
	  <title>Stateless address autoconfiguration on Hosts</title>

	  <para>In IPv6 specification, nodes are separated into two
	    categories: <emphasis>routers</emphasis> and
	    <emphasis>hosts</emphasis>.  Routers forward packets
	    addressed to others, hosts does not forward the packets.
	    net.inet6.ip6.forwarding defines whether this node is
	    router or host (router if it is 1, host if it is
	    0).</para>

	  <para>When a host hears Router Advertisement from the
	    router, a host may autoconfigure itself by stateless
	    address autoconfiguration.  This behavior can be
	    controlled by net.inet6.ip6.accept_rtadv (host
	    autoconfigures itself if it is set to 1).  By
	    autoconfiguration, network address prefix for the
	    receiving interface (usually global address prefix) is
	    added.  Default route is also configured.  Routers
	    periodically generate Router Advertisement packets.  To
	    request an adjacent router to generate RA packet, a host
	    can transmit Router Solicitation.  To generate a RS packet
	    at any time, use the <emphasis>rtsol</emphasis> command.
	    &man.rtsold.8; daemon is also available.  &man.rtsold.8;
	    generates Router Solicitation whenever necessary, and it
	    works great for nomadic usage (notebooks/laptops).  If one
	    wishes to ignore Router Advertisements, use sysctl to set
	    net.inet6.ip6.accept_rtadv to 0.</para>

	  <para>To generate Router Advertisement from a router, use
	    the &man.rtadvd.8; daemon.</para>

	  <para>Note that, IPv6 specification assumes the following
	    items, and nonconforming cases are left
	    unspecified:</para>

	  <itemizedlist>
	    <listitem>
	      <para>Only hosts will listen to router
		advertisements</para>
	    </listitem>
	    <listitem>
	      <para>Hosts have single network interface (except
		loopback)</para>
	    </listitem>
	  </itemizedlist>

	  <para>Therefore, this is unwise to enable
	    net.inet6.ip6.accept_rtadv on routers, or multi-interface
	    host.  A misconfigured node can behave strange
	    (nonconforming configuration allowed for those who would
	    like to do some experiments).</para>

	  <para>To summarize the sysctl knob:</para>

	  <screen>	accept_rtadv	forwarding	role of the node
	---		---		---
	0		0		host (to be manually configured)
	0		1		router
	1		0		autoconfigured host
					(spec assumes that host has single
					interface only, autoconfigured host
					with multiple interface is
					out-of-scope)
	1		1		invalid, or experimental
					(out-of-scope of spec)</screen>

	  <para>RFC2462 has validation rule against incoming RA prefix
	    information option, in 5.5.3 (e).  This is to protect
	    hosts from malicious (or misconfigured) routers that
	    advertise very short prefix lifetime.  There was an update
	    from Jim Bound to ipngwg mailing list (look for "(ipng
	    6712)" in the archive) and it is implemented Jim's
	    update.</para>

	  <para>See <link linkend="neighbor-discovery">23.5.1.2</link>
	    in the document for relationship between DAD and
	    autoconfiguration.</para>
	</sect4>
      </sect3>

      <sect3 xml:id="gif">
	<title>Generic Tunnel Interface</title>

	<para>GIF (Generic InterFace) is a pseudo interface for
	  configured tunnel.  Details are described in &man.gif.4;.
	  Currently</para>

	<itemizedlist>
	  <listitem>
	    <para>v6 in v6</para>
	  </listitem>
	  <listitem>
	    <para>v6 in v4</para>
	  </listitem>
	  <listitem>
	    <para>v4 in v6</para>
	  </listitem>
	  <listitem>
	    <para>v4 in v4</para>
	  </listitem>
	</itemizedlist>

	<para>are available.  Use &man.gifconfig.8; to assign physical
	  (outer) source and destination address to gif interfaces.
	  Configuration that uses same address family for inner and
	  outer IP header (v4 in v4, or v6 in v6) is dangerous.  It is
	  very easy to configure interfaces and routing tables to
	  perform infinite level of tunneling.  <emphasis>Please be
	    warned</emphasis>.</para>

	<para>gif can be configured to be ECN-friendly.  See <link
	    linkend="ipsec-ecn">23.5.4.5</link> for ECN-friendliness
	  of tunnels, and &man.gif.4; for how to configure.</para>

	<para>If you would like to configure an IPv4-in-IPv6 tunnel
	  with gif interface, read &man.gif.4; carefully.  You will
	  need to remove IPv6 link-local address automatically
	  assigned to the gif interface.</para>
      </sect3>

      <sect3 xml:id="ipv6-sas">
	<title>Source Address Selection</title>

	<para>Current source selection rule is scope oriented (there
	  are some exceptions - see below).  For a given destination,
	  a source IPv6 address is selected by the following
	  rule:</para>

	<orderedlist>
	  <listitem>
	    <para>If the source address is explicitly specified by the
	      user (e.g.,  via the advanced API), the specified
	      address is used.</para>
	  </listitem>

	  <listitem>
	    <para>If there is an address assigned to the outgoing
	      interface (which is usually determined by looking up the
	      routing table) that has the same scope as the
	      destination address, the address is used.</para>

	    <para>This is the most typical case.</para>
	  </listitem>

	  <listitem>
	    <para>If there is no address that satisfies the above
	      condition, choose a global address assigned to one of
	      the interfaces on the sending node.</para>
	  </listitem>

	  <listitem>
	    <para>If there is no address that satisfies the above
	      condition, and destination address is site local scope,
	      choose a site local address assigned to one of the
	      interfaces on the sending node.</para>
	  </listitem>

	  <listitem>
	    <para>If there is no address that satisfies the above
	      condition, choose the address associated with the
	      routing table entry for the destination.  This is the
	      last resort, which may cause scope violation.</para>
	  </listitem>
	</orderedlist>

	<para>For instance, ::1 is selected for ff01::1,
	  fe80:1::200:f8ff:fe01:6317 for fe80:1::2a0:24ff:feab:839b
	  (note that embedded interface index - described in <link
	    linkend="ipv6-scope-index">23.5.1.3</link> - helps us
	  choose the right source address.  Those embedded indices
	  will not be on the wire).  If the outgoing interface has
	  multiple address for the scope, a source is selected longest
	  match basis (rule 3).  Suppose
	  2001:0DB8:808:1:200:f8ff:fe01:6317 and
	  2001:0DB8:9:124:200:f8ff:fe01:6317 are given to the outgoing
	  interface.  2001:0DB8:808:1:200:f8ff:fe01:6317 is chosen as
	  the source for the destination 2001:0DB8:800::1.</para>

	<para>Note that the above rule is not documented in the IPv6
	  spec.  It is considered "up to implementation" item.  There
	  are some cases where we do not use the above rule.  One
	  example is connected TCP session, and we use the address
	  kept in tcb as the source.  Another example is source
	  address for Neighbor Advertisement.  Under the spec (RFC2461
	  7.2.2) NA's source should be the target address of the
	  corresponding NS's target.  In this case we follow the spec
	  rather than the above longest-match rule.</para>

	<para>For new connections (when rule 1 does not apply),
	  deprecated addresses (addresses with preferred lifetime = 0)
	  will not be chosen as source address if other choices are
	  available.  If no other choices are available, deprecated
	  address will be used as a last resort.  If there are
	  multiple choice of deprecated addresses, the above scope
	  rule will be used to choose from those deprecated addresses.
	  If you would like to prohibit the use of deprecated address
	  for some reason, configure net.inet6.ip6.use_deprecated to
	  0.  The issue related to deprecated address is described in
	  RFC2462 5.5.4 (NOTE: there is some debate underway in IETF
	  ipngwg on how to use "deprecated" address).</para>
      </sect3>

      <sect3 xml:id="ipv6-jumbo">
	<title>Jumbo Payload</title>

	<para>The Jumbo Payload hop-by-hop option is implemented and
	  can be used to send IPv6 packets with payloads longer than
	  65,535 octets.  But currently no physical interface whose
	  MTU is more than 65,535 is supported, so such payloads can
	  be seen only on the loopback interface (i.e., lo0).</para>

	<para>If you want to try jumbo payloads, you first have to
	  reconfigure the kernel so that the MTU of the loopback
	  interface is more than 65,535 bytes; add the following to
	  the kernel configuration file:</para>

	<para><literal>options		"LARGE_LOMTU"		#To
	    test jumbo payload</literal></para>

	<para>and recompile the new kernel.</para>

	<para>Then you can test jumbo payloads by the &man.ping6.8;
	  command with -b and -s options.  The -b option must be
	  specified to enlarge the size of the socket buffer and the
	  -s option specifies the length of the packet, which should
	  be more than 65,535.  For example, type as follows:</para>

	<screen>&prompt.user; <userinput>ping6 -b 70000 -s 68000 ::1</userinput></screen>

	<para>The IPv6 specification requires that the Jumbo Payload
	  option must not be used in a packet that carries a fragment
	  header.  If this condition is broken, an ICMPv6 Parameter
	  Problem message must be sent to the sender.  specification
	  is followed, but you cannot usually see an ICMPv6 error
	  caused by this requirement.</para>

	<para>When an IPv6 packet is received, the frame length is
	  checked and compared to the length specified in the payload
	  length field of the IPv6 header or in the value of the Jumbo
	  Payload option, if any.  If the former is shorter than the
	  latter, the packet is discarded and statistics are
	  incremented.  You can see the statistics as output of
	  &man.netstat.8; command with `-s -p ip6' option:</para>

	<screen>&prompt.user; <userinput>netstat -s -p ip6</userinput>
	  ip6:
		(snip)
		1 with data size &lt; data length</screen>

	<para>So, kernel does not send an ICMPv6 error unless the
	  erroneous packet is an actual Jumbo Payload, that is, its
	  packet size is more than 65,535 bytes.  As described above,
	  currently no physical interface with such a huge MTU is
	  supported, so it rarely returns an ICMPv6 error.</para>

	<para>TCP/UDP over jumbogram is not supported at this moment.
	  This is because we have no medium (other than loopback) to
	  test this.  Contact us if you need this.</para>

	<para>IPsec does not work on jumbograms.  This is due to some
	  specification twists in supporting AH with jumbograms (AH
	  header size influences payload length, and this makes it
	  real hard to authenticate inbound packet with jumbo payload
	  option as well as AH).</para>

	<para>There are fundamental issues in *BSD support for
	  jumbograms.  We would like to address those, but we need
	  more time to finalize these.  To name a few:</para>

	<itemizedlist>
	  <listitem>
	    <para>mbuf pkthdr.len field is typed as "int" in 4.4BSD,
	      so it will not hold jumbogram with len &gt; 2G on 32bit
	      architecture CPUs.  If we would like to support
	      jumbogram properly, the field must be expanded to hold
	      4G + IPv6 header + link-layer header.  Therefore, it
	      must be expanded to at least int64_t (u_int32_t is NOT
	      enough).</para>
	  </listitem>

	  <listitem>
	    <para>We mistakingly use "int" to hold packet length in
	      many places.  We need to convert them into larger
	      integral type.  It needs a great care, as we may
	      experience overflow during packet length
	      computation.</para>
	  </listitem>

	  <listitem>
	    <para>We mistakingly check for ip6_plen field of IPv6
	      header for packet payload length in various places.  We
	      should be checking mbuf pkthdr.len instead.  ip6_input()
	      will perform sanity check on jumbo payload option on
	      input, and we can safely use mbuf pkthdr.len
	      afterwards.</para>
	  </listitem>

	  <listitem>
	    <para>TCP code needs a careful update in bunch of places,
	      of course.</para>
	  </listitem>
	</itemizedlist>
      </sect3>

      <sect3>
	<title>Loop Prevention in Header Processing</title>

	<para>IPv6 specification allows arbitrary number of extension
	  headers to be placed onto packets.  If we implement IPv6
	  packet processing code in the way BSD IPv4 code is
	  implemented, kernel stack may overflow due to long function
	  call chain.  sys/netinet6 code is carefully designed to
	  avoid kernel stack overflow.  Because of this, sys/netinet6
	  code defines its own protocol switch structure, as "struct
	  ip6protosw" (see
	  <filename>netinet6/ip6protosw.h</filename>).  There is no
	  such update to IPv4 part (sys/netinet) for compatibility,
	  but small change is added to its pr_input() prototype.  So
	  "struct ipprotosw" is also defined.  Because of this, if you
	  receive IPsec-over-IPv4 packet with massive number of IPsec
	  headers, kernel stack may blow up.  IPsec-over-IPv6 is okay.
	  (Off-course, for those all IPsec headers to be processed,
	  each such IPsec header must pass each IPsec check.  So an
	  anonymous attacker will not be able to do such an
	  attack.)</para>
      </sect3>

      <sect3 xml:id="icmpv6">
	<title>ICMPv6</title>

	<para>After RFC2463 was published, IETF ipngwg has decided to
	  disallow ICMPv6 error packet against ICMPv6 redirect, to
	  prevent ICMPv6 storm on a network medium.  This is already
	  implemented into the kernel.</para>
      </sect3>

      <sect3>
	<title>Applications</title>

	<para>For userland programming, we support IPv6 socket API as
	  specified in RFC2553, RFC2292 and upcoming Internet
	  drafts.</para>

	<para>TCP/UDP over IPv6 is available and quite stable.  You
	  can enjoy &man.telnet.1;, &man.ftp.1;, &man.rlogin.1;,
	  &man.rsh.1;, &man.ssh.1;, etc.  These applications are
	  protocol independent.  That is, they automatically chooses
	  IPv4 or IPv6 according to DNS.</para>
      </sect3>

      <sect3>
	<title>Kernel Internals</title>

	<para>While ip_forward() calls ip_output(), ip6_forward()
	  directly calls if_output() since routers must not divide
	  IPv6 packets into fragments.</para>

	<para>ICMPv6 should contain the original packet as long as
	  possible up to 1280.  UDP6/IP6 port unreach, for instance,
	  should contain all extension headers and the *unchanged*
	  UDP6 and IP6 headers.  So, all IP6 functions except TCP
	  never convert network byte order into host byte order, to
	  save the original packet.</para>

	<para>tcp_input(), udp6_input() and icmp6_input() can not
	  assume that IP6 header is preceding the transport headers
	  due to extension headers.  So, in6_cksum() was implemented
	  to handle packets whose IP6 header and transport header is
	  not continuous.  TCP/IP6 nor UDP6/IP6 header structures do
	  not exist for checksum calculation.</para>

	<para>To process IP6 header, extension headers and transport
	  headers easily, network drivers are now required to store
	  packets in one internal mbuf or one or more external mbufs.
	  A typical old driver prepares two internal mbufs for 96 -
	  204 bytes data, however, now such packet data is stored in
	  one external mbuf.</para>

	<para><command>netstat -s -p ip6</command> tells you whether
	  or not your driver conforms such requirement.  In the
	  following example, "cce0" violates the requirement.  (For
	  more information, refer to Section 2.)</para>

	<screen>Mbuf statistics:
                317 one mbuf
                two or more mbuf::
                        lo0 = 8
			cce0 = 10
                3282 one ext mbuf
                0 two or more ext mbuf</screen>

	<para>Each input function calls IP6_EXTHDR_CHECK in the
	  beginning to check if the region between IP6 and its header
	  is continuous.  IP6_EXTHDR_CHECK calls m_pullup() only if
	  the mbuf has M_LOOP flag, that is, the packet comes from the
	  loopback interface.  m_pullup() is never called for packets
	  coming from physical network interfaces.</para>

	<para>Both IP and IP6 reassemble functions never call
	  m_pullup().</para>
      </sect3>

      <sect3 xml:id="ipv6-wildcard-socket">
	<title>IPv4 Mapped Address and IPv6 Wildcard Socket</title>

	<para>RFC2553 describes IPv4 mapped address (3.7) and special
	  behavior of IPv6 wildcard bind socket (3.8).  The spec
	  allows you to:</para>
	<itemizedlist>
	  <listitem>
	    <para>Accept IPv4 connections by AF_INET6 wildcard bind
	      socket.</para>
	  </listitem>
	  <listitem>
	    <para>Transmit IPv4 packet over AF_INET6 socket by using
	      special form of the address like ::ffff:10.1.1.1.</para>
	  </listitem>
	</itemizedlist>

	<para>but the spec itself is very complicated and does not
	  specify how the socket layer should behave.  Here we call
	  the former one "listening side" and the latter one
	  "initiating side", for reference purposes.</para>

	<para>You can perform wildcard bind on both of the address
	  families, on the same port.</para>

	<para>The following table show the behavior of FreeBSD
	  4.x.</para>

	<screen>listening side          initiating side
                (AF_INET6 wildcard      (connection to ::ffff:10.1.1.1)
                socket gets IPv4 conn.)
                ---                     ---
FreeBSD 4.x     configurable            supported
                default: enabled</screen>

	<para>The following sections will give you more details, and
	  how you can configure the behavior.</para>

	<para>Comments on listening side:</para>

	<para>It looks that RFC2553 talks too little on wildcard bind
	  issue, especially on the port space issue, failure mode and
	  relationship between AF_INET/INET6 wildcard bind.  There can
	  be several separate interpretation for this RFC which
	  conform to it but behaves differently.  So, to implement
	  portable application you should assume nothing about the
	  behavior in the kernel.  Using &man.getaddrinfo.3; is the
	  safest way.  Port number space and wildcard bind issues were
	  discussed in detail on ipv6imp mailing list, in mid March
	  1999 and it looks that there is no concrete consensus
	  (means, up to implementers).  You may want to check the
	  mailing list archives.</para>

	<para>If a server application would like to accept IPv4 and
	  IPv6 connections, there will be two alternatives.</para>

	<para>One is using AF_INET and AF_INET6 socket (you will need
	  two sockets).  Use &man.getaddrinfo.3; with AI_PASSIVE into
	  ai_flags, and &man.socket.2; and &man.bind.2; to all the
	  addresses returned.  By opening multiple sockets, you can
	  accept connections onto the socket with proper address
	  family.  IPv4 connections will be accepted by AF_INET
	  socket, and IPv6 connections will be accepted by AF_INET6
	  socket.</para>

	<para>Another way is using one AF_INET6 wildcard bind socket.
	  Use &man.getaddrinfo.3; with AI_PASSIVE into ai_flags and
	  with AF_INET6 into ai_family, and set the 1st argument
	  hostname to NULL. And &man.socket.2; and &man.bind.2; to the
	  address returned.  (should be IPv6 unspecified addr).  You
	  can accept either of IPv4 and IPv6 packet via this one
	  socket.</para>

	<para>To support only IPv6 traffic on AF_INET6 wildcard binded
	  socket portably, always check the peer address when a
	  connection is made toward AF_INET6 listening socket.  If the
	  address is IPv4 mapped address, you may want to reject the
	  connection.  You can check the condition by using
	  IN6_IS_ADDR_V4MAPPED() macro.</para>

	<para>To resolve this issue more easily, there is system
	  dependent &man.setsockopt.2; option, IPV6_BINDV6ONLY, used
	  like below.</para>

	<programlisting>	int on;

	setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY,
		   (char *)&amp;on, sizeof (on)) &lt; 0));</programlisting>

	<para>When this call succeed, then this socket only receive
	  IPv6 packets.</para>

	<para>Comments on initiating side:</para>

	<para>Advise to application implementers: to implement a
	  portable IPv6 application (which works on multiple IPv6
	  kernels), we believe that the following is the key to the
	  success:</para>

	<itemizedlist>
	  <listitem>
	    <para>NEVER hardcode AF_INET nor AF_INET6.</para>
	  </listitem>

	  <listitem>
	    <para>Use &man.getaddrinfo.3; and &man.getnameinfo.3;
	      throughout the system.  Never use gethostby*(),
	      getaddrby*(), inet_*() or getipnodeby*().  (To update
	      existing applications to be IPv6 aware easily, sometime
	      getipnodeby*() will be useful.  But if possible, try to
	      rewrite the code to use &man.getaddrinfo.3; and
	      &man.getnameinfo.3;.)</para>
	  </listitem>

	  <listitem>
	    <para>If you would like to connect to destination, use
	      &man.getaddrinfo.3; and try all the destination
	      returned, like &man.telnet.1; does.</para>
	  </listitem>

	  <listitem>
	    <para>Some of the IPv6 stack is shipped with buggy
	      &man.getaddrinfo.3;.  Ship a minimal working version
	      with your application and use that as last
	      resort.</para>
	  </listitem>
	</itemizedlist>

	<para>If you would like to use AF_INET6 socket for both IPv4
	  and IPv6 outgoing connection, you will need to use
	  &man.getipnodebyname.3;.  When you would like to update your
	  existing application to be IPv6 aware with minimal effort,
	  this approach might be chosen.  But please note that it is a
	  temporal solution, because &man.getipnodebyname.3; itself is
	  not recommended as it does not handle scoped IPv6 addresses
	  at all.  For IPv6 name resolution, &man.getaddrinfo.3; is
	  the preferred API. So you should rewrite your application to
	  use &man.getaddrinfo.3;, when you get the time to do
	  it.</para>

	<para>When writing applications that make outgoing
	  connections, story goes much simpler if you treat AF_INET
	  and AF_INET6 as totally separate address family.
	  {set,get}sockopt issue goes simpler, DNS issue will be made
	  simpler.  We do not recommend you to rely upon IPv4 mapped
	  address.</para>

	<sect4>
	  <title>unified tcp and inpcb code</title>

	  <para>FreeBSD 4.x uses shared tcp code between IPv4 and IPv6
	    (from sys/netinet/tcp*) and separate udp4/6 code.  It uses
	    unified inpcb structure.</para>

	  <para>The platform can be configured to support IPv4 mapped
	    address.  Kernel configuration is summarized as
	    follows:</para>

	  <itemizedlist>
	    <listitem>
	      <para>By default, AF_INET6 socket will grab IPv4
		connections in certain condition, and can initiate
		connection to IPv4 destination embedded in IPv4 mapped
		IPv6 address.</para>
	    </listitem>

	    <listitem>
	      <para>You can disable it on entire system with sysctl
		like below.</para>

	      <para><command>sysctl
		  net.inet6.ip6.mapped_addr=0</command></para>
	    </listitem>
	  </itemizedlist>

	  <sect5>
	    <title>Listening Side</title>

	    <para>Each socket can be configured to support special
	      AF_INET6 wildcard bind (enabled by default).  You can
	      disable it on each socket basis with &man.setsockopt.2;
	      like below.</para>

	    <programlisting>	int on;

	setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY,
		   (char *)&amp;on, sizeof (on)) &lt; 0));</programlisting>

	    <para>Wildcard AF_INET6 socket grabs IPv4 connection if
	      and only if the following conditions are
	      satisfied:</para>

	    <itemizedlist>
	      <listitem>
		<para>there is no AF_INET socket that matches the IPv4
		  connection</para>
	      </listitem>

	      <listitem>
		<para>the AF_INET6 socket is configured to accept IPv4
		  traffic, i.e.,  getsockopt(IPV6_BINDV6ONLY) returns
		  0.</para>
	      </listitem>
	    </itemizedlist>

	    <para>There is no problem with open/close ordering.</para>
	  </sect5>

	  <sect5>
	    <title>Initiating Side</title>

	    <para>FreeBSD 4.x supports outgoing connection to IPv4
	      mapped address (::ffff:10.1.1.1), if the node is
	      configured to support IPv4 mapped address.</para>
	  </sect5>
	</sect4>
      </sect3>

      <sect3>
	<title>sockaddr_storage</title>

	<para>When RFC2553 was about to be finalized, there was
	  discussion on how struct sockaddr_storage members are named.
	  One proposal is to prepend "__" to the members (like
	  "__ss_len") as they should not be touched.  The other
	  proposal was not to prepend it (like "ss_len") as we need to
	  touch those members directly.  There was no clear consensus
	  on it.</para>

	<para>As a result, RFC2553 defines struct sockaddr_storage as
	  follows:</para>

	<programlisting>	struct sockaddr_storage {
		u_char	__ss_len;	/* address length */
		u_char	__ss_family;	/* address family */
		/* and bunch of padding */
	};</programlisting>

	<para>On the contrary, XNET draft defines as follows:</para>

	<programlisting>	struct sockaddr_storage {
		u_char	ss_len;		/* address length */
		u_char	ss_family;	/* address family */
		/* and bunch of padding */
	};</programlisting>

	<para>In December 1999, it was agreed that RFC2553bis should
	  pick the latter (XNET) definition.</para>

	<para>Current implementation conforms to XNET definition,
	  based on RFC2553bis discussion.</para>

	<para>If you look at multiple IPv6 implementations, you will
	  be able to see both definitions.  As an userland programmer,
	  the most portable way of dealing with it is to:</para>

	<orderedlist>
	  <listitem>
	    <para>ensure ss_family and/or ss_len are available on the
	      platform, by using GNU autoconf,</para>
	  </listitem>

	  <listitem>
	    <para>have -Dss_family=__ss_family to unify all
	      occurrences (including header file) into __ss_family,
	      or</para>
	  </listitem>

	  <listitem>
	    <para>never touch __ss_family.  cast to sockaddr * and use
	      sa_family like:</para>

	    <programlisting>	struct sockaddr_storage ss;
	family = ((struct sockaddr *)&amp;ss)-&gt;sa_family</programlisting>

	  </listitem>
	</orderedlist>
      </sect3>
    </sect2>

    <sect2>
      <title>Network Drivers</title>

      <para>Now following two items are required to be supported by
	standard drivers:</para>

      <orderedlist>
	<listitem>
	  <para>mbuf clustering requirement.  In this stable release,
	    we changed MINCLSIZE into MHLEN+1 for all the operating
	    systems in order to make all the drivers behave as we
	    expect.</para>
	</listitem>

	<listitem>
	  <para>multicast.  If &man.ifmcstat.8; yields no multicast
	    group for a interface, that interface has to be
	    patched.</para>
	</listitem>
      </orderedlist>

      <para>If any of the drivers do not support the requirements,
	then the drivers cannot be used for IPv6 and/or IPsec
	communication.  If you find any problem with your card using
	IPv6/IPsec, then, please report it to the &a.bugs;.</para>

      <para>(NOTE: In the past we required all PCMCIA drivers to have
	a call to in6_ifattach().  We have no such requirement any
	more)</para>
    </sect2>

    <sect2>
      <title>Translator</title>

      <para>We categorize IPv4/IPv6 translator into 4 types:</para>

      <itemizedlist>
	<listitem>
	  <para><emphasis>Translator A</emphasis> --- It is used in
	    the early stage of transition to make it possible to
	    establish a connection from an IPv6 host in an IPv6 island
	    to an IPv4 host in the IPv4 ocean.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Translator B</emphasis> --- It is used in
	    the early stage of transition to make it possible to
	    establish a connection from an IPv4 host in the IPv4 ocean
	    to an IPv6 host in an IPv6 island.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Translator C</emphasis> --- It is used in
	    the late stage of transition to make it possible to
	    establish a connection from an IPv4 host in an IPv4 island
	    to an IPv6 host in the IPv6 ocean.</para>
	</listitem>

	<listitem>
	  <para><emphasis>Translator D</emphasis> --- It is used in
	    the late stage of transition to make it possible to
	    establish a connection from an IPv6 host in the IPv6 ocean
	    to an IPv4 host in an IPv4 island.</para>
	</listitem>
      </itemizedlist>
    </sect2>

    <sect2 xml:id="ipsec-implementation">
      <title>IPsec</title>

      <para>IPsec is mainly organized by three components.</para>

      <orderedlist>
	<listitem>
	  <para>Policy Management</para>
	</listitem>

	<listitem>
	  <para>Key Management</para>
	</listitem>

	<listitem>
	  <para>AH and ESP handling</para>
	</listitem>
      </orderedlist>

      <sect3>
	<title>Policy Management</title>

	<para>The kernel implements experimental policy management
	  code.  There are two way to manage security policy.  One is
	  to configure per-socket policy using &man.setsockopt.2;.  In
	  this cases, policy configuration is described in
	  &man.ipsec.set.policy.3;.  The other is to configure kernel
	  packet filter-based policy using PF_KEY interface, via
	  &man.setkey.8;.</para>

	<para>The policy entry is not re-ordered with its indexes, so
	  the order of entry when you add is very significant.</para>
      </sect3>

      <sect3>
	<title>Key Management</title>

	<para>The key management code implemented in this kit
	  (sys/netkey) is a home-brew PFKEY v2 implementation.  This
	  conforms to RFC2367.</para>

	<para>The home-brew IKE daemon, "racoon" is included in the
	  kit (kame/kame/racoon).  Basically you will need to run
	  racoon as daemon, then set up a policy to require keys (like
	  <command>ping -P 'out ipsec esp/transport//use'</command>).
	  The kernel will contact racoon daemon as necessary to
	  exchange keys.</para>
      </sect3>

      <sect3>
	<title>AH and ESP Handling</title>

	<para>IPsec module is implemented as "hooks" to the standard
	  IPv4/IPv6 processing.  When sending a packet,
	  ip{,6}_output() checks if ESP/AH processing is required by
	  checking if a matching SPD (Security Policy Database) is
	  found.  If ESP/AH is needed, {esp,ah}{4,6}_output() will be
	  called and mbuf will be updated accordingly.  When a packet
	  is received, {esp,ah}4_input() will be called based on
	  protocol number, i.e., (*inetsw[proto])().
	  {esp,ah}4_input() will decrypt/check authenticity of the
	  packet, and strips off daisy-chained header and padding for
	  ESP/AH.  It is safe to strip off the ESP/AH header on packet
	  reception, since we will never use the received packet in
	  "as is" form.</para>

	<para>By using ESP/AH, TCP4/6 effective data segment size will
	  be affected by extra daisy-chained headers inserted by
	  ESP/AH.  Our code takes care of the case.</para>

	<para>Basic crypto functions can be found in directory
	  "sys/crypto".  ESP/AH transform are listed in
	  {esp,ah}_core.c with wrapper functions.  If you wish to add
	  some algorithm, add wrapper function in {esp,ah}_core.c, and
	  add your crypto algorithm code into sys/crypto.</para>

	<para>Tunnel mode is partially supported in this release, with
	  the following restrictions:</para>

	<itemizedlist>
	  <listitem>
	    <para>IPsec tunnel is not combined with GIF generic
	      tunneling interface.  It needs a great care because we
	      may create an infinite loop between ip_output() and
	      tunnelifp-&gt;if_output().  Opinion varies if it is
	      better to unify them, or not.</para>
	  </listitem>

	  <listitem>
	    <para>MTU and Don't Fragment bit (IPv4) considerations
	      need more checking, but basically works fine.</para>
	  </listitem>

	  <listitem>
	    <para>Authentication model for AH tunnel must be
	      revisited.  We will need to improve the policy
	      management engine, eventually.</para>
	  </listitem>
	</itemizedlist>
      </sect3>

      <sect3>
	<title>Conformance to RFCs and IDs</title>

	<para>The IPsec code in the kernel conforms (or, tries to
	  conform) to the following standards:</para>

	<para>"old IPsec" specification documented in
	  <filename>rfc182[5-9].txt</filename></para>

	<para>"new IPsec" specification documented in
	  <filename>rfc240[1-6].txt</filename>,
	  <filename>rfc241[01].txt</filename>,
	  <filename>rfc2451.txt</filename> and
	  <filename>draft-mcdonald-simple-ipsec-api-01.txt</filename>
	  (draft expired, but you can take from <link
	    xlink:href="ftp://ftp.kame.net/pub/internet-drafts/">
	    ftp://ftp.kame.net/pub/internet-drafts/</link>).  (NOTE:
	  IKE specifications, <filename>rfc241[7-9].txt</filename> are
	  implemented in userland, as "racoon" IKE daemon)</para>

	<para>Currently supported algorithms are:</para>
	<itemizedlist>
	  <listitem>
	    <para>old IPsec AH</para>
	    <itemizedlist>
	      <listitem>
		<para>null crypto checksum (no document, just for
		  debugging)</para>
	      </listitem>
	      <listitem>
		<para>keyed MD5 with 128bit crypto checksum
		  (<filename>rfc1828.txt</filename>)</para>
	      </listitem>
	      <listitem>
		<para>keyed SHA1 with 128bit crypto checksum (no
		  document)</para>
	      </listitem>
	      <listitem>
		<para>HMAC MD5 with 128bit crypto checksum
		  (<filename>rfc2085.txt</filename>)</para>
	      </listitem>
	      <listitem>
		<para>HMAC SHA1 with 128bit crypto checksum (no
		  document)</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>old IPsec ESP</para>
	    <itemizedlist>
	      <listitem>
		<para>null encryption (no document, similar to
		  <filename>rfc2410.txt</filename>)</para>
	      </listitem>
	      <listitem>
		<para>DES-CBC mode
		  (<filename>rfc1829.txt</filename>)</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>new IPsec AH</para>
	    <itemizedlist>
	      <listitem>
		<para>null crypto checksum (no document, just for
		  debugging)</para>
	      </listitem>
	      <listitem>
		<para>keyed MD5 with 96bit crypto checksum (no
		  document)</para>
	      </listitem>
	      <listitem>
		<para>keyed SHA1 with 96bit crypto checksum (no
		  document)</para>
	      </listitem>
	      <listitem>
		<para>HMAC MD5 with 96bit crypto checksum
		  (<filename>rfc2403.txt</filename>)</para>
	      </listitem>
	      <listitem>
		<para>HMAC SHA1 with 96bit crypto checksum
		  (<filename>rfc2404.txt</filename>)</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>

	  <listitem>
	    <para>new IPsec ESP</para>
	    <itemizedlist>
	      <listitem>
		<para>null encryption
		  (<filename>rfc2410.txt</filename>)</para>
	      </listitem>
	      <listitem>
		<para>DES-CBC with derived IV
		  (<filename>draft-ietf-ipsec-ciph-des-derived-01.txt</filename>,
		  draft expired)</para>
	      </listitem>
	      <listitem>
		<para>DES-CBC with explicit IV
		  (<filename>rfc2405.txt</filename>)</para>
	      </listitem>
	      <listitem>
		<para>3DES-CBC with explicit IV
		  (<filename>rfc2451.txt</filename>)</para>
	      </listitem>
	      <listitem>
		<para>BLOWFISH CBC
		  (<filename>rfc2451.txt</filename>)</para>
	      </listitem>
	      <listitem>
		<para>CAST128 CBC
		  (<filename>rfc2451.txt</filename>)</para>
	      </listitem>
	      <listitem>
		<para>RC5 CBC
		  (<filename>rfc2451.txt</filename>)</para>
	      </listitem>
	      <listitem>
		<para>each of the above can be combined with:</para>
		<itemizedlist>
		  <listitem>
		    <para>ESP authentication with
		      HMAC-MD5(96bit)</para>
		  </listitem>
		  <listitem>
		    <para>ESP authentication with
		      HMAC-SHA1(96bit)</para>
		  </listitem>
		</itemizedlist>
	      </listitem>
	    </itemizedlist>
	  </listitem>
	</itemizedlist>

	<para>The following algorithms are NOT supported:</para>
	<itemizedlist>
	  <listitem>

	    <para>old IPsec AH</para>

	    <itemizedlist>
	      <listitem>
		<para>HMAC MD5 with 128bit crypto checksum + 64bit
		  replay prevention
		  (<filename>rfc2085.txt</filename>)</para>
	      </listitem>
	      <listitem>
		<para>keyed SHA1 with 160bit crypto checksum + 32bit
		  padding (<filename>rfc1852.txt</filename>)</para>
	      </listitem>
	    </itemizedlist>
	  </listitem>
	</itemizedlist>

	<para>IPsec (in kernel) and IKE (in userland as "racoon") has
	  been tested at several interoperability test events, and it
	  is known to interoperate with many other implementations
	  well.  Also, current IPsec implementation as quite wide
	  coverage for IPsec crypto algorithms documented in RFC (we
	  cover algorithms without intellectual property issues
	  only).</para>
      </sect3>

      <sect3 xml:id="ipsec-ecn">
	<title>ECN Consideration on IPsec Tunnels</title>

	<para>ECN-friendly IPsec tunnel is supported as described in
	  <filename>draft-ipsec-ecn-00.txt</filename>.</para>

	<para>Normal IPsec tunnel is described in RFC2401.  On
	  encapsulation, IPv4 TOS field (or, IPv6 traffic class field)
	  will be copied from inner IP header to outer IP header.  On
	  decapsulation outer IP header will be simply dropped.  The
	  decapsulation rule is not compatible with ECN, since ECN bit
	  on the outer IP TOS/traffic class field will be lost.</para>

	<para>To make IPsec tunnel ECN-friendly, we should modify
	  encapsulation and decapsulation procedure.  This is
	  described in <link
	    xlink:href="http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt">
	    http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt</link>,
	  chapter 3.</para>

	<para>IPsec tunnel implementation can give you three
	  behaviors, by setting net.inet.ipsec.ecn (or
	  net.inet6.ipsec6.ecn) to some value:</para>

	<itemizedlist>
	  <listitem>
	    <para>RFC2401: no consideration for ECN (sysctl value
	      -1)</para>
	  </listitem>
	  <listitem>
	    <para>ECN forbidden (sysctl value 0)</para>
	  </listitem>
	  <listitem>
	    <para>ECN allowed (sysctl value 1)</para>
	  </listitem>
	</itemizedlist>

	<para>Note that the behavior is configurable in per-node
	  manner, not per-SA manner (draft-ipsec-ecn-00 wants per-SA
	  configuration, but it looks too much for me).</para>

	<para>The behavior is summarized as follows (see source code
	  for more detail):</para>

	<screen>encapsulate                     decapsulate
                ---                             ---
RFC2401         copy all TOS bits               drop TOS bits on outer
                from inner to outer.            (use inner TOS bits as is)

ECN forbidden   copy TOS bits except for ECN    drop TOS bits on outer
                (masked with 0xfc) from inner   (use inner TOS bits as is)
                to outer.  set ECN bits to 0.

ECN allowed     copy TOS bits except for ECN    use inner TOS bits with some
                CE (masked with 0xfe) from      change.  if outer ECN CE bit
                inner to outer.                 is 1, enable ECN CE bit on
                set ECN CE bit to 0.            the inner.</screen>

	<para>General strategy for configuration is as follows:</para>
	<itemizedlist>
	  <listitem>
	    <para>if both IPsec tunnel endpoint are capable of
	      ECN-friendly behavior, you should better configure both
	      end to <quote>ECN allowed</quote> (sysctl value
	      1).</para>
	  </listitem>
	  <listitem>
	    <para>if the other end is very strict about TOS bit, use
	      "RFC2401" (sysctl value -1).</para>
	  </listitem>
	  <listitem>
	    <para>in other cases, use "ECN forbidden" (sysctl value
	      0).</para>
	  </listitem>
	</itemizedlist>

	<para>The default behavior is "ECN forbidden" (sysctl value
	  0).</para>

	<para>For more information, please refer to:</para>

	<para><link
	    xlink:href="http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt">
	    http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt</link>,
	  RFC2481 (Explicit Congestion Notification),
	  src/sys/netinet6/{ah,esp}_input.c</para>

	<para>(Thanks goes to Kenjiro Cho
	  <email>kjc@csl.sony.co.jp</email> for detailed
	  analysis)</para>
      </sect3>

      <sect3>
	<title>Interoperability</title>

	<para>Here are (some of) platforms that KAME code have tested
	  IPsec/IKE interoperability in the past.  Note that both ends
	  may have modified their implementation, so use the following
	  list just for reference purposes.</para>

	<para>Altiga, Ashley-laurent (vpcom.com), Data Fellows
	  (F-Secure), Ericsson ACC, FreeS/WAN, HITACHI, IBM &aix;,
	  IIJ, Intel, &microsoft; &windowsnt;, NIST (linux IPsec +
	  plutoplus), Netscreen, OpenBSD, RedCreek, Routerware, SSH,
	  Secure Computing, Soliton, Toshiba, VPNet, Yamaha
	  RT100i</para>
      </sect3>
    </sect2>
  </sect1>
</chapter>