/
IMPLEMENTATION
1740 lines (1447 loc) · 76.4 KB
/
IMPLEMENTATION
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
Implementation Note
KAME Project
http://www.kame.net/
$KAME: IMPLEMENTATION,v 1.168 2000/12/11 05:08:27 itojun Exp $
1. IPv6
1.1 Conformance
The KAME kit conforms, or tries to conform, to the latest set of IPv6
specifications. For future reference we list some of the relevant documents
below (NOTE: this is not a complete list - this is too hard to maintain...).
For details please refer to specific chapter in the document, RFCs, manpages
come with KAME, or comments in the source code.
Conformance tests have been performed on past and latest KAME STABLE kit,
at TAHI project. Results can be viewed at http://www.tahi.org/report/KAME/.
We also attended Univ. of New Hampshire IOL tests (http://www.iol.unh.edu/)
in the past, with our past snapshots.
RFC1639: FTP Operation Over Big Address Records (FOOBAR)
* RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428,
then RFC1639 if failed.
RFC1886: DNS Extensions to support IPv6
RFC1933: (see RFC2893)
RFC1981: Path MTU Discovery for IPv6
RFC2080: RIPng for IPv6
* KAME-supplied route6d, bgpd and hroute6d support this.
RFC2283: Multiprotocol Extensions for BGP-4
* so-called "BGP4+".
* KAME-supplied bgpd supports this.
RFC2292: Advanced Sockets API for IPv6
* For supported library functions/kernel APIs, see sys/netinet6/ADVAPI.
RFC2362: Protocol Independent Multicast-Sparse Mode (PIM-SM)
* RFC2362 defines packet formats for PIM-SM. draft-ietf-pim-ipv6-01.txt
is written based on this.
RFC2373: IPv6 Addressing Architecture
* KAME supports node required addresses, and conforms to the scope
requirement.
RFC2374: An IPv6 Aggregatable Global Unicast Address Format
* KAME supports 64-bit length of Interface ID.
RFC2375: IPv6 Multicast Address Assignments
* Userland applications use the well-known addresses assigned in the RFC.
RFC2428: FTP Extensions for IPv6 and NATs
* RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428,
then RFC1639 if failed.
RFC2460: IPv6 specification
RFC2461: Neighbor discovery for IPv6
* See 1.2 in this document for details.
RFC2462: IPv6 Stateless Address Autoconfiguration
* See 1.4 in this document for details.
RFC2463: ICMPv6 for IPv6 specification
* See 1.8 in this document for details.
RFC2464: Transmission of IPv6 Packets over Ethernet Networks
RFC2465: MIB for IPv6: Textual Conventions and General Group
* Necessary statistics are gathered by the kernel. Actual IPv6 MIB
support is provided as patchkit for ucd-snmp.
RFC2466: MIB for IPv6: ICMPv6 group
* Necessary statistics are gathered by the kernel. Actual IPv6 MIB
support is provided as patchkit for ucd-snmp.
RFC2467: Transmission of IPv6 Packets over FDDI Networks
RFC2472: IPv6 over PPP
RFC2492: IPv6 over ATM Networks
* only PVC is supported.
RFC2497: Transmission of IPv6 packet over ARCnet Networks
RFC2545: Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing
RFC2553: Basic Socket Interface Extensions for IPv6
* IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind
socket (3.8) are,
- supported and turned on by default on KAME/FreeBSD[34]x
and KAME/BSDI4,
- supported but turned off by default on KAME/NetBSD,
- not supported on KAME/FreeBSD228, KAME/OpenBSD and KAME/BSDI3.
see 1.12 in this document for details.
RFC2671: Extension Mechanisms for DNS (EDNS0)
* see USAGE for how to use it.
* not supported on kame/freebsd4 and kame/bsdi4.
RFC2675: IPv6 Jumbograms
* See 1.7 in this document for details.
RFC2710: Multicast Listener Discovery for IPv6
RFC2711: IPv6 router alert option
RFC2732: Format for Literal IPv6 Addresses in URL's
* The spec is implemented in programs that handle URLs
(like freebsd ftpio(3) and fetch(1), or netbsd ftp(1))
RFC2766: Network Address Translation - Protocol Translation (NAT-PT)
* Section 4.2 is implemented by totd (see ports/totd, or pkgsrc/net/totd).
RFC2893: Transition Mechanisms for IPv6 Hosts and Routers
* IPv4 compatible address is not supported.
* automatic tunneling (4.3) is not supported.
* "gif" interface implements IPv[46]-over-IPv[46] tunnel in a generic way,
and it covers "configured tunnel" described in the spec.
See 1.5 in this document for details.
RFC2894: Router renumbering for IPv6
draft-ietf-ipngwg-icmp-name-lookups-07: IPv6 Name Lookups Through ICMP
draft-ietf-pim-ipv6-03.txt: PIM for IPv6
* pim6dd implements dense mode. pim6sd implements sparse mode.
draft-ietf-dhc-dhcpv6-15.txt: DHCPv6
draft-ietf-dhc-dhcpv6exts-12.txt: Extensions for DHCPv6
* kame/dhcp6 has test implementation, which will not be compiled in
default compilation.
* 15/12 drafts are not explicit about padding and string termination.
at IETF48, the author confirmed that there's no padding/termination
(and extensions can appear unaligned). our code follows the comment.
draft-itojun-ipv6-tcp-to-anycast-00.txt:
Disconnecting TCP connection toward IPv6 anycast address
draft-ietf-ipngwg-scopedaddr-format-02.txt:
An Extension of Format for IPv6 Scoped Addresses
* A revised version of the basic API to support scoped addresses.
draft-ietf-ipngwg-rfc2553bis-00.txt:
Basic Socket Interface Extensions for IPv6 (revised)
draft-ietf-ipngwg-rfc2292bis-01.txt:
Advanced Sockets API for IPv6 (revised)
* Some of the updates in the draft are not implemented yet. See
TODO.2292bis for more details.
draft-ietf-ngtrans-tcpudp-relay-01.txt:
An IPv6-to-IPv4 transport relay translator
* FAITH tcp relay translator (faithd) implements this. See 3.1 for more
details.
draft-ietf-ngtrans-6to4-06.txt:
Connection of IPv6 Domains via IPv4 Clouds without Explicit Tunnels
* "stf" interface implements it. Be sure to read the next item before
configuring it, there are security issues.
draft-itojun-ipv6-transition-abuse-01.txt:
Possible abuse against IPv6 transition technologies
* KAME does not implement RFC1933/2893 automatic tunnel.
* "stf" interface implements some address filters. Refer to stf(4)
for details. Since there's no way to make 6to4 interface 100% secure,
we do not include "stf" interface into GENERIC.v6 compilation.
* kame/openbsd completely disables IPv4 mapped address support.
* kame/netbsd makes IPv4 mapped address support off by default.
* See section 1.12.6 and 1.14 for more details.
draft-aboba-dnsext-mdns-00.txt: Multicast DNS
* kame/mdnsd has test implementation, which will not be built in
default compilation. The draft will experience a major change in the
near future, so don't rely upon it.
draft-itojun-ipv6-tclass-api-01.txt: Socket API for IPv6 traffic class field
draft-itojun-ipv6-flowlabel-api-01.txt: Socket API for IPv6 flow label field
* no consideration is made against the use of routing headers and such.
1.2 Neighbor Discovery
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 Unsolicited Neighbor
Advertisement transmission command as admin tool.
Duplicated Address Detection (DAD) will be performed when an IPv6 address
is assigned to a network interface, or the network interface is enabled
(ifconfig up). It is documented in RFC2462 5.4.
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 ifconfig. It is administrators' responsibility to check
for and recover from DAD failures. We may try to improve failure recovery
in future KAME code.
DAD procedure may not be effective on certain network interfaces/drivers.
If a network driver needs long initialization time (with wireless network
interfaces this situation is popular), and the driver mistakingly raises
IFF_RUNNING before the driver becomes ready, DAD code will try to transmit
DAD probes to not-really-ready network driver and the packet will not go out
from the interface. In such cases, network drivers should be corrected.
Some of network drivers loop multicast packets back to themselves,
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.
In this case, drivers should be corrected to honor IFF_SIMPLEX behavior.
For example, you may need to check source MAC address on a inbound packet,
and reject it if it is from the node itself.
You may also 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).
Neighbor Discovery specification (RFC2461) does not talk about neighbor
cache handling in the following cases:
(1) when there was no neighbor cache entry, node received unsolicited
RS/NS/NA/redirect packet without link-layer address
(2) neighbor cache handling on medium without link-layer address
(we need a neighbor cache entry for IsRouter bit)
For (1), 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.
IPv6 on-link determination rule (RFC2461) is quite different from assumptions
in BSD IPv4 network code. To implement behavior in RFC2461 section 5.2
(when default router list is empty), the kernel needs to know the default
outgoing interface. To configure the default outgoing interface, use
commands like "ndp -I de0" as root. Note that the spec misuse the word
"host" and "node" in several places in the section.
To avoid possible DoS attacks and infinite loops, KAME stack will accept
only 10 options on ND packet. Therefore, if you have 20 prefix options
attached to RA, only the first 10 prefixes will be recognized.
If this troubles you, please contact KAME team and/or modify
nd6_maxndopt in sys/netinet6/nd6.c. If there are high demands we may
provide sysctl knob for the variable.
Proxy Neighbor Advertisement support is implemented in the kernel.
For instance, you can configure it by using the following command:
# ndp -s fe80::1234%ne0 0:1:2:3:4:5 proxy
where ne0 is the interface which attaches to the same link as the
proxy target.
There are certain limitations, though:
- It does not send unsolicited multicast NA on configuration. This is MAY
behavior in RFC2461.
- It does not add random delay before transmission of solicited NA. This is
SHOULD behavior in RFC2461.
- We cannot configure proxy NDP for off-link address. The target address for
proxying must be link-local address, or must be in prefixes configured to
node which does proxy NDP.
- RFC2461 is unclear about if it is legal for a host to perform proxy ND.
We do not prohibit hosts from doing proxy ND, but there will be very limited
use in it.
Starting mid March 2000, we support Neighbor Unreachability Detection (NUD)
on p2p interfaces, including tunnel interfaces (gif). NUD is turned on by
default. Before March 2000 KAME stack did not perform NUD on p2p interfaces.
If the change raises any interoperability issues, you can turn off/on NUD
by per-interface basis. Use "ndp -i interface -nud" to turn it off.
Consult ndp(8) for details.
RFC2461 specifies upper-layer reachability confirmation hint. Whenever
upper-layer reachability confirmation hint comes, ND process can use it
to optimize neighbor discovery process - ND process can omit real ND exchange
and keep the neighbor cache state in REACHABLE.
We currently have two sources for hints: (1) setsockopt(IPV6_REACHCONF)
defined by 2292bis API, and (2) hints from tcp_input.
It is questionable if they are really trustworthy. For example, a rogue
userland program can use IPV6_REACHCONF to confuse ND process. Neighbor
cache is a system-wide information pool, and it is bad to allow single process
to affect others. Also, tcp_input can be hosed by hijack attempts. It is
wrong to allow hijack attempts to affect ND process.
Starting June 2000, ND code has a protection mechanism against incorrect
upper-layer reachability confirmation. ND code counts subsequent upper-layer
hints. If the number of hints reaches maximum, ND code will ignore further
upper-layer hints and run real ND process to confirm reachability to the peer.
sysctl net.inet6.icmp6.nd6_maxnudhint defines maximum # of subsequent
upper-layer hints to be accepted.
(from April 2000 to June 2000, we rejected setsockopt(IPV6_REACHCONF) from
non-root process - after local discussion, it looks that hints are not
that trustworthy even if they are from privileged processes)
1.3 Scope Index
IPv6 uses scoped addresses. It is therefore very important to
specify scope index (link index for link-local address, or
site index for site-local address) with an IPv6 address. Without
scope index, a scoped IPv6 address is ambiguous to the kernel, and
the kernel will not be able to determine the outbound interface for a
packet. KAME code tries to address the issue in several ways.
Site-local address is very vaguely defined in the specs, and both specification
and KAME code need tons of improvements to enable its actual use.
For example, it is still very unclear how we define a site, or how we resolve
hostnames in a site. There are work underway to define behavior of routers
at site border, however, we have almost no code for site boundary node support
(both forwarding nor routing) and we bet almost noone has.
We recommend, at this moment, you to use global addresses for experiments -
there are way too many pitfalls if you use site-local addresses.
1.3.1 Kernel internal
In the kernel, the interface index for a link-local scope address is
embedded into the 2nd 16bit-word (the 3rd and 4th bytes) in the IPv6
address.
For example, you may see something like:
fe80:1::200:f8ff:fe01:6317
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.
1.3.2 Interaction with API
Ordinary userland applications should use the advanced API (RFC2292)
to specify scope index, or interface index. For the similar purpose,
the sin6_scope_id member in the 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 the advanced API rather than sin6_scope_id.
Routing daemons and configuration programs, like route6d and
ifconfig, 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.
getaddrinfo(3) and getnameinfo(3) are modified to support extended numeric
IPv6 syntax, as documented in draft-ietf-ipngwg-scopedaddr-format-xx.txt.
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.
To use this extension in your program, you'll need to use getaddrinfo(3),
and getnameinfo(3) with NI_WITHSCOPEID.
The implementation currently assumes 1-to-1 relationship between a link and an
interface, which is stronger than what IPv6 specs say.
Other APIs like inet_pton(3) or getipnodebyname(3) are inherently unfriendly
with scoped addresses, since they are unable to annotate addresses with
scope identifier.
1.3.3 Interaction with users (command line)
Most of user applications now support an extended numeric IPv6 syntax,
as documented in draft-ietf-ipngwg-scopedaddr-format-xx.txt. In this
case, you can specify outgoing link, by using the name of the outgoing
interface like "fe80::1%ne0". This is the case for some management
tools such as route(8) or ndp(8). For example, to install the IPv6
default route by hand, you can type like
# route add -inet6 default fe80::9876:5432:1234:abcd%ne0
(Although we suggest you to run dynamic routing instead of static
routes, in order to avoid configuration mistakes.)
Some applications have command line options for specifying an
appropriate zone of a scoped address (like "ping6 -I ne0 ff02::1" to
specify the outgoing interface). However, you can't always expect such
options. Thus, we recommend you to use the extended format described
above.
In any case, when you specify a scoped address to the command line,
NEVER write the embedded form (such as ff02:1::1 or fe80:2::fedc),
which should only be used inside the kernel (see Section 1.3.1), and
is not supposed to work.
1.4 Plug and Play
The KAME kit implements most of the IPv6 stateless address
autoconfiguration 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.
1.4.1 Assignment of link-local, and special addresses
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.
Here is an output of netstat command:
Internet6:
Destination Gateway Flags Netif Expire
fe80::%ed0/64 link#1 UC ed0
fe80::%ep0/64 link#2 UC ep0
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, last-resort pseudorandom value,
which is from 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.
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.
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.
1.4.2 Stateless address autoconfiguration on hosts
In IPv6 specification, nodes are separated into two categories:
routers and hosts. Routers forward packets addressed to others, hosts does
not forward the packets. net.inet6.ip6.forwarding defines whether this
node is a router or a host (router if it is 1, host if it is 0).
It is NOT recommended to change net.inet6.ip6.forwarding while the node
is in operation. IPv6 specification defines behavior for "host" and "router"
quite differently, and switching from one to another can cause serious
troubles. It is recommended to configure the variable at bootstrap time only.
The first step in stateless address configuration is Duplicated Address
Detection (DAD). See 1.2 for more detail on DAD.
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. The 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 an RS packet at any time, use the
"rtsol" command. The "rtsold" daemon is also available. "rtsold"
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.
To generate Router Advertisement from a router, use the "rtadvd" daemon.
Note that the IPv6 specification assumes the following items and that
nonconforming cases are left unspecified:
- Only hosts will listen to router advertisements
- Hosts have single network interface (except loopback)
This is therefore unwise to enable net.inet6.ip6.accept_rtadv on routers,
or multi-interface host. A misconfigured node can behave strange
(KAME code allows nonconforming configuration, for those who would like
to do some experiments).
To summarize the sysctl knob:
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, autoconfigred host with
multiple interface is out-of-scope)
1 1 invalid, or experimental
(out-of-scope of spec)
See 1.2 in the document for relationship between DAD and autoconfiguration.
1.4.3 DHCPv6
We supply a tiny DHCPv6 server/client in kame/dhcp6. However, the
implementation is premature (for example, this does NOT implement
address lease/release), and it is not in default compilation tree on
some platforms. If you want to do some experiment, compile it on your
own.
DHCPv6 and autoconfiguration also needs more work. "Managed" and "Other"
bits in RA have no special effect to stateful autoconfiguration procedure
in DHCPv6 client program ("Managed" bit actually prevents stateless
autoconfiguration, but no special action will be taken for DHCPv6 client).
1.5 Generic tunnel interface
GIF (Generic InterFace) is a pseudo interface for configured tunnel.
Details are described in gif(4) manpage.
Currently
v6 in v6
v6 in v4
v4 in v6
v4 in v4
are available. Use "gifconfig" 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. Please be warned.
gif can be configured to be ECN-friendly. See 4.5 for ECN-friendliness
of tunnels, and gif(4) manpage for how to configure.
If you would like to configure an IPv4-in-IPv6 tunnel with gif interface,
read gif(4) carefully. You may need to remove IPv6 link-local address
automatically assigned to the gif interface.
1.6 Source Address Selection
KAME's source address selection takes care of the following
conditions:
- address scope
- prefix matching against the destination
- outgoing interface
- whether an address is deprecated
Roughly speaking, the selection policy is as follows:
- always use an address that belongs to the same scope zone as the
destination.
- addresses that have equal or larger scope than the scope of the
destination are preferred.
- if multiple addresses have the equal scope, one which is longest
prefix matching against the destination is preferred.
- a deprecated address is not used in new communications if an
alternate (non-deprecated) address is available and has sufficient
scope.
- if none of above conditions tie-breaks, addresses assigned on the
outgoing interface are preferred.
For instance, ::1 is selected for ff01::1,
fe80::200:f8ff:fe01:6317%ne0 for fe80::2a0:24ff:feab:839b%ne0.
To see how longest-matching works, suppose that
3ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317
are given on the outgoing interface. Then the former is chosen as the
source for the destination 3ffe:501:800::1. Note that even if all
available addresses have smaller scope than the scope of the
destination, we choose one anyway. For example, if we have link-local
and site-local addresses only, we choose a site-local addresses for a
global destination. If the packet is going to break a site boundary,
the boundary router will return an ICMPv6 destination unreachable
error with code 2 - beyond scope of source address.
The precise desripction of the algorithm is quite complicated. To
describe the algorithm, we introduce the following notation:
For a given destination D,
samescope(D): A set of addresses that have the same scope as D.
largerscope(D): A set of addresses that have a larger scope than D.
smallerscope(D): A set of addresses that have a smaller scope than D.
For a given set of addresses A,
DEP(A): a set of deprecated addresses in A.
nonDEP(A): A - DEP(A).
Also, the algorithm assumes that the outgoing interface for the
destination D is determined. We call the interface "I".
The algorithm is as follows. Selection proceeds step by step as
described; For example, if an address is selected by item 1, item 2 or
later are not considered at all.
0. If there is no address in the same scope zone as D, just give up;
the packet will not be sent.
1. If nonDEP(samescope(D)) is not empty,
choose a longest matching address against D. If more than one
address is longest matching, choose arbitrary one provided that
an address on I is always preferred.
2. If nonDEP(largerscope(D)) is not empty,
choose an address that has the smallest scope. If more than one
address has the smallest scope, choose arbitrary one provided
that an address on I is always preferred.
3. If DEP(samescope(D)) is not empty,
choose a longest matching address against D. If more than one
address is longest matching, choose arbitrary one provided that
an address on I is always preferred.
4. If DEP(largerscope(D)) is not empty,
choose an address that has the smallest scope. If more than one
address has the smallest scope, choose arbitrary one provided
that an address on I is always preferred.
5. if nonDEP(smallerscope(D)) is not empty,
choose an address that has the largest scope. If more than one
address has the largest scope, choose arbitrary one provided
that an address on I is always preferred.
6. if DEP(smallerscope(D)) is not empty,
choose an address that has the largest scope. If more than one
address has the largest scope, choose arbitrary one provided
that an address on I is always preferred.
There exists a document about source address selection
(draft-ietf-ipngwg-default-addr-select-xx.txt). KAME's algorithm
described above takes a similar approach to the document, but there
are some differences. See the document for more details.
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 TCP
protocol control block (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.
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).
1.7 Jumbo Payload
KAME supports the Jumbo Payload hop-by-hop option used to send IPv6
packets with payloads longer than 65,535 octets. But since currently
KAME does not support any physical interface whose MTU is more than
65,535, such payloads can be seen only on the loopback interface(i.e.
lo0).
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:
options "LARGE_LOMTU" #To test jumbo payload
and recompile the new kernel.
Then you can test jumbo payloads by the ping6 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;
% ping6 -b 70000 -s 68000 ::1
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. KAME kernel follows the specification, but you cannot usually
see an ICMPv6 error caused by this requirement.
If KAME kernel receives an IPv6 packet, it checks the frame length of
the packet and compares it 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, KAME kernel
discards the packet and increments the statistics. You can see the
statistics as output of netstat command with `-s -p ip6' option:
% netstat -s -p ip6
ip6:
(snip)
1 with data size < data length
So, KAME 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, KAME kernel currently does not
support physical interface with such a huge MTU, so it rarely returns an
ICMPv6 error.
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.
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).
There are fundamental issues in *BSD support for jumbograms. We would like to
address those, but we need more time to finalize the task. To name a few:
- mbuf pkthdr.len field is typed as "int" in 4.4BSD, so it cannot hold
jumbogram with len > 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).
- We mistakingly use "int" to hold packet length in many places. We need
to convert them into larger numeric type. It needs a great care, as we may
experience overflow during packet length computation.
- 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.
- TCP code needs careful updates in bunch of places, of course.
1.8 Loop prevention in header processing
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. KAME sys/netinet6 code
is carefully designed to avoid kernel stack overflow. Because of
this, KAME sys/netinet6 code defines its own protocol switch
structure, as "struct ip6protosw" (see netinet6/ip6protosw.h).
In addition to this, we restrict the number of extension headers
(including the IPv6 header) in each incoming packet, in order to
prevent a DoS attack that tries to send packets with a massive number
of extension headers. The upper limit can be configured by the sysctl
value net.inet6.ip6.hdrnestlimit. In particular, if the value is 0,
the node will allow an arbitrary number of headers. As of writing this
document, the default value is 50.
IPv4 part (sys/netinet) remains untouched for compatibility.
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.
1.9 ICMPv6
After RFC2463 was published, IETF ipngwg has decided to disallow ICMPv6 error
packet against ICMPv6 redirect, to prevent ICMPv6 storm on a network medium.
KAME already implements this into the kernel.
RFC2463 requires rate limitation for ICMPv6 error packets generated by a
node, to avoid possible DoS attacks. KAME kernel implements two rate-
limitation mechanisms, tunable via sysctl:
- Minimum time interval between ICMPv6 error packets
KAME kernel will generate no more than one ICMPv6 error packet,
during configured time interval. net.inet6.icmp6.errratelimit
controls the interval (default: disabled).
- Maximum ICMPv6 error packet-per-second
KAME kernel will generate no more than the configured number of
packets in one second. net.inet6.icmp6.errppslimit controls the
maximum packet-per-second value (default: 200pps)
Basically, we need to pick values that are suitable against the bandwidth
of link layer devices directly attached to the node. In some cases the
default values may not fit well. We are still unsure if the default value
is sane or not. Comments are welcome.
1.10 Applications
For userland programming, we support IPv6 socket API as specified in
RFC2553, RFC2292 and upcoming internet drafts.
TCP/UDP over IPv6 is available and quite stable. You can enjoy "telnet",
"ftp", "rlogin", "rsh", "ssh", etc. These applications are protocol
independent. That is, they automatically chooses IPv4 or IPv6
according to DNS.
1.11 Kernel Internals
(*) TCP/UDP part is handled differently between operating system platforms.
See 1.12 for details.
The current KAME has escaped from the IPv4 netinet logic. While
ip_forward() calls ip_output(), ip6_forward() directly calls
if_output() since routers must not divide IPv6 packets into fragments.
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 TCP6 never convert network byte
order into host byte order, to save the original packet.
tcp6_input(), udp6_input() and icmp6_input() can't 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 UDP/IP6
header structure don't exist for checksum calculation.
To process IP6 header, extension headers and transport headers easily,
KAME requires network drivers to store packets in one internal mbuf or
one or more external mbufs. A typical old driver prepares two
internal mbufs for 100 - 208 bytes data, however, KAME's reference
implementation stores it in one external mbuf.
"netstat -s -p ip6" tells you whether or not your driver conforms
KAME's requirement. In the following example, "cce0" violates the
requirement. (For more information, refer to Section 2.)
Mbuf statistics:
317 one mbuf
two or more mbuf::
lo0 = 8
cce0 = 10
3282 one ext mbuf
0 two or more ext mbuf
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.
TCP6 reassembly makes use of IP6 header to store reassemble
information. IP6 is not supposed to be just before TCP6, so
ip6tcpreass structure has a pointer to TCP6 header. Of course, it has
also a pointer back to mbuf to avoid m_pullup().
Like TCP6, both IP and IP6 reassemble functions never call m_pullup().
xxx_ctlinput() calls in_mrejoin() on PRC_IFNEWADDR. We think this is
one of 4.4BSD implementation flaws. Since 4.4BSD keeps ia_multiaddrs
in in_ifaddr{}, it can't use multicast feature if the interface has no
unicast address. So, if an application joins to an interface and then
all unicast addresses are removed from the interface, the application
can't send/receive any multicast packets. Moreover, if a new unicast
address is assigned to the interface, in_mrejoin() must be called.
KAME's interfaces, however, have ALWAYS one link-local unicast
address. These extensions have thus not been implemented in KAME.
1.12 IPv4 mapped address and IPv6 wildcard socket
RFC2553 describes IPv4 mapped address (3.7) and special behavior
of IPv6 wildcard bind socket (3.8). The spec allows you to:
- Accept IPv4 connections by AF_INET6 wildcard bind socket.
- Transmit IPv4 packet over AF_INET6 socket by using special form of
the address like ::ffff:10.1.1.1.
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.
Almost all KAME implementations treat tcp/udp port number space separately
between IPv4 and IPv6. You can perform wildcard bind on both of the address
families, on the same port.
There are some OS-platform differences in KAME code, as we use tcp/udp
code from different origin. The following table summarizes the behavior.
listening side initiating side
(AF_INET6 wildcard (connection to ::ffff:10.1.1.1)
socket gets IPv4 conn.)
--- ---
KAME/BSDI3 not supported not supported
KAME/FreeBSD228 not supported not supported
KAME/FreeBSD3x configurable supported
default: enabled
KAME/FreeBSD4x configurable supported
default: enabled
KAME/NetBSD configurable supported
default: disabled
KAME/BSDI4 enabled supported
KAME/OpenBSD not supported not supported
The following sections will give you more details, and how you can
configure the behavior.
Comments on listening side:
It looks that RFC2553 talks too little on wildcard bind issue,
specifically on (1) port space issue, (2) failure mode, (3) relationship
between AF_INET/INET6 wildcard bind like ordering constraint, and (4) behavior
when conflicting socket is opened/closed. 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 getaddrinfo() 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's
no concrete consensus (means, up to implementers). You may want to
check the mailing list archives.
We supply a tool called "bindtest" that explores the behavior of
kernel bind(2). The tool will not be compiled by default.
If a server application would like to accept IPv4 and IPv6 connections,
it should use AF_INET and AF_INET6 socket (you'll need two sockets).
Use getaddrinfo() with AI_PASSIVE into ai_flags, and socket(2) and 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 (NOTE: KAME/BSDI4
kernel sometimes violate this - we will fix it).
If you try to support IPv6 traffic only and would like to reject IPv4
traffic, 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. This is one of the reasons the author of
the section (itojun) dislikes special behavior of AF_INET6 wildcard bind.
Comments on initiating side:
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:
- NEVER hardcode AF_INET nor AF_INET6.
- Use getaddrinfo() and getnameinfo() throughout the system.
Never use gethostby*(), getaddrby*(), inet_*() or getipnodeby*().
- If you would like to connect to destination, use getaddrinfo() and try
all the destination returned, like telnet does.
- Some of the IPv6 stack is shipped with buggy getaddrinfo(). Ship a minimal
working version with your application and use that as last resort.
If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing
connection, you will need tweaked implementation in DNS support libraries,
as documented in RFC2553 6.1. KAME libinet6 includes the tweak in
getipnodebyname(). Note that getipnodebyname() itself is not recommended as
it does not handle scoped IPv6 addresses at all. For IPv6 name resolution
getaddrinfo() is the preferred API. getaddrinfo() does not implement the
tweak.
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.
1.12.1 KAME/BSDI3 and KAME/FreeBSD228
The platforms do not support IPv4 mapped address at all (both listening side
and initiating side). AF_INET6 and AF_INET sockets are totally separated.
Port number space is totally separate between AF_INET and AF_INET6 sockets.
It should be noted that KAME/BSDI3 and KAME/FreeBSD228 are not conformant
to RFC2553 section 3.7 and 3.8. It is due to code sharing reasons.
1.12.2 KAME/FreeBSD[34]x
KAME/FreeBSD3x and KAME/FreeBSD4x use shared tcp4/6 code (from
sys/netinet/tcp*) and shared udp4/6 code (from sys/netinet/udp*).
They use unified inpcb/in6pcb structure.
1.12.2.1 KAME/FreeBSD[34]x, listening side
The platform can be configured to support IPv4 mapped address/special
AF_INET6 wildcard bind (enabled by default). There is no kernel compilation
option to disable it. You can enable/disable the behavior with sysctl
(per-node), or setsockopt (per-socket).
Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
conditions are satisfied:
- there's no AF_INET socket that matches the IPv4 connection
- the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
getsockopt(IPV6_BINDV6ONLY) returns 0.
(XXX need checking)
1.12.2.2 KAME/FreeBSD[34]x, initiating side
KAME/FreeBSD3x supports outgoing connection to IPv4 mapped address
(::ffff:10.1.1.1), if the node is configured to accept IPv4 connections
by AF_INET6 socket.
(XXX need checking)
1.12.3 KAME/NetBSD
KAME/NetBSD uses shared tcp4/6 code (from sys/netinet/tcp*) and shared
udp4/6 code (from sys/netinet/udp*). The implementation is made differently
from KAME/FreeBSD[34]x. KAME/NetBSD uses separate inpcb/in6pcb structures,
while KAME/FreeBSD[34]x uses merged inpcb structure.
It should be noted that the default configuration of KAME/NetBSD is not
conformant to RFC2553 section 3.8. It is intentionally turned off by default
for security reasons.
1.12.3.1 KAME/NetBSD, listening side
The platform can be configured to support IPv4 mapped address/special AF_INET6
wildcard bind (disabled by default). Kernel behavior can be summarized as
follows:
- default: special support code will be compiled in, but is disabled by
default. It can be controlled by sysctl (net.inet6.ip6.bindv6only),
or setsockopt(IPV6_BINDV6ONLY).
- add "INET6_BINDV6ONLY": No special support code for AF_INET6 wildcard socket
will be compiled in. AF_INET6 sockets and AF_INET sockets are totally
separate. The behavior is similar to what described in 1.12.1.
sysctl setting will affect per-socket configuration at in6pcb creation time
only. In other words, per-socket configuration will be copied from sysctl
configuration at in6pcb creation time. To change per-socket behavior, you
must perform setsockopt or reopen the socket. Change in sysctl configuration
will not change the behavior or sockets that are already opened.
Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
conditions are satisfied:
- there's no AF_INET socket that matches the IPv4 connection
- the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
getsockopt(IPV6_BINDV6ONLY) returns 0.
You cannot bind(2) with IPv4 mapped address. This is a workaround for port
number duplicate and other twists.
1.12.3.2 KAME/NetBSD, initiating side
When you initiate a connection, you can always connect to IPv4 destination
over AF_INET6 socket, usin IPv4 mapped address destination (::ffff:10.1.1.1).
This is enabled independently from the configuration for listening side, and
always enabled.
1.12.4 KAME/BSDI4
KAME/BSDI4 uses NRL-based TCP/UDP stack and inpcb source code,
which was derived from NRL IPv6/IPsec stack. We guess it supports IPv4 mapped
address and speical AF_INET6 wildcard bind. The implementation is, again,
different from other KAME/*BSDs.
1.12.4.1 KAME/BSDI4, listening side
NRL inpcb layer supports special behavior of AF_INET6 wildcard socket.
There is no way to disable the behavior.
Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
condition is satisfied:
- there's no AF_INET socket that matches the IPv4 connection
1.12.4.2 KAME/BSDI4, initiating side
KAME/BSDi4 supports connection initiation to IPv4 mapped address
(like ::ffff:10.1.1.1).
1.12.5 KAME/OpenBSD
KAME/OpenBSD uses NRL-based TCP/UDP stack and inpcb source code,
which was derived from NRL IPv6/IPsec stack.
It should be noted that KAME/OpenBSD is not conformant to RFC2553 section 3.7
and 3.8. It is intentionally omitted for security reasons.
1.12.5.1 KAME/OpenBSD, listening side
KAME/OpenBSD disables special behavior on AF_INET6 wildcard bind for
security reasons (if IPv4 traffic toward AF_INET6 wildcard bind is allowed,
access control will become much harder). KAME/BSDI4 uses NRL-based TCP/UDP
stack as well, however, the behavior is different due to OpenBSD's security
policy.
As a result the behavior of KAME/OpenBSD is similar to KAME/BSDI3 and
KAME/FreeBSD228 (see 1.12.1 for more detail).
1.12.5.2 KAME/OpenBSD, initiating side
KAME/OpenBSD does not support connection initiation to IPv4 mapped address
(like ::ffff:10.1.1.1).
1.12.6 More issues
IPv4 mapped address support adds a big requirement to EVERY userland codebase.
Every userland code should check if an AF_INET6 sockaddr contains IPv4
mapped address or not. This adds many twists:
- Access controls code becomes harder to write.
For example, if you would like to reject packets from 10.0.0.0/8,
you need to reject packets to AF_INET socket from 10.0.0.0/8,
and to AF_INET6 socket from ::ffff:10.0.0.0/104.
- If a protocol on top of IPv4 is defined differently with IPv6, we need to be
really careful when we determine which protocol to use.
For example, with FTP protocol, we can not simply use sa_family to determine
FTP command sets. The following example is incorrect:
if (sa_family == AF_INET)
use EPSV/EPRT or PASV/PORT; /*IPv4*/
else if (sa_family == AF_INET6)
use EPSV/EPRT or LPSV/LPRT; /*IPv6*/
else
error;
The correct code, with consideration to IPv4 mapped address, would be:
if (sa_family == AF_INET)
use EPSV/EPRT or PASV/PORT; /*IPv4*/
else if (sa_family == AF_INET6 && IPv4 mapped address)
use EPSV/EPRT or PASV/PORT; /*IPv4 command set on AF_INET6*/
else if (sa_family == AF_INET6 && !IPv4 mapped address)
use EPSV/EPRT or LPSV/LPRT; /*IPv6*/
else