1# NOTE: this is from original KAME distribution.
2# Some portion of this document is not applicable to the code merged into
3# FreeBSD-current (for example, section 5).
4
5 Implementation Note
6
7 KAME Project
8 http://www.kame.net/
9 $FreeBSD: head/share/doc/IPv6/IMPLEMENTATION 62588 2000-07-04 16:35:31Z itojun $
10
111. IPv6
12
131.1 Conformance
14
15The KAME kit conforms, or tries to conform, to the latest set of IPv6
16specifications. For future reference we list some of the relevant documents
17below (NOTE: this is not a complete list - this is too hard to maintain...).
18For details please refer to specific chapter in the document, RFCs, manpages
19come with KAME, or comments in the source code.
20
21Conformance tests have been performed on past and latest KAME STABLE kit,
22at TAHI project. Results can be viewed at http://www.tahi.org/report/KAME/.
23We also attended Univ. of New Hampshire IOL tests (http://www.iol.unh.edu/)
24in the past, with our past snapshots.
25
26RFC1639: FTP Operation Over Big Address Records (FOOBAR)
27 * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428,
28 then RFC1639 if failed.
29RFC1886: DNS Extensions to support IPv6
--- 41 unchanged lines hidden (view full) ---
71RFC2467: Transmission of IPv6 Packets over FDDI Networks
72RFC2472: IPv6 over PPP
73RFC2492: IPv6 over ATM Networks
74 * only PVC is supported.
75RFC2497: Transmission of IPv6 packet over ARCnet Networks
76RFC2545: Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing
77RFC2553: Basic Socket Interface Extensions for IPv6
78 * IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind
79 socket (3.8) are,
80 - supported and turned on by default on KAME/FreeBSD[34]x
81 and KAME/BSDI4,
82 - supported but turned off by default on KAME/NetBSD,
83 - not supported on KAME/FreeBSD228, KAME/OpenBSD and KAME/BSDI3.
84 see 1.12 in this document for details.
85RFC2675: IPv6 Jumbograms
86 * See 1.7 in this document for details.
87RFC2710: Multicast Listener Discovery for IPv6
88RFC2711: IPv6 router alert option
89RFC2732: Format for Literal IPv6 Addresses in URL's
90 * The spec is implemented in programs that handle URLs
91 (like freebsd ftpio(3) and fetch(1), or netbsd ftp(1))
92draft-ietf-ipngwg-router-renum-10: Router renumbering for IPv6
93draft-ietf-ipngwg-icmp-name-lookups-05: IPv6 Name Lookups Through ICMP
94draft-ietf-pim-ipv6-03.txt: PIM for IPv6
95 * pim6dd implements dense mode. pim6sd implements sparse mode.
96draft-ietf-dhc-dhcpv6-15.txt: DHCPv6
97draft-ietf-dhc-dhcpv6exts-12.txt: Extensions for DHCPv6
98 * kame/dhcp6 has test implementation, which will not be compiled in
99 default compilation.
100draft-itojun-ipv6-tcp-to-anycast-00.txt:
101 Disconnecting TCP connection toward IPv6 anycast address
102draft-ietf-ipngwg-scopedaddr-format-02.txt:
103 An Extension of Format for IPv6 Scoped Addresses
104draft-ietf-ngtrans-tcpudp-relay-01.txt:
105 An IPv6-to-IPv4 transport relay translator
106 * FAITH tcp relay translator (faithd) implements this. See 3.1 for more
107 details.
108draft-ietf-ngtrans-6to4-06.txt:
109 Connection of IPv6 Domains via IPv4 Clouds without Explicit Tunnels
110 * "stf" interface implements it. Be sure to read the next item before
111 configuring it, there are security issues.
112http://playground.iijlab.net/i-d/draft-itojun-ipv6-transition-abuse-00.txt:
113 Possible abuse against IPv6 transition technologies
114 * KAME does not implement RFC1933 automatic tunnel.
115 * "stf" interface implements some address filters. Refer to stf(4)
116 for details. Since there's no way to make 6to4 interface 100% secure,
117 we do not include "stf" interface into GENERIC.v6 compilation.
118 * kame/openbsd completely disables IPv4 mapped address support.
119 * kame/netbsd makes IPv4 mapped address support off by default.
120 * See section 12.6 and 14 for more details.
121
1221.2 Neighbor Discovery
123
124Neighbor Discovery is fairly stable. Currently Address Resolution,
125Duplicated Address Detection, and Neighbor Unreachability Detection
126are supported. In the near future we will be adding Unsolicited Neighbor
127Advertisement transmission command as admin tool.
128
129Duplicated Address Detection (DAD) will be performed when an IPv6 address
130is assigned to a network interface, or the network interface is enabled
131(ifconfig up). It is documented in RFC2462 5.4.
132If DAD fails, the address will be marked "duplicated" and message will be
133generated to syslog (and usually to console). The "duplicated" mark
134can be checked with ifconfig. It is administrators' responsibility to check
135for and recover from DAD failures. We may try to improve failure recovery
136in future KAME code.
137DAD procedure may not be effective on certain network interfaces/drivers.
138If a network driver needs long initialization time (with wireless network
139interfaces this situation is popular), and the driver mistakingly raises
140IFF_RUNNING before the driver becomes ready, DAD code will try to transmit
141DAD probes to not-really-ready network driver and the packet will not go out
142from the interface. In such cases, network drivers should be corrected.
143
144Some of network drivers loop multicast packets back to themselves,
145even if instructed not to do so (especially in promiscuous mode).
146In such cases DAD may fail, because DAD engine sees inbound NS packet
147(actually from the node itself) and considers it as a sign of duplicate.
148You may want to look at #if condition marked "heuristics" in
149sys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note that the code
150fragment in "heuristics" section is not spec conformant).
151
152Neighbor Discovery specification (RFC2461) does not talk about neighbor
153cache handling in the following cases:
154(1) when there was no neighbor cache entry, node received unsolicited
155 RS/NS/NA/redirect packet without link-layer address
156(2) neighbor cache handling on medium without link-layer address
157 (we need a neighbor cache entry for IsRouter bit)
158For (1), we implemented workaround based on discussions on IETF ipngwg mailing
159list. For more details, see the comments in the source code and email
160thread started from (IPng 7155), dated Feb 6 1999.
161
162IPv6 on-link determination rule (RFC2461) is quite different from assumptions
163in BSD IPv4 network code. To implement behavior in RFC2461 section 5.2
164(when default router list is empty), the kernel needs to know the default
165outgoing interface. To configure the default outgoing interface, use
166commands like "ndp -I de0" as root. Note that the spec misuse the word
167"host" and "node" in several places in the section.
168
169To avoid possible DoS attacks and infinite loops, KAME stack will accept
170only 10 options on ND packet. Therefore, if you have 20 prefix options
171attached to RA, only the first 10 prefixes will be recognized.
172If this troubles you, please contact KAME team and/or modify
173nd6_maxndopt in sys/netinet6/nd6.c. If there are high demands we may
174provide sysctl knob for the variable.
175
176Proxy Neighbor Advertisement support is implemented in the kernel.
177For instance, you can configure it by using the following command:
178 # ndp -s fe80::1234%ne0 0:1:2:3:4:5 proxy
179where ne0 is the interface which attaches to the same link as the
180proxy target.
181There are certain limitations, though:
182- It does not send unsolicited multicast NA on configuration. This is MAY
183 behavior in RFC2461.
184- It does not add random delay before transmission of solicited NA. This is
185 SHOULD behavior in RFC2461.
186- We cannot configure proxy NDP for off-link address. The target address for
187 proxying must be link-local address, or must be in prefixes configured to
188 node which does proxy NDP.
189- RFC2461 is unclear about if it is legal for a host to perform proxy ND.
190 We do not prohibit hosts from doing proxy ND, but there will be very limited
191 use in it.
192
193Starting mid March 2000, we support Neighbor Unreachability Detection (NUD)
194on p2p interfaces, including tunnel interfaces (gif). NUD is turned on by
195default. Before March 2000 KAME stack did not perform NUD on p2p interfaces.
196If the change raises any interoperability issues, you can turn off/on NUD
197by per-interface basis. Use "ndp -i interface -nud" to turn it off.
198Consult ndp(8) for details.
199
200RFC2461 specifies upper-layer reachability confirmation hint. Whenever
201upper-layer reachability confirmation hint comes, ND process can use it
202to optimize neighbor discovery process - ND process can omit real ND exchange
203and keep the neighbor cache state in REACHABLE.
204We currently have two sources for hints: (1) setsockopt(IPV6_REACHCONF)
205defined by 2292bis API, and (2) hints from tcp_input.
206It is questionable if they are really trustworthy. For example, a rogue
207userland program can use IPV6_REACHCONF to confuse ND process. Neighbor
208cache is a system-wide information pool, and it is bad to allow single process
209to affect others. Also, tcp_input can be hosed by hijack attempts. It is
210wrong to allow hijack attempts to affect ND process.
211Starting June 2000, ND code has a protection mechanism against incorrect
212upper-layer reachability confirmation. ND code counts subsequent upper-layer
213hints. If the number of hints reaches maximum, ND code will ignore further
214upper-layer hints and run real ND process to confirm reachability to the peer.
215sysctl net.inet6.icmp6.nd6_maxnudhint defines maximum # of subsequent
216upper-layer hints to be accepted.
217(from April 2000 to June 2000, we rejected setsockopt(IPV6_REACHCONF) from
218non-root process - after local discussion, it looks that hints are not
219that trustworthy even if they are from privileged processes)
220
2211.3 Scope Index
222
223IPv6 uses scoped addresses. It is therefore very important to
224specify scope index (interface index for link-local address, or
225site index for site-local address) with an IPv6 address. Without
226scope index, a scoped IPv6 address is ambiguous to the kernel, and
227the kernel will not be able to determine the outbound interface for a
228packet. KAME code tries to address the issue in several ways.
229
230Site-local address is very vaguely defined in the specs, and both specification
231and KAME code need tons of improvements to enable its actual use.
232For example, it is still very unclear how we define a site, or how we resolve
233hostnames in a site. There are work underway to define behavior of routers
234at site border, however, we have almost no code for site boundary node support
235(both forwarding nor routing) and we bet almost noone has.
236We recommend, at this moment, you to use global addresses for experiments -
237there are way too many pitfalls if you use site-local addresses.
238
2391.3.1 Kernel internal
240
241In the kernel, the interface index for a link-local scope address is
242embedded into the 2nd 16bit-word (the 3rd and 4th bytes) in the IPv6
243address.
244For example, you may see something like:
245 fe80:1::200:f8ff:fe01:6317
246in the routing table and interface address structure (struct
247in6_ifaddr). The address above is a link-local unicast address
248which belongs to a network interface whose interface identifier is 1.
249The embedded index enables us to identify IPv6 link local
250addresses over multiple interfaces effectively and with only a
251little code change.
252
2531.3.2 Interaction with API
254
255Ordinary userland applications should use the advanced API (RFC2292)
256to specify scope index, or interface index. For the similar purpose,
257the sin6_scope_id member in the sockaddr_in6 structure is defined in
258RFC2553. However, the semantics for sin6_scope_id is rather vague.
259If you care about portability of your application, we suggest you to
260use the advanced API rather than sin6_scope_id.
261
262Routing daemons and configuration programs, like route6d and
263ifconfig, will need to manipulate the "embedded" scope index.
264These programs use routing sockets and ioctls (like SIOCGIFADDR_IN6)
265and the kernel API will return IPv6 addresses with 2nd 16bit-word
266filled in. The APIs are for manipulating kernel internal structure.
267Programs that use these APIs have to be prepared about differences
268in kernels anyway.
269
270getaddrinfo(3) and getnameinfo(3) are modified to support extended numeric
271IPv6 syntax, as documented in draft-ietf-ipngwg-scopedaddr-format-xx.txt.
272You can specify outgoing link, by using name of the outgoing interface
273like "fe80::1%ne0". This way you will be able to specify link-local scoped
274address without much trouble.
275To use this extension in your program, you'll need to use getaddrinfo(3),
276and getnameinfo(3) with NI_WITHSCOPEID.
277The implementation currently assumes 1-to-1 relationship between a link and an
278interface, which is stronger than what IPv6 specs say.
279Other APIs like inet_pton(3) or getipnodebyname(3) are inherently unfriendly
280with scoped addresses, since they are unable to annotate addresses with
281scope identifier.
282
2831.3.3 Interaction with users (command line)
284
285Most of user applications now support an extended numeric IPv6 syntax,
286as documented in draft-ietf-ipngwg-scopedaddr-format-xx.txt. In this
287case, you can specify outgoing link, by using the name of the outgoing
288interface like "fe80::1%ne0". This is the case for some management
289tools such as route(8) or ndp(8). For example, to install the IPv6
290default route by hand, you can type like
291 # route add -inet6 default fe80::9876:5432:1234:abcd%ne0
292(Although we suggest you to run dynamic routing instead of static
293routes, in order to avoid configuration mistakes.)
294
295Some applications have command line options for specifying an
296appropriate zone of a scoped address (like "ping6 -I ne0 ff02::1" to
297specify the outgoing interface). However, you can't always expect such
298options. Thus, we recommend you to use the extended format described
299above.
300
301In any case, when you specify a scoped address to the command line,
302NEVER write the embedded form (such as ff02:1::1 or fe80:2::fedc),
303which should only be used inside the kernel (see Section 1.3.1), and
304is not supposed to work.
305
3061.4 Plug and Play
307
308The KAME kit implements most of the IPv6 stateless address
309autoconfiguration in the kernel.
310Neighbor Discovery functions are implemented in the kernel as a whole.
311Router Advertisement (RA) input for hosts is implemented in the
312kernel. Router Solicitation (RS) output for endhosts, RS input
313for routers, and RA output for routers are implemented in the
314userland.
315
3161.4.1 Assignment of link-local, and special addresses
317
318IPv6 link-local address is generated from IEEE802 address (ethernet MAC
319address). Each of interface is assigned an IPv6 link-local address
320automatically, when the interface becomes up (IFF_UP). Also, direct route
321for the link-local address is added to routing table.
322
323Here is an output of netstat command:
324
325Internet6:
326Destination Gateway Flags Netif Expire
327fe80::%ed0/64 link#1 UC ed0
328fe80::%ep0/64 link#2 UC ep0
329
330Interfaces that has no IEEE802 address (pseudo interfaces like tunnel
331interfaces, or ppp interfaces) will borrow IEEE802 address from other
332interfaces, such as ethernet interfaces, whenever possible.
333If there is no IEEE802 hardware attached, last-resort pseudorandom value,
334which is from MD5(hostname), will be used as source of link-local address.
335If it is not suitable for your usage, you will need to configure the
336link-local address manually.
--- 10 unchanged lines hidden (view full) ---
347automatically added to routing table, and loopback interface joins
348node-local multicast group ff01::1.
349
3501.4.2 Stateless address autoconfiguration on hosts
351
352In IPv6 specification, nodes are separated into two categories:
353routers and hosts. Routers forward packets addressed to others, hosts does
354not forward the packets. net.inet6.ip6.forwarding defines whether this
355node is a router or a host (router if it is 1, host if it is 0).
356
357It is NOT recommended to change net.inet6.ip6.forwarding while the node
358is in operation. IPv6 specification defines behavior for "host" and "router"
359quite differently, and switching from one to another can cause serious
360troubles. It is recommended to configure the variable at bootstrap time only.
361
362The first step in stateless address configuration is Duplicated Address
363Detection (DAD). See 1.2 for more detail on DAD.
364
365When a host hears Router Advertisement from the router, a host may
366autoconfigure itself by stateless address autoconfiguration.
367This behavior can be controlled by net.inet6.ip6.accept_rtadv
368(host autoconfigures itself if it is set to 1).
369By autoconfiguration, network address prefix for the receiving interface
370(usually global address prefix) is added. The default route is also
371configured.
372
373Routers periodically generate Router Advertisement packets. To
374request an adjacent router to generate RA packet, a host can transmit
375Router Solicitation. To generate an RS packet at any time, use the
376"rtsol" command. The "rtsold" daemon is also available. "rtsold"
377generates Router Solicitation whenever necessary, and it works great
378for nomadic usage (notebooks/laptops). If one wishes to ignore Router
379Advertisements, use sysctl to set net.inet6.ip6.accept_rtadv to 0.
380
381To generate Router Advertisement from a router, use the "rtadvd" daemon.
382
383Note that the IPv6 specification assumes the following items and that
384nonconforming cases are left unspecified:
385- Only hosts will listen to router advertisements
386- Hosts have single network interface (except loopback)
387This is therefore unwise to enable net.inet6.ip6.accept_rtadv on routers,
388or multi-interface host. A misconfigured node can behave strange
389(KAME code allows nonconforming configuration, for those who would like
390to do some experiments).
391
392To summarize the sysctl knob:
393 accept_rtadv forwarding role of the node
394 --- --- ---
395 0 0 host (to be manually configured)
396 0 1 router
397 1 0 autoconfigured host
398 (spec assumes that host has single
399 interface only, autoconfigred host with
400 multiple interface is out-of-scope)
401 1 1 invalid, or experimental
402 (out-of-scope of spec)
403
404RFC2462 has validation rules against incoming RA prefix information option,
405in 5.5.3 (e). This is to protect hosts from malicious (or misconfigured)
406routers that advertise very short prefix lifetime.
407There was an update from Jim Bound to ipngwg mailing list (look
408for "(ipng 6712)" in the archive) and KAME implements Jim's update.
409
410See 1.2 in the document for relationship between DAD and autoconfiguration.
411
4121.4.3 DHCPv6
413
414We supply a tiny DHCPv6 server/client in kame/dhcp6. However, the
415implementation is premature (for example, this does NOT implement
416address lease/release), and it is not in default compilation tree on
417some platforms. If you want to do some experiment, compile it on your
418own.
419
420DHCPv6 and autoconfiguration also needs more work. "Managed" and "Other"
421bits in RA have no special effect to stateful autoconfiguration procedure
422in DHCPv6 client program ("Managed" bit actually prevents stateless
423autoconfiguration, but no special action will be taken for DHCPv6 client).
424
4251.5 Generic tunnel interface
426
--- 10 unchanged lines hidden (view full) ---
437header (v4 in v4, or v6 in v6) is dangerous. It is very easy to
438configure interfaces and routing tables to perform infinite level
439of tunneling. Please be warned.
440
441gif can be configured to be ECN-friendly. See 4.5 for ECN-friendliness
442of tunnels, and gif(4) manpage for how to configure.
443
444If you would like to configure an IPv4-in-IPv6 tunnel with gif interface,
445read gif(4) carefully. You may need to remove IPv6 link-local address
446automatically assigned to the gif interface.
447
4481.6 Source Address Selection
449
450KAME's source address selection takes care of the following
451conditions:
452- address scope
453- prefix matching against the destination
454- outgoing interface
455- whether an address is deprecated
456
457Roughly speaking, the selection policy is as follows:
458- always use an address that belongs to the same scope zone as the
459 destination.
460- addresses that have equal or larger scope than the scope of the
461 destination are preferred.
462- if multiple addresses have the equal scope, one which is longest
463 prefix matching against the destination is preferred.
464- a deprecated address is not used in new communications if an
465 alternate (non-deprecated) address is available and has sufficient
466 scope.
467- if none of above conditions tie-breaks, addresses assigned on the
468 outgoing interface are preferred.
469
470For instance, ::1 is selected for ff01::1,
471fe80::200:f8ff:fe01:6317%ne0 for fe80::2a0:24ff:feab:839b%ne0.
472To see how longest-matching works, suppose that
4733ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317
474are given on the outgoing interface. Then the former is chosen as the
475source for the destination 3ffe:501:800::1. Note that even if all
476available addresses have smaller scope than the scope of the
477destination, we choose one anyway. For example, if we have link-local
478and site-local addresses only, we choose a site-local addresses for a
479global destination. If the packet is going to break a site boundary,
480the boundary router will return an ICMPv6 destination unreachable
481error with code 2 - beyond scope of source address.
482
483The precise desripction of the algorithm is quite complicated. To
484describe the algorithm, we introduce the following notation:
485
486For a given destination D,
487 samescope(D): A set of addresses that have the same scope as D.
488 largerscope(D): A set of addresses that have a larger scope than D.
489 smallerscope(D): A set of addresses that have a smaller scope than D.
490
491For a given set of addresses A,
492 DEP(A): a set of deprecated addresses in A.
493 nonDEP(A): A - DEP(A).
494
495Also, the algorithm assumes that the outgoing interface for the
496destination D is determined. We call the interface "I".
497
498The algorithm is as follows. Selection proceeds step by step as
499described; For example, if an address is selected by item 1, item 2 or
500later are not considered at all.
501
502 0. If there is no address in the same scope zone as D, just give up;
503 the packet will not be sent.
504 1. If nonDEP(samescope(D)) is not empty,
505 choose a longest matching address against D. If more than one
506 address is longest matching, choose arbitrary one provided that
507 an address on I is always preferred.
508 2. If nonDEP(largerscope(D)) is not empty,
509 choose an address that has the smallest scope. If more than one
510 address has the smallest scope, choose arbitrary one provided
511 that an address on I is always preferred.
512 3. If DEP(samescope(D)) is not empty,
513 choose a longest matching address against D. If more than one
514 address is longest matching, choose arbitrary one provided that
515 an address on I is always preferred.
516 4. If DEP(largerscope(D)) is not empty,
517 choose an address that has the smallest scope. If more than one
518 address has the smallest scope, choose arbitrary one provided
519 that an address on I is always preferred.
520 5. if nonDEP(smallerscope(D)) is not empty,
521 choose an address that has the largest scope. If more than one
522 address has the largest scope, choose arbitrary one provided
523 that an address on I is always preferred.
524 6. if DEP(smallerscope(D)) is not empty,
525 choose an address that has the largest scope. If more than one
526 address has the largest scope, choose arbitrary one provided
527 that an address on I is always preferred.
528
529There exists a document about source address selection
530(draft-ietf-ipngwg-default-addr-select-xx.txt). KAME's algorithm
531described above takes a similar approach to the document, but there
532are some differences. See the document for more details.
533
534There are some cases where we do not use the above rule. One
535example is connected TCP session, and we use the address kept in TCP
536protocol control block (tcb) as the source.
537Another example is source address for Neighbor Advertisement.
538Under the spec (RFC2461 7.2.2) NA's source should be the target
539address of the corresponding NS's target. In this case we follow
540the spec rather than the above longest-match rule.
541
542If you would like to prohibit the use of deprecated address for some
543reason, configure net.inet6.ip6.use_deprecated to 0. The issue
544related to deprecated address is described in RFC2462 5.5.4 (NOTE:
545there is some debate underway in IETF ipngwg on how to use
546"deprecated" address).
547
5481.7 Jumbo Payload
549
550KAME supports the Jumbo Payload hop-by-hop option used to send IPv6
551packets with payloads longer than 65,535 octets. But since currently
552KAME does not support any physical interface whose MTU is more than
55365,535, such payloads can be seen only on the loopback interface(i.e.
554lo0).
555
556If you want to try jumbo payloads, you first have to reconfigure the
557kernel so that the MTU of the loopback interface is more than 65,535
558bytes; add the following to the kernel configuration file:
559 options "LARGE_LOMTU" #To test jumbo payload
560and recompile the new kernel.
561
562Then you can test jumbo payloads by the ping6 command with -b and -s
563options. The -b option must be specified to enlarge the size of the
564socket buffer and the -s option specifies the length of the packet,
565which should be more than 65,535. For example, type as follows;
566 % ping6 -b 70000 -s 68000 ::1
567
568The IPv6 specification requires that the Jumbo Payload option must not
569be used in a packet that carries a fragment header. If this condition
570is broken, an ICMPv6 Parameter Problem message must be sent to the
571sender. KAME kernel follows the specification, but you cannot usually
572see an ICMPv6 error caused by this requirement.
573
--- 19 unchanged lines hidden (view full) ---
593need this.
594
595IPsec does not work on jumbograms. This is due to some specification twists
596in supporting AH with jumbograms (AH header size influences payload length,
597and this makes it real hard to authenticate inbound packet with jumbo payload
598option as well as AH).
599
600There are fundamental issues in *BSD support for jumbograms. We would like to
601address those, but we need more time to finalize the task. To name a few:
602- mbuf pkthdr.len field is typed as "int" in 4.4BSD, so it cannot hold
603 jumbogram with len > 2G on 32bit architecture CPUs. If we would like to
604 support jumbogram properly, the field must be expanded to hold 4G +
605 IPv6 header + link-layer header. Therefore, it must be expanded to at least
606 int64_t (u_int32_t is NOT enough).
607- We mistakingly use "int" to hold packet length in many places. We need
608 to convert them into larger numeric type. It needs a great care, as we may
609 experience overflow during packet length computation.
610- We mistakingly check for ip6_plen field of IPv6 header for packet payload
611 length in various places. We should be checking mbuf pkthdr.len instead.
612 ip6_input() will perform sanity check on jumbo payload option on input,
613 and we can safely use mbuf pkthdr.len afterwards.
614- TCP code needs careful updates in bunch of places, of course.
615
6161.8 Loop prevention in header processing
617
618IPv6 specification allows arbitrary number of extension headers to
619be placed onto packets. If we implement IPv6 packet processing
620code in the way BSD IPv4 code is implemented, kernel stack may
621overflow due to long function call chain. KAME sys/netinet6 code
622is carefully designed to avoid kernel stack overflow. Because of
623this, KAME sys/netinet6 code defines its own protocol switch
624structure, as "struct ip6protosw" (see netinet6/ip6protosw.h).
625IPv4 part (sys/netinet) remains untouched for compatibility.
626Because of this, if you receive IPsec-over-IPv4 packet with massive
627number of IPsec headers, kernel stack may blow up. IPsec-over-IPv6 is okay.
628
6291.9 ICMPv6
630
631After RFC2463 was published, IETF ipngwg has decided to disallow ICMPv6 error
632packet against ICMPv6 redirect, to prevent ICMPv6 storm on a network medium.
633KAME already implements this into the kernel.
634
635RFC2463 requires rate limitation for ICMPv6 error packets generated by a
636node, to avoid possible DoS attacks. KAME kernel implements two rate-
637limitation mechanisms, tunable via sysctl:
638- Minimum time interval between ICMPv6 error packets
639 KAME kernel will generate no more than one ICMPv6 error packet,
640 during configured time interval. net.inet6.icmp6.errratelimit
641 controls the interval (default: disabled).
642- Maximum ICMPv6 error packet-per-second
643 KAME kernel will generate no more than the configured number of
644 packets in one second. net.inet6.icmp6.errppslimit controls the
645 maximum packet-per-second value (default: 200pps)
646Basically, we need to pick values that are suitable against the bandwidth
647of link layer devices directly attached to the node. In some cases the
648default values may not fit well. We are still unsure if the default value
649is sane or not. Comments are welcome.
650
6511.10 Applications
652
653For userland programming, we support IPv6 socket API as specified in
654RFC2553, RFC2292 and upcoming internet drafts.
655
656TCP/UDP over IPv6 is available and quite stable. You can enjoy "telnet",
657"ftp", "rlogin", "rsh", "ssh", etc. These applications are protocol
658independent. That is, they automatically chooses IPv4 or IPv6
--- 6 unchanged lines hidden (view full) ---
665
666The current KAME has escaped from the IPv4 netinet logic. While
667ip_forward() calls ip_output(), ip6_forward() directly calls
668if_output() since routers must not divide IPv6 packets into fragments.
669
670ICMPv6 should contain the original packet as long as possible up to
6711280. UDP6/IP6 port unreach, for instance, should contain all
672extension headers and the *unchanged* UDP6 and IP6 headers.
673So, all IP6 functions except TCP6 never convert network byte
674order into host byte order, to save the original packet.
675
676tcp6_input(), udp6_input() and icmp6_input() can't assume that IP6
677header is preceding the transport headers due to extension
678headers. So, in6_cksum() was implemented to handle packets whose IP6
679header and transport header is not continuous. TCP/IP6 nor UDP/IP6
680header structure don't exist for checksum calculation.
681
682To process IP6 header, extension headers and transport headers easily,
683KAME requires network drivers to store packets in one internal mbuf or
684one or more external mbufs. A typical old driver prepares two
685internal mbufs for 100 - 208 bytes data, however, KAME's reference
686implementation stores it in one external mbuf.
687
688"netstat -s -p ip6" tells you whether or not your driver conforms
689KAME's requirement. In the following example, "cce0" violates the
690requirement. (For more information, refer to Section 2.)
691
692 Mbuf statistics:
693 317 one mbuf
--- 5 unchanged lines hidden (view full) ---
699
700Each input function calls IP6_EXTHDR_CHECK in the beginning to check
701if the region between IP6 and its header is
702continuous. IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has
703M_LOOP flag, that is, the packet comes from the loopback
704interface. m_pullup() is never called for packets coming from physical
705network interfaces.
706
707TCP6 reassembly makes use of IP6 header to store reassemble
708information. IP6 is not supposed to be just before TCP6, so
709ip6tcpreass structure has a pointer to TCP6 header. Of course, it has
710also a pointer back to mbuf to avoid m_pullup().
711
712Like TCP6, both IP and IP6 reassemble functions never call m_pullup().
713
714xxx_ctlinput() calls in_mrejoin() on PRC_IFNEWADDR. We think this is
715one of 4.4BSD implementation flaws. Since 4.4BSD keeps ia_multiaddrs
716in in_ifaddr{}, it can't use multicast feature if the interface has no
717unicast address. So, if an application joins to an interface and then
718all unicast addresses are removed from the interface, the application
719can't send/receive any multicast packets. Moreover, if a new unicast
720address is assigned to the interface, in_mrejoin() must be called.
721KAME's interfaces, however, have ALWAYS one link-local unicast
722address. These extensions have thus not been implemented in KAME.
723
7241.12 IPv4 mapped address and IPv6 wildcard socket
725
726RFC2553 describes IPv4 mapped address (3.7) and special behavior
727of IPv6 wildcard bind socket (3.8). The spec allows you to:
728- Accept IPv4 connections by AF_INET6 wildcard bind socket.
729- Transmit IPv4 packet over AF_INET6 socket by using special form of
730 the address like ::ffff:10.1.1.1.
731but the spec itself is very complicated and does not specify how the
732socket layer should behave.
733Here we call the former one "listening side" and the latter one "initiating
734side", for reference purposes.
735
736Almost all KAME implementations treat tcp/udp port number space separately
737between IPv4 and IPv6. You can perform wildcard bind on both of the address
738families, on the same port.
739
740There are some OS-platform differences in KAME code, as we use tcp/udp
741code from different origin. The following table summarizes the behavior.
742
743 listening side initiating side
744 (AF_INET6 wildcard (connection to ::ffff:10.1.1.1)
745 socket gets IPv4 conn.)
746 --- ---
747KAME/BSDI3 not supported not supported
748KAME/FreeBSD228 not supported not supported
749KAME/FreeBSD3x configurable supported
750 default: enabled
751KAME/FreeBSD4x configurable supported
752 default: enabled
753KAME/NetBSD configurable supported
754 default: disabled
755KAME/BSDI4 enabled supported
756KAME/OpenBSD not supported not supported
757
758The following sections will give you more details, and how you can
759configure the behavior.
760
761Comments on listening side:
762
763It looks that RFC2553 talks too little on wildcard bind issue,
764specifically on (1) port space issue, (2) failure mode, (3) relationship
765between AF_INET/INET6 wildcard bind like ordering constraint, and (4) behavior
766when conflicting socket is opened/closed. There can be several separate
767interpretation for this RFC which conform to it but behaves differently.
768So, to implement portable application you should assume nothing
769about the behavior in the kernel. Using getaddrinfo() is the safest way.
770Port number space and wildcard bind issues were discussed in detail
771on ipv6imp mailing list, in mid March 1999 and it looks that there's
772no concrete consensus (means, up to implementers). You may want to
773check the mailing list archives.
774We supply a tool called "bindtest" that explores the behavior of
775kernel bind(2). The tool will not be compiled by default.
776
777If a server application would like to accept IPv4 and IPv6 connections,
778it should use AF_INET and AF_INET6 socket (you'll need two sockets).
779Use getaddrinfo() with AI_PASSIVE into ai_flags, and socket(2) and bind(2)
780to all the addresses returned.
781By opening multiple sockets, you can accept connections onto the socket with
782proper address family. IPv4 connections will be accepted by AF_INET socket,
783and IPv6 connections will be accepted by AF_INET6 socket (NOTE: KAME/BSDI4
784kernel sometimes violate this - we will fix it).
785
786If you try to support IPv6 traffic only and would like to reject IPv4
787traffic, always check the peer address when a connection is made toward
788AF_INET6 listening socket. If the address is IPv4 mapped address, you may
789want to reject the connection. You can check the condition by using
790IN6_IS_ADDR_V4MAPPED() macro. This is one of the reasons the author of
791the section (itojun) dislikes special behavior of AF_INET6 wildcard bind.
792
793Comments on initiating side:
794
795Advise to application implementers: to implement a portable IPv6 application
796(which works on multiple IPv6 kernels), we believe that the following
797is the key to the success:
798- NEVER hardcode AF_INET nor AF_INET6.
799- Use getaddrinfo() and getnameinfo() throughout the system.
800 Never use gethostby*(), getaddrby*(), inet_*() or getipnodeby*().
801- If you would like to connect to destination, use getaddrinfo() and try
802 all the destination returned, like telnet does.
803- Some of the IPv6 stack is shipped with buggy getaddrinfo(). Ship a minimal
804 working version with your application and use that as last resort.
805
806If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing
807connection, you will need tweaked implementation in DNS support libraries,
808as documented in RFC2553 6.1. KAME libinet6 includes the tweak in
809getipnodebyname(). Note that getipnodebyname() itself is not recommended as
810it does not handle scoped IPv6 addresses at all. For IPv6 name resolution
811getaddrinfo() is the preferred API. getaddrinfo() does not implement the
812tweak.
813
814When writing applications that make outgoing connections, story goes much
815simpler if you treat AF_INET and AF_INET6 as totally separate address family.
816{set,get}sockopt issue goes simpler, DNS issue will be made simpler. We do
817not recommend you to rely upon IPv4 mapped address.
818
8191.12.1 KAME/BSDI3 and KAME/FreeBSD228
820
821The platforms do not support IPv4 mapped address at all (both listening side
822and initiating side). AF_INET6 and AF_INET sockets are totally separated.
823
824Port number space is totally separate between AF_INET and AF_INET6 sockets.
825
8261.12.2 KAME/FreeBSD[34]x
827
828KAME/FreeBSD3x and KAME/FreeBSD4x use shared tcp4/6 code (from
829sys/netinet/tcp*) and shared udp4/6 code (from sys/netinet/udp*).
830They use unified inpcb/in6pcb structure.
831
8321.12.2.1 KAME/FreeBSD[34]x, listening side
833
834The platform can be configured to support IPv4 mapped address/special
835AF_INET6 wildcard bind (enabled by default). There is no kernel compilation
836option to disable it. You can enable/disable the behavior with sysctl
837(per-node), or setsockopt (per-socket).
838
839Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
840conditions are satisfied:
841- there's no AF_INET socket that matches the IPv4 connection
842- the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
843 getsockopt(IPV6_BINDV6ONLY) returns 0.
844
845(XXX need checking)
846
8471.12.2.2 KAME/FreeBSD[34]x, initiating side
848
849KAME/FreeBSD3x supports outgoing connection to IPv4 mapped address
850(::ffff:10.1.1.1), if the node is configured to accept IPv4 connections
851by AF_INET6 socket.
852
853(XXX need checking)
854
8551.12.3 KAME/NetBSD
856
857KAME/NetBSD uses shared tcp4/6 code (from sys/netinet/tcp*) and shared
858udp4/6 code (from sys/netinet/udp*). The implementation is made differently
859from KAME/FreeBSD[34]x. KAME/NetBSD uses separate inpcb/in6pcb structures,
860while KAME/FreeBSD[34]x uses merged inpcb structure.
861
8621.12.3.1 KAME/NetBSD, listening side
863
864The platform can be configured to support IPv4 mapped address/special AF_INET6
865wildcard bind (disabled by default). Kernel behavior can be summarized as
866follows:
867- default: special support code will be compiled in, but is disabled by
868 default. It can be controlled by sysctl (net.inet6.ip6.bindv6only),
869 or setsockopt(IPV6_BINDV6ONLY).
870- add "INET6_BINDV6ONLY": No special support code for AF_INET6 wildcard socket
871 will be compiled in. AF_INET6 sockets and AF_INET sockets are totally
872 separate. The behavior is similar to what described in 1.12.1.
873
874sysctl setting will affect per-socket configuration at in6pcb creation time
875only. In other words, per-socket configuration will be copied from sysctl
876configuration at in6pcb creation time. To change per-socket behavior, you
877must perform setsockopt or reopen the socket. Change in sysctl configuration
878will not change the behavior or sockets that are already opened.
879
880Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
881conditions are satisfied:
882- there's no AF_INET socket that matches the IPv4 connection
883- the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
884 getsockopt(IPV6_BINDV6ONLY) returns 0.
885
886You cannot bind(2) with IPv4 mapped address. This is a workaround for port
887number duplicate and other twists.
888
8891.12.3.2 KAME/NetBSD, initiating side
890
891When you initiate a connection, you can always connect to IPv4 destination
892over AF_INET6 socket, usin IPv4 mapped address destination (::ffff:10.1.1.1).
893This is enabled independently from the configuration for listening side, and
894always enabled.
895
8961.12.4 KAME/BSDI4
897
898KAME/BSDI4 uses NRL-based TCP/UDP stack and inpcb source code,
899which was derived from NRL IPv6/IPsec stack. We guess it supports IPv4 mapped
900address and speical AF_INET6 wildcard bind. The implementation is, again,
901different from other KAME/*BSDs.
902
9031.12.4.1 KAME/BSDI4, listening side
904
905NRL inpcb layer supports special behavior of AF_INET6 wildcard socket.
906There is no way to disable the behavior.
907
908Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
909condition is satisfied:
910- there's no AF_INET socket that matches the IPv4 connection
911
9121.12.4.2 KAME/BSDI4, initiating side
913
914KAME/BSDi4 supports connection initiation to IPv4 mapped address
915(like ::ffff:10.1.1.1).
916
9171.12.5 KAME/OpenBSD
918
919KAME/OpenBSD uses NRL-based TCP/UDP stack and inpcb source code,
920which was derived from NRL IPv6/IPsec stack.
921
9221.12.5.1 KAME/OpenBSD, listening side
923
924KAME/OpenBSD disables special behavior on AF_INET6 wildcard bind for
925security reasons (if IPv4 traffic toward AF_INET6 wildcard bind is allowed,
926access control will become much harder). KAME/BSDI4 uses NRL-based TCP/UDP
927stack as well, however, the behavior is different due to OpenBSD's security
928policy.
929
930As a result the behavior of KAME/OpenBSD is similar to KAME/BSDI3 and
931KAME/FreeBSD228 (see 1.12.1 for more detail).
932
9331.12.5.2 KAME/OpenBSD, initiating side
934
935KAME/OpenBSD does not support connection initiation to IPv4 mapped address
936(like ::ffff:10.1.1.1).
937
9381.12.6 More issues
939
940IPv4 mapped address support adds a big requirement to EVERY userland codebase.
941Every userland code should check if an AF_INET6 sockaddr contains IPv4
942mapped address or not. This adds many twists:
943
944- Access controls code becomes harder to write.
945 For example, if you would like to reject packets from 10.0.0.0/8,
946 you need to reject packets to AF_INET socket from 10.0.0.0/8,
947 and to AF_INET6 socket from ::ffff:10.0.0.0/104.
948- If a protocol on top of IPv4 is defined differently with IPv6, we need to be
949 really careful when we determine which protocol to use.
950 For example, with FTP protocol, we can not simply use sa_family to determine
951 FTP command sets. The following example is incorrect:
952 if (sa_family == AF_INET)
953 use EPSV/EPRT or PASV/PORT; /*IPv4*/
954 else if (sa_family == AF_INET6)
955 use EPSV/EPRT or LPSV/LPRT; /*IPv6*/
956 else
957 error;
958 Under SIIT environment, the correct code would be:
959 if (sa_family == AF_INET)
960 use EPSV/EPRT or PASV/PORT; /*IPv4*/
961 else if (sa_family == AF_INET6 && IPv4 mapped address)
962 use EPSV/EPRT or PASV/PORT; /*IPv4 command set on AF_INET6*/
963 else if (sa_family == AF_INET6 && !IPv4 mapped address)
964 use EPSV/EPRT or LPSV/LPRT; /*IPv6*/
965 else
966 error;
967 It is too much to ask for every body to be careful like this.
968 The problem is, we are not sure if the above code fragment is perfect for
969 all situations.
970- By enabling kernel support for IPv4 mapped address (outgoing direction),
971 servers on the kernel can be hosed by IPv6 native packet that has IPv4
972 mapped address in IPv6 header source, and can generate unwanted IPv4 packets.
973 http://playground.iijlab.net/i-d/draft-itojun-ipv6-transition-abuse-00.txt
974 talks more about this scenario.
975
976Due to the above twists, some of KAME userland programs has restrictions on
977the use of IPv4 mapped addresses:
978- rshd/rlogind do not accept connections from IPv4 mapped address.
979 This is to avoid malicious use of IPv4 mapped address in IPv6 native
980 packet, to bypass source-address based authentication.
981- ftp/ftpd does not support SIIT environment. IPv4 mapped address will be
982 decoded in userland, and will be passed to AF_INET sockets
983 (SIIT client should pass IPv4 mapped address as is, to AF_INET6 sockets).
984
9851.13 sockaddr_storage
986
987When RFC2553 was about to be finalized, there was discussion on how struct
988sockaddr_storage members are named. One proposal is to prepend "__" to the
989members (like "__ss_len") as they should not be touched. The other proposal
990was that don't prepend it (like "ss_len") as we need to touch those members
991directly. There was no clear consensus on it.
992
993As a result, RFC2553 defines struct sockaddr_storage as follows:
994 struct sockaddr_storage {
995 u_char __ss_len; /* address length */
--- 7 unchanged lines hidden (view full) ---
1003 /* and bunch of padding */
1004 };
1005
1006In December 1999, it was agreed that RFC2553bis should pick the latter (XNET)
1007definition.
1008
1009KAME kit prior to December 1999 used RFC2553 definition. KAME kit after
1010December 1999 (including December) will conform to XNET definition,
1011based on RFC2553bis discussion.
1012
1013If you look at multiple IPv6 implementations, you will be able to see
1014both definitions. As an userland programmer, the most portable way of
1015dealing with it is to:
1016(1) ensure ss_family and/or ss_len are available on the platform, by using
1017 GNU autoconf,
1018(2) have -Dss_family=__ss_family to unify all occurences (including header
1019 file) into __ss_family, or
1020(3) never touch __ss_family. cast to sockaddr * and use sa_family like:
1021 struct sockaddr_storage ss;
1022 family = ((struct sockaddr *)&ss)->sa_family
1023
10241.14 Invalid addresses on the wire
1025
1026Some of IPv6 transition technologies embed IPv4 address into IPv6 address.
1027These specifications themselves are fine, however, there can be certain
1028set of attacks enabled by these specifications. Recent speicifcation
1029documents covers up those issues, however, there are already-published RFCs
1030that does not have protection against those (like using source address of
1031::ffff:127.0.0.1 to bypass "reject packet from remote" filter).
1032
1033To name a few, these address ranges can be used to hose an IPv6 implementation,
1034or bypass security controls:
1035- IPv4 mapped address that embeds unspecified/multicast/loopback/broadcast
1036 IPv4 address (if they are in IPv6 native packet header, they are malicious)
1037 ::ffff:0.0.0.0/104 ::ffff:127.0.0.0/104
1038 ::ffff:224.0.0.0/100 ::ffff:255.0.0.0/104
1039- 6to4 prefix generated from unspecified/multicast/loopback/broadcast/private
1040 IPv4 address
1041 2002:0000::/24 2002:7f00::/24 2002:e000::/24
1042 2002:ff00::/24 2002:0a00::/24 2002:ac10::/28
1043 2002:c0a8::/32
1044
1045Also, since KAME does not support RFC1933 auto tunnels, seeing IPv4 compatible
1046is very rare. You should take caution if you see those on the wire.
1047
1048KAME code is carefully written to avoid such incidents. More specifically,
1049KAME kernel will reject packets with certain source/dstination address in IPv6
1050base header, or IPv6 routing header. Also, KAME default configuration file
1051is written carefully, to avoid those attacks.
1052
1053http://playground.iijlab.net/i-d/draft-itojun-ipv6-transition-abuse-00.txt
1054talks about more about this.
1055
10561.15 Node's required addresses
1057
1058RFC2373 section 2.8 talks about required addresses for an IPv6
1059node. The section talks about how KAME stack manages those required
1060addresses.
1061
10621.15.1 Host case
1063
1064The following items are automatically assigned to the node (or the node will
1065automatically joins the group), at bootstrap time:
1066- Loopback address
1067- All-nodes multicast addresses (ff01::1)
1068
1069The following items will be automatically handled when the interface becomes
1070IFF_UP:
1071- Its link-local address for each interface
1072- Solicited-node multicast address for link-local addresses
1073- Link-local allnodes multicast address (ff02::1)
1074
1075The following items need to be configured manually by ifconfig(8) or prefix(8).
1076Alternatively, these can be autoconfigured by using stateless address
1077autoconfiguration.
1078- Assigned unicast/anycast addresses
1079- Solicited-Node multicast address for assigned unicast address
1080
1081Users can join groups by using appropriate system calls like setsockopt(2).
1082
10831.15.2 Router case
1084
1085In addition to the above, routers needs to handle the following items.
1086
1087The following items need to be configured manually by using ifconfig(8).
1088o The subnet-router anycast addresses for the interfaces it is configured
1089 to act as a router on (prefix::/64)
1090o All other anycast addresses with which the router has been configured
1091
1092The router will join the following multicast group when rtadvd(8) is available
1093for the interface.
1094o All-Routers Multicast Addresses (ff02::2)
1095
1096Routing daemons will join appropriate multicast groups, as necessary,
1097like ff02::9 for RIPng.
1098
1099Users can join groups by using appropriate system calls like setsockopt(2).
1100
11012. Network Drivers
1102
1103KAME requires three items to be added into the standard drivers:
1104
1105(1) mbuf clustering requirement. In this stable release, we changed
1106 MINCLSIZE into MHLEN+1 for all the operating systems in order to make
1107 all the drivers behave as we expect.
1108
1109(2) multicast. If "ifmcstat" yields no multicast group for a
1110 interface, that interface has to be patched.
1111
1112To avoid troubles, we suggest you to comment out the device drivers
1113for unsupported/unnecessary cards, from the kernel configuration file.
1114If you accidentally enable unsupported drivers, some of the userland
1115tools may not work correctly (routing daemons are typical example).
1116
1117In the following sections, "official support" means that KAME developers
1118are using that ethernet card/driver frequently.
1119
1120(NOTE: In the past we required all pcmcia drivers to have a call to
1121in6_ifattach(). We have no such requirement any more)
1122
11232.1 FreeBSD 2.2.x-RELEASE
1124
1125Here is a list of FreeBSD 2.2.x-RELEASE drivers and its conditions:
1126
1127 driver mbuf(1) multicast(2) official support?
1128 --- --- --- ---
1129 (Ethernet)
1130 ar looks ok - -
1131 cnw ok ok yes (*)
1132 ed ok ok yes
1133 ep ok ok yes
1134 fe ok ok yes
1135 sn looks ok - - (*)
1136 vx looks ok - -
1137 wlp ok ok - (*)
1138 xl ok ok yes
1139 zp ok ok -
1140 (FDDI)
1141 fpa looks ok ? -
1142 (ATM)
1143 en ok ok yes
1144 (Serial)
1145 lp ? - not work
1146 sl ? - not work
1147 sr looks ok ok - (**)
1148
1149You may want to add an invocation of "rtsol" in "/etc/pccard_ether",
1150if you are using notebook computers and PCMCIA ethernet card.
1151
1152(*) These drivers are distributed with PAO (http://www.jp.freebsd.org/PAO/).
1153
1154(**) There was some report says that, if you make sr driver up and down and
1155then up, the kernel may hang up. We have disabled frame-relay support from
1156sr driver and after that this looks to be working fine. If you need
1157frame-relay support to come back, please contact KAME developers.
1158
11592.2 BSD/OS 3.x
1160
1161The following lists BSD/OS 3.x device drivers and its conditions:
1162
1163 driver mbuf(1) multicast(2) official support?
1164 --- --- --- ---
1165 (Ethernet)
1166 cnw ok ok yes
1167 de ok ok -
1168 df ok ok -
1169 eb ok ok -
1170 ef ok ok yes
1171 exp ok ok -
1172 mz ok ok yes
1173 ne ok ok yes
1174 we ok ok -
1175 (FDDI)
1176 fpa ok ok -
1177 (ATM)
1178 en maybe ok -
1179 (Serial)
1180 ntwo ok ok yes
1181 sl ? - not work
1182 appp ? - not work
1183
1184You may want to use "@insert" directive in /etc/pccard.conf to invoke
1185"rtsol" command right after dynamic insertion of PCMCIA ethernet cards.
1186
11872.3 NetBSD
1188
1189The following table lists the network drivers we have tried so far.
1190
1191 driver mbuf(1) multicast(2) official support?
1192 --- --- --- ---
1193 (Ethernet)
1194 awi pcmcia/i386 ok ok -
1195 bah zbus/amiga NG(*)
1196 cnw pcmcia/i386 ok ok yes
1197 ep pcmcia/i386 ok ok -
1198 le sbus/sparc ok ok yes
1199 ne pci/i386 ok ok yes
1200 ne pcmcia/i386 ok ok yes
1201 wi pcmcia/i386 ok ok yes
1202 (ATM)
1203 en pci/i386 ok ok -
1204
1205(*) This may need some fix, but I'm not sure what arcnet interfaces assume...
1206
12072.4 FreeBSD 3.x-RELEASE
1208
1209Here is a list of FreeBSD 3.x-RELEASE drivers and its conditions:
1210
1211 driver mbuf(1) multicast(2) official support?
1212 --- --- --- ---
1213 (Ethernet)
1214 cnw ok ok -(*)
1215 ed ? ok -
1216 ep ok ok -
1217 fe ok ok yes
1218 fxp ?(**)
1219 lnc ? ok -
1220 sn ? ? -(*)
1221 wi ok ok yes
1222 xl ? ok -
1223
1224(*) These drivers are distributed with PAO as PAO3
1225 (http://www.jp.freebsd.org/PAO/).
1226(**) there are trouble reports with multicast filter initialization.
1227
1228More drivers will just simply work on KAME FreeBSD 3.x-RELEASE but have not
1229been checked yet.
1230
12312.5 OpenBSD 2.x
1232
1233Here is a list of OpenBSD 2.x drivers and its conditions:
1234
1235 driver mbuf(1) multicast(2) official support?
1236 --- --- --- ---
1237 (Ethernet)
1238 de pci/i386 ok ok yes
1239 fxp pci/i386 ?(*)
1240 le sbus/sparc ok ok yes
1241 ne pci/i386 ok ok yes
1242 ne pcmcia/i386 ok ok yes
1243 wi pcmcia/i386 ok ok yes
1244
1245(*) There seem to be some problem in driver, with multicast filter
1246configuration. This happens with certain revision of chipset on the card.
1247Should be fixed by now by workaround in sys/net/if.c, but still not sure.
1248
12492.6 BSD/OS 4.x
1250
1251The following lists BSD/OS 4.x device drivers and its conditions:
1252
1253 driver mbuf(1) multicast(2) official support?
1254 --- --- --- ---
1255 (Ethernet)
1256 de ok ok yes
1257 exp (*)
1258
1259You may want to use "@insert" directive in /etc/pccard.conf to invoke
1260"rtsol" command right after dynamic insertion of PCMCIA ethernet cards.
1261
1262(*) exp driver has serious conflict with KAME initialization sequence.
1263A workaround is committed into sys/i386/pci/if_exp.c, and should be okay by now.
1264
12653. Translator
1266
1267We categorize IPv4/IPv6 translator into 4 types.
1268
1269Translator A --- It is used in the early stage of transition to make
1270it possible to establish a connection from an IPv6 host in an IPv6
1271island to an IPv4 host in the IPv4 ocean.
1272
--- 6 unchanged lines hidden (view full) ---
1279to an IPv6 host in the IPv6 ocean.
1280
1281Translator D --- It is used in the late stage of transition to make it
1282possible to establish a connection from an IPv6 host in the IPv6 ocean
1283to an IPv4 host in an IPv4 island.
1284
1285KAME provides an TCP relay translator for category A. This is called
1286"FAITH". We also provide IP header translator for category A.
1287
12883.1 FAITH TCP relay translator
1289
1290FAITH system uses TCP relay daemon called "faithd" helped by the KAME kernel.
1291FAITH will reserve an IPv6 address prefix, and relay TCP connection
1292toward that prefix to IPv4 destination.
1293
1294For example, if the reserved IPv6 prefix is 3ffe:0501:0200:ffff::, and
--- 5 unchanged lines hidden (view full) ---
1300 | IPv4 tcp toward 163.221.202.12
1301 FAITH-relay dual stack node
1302 ^
1303 | IPv6 TCP toward 3ffe:0501:0200:ffff::163.221.202.12
1304 source IPv6 node
1305
1306faithd must be invoked on FAITH-relay dual stack node.
1307
1308For more details, consult kame/kame/faithd/README and
1309draft-ietf-ngtrans-tcpudp-relay-01.txt.
1310
13113.2 IPv6-to-IPv4 header translator
1312
1313# removed since it is not imported to FreeBSD-current
1314
13154. IPsec
1316
1317IPsec is implemented as the following three components.
1318
1319(1) Policy Management
1320(2) Key Management
1321(3) AH, ESP and IPComp handling in kernel
1322
1323Note that KAME/OpenBSD does NOT include support for KAME IPsec code,
1324as OpenBSD team has their home-brew IPsec stack and they have no plan
1325to replace it. IPv6 support for IPsec is, therefore, lacking on KAME/OpenBSD.
1326
13274.1 Policy Management
1328
1329The kernel implements experimental policy management code. There are two way
1330to manage security policy. One is to configure per-socket policy using
1331setsockopt(3). In this cases, policy configuration is described in
1332ipsec_set_policy(3). The other is to configure kernel packet filter-based
1333policy using PF_KEY interface, via setkey(8).
1334
1335The policy entry will be matched in order. The order of entries makes
1336difference in behavior.
1337
13384.2 Key Management
1339
1340The key management code implemented in this kit (sys/netkey) is a
1341home-brew PFKEY v2 implementation. This conforms to RFC2367.
1342
1343The home-brew IKE daemon, "racoon" is included in the kit (kame/kame/racoon,
1344or usr.sbin/racoon).
1345Basically you'll need to run racoon as daemon, then setup a policy
1346to require keys (like ping -P 'out ipsec esp/transport//use').
1347The kernel will contact racoon daemon as necessary to exchange keys.
1348
1349In IKE spec, there's ambiguity about interpretation of "tunnel" proposal.
1350For example, if we would like to propose the use of following packet:
1351 IP AH ESP IP payload
1352some implementation proposes it as "AH transport and ESP tunnel", since
1353this is more logical from packet construction point of view. Some
1354implementation proposes it as "AH tunnel and ESP tunnel".
1355Racoon follows the former route.
1356This raises real interoperability issue. We hope this to be resolved quickly.
1357
13584.3 AH and ESP handling
1359
1360IPsec module is implemented as "hooks" to the standard IPv4/IPv6
1361processing. When sending a packet, ip{,6}_output() checks if ESP/AH
1362processing is required by checking if a matching SPD (Security
1363Policy Database) is found. If ESP/AH is needed,
1364{esp,ah}{4,6}_output() will be called and mbuf will be updated
1365accordingly. When a packet is received, {esp,ah}4_input() will be
--- 7 unchanged lines hidden (view full) ---
1373extra daisy-chained headers inserted by ESP/AH. Our code takes care of
1374the case.
1375
1376Basic crypto functions can be found in directory "sys/crypto". ESP/AH
1377transform are listed in {esp,ah}_core.c with wrapper functions. If you
1378wish to add some algorithm, add wrapper function in {esp,ah}_core.c, and
1379add your crypto algorithm code into sys/crypto.
1380
1381Tunnel mode works basically fine, but comes with the following restrictions:
1382- You cannot run routing daemon across IPsec tunnel, since we do not model
1383 IPsec tunnel as pseudo interfaces.
1384- Authentication model for AH tunnel must be revisited. We'll need to
1385 improve the policy management engine, eventually.
1386- Tunnelling for IPv6 IPsec is still incomplete. This is disabled by default.
1387 If you need to perform experiments, add "options IPSEC_IPV6FWD" into
1388 the kernel configuration file. Note that path MTU discovery does not work
1389 across IPv6 IPsec tunnel gateway due to insufficient code.
1390
1391AH specificaton does not talk much about "multiple AH on a packet" case.
1392We incrementally compute AH checksum, from inside to outside. Also, we
1393treat inner AH to be immutable.
1394For example, if we are to create the following packet:
1395 IP AH1 AH2 AH3 payload
1396we do it incrementally. As a result, we get crypto checksums like below:
1397 AH3 has checksum against "IP AH3' payload".
1398 where AH3' = AH3 with checksum field filled with 0.
1399 AH2 has checksum against "IP AH2' AH3 payload".
1400 AH1 has checksum against "IP AH1' AH2 AH3 payload",
1401Also note that AH3 has the smallest sequence number, and AH1 has the largest
1402sequence number.
1403
14044.4 IPComp handling
1405
1406IPComp stands for IP payload compression protocol. This is aimed for
1407payload compression, not the header compression like PPP VJ compression.
1408This may be useful when you are using slow serial link (say, cell phone)
1409with powerful CPU (well, recent notebook PCs are really powerful...).
1410The protocol design of IPComp is very similar to IPsec, though it was
1411defined separately from IPsec itself.
1412
1413Here are some points to be noted:
1414- IPComp is treated as part of IPsec protocol suite, and SPI and
1415 CPI space is unified. Spec says that there's no relationship
1416 between two so they are assumed to be separate in specs.
1417- IPComp association (IPCA) is kept in SAD.
1418- It is possible to use well-known CPI (CPI=2 for DEFLATE for example),
1419 for outbound/inbound packet, but for indexing purposes one element from
1420 SPI/CPI space will be occupied anyway.
1421- pfkey is modified to support IPComp. However, there's no official
1422 SA type number assignment yet. Portability with other IPComp
1423 stack is questionable (anyway, who else implement IPComp on UN*X?).
1424- Spec says that IPComp output processing must be performed before AH/ESP
1425 output processing, to achieve better compression ratio and "stir" data
1426 stream before encryption. The most meaningful processing order is:
1427 (1) compress payload by IPComp, (2) encrypt payload by ESP, then (3) attach
1428 authentication data by AH.
1429 However, with manual SPD setting, you are able to violate the ordering
1430 (KAME code is too generic, maybe). Also, it is just okay to use IPComp
1431 alone, without AH/ESP.
1432- Though the packet size can be significantly decreased by using IPComp, no
1433 special consideration is made about path MTU (spec talks nothing about MTU
1434 consideration). IPComp is designed for serial links, not ethernet-like
1435 medium, it seems.
1436- You can change compression ratio on outbound packet, by changing
1437 deflate_policy in sys/netinet6/ipcomp_core.c. You can also change outbound
1438 history buffer size by changing deflate_window_out in the same source code.
1439 (should it be sysctl accessible, or per-SAD configurable?)
1440- Tunnel mode IPComp is not working right. KAME box can generate tunnelled
1441 IPComp packet, however, cannot accept tunneled IPComp packet.
1442- You can negotiate IPComp association with racoon IKE daemon.
1443- KAME code does not attach Adler32 checksum to compressed data.
1444 see ipsec wg mailing list discussion in Jan 2000 for details.
1445
14464.5 Conformance to RFCs and IDs
1447
1448The IPsec code in the kernel conforms (or, tries to conform) to the
1449following standards:
1450 "old IPsec" specification documented in rfc182[5-9].txt
1451 "new IPsec" specification documented in rfc240[1-6].txt, rfc241[01].txt,
1452 rfc2451.txt and draft-mcdonald-simple-ipsec-api-01.txt (draft expired,
1453 but you can take from ftp://ftp.kame.net/pub/internet-drafts/).
1454 (NOTE: IKE specifications, rfc240[7-9].txt are implemented in userland,
1455 as "racoon" IKE daemon)
1456 IPComp:
1457 RFC2393: IP Payload Compression Protocol (IPComp)
1458
1459Currently supported algorithms are:
1460 old IPsec AH
1461 null crypto checksum (no document, just for debugging)
1462 keyed MD5 with 128bit crypto checksum (rfc1828.txt)
1463 keyed SHA1 with 128bit crypto checksum (no document)
1464 HMAC MD5 with 128bit crypto checksum (rfc2085.txt)
1465 HMAC SHA1 with 128bit crypto checksum (no document)
--- 13 unchanged lines hidden (view full) ---
1479 DES-CBC with explicit IV (rfc2405.txt)
1480 3DES-CBC with explicit IV (rfc2451.txt)
1481 BLOWFISH CBC (rfc2451.txt)
1482 CAST128 CBC (rfc2451.txt)
1483 RC5 CBC (rfc2451.txt)
1484 each of the above can be combined with:
1485 ESP authentication with HMAC-MD5(96bit)
1486 ESP authentication with HMAC-SHA1(96bit)
1487 IPComp
1488 RFC2394: IP Payload Compression Using DEFLATE
1489
1490The following algorithms are NOT supported:
1491 old IPsec AH
1492 HMAC MD5 with 128bit crypto checksum + 64bit replay prevention
1493 (rfc2085.txt)
1494 keyed SHA1 with 160bit crypto checksum + 32bit padding (rfc1852.txt)
1495
1496The key/policy management API is based on the following document, with fair
1497amount of extensions:
1498 RFC2367: PF_KEY key management API
1499
15004.6 ECN consideration on IPsec tunnels
1501
1502KAME IPsec implements ECN-friendly IPsec tunnel, described in
1503draft-ietf-ipsec-ecn-02.txt.
1504Normal IPsec tunnel is described in RFC2401. On encapsulation,
1505IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner
1506IP header to outer IP header. On decapsulation outer IP header
1507will be simply dropped. The decapsulation rule is not compatible
1508with ECN, since ECN bit on the outer IP TOS/traffic class field will be
1509lost.
1510To make IPsec tunnel ECN-friendly, we should modify encapsulation
1511and decapsulation procedure. This is described in
1512draft-ietf-ipsec-ecn-02.txt, chapter 3.3.
1513
1514KAME IPsec tunnel implementation can give you three behaviors, by setting
1515net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some value:
1516- RFC2401: no consideration for ECN (sysctl value -1)
1517- ECN forbidden (sysctl value 0)
1518- ECN allowed (sysctl value 1)
1519Note that the behavior is configurable in per-node manner, not per-SA manner
1520(draft-ietf-ipsec-ecn-02 wants per-SA configuration, but it looks too much
1521for me).
1522
1523The behavior is summarized as follows (see source code for more detail):
1524
1525 encapsulate decapsulate
1526 --- ---
1527RFC2401 copy all TOS bits drop TOS bits on outer
1528 from inner to outer. (use inner TOS bits as is)
1529
--- 10 unchanged lines hidden (view full) ---
1540- if both IPsec tunnel endpoint are capable of ECN-friendly behavior,
1541 you'd better configure both end to "ECN allowed" (sysctl value 1).
1542- if the other end is very strict about TOS bit, use "RFC2401"
1543 (sysctl value -1).
1544- in other cases, use "ECN forbidden" (sysctl value 0).
1545The default behavior is "ECN forbidden" (sysctl value 0).
1546
1547For more information, please refer to:
1548 draft-ietf-ipsec-ecn-02.txt
1549 RFC2481 (Explicit Congestion Notification)
1550 KAME sys/netinet6/{ah,esp}_input.c
1551
1552(Thanks goes to Kenjiro Cho <kjc@csl.sony.co.jp> for detailed analysis)
1553
15544.7 Interoperability
1555
1556IPsec, IPComp (in kernel) and IKE (in userland as "racoon") has been tested
1557at several interoperability test events, and it is known to interoperate
1558with many other implementations well. Also, KAME IPsec has quite wide
1559coverage for IPsec crypto algorithms documented in RFC (we do not cover
1560algorithms with intellectual property issues, though).
1561
1562Here are (some of) platforms we have tested IPsec/IKE interoperability
1563in the past, in no particular order. Note that both ends (KAME and
1564others) may have modified their implementation, so use the following
1565list just for reference purposes.
1566 Altiga, Ashley-laurent (vpcom.com), Data Fellows (F-Secure),
1567 BlueSteel, CISCO, Ericsson, ACC, Fitel, FreeS/WAN, HITACHI, IBM
1568 AIX, IIJ, Intel, Microsoft WinNT, NAI PGPnet,
1569 NIST (linux IPsec + plutoplus), Netscreen, OpenBSD isakmpd, Radguard,
1570 RedCreek, Routerware, SSH, Secure Computing, Soliton, Toshiba,
1571 TIS/NAI Gauntret, VPNet, Yamaha RT100i
1572
1573Here are (some of) platforms we have tested IPComp/IKE interoperability
1574in the past, in no particular order.
1575 IRE
1576
15775. ALTQ
1578
1579# removed since it is not imported to FreeBSD-current
1580
15816. mobile-ip6
1582
1583# removed since it is not imported to FreeBSD-current
1584
1585 <end of IMPLEMENTATION>
2# Some portion of this document is not applicable to the code merged into
3# FreeBSD-current (for example, section 5).
4
5 Implementation Note
6
7 KAME Project
8 http://www.kame.net/
9 $FreeBSD: head/share/doc/IPv6/IMPLEMENTATION 62588 2000-07-04 16:35:31Z itojun $
10
111. IPv6
12
131.1 Conformance
14
15The KAME kit conforms, or tries to conform, to the latest set of IPv6
16specifications. For future reference we list some of the relevant documents
17below (NOTE: this is not a complete list - this is too hard to maintain...).
18For details please refer to specific chapter in the document, RFCs, manpages
19come with KAME, or comments in the source code.
20
21Conformance tests have been performed on past and latest KAME STABLE kit,
22at TAHI project. Results can be viewed at http://www.tahi.org/report/KAME/.
23We also attended Univ. of New Hampshire IOL tests (http://www.iol.unh.edu/)
24in the past, with our past snapshots.
25
26RFC1639: FTP Operation Over Big Address Records (FOOBAR)
27 * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428,
28 then RFC1639 if failed.
29RFC1886: DNS Extensions to support IPv6
--- 41 unchanged lines hidden (view full) ---
71RFC2467: Transmission of IPv6 Packets over FDDI Networks
72RFC2472: IPv6 over PPP
73RFC2492: IPv6 over ATM Networks
74 * only PVC is supported.
75RFC2497: Transmission of IPv6 packet over ARCnet Networks
76RFC2545: Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing
77RFC2553: Basic Socket Interface Extensions for IPv6
78 * IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind
79 socket (3.8) are,
80 - supported and turned on by default on KAME/FreeBSD[34]x
81 and KAME/BSDI4,
82 - supported but turned off by default on KAME/NetBSD,
83 - not supported on KAME/FreeBSD228, KAME/OpenBSD and KAME/BSDI3.
84 see 1.12 in this document for details.
85RFC2675: IPv6 Jumbograms
86 * See 1.7 in this document for details.
87RFC2710: Multicast Listener Discovery for IPv6
88RFC2711: IPv6 router alert option
89RFC2732: Format for Literal IPv6 Addresses in URL's
90 * The spec is implemented in programs that handle URLs
91 (like freebsd ftpio(3) and fetch(1), or netbsd ftp(1))
92draft-ietf-ipngwg-router-renum-10: Router renumbering for IPv6
93draft-ietf-ipngwg-icmp-name-lookups-05: IPv6 Name Lookups Through ICMP
94draft-ietf-pim-ipv6-03.txt: PIM for IPv6
95 * pim6dd implements dense mode. pim6sd implements sparse mode.
96draft-ietf-dhc-dhcpv6-15.txt: DHCPv6
97draft-ietf-dhc-dhcpv6exts-12.txt: Extensions for DHCPv6
98 * kame/dhcp6 has test implementation, which will not be compiled in
99 default compilation.
100draft-itojun-ipv6-tcp-to-anycast-00.txt:
101 Disconnecting TCP connection toward IPv6 anycast address
102draft-ietf-ipngwg-scopedaddr-format-02.txt:
103 An Extension of Format for IPv6 Scoped Addresses
104draft-ietf-ngtrans-tcpudp-relay-01.txt:
105 An IPv6-to-IPv4 transport relay translator
106 * FAITH tcp relay translator (faithd) implements this. See 3.1 for more
107 details.
108draft-ietf-ngtrans-6to4-06.txt:
109 Connection of IPv6 Domains via IPv4 Clouds without Explicit Tunnels
110 * "stf" interface implements it. Be sure to read the next item before
111 configuring it, there are security issues.
112http://playground.iijlab.net/i-d/draft-itojun-ipv6-transition-abuse-00.txt:
113 Possible abuse against IPv6 transition technologies
114 * KAME does not implement RFC1933 automatic tunnel.
115 * "stf" interface implements some address filters. Refer to stf(4)
116 for details. Since there's no way to make 6to4 interface 100% secure,
117 we do not include "stf" interface into GENERIC.v6 compilation.
118 * kame/openbsd completely disables IPv4 mapped address support.
119 * kame/netbsd makes IPv4 mapped address support off by default.
120 * See section 12.6 and 14 for more details.
121
1221.2 Neighbor Discovery
123
124Neighbor Discovery is fairly stable. Currently Address Resolution,
125Duplicated Address Detection, and Neighbor Unreachability Detection
126are supported. In the near future we will be adding Unsolicited Neighbor
127Advertisement transmission command as admin tool.
128
129Duplicated Address Detection (DAD) will be performed when an IPv6 address
130is assigned to a network interface, or the network interface is enabled
131(ifconfig up). It is documented in RFC2462 5.4.
132If DAD fails, the address will be marked "duplicated" and message will be
133generated to syslog (and usually to console). The "duplicated" mark
134can be checked with ifconfig. It is administrators' responsibility to check
135for and recover from DAD failures. We may try to improve failure recovery
136in future KAME code.
137DAD procedure may not be effective on certain network interfaces/drivers.
138If a network driver needs long initialization time (with wireless network
139interfaces this situation is popular), and the driver mistakingly raises
140IFF_RUNNING before the driver becomes ready, DAD code will try to transmit
141DAD probes to not-really-ready network driver and the packet will not go out
142from the interface. In such cases, network drivers should be corrected.
143
144Some of network drivers loop multicast packets back to themselves,
145even if instructed not to do so (especially in promiscuous mode).
146In such cases DAD may fail, because DAD engine sees inbound NS packet
147(actually from the node itself) and considers it as a sign of duplicate.
148You may want to look at #if condition marked "heuristics" in
149sys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note that the code
150fragment in "heuristics" section is not spec conformant).
151
152Neighbor Discovery specification (RFC2461) does not talk about neighbor
153cache handling in the following cases:
154(1) when there was no neighbor cache entry, node received unsolicited
155 RS/NS/NA/redirect packet without link-layer address
156(2) neighbor cache handling on medium without link-layer address
157 (we need a neighbor cache entry for IsRouter bit)
158For (1), we implemented workaround based on discussions on IETF ipngwg mailing
159list. For more details, see the comments in the source code and email
160thread started from (IPng 7155), dated Feb 6 1999.
161
162IPv6 on-link determination rule (RFC2461) is quite different from assumptions
163in BSD IPv4 network code. To implement behavior in RFC2461 section 5.2
164(when default router list is empty), the kernel needs to know the default
165outgoing interface. To configure the default outgoing interface, use
166commands like "ndp -I de0" as root. Note that the spec misuse the word
167"host" and "node" in several places in the section.
168
169To avoid possible DoS attacks and infinite loops, KAME stack will accept
170only 10 options on ND packet. Therefore, if you have 20 prefix options
171attached to RA, only the first 10 prefixes will be recognized.
172If this troubles you, please contact KAME team and/or modify
173nd6_maxndopt in sys/netinet6/nd6.c. If there are high demands we may
174provide sysctl knob for the variable.
175
176Proxy Neighbor Advertisement support is implemented in the kernel.
177For instance, you can configure it by using the following command:
178 # ndp -s fe80::1234%ne0 0:1:2:3:4:5 proxy
179where ne0 is the interface which attaches to the same link as the
180proxy target.
181There are certain limitations, though:
182- It does not send unsolicited multicast NA on configuration. This is MAY
183 behavior in RFC2461.
184- It does not add random delay before transmission of solicited NA. This is
185 SHOULD behavior in RFC2461.
186- We cannot configure proxy NDP for off-link address. The target address for
187 proxying must be link-local address, or must be in prefixes configured to
188 node which does proxy NDP.
189- RFC2461 is unclear about if it is legal for a host to perform proxy ND.
190 We do not prohibit hosts from doing proxy ND, but there will be very limited
191 use in it.
192
193Starting mid March 2000, we support Neighbor Unreachability Detection (NUD)
194on p2p interfaces, including tunnel interfaces (gif). NUD is turned on by
195default. Before March 2000 KAME stack did not perform NUD on p2p interfaces.
196If the change raises any interoperability issues, you can turn off/on NUD
197by per-interface basis. Use "ndp -i interface -nud" to turn it off.
198Consult ndp(8) for details.
199
200RFC2461 specifies upper-layer reachability confirmation hint. Whenever
201upper-layer reachability confirmation hint comes, ND process can use it
202to optimize neighbor discovery process - ND process can omit real ND exchange
203and keep the neighbor cache state in REACHABLE.
204We currently have two sources for hints: (1) setsockopt(IPV6_REACHCONF)
205defined by 2292bis API, and (2) hints from tcp_input.
206It is questionable if they are really trustworthy. For example, a rogue
207userland program can use IPV6_REACHCONF to confuse ND process. Neighbor
208cache is a system-wide information pool, and it is bad to allow single process
209to affect others. Also, tcp_input can be hosed by hijack attempts. It is
210wrong to allow hijack attempts to affect ND process.
211Starting June 2000, ND code has a protection mechanism against incorrect
212upper-layer reachability confirmation. ND code counts subsequent upper-layer
213hints. If the number of hints reaches maximum, ND code will ignore further
214upper-layer hints and run real ND process to confirm reachability to the peer.
215sysctl net.inet6.icmp6.nd6_maxnudhint defines maximum # of subsequent
216upper-layer hints to be accepted.
217(from April 2000 to June 2000, we rejected setsockopt(IPV6_REACHCONF) from
218non-root process - after local discussion, it looks that hints are not
219that trustworthy even if they are from privileged processes)
220
2211.3 Scope Index
222
223IPv6 uses scoped addresses. It is therefore very important to
224specify scope index (interface index for link-local address, or
225site index for site-local address) with an IPv6 address. Without
226scope index, a scoped IPv6 address is ambiguous to the kernel, and
227the kernel will not be able to determine the outbound interface for a
228packet. KAME code tries to address the issue in several ways.
229
230Site-local address is very vaguely defined in the specs, and both specification
231and KAME code need tons of improvements to enable its actual use.
232For example, it is still very unclear how we define a site, or how we resolve
233hostnames in a site. There are work underway to define behavior of routers
234at site border, however, we have almost no code for site boundary node support
235(both forwarding nor routing) and we bet almost noone has.
236We recommend, at this moment, you to use global addresses for experiments -
237there are way too many pitfalls if you use site-local addresses.
238
2391.3.1 Kernel internal
240
241In the kernel, the interface index for a link-local scope address is
242embedded into the 2nd 16bit-word (the 3rd and 4th bytes) in the IPv6
243address.
244For example, you may see something like:
245 fe80:1::200:f8ff:fe01:6317
246in the routing table and interface address structure (struct
247in6_ifaddr). The address above is a link-local unicast address
248which belongs to a network interface whose interface identifier is 1.
249The embedded index enables us to identify IPv6 link local
250addresses over multiple interfaces effectively and with only a
251little code change.
252
2531.3.2 Interaction with API
254
255Ordinary userland applications should use the advanced API (RFC2292)
256to specify scope index, or interface index. For the similar purpose,
257the sin6_scope_id member in the sockaddr_in6 structure is defined in
258RFC2553. However, the semantics for sin6_scope_id is rather vague.
259If you care about portability of your application, we suggest you to
260use the advanced API rather than sin6_scope_id.
261
262Routing daemons and configuration programs, like route6d and
263ifconfig, will need to manipulate the "embedded" scope index.
264These programs use routing sockets and ioctls (like SIOCGIFADDR_IN6)
265and the kernel API will return IPv6 addresses with 2nd 16bit-word
266filled in. The APIs are for manipulating kernel internal structure.
267Programs that use these APIs have to be prepared about differences
268in kernels anyway.
269
270getaddrinfo(3) and getnameinfo(3) are modified to support extended numeric
271IPv6 syntax, as documented in draft-ietf-ipngwg-scopedaddr-format-xx.txt.
272You can specify outgoing link, by using name of the outgoing interface
273like "fe80::1%ne0". This way you will be able to specify link-local scoped
274address without much trouble.
275To use this extension in your program, you'll need to use getaddrinfo(3),
276and getnameinfo(3) with NI_WITHSCOPEID.
277The implementation currently assumes 1-to-1 relationship between a link and an
278interface, which is stronger than what IPv6 specs say.
279Other APIs like inet_pton(3) or getipnodebyname(3) are inherently unfriendly
280with scoped addresses, since they are unable to annotate addresses with
281scope identifier.
282
2831.3.3 Interaction with users (command line)
284
285Most of user applications now support an extended numeric IPv6 syntax,
286as documented in draft-ietf-ipngwg-scopedaddr-format-xx.txt. In this
287case, you can specify outgoing link, by using the name of the outgoing
288interface like "fe80::1%ne0". This is the case for some management
289tools such as route(8) or ndp(8). For example, to install the IPv6
290default route by hand, you can type like
291 # route add -inet6 default fe80::9876:5432:1234:abcd%ne0
292(Although we suggest you to run dynamic routing instead of static
293routes, in order to avoid configuration mistakes.)
294
295Some applications have command line options for specifying an
296appropriate zone of a scoped address (like "ping6 -I ne0 ff02::1" to
297specify the outgoing interface). However, you can't always expect such
298options. Thus, we recommend you to use the extended format described
299above.
300
301In any case, when you specify a scoped address to the command line,
302NEVER write the embedded form (such as ff02:1::1 or fe80:2::fedc),
303which should only be used inside the kernel (see Section 1.3.1), and
304is not supposed to work.
305
3061.4 Plug and Play
307
308The KAME kit implements most of the IPv6 stateless address
309autoconfiguration in the kernel.
310Neighbor Discovery functions are implemented in the kernel as a whole.
311Router Advertisement (RA) input for hosts is implemented in the
312kernel. Router Solicitation (RS) output for endhosts, RS input
313for routers, and RA output for routers are implemented in the
314userland.
315
3161.4.1 Assignment of link-local, and special addresses
317
318IPv6 link-local address is generated from IEEE802 address (ethernet MAC
319address). Each of interface is assigned an IPv6 link-local address
320automatically, when the interface becomes up (IFF_UP). Also, direct route
321for the link-local address is added to routing table.
322
323Here is an output of netstat command:
324
325Internet6:
326Destination Gateway Flags Netif Expire
327fe80::%ed0/64 link#1 UC ed0
328fe80::%ep0/64 link#2 UC ep0
329
330Interfaces that has no IEEE802 address (pseudo interfaces like tunnel
331interfaces, or ppp interfaces) will borrow IEEE802 address from other
332interfaces, such as ethernet interfaces, whenever possible.
333If there is no IEEE802 hardware attached, last-resort pseudorandom value,
334which is from MD5(hostname), will be used as source of link-local address.
335If it is not suitable for your usage, you will need to configure the
336link-local address manually.
--- 10 unchanged lines hidden (view full) ---
347automatically added to routing table, and loopback interface joins
348node-local multicast group ff01::1.
349
3501.4.2 Stateless address autoconfiguration on hosts
351
352In IPv6 specification, nodes are separated into two categories:
353routers and hosts. Routers forward packets addressed to others, hosts does
354not forward the packets. net.inet6.ip6.forwarding defines whether this
355node is a router or a host (router if it is 1, host if it is 0).
356
357It is NOT recommended to change net.inet6.ip6.forwarding while the node
358is in operation. IPv6 specification defines behavior for "host" and "router"
359quite differently, and switching from one to another can cause serious
360troubles. It is recommended to configure the variable at bootstrap time only.
361
362The first step in stateless address configuration is Duplicated Address
363Detection (DAD). See 1.2 for more detail on DAD.
364
365When a host hears Router Advertisement from the router, a host may
366autoconfigure itself by stateless address autoconfiguration.
367This behavior can be controlled by net.inet6.ip6.accept_rtadv
368(host autoconfigures itself if it is set to 1).
369By autoconfiguration, network address prefix for the receiving interface
370(usually global address prefix) is added. The default route is also
371configured.
372
373Routers periodically generate Router Advertisement packets. To
374request an adjacent router to generate RA packet, a host can transmit
375Router Solicitation. To generate an RS packet at any time, use the
376"rtsol" command. The "rtsold" daemon is also available. "rtsold"
377generates Router Solicitation whenever necessary, and it works great
378for nomadic usage (notebooks/laptops). If one wishes to ignore Router
379Advertisements, use sysctl to set net.inet6.ip6.accept_rtadv to 0.
380
381To generate Router Advertisement from a router, use the "rtadvd" daemon.
382
383Note that the IPv6 specification assumes the following items and that
384nonconforming cases are left unspecified:
385- Only hosts will listen to router advertisements
386- Hosts have single network interface (except loopback)
387This is therefore unwise to enable net.inet6.ip6.accept_rtadv on routers,
388or multi-interface host. A misconfigured node can behave strange
389(KAME code allows nonconforming configuration, for those who would like
390to do some experiments).
391
392To summarize the sysctl knob:
393 accept_rtadv forwarding role of the node
394 --- --- ---
395 0 0 host (to be manually configured)
396 0 1 router
397 1 0 autoconfigured host
398 (spec assumes that host has single
399 interface only, autoconfigred host with
400 multiple interface is out-of-scope)
401 1 1 invalid, or experimental
402 (out-of-scope of spec)
403
404RFC2462 has validation rules against incoming RA prefix information option,
405in 5.5.3 (e). This is to protect hosts from malicious (or misconfigured)
406routers that advertise very short prefix lifetime.
407There was an update from Jim Bound to ipngwg mailing list (look
408for "(ipng 6712)" in the archive) and KAME implements Jim's update.
409
410See 1.2 in the document for relationship between DAD and autoconfiguration.
411
4121.4.3 DHCPv6
413
414We supply a tiny DHCPv6 server/client in kame/dhcp6. However, the
415implementation is premature (for example, this does NOT implement
416address lease/release), and it is not in default compilation tree on
417some platforms. If you want to do some experiment, compile it on your
418own.
419
420DHCPv6 and autoconfiguration also needs more work. "Managed" and "Other"
421bits in RA have no special effect to stateful autoconfiguration procedure
422in DHCPv6 client program ("Managed" bit actually prevents stateless
423autoconfiguration, but no special action will be taken for DHCPv6 client).
424
4251.5 Generic tunnel interface
426
--- 10 unchanged lines hidden (view full) ---
437header (v4 in v4, or v6 in v6) is dangerous. It is very easy to
438configure interfaces and routing tables to perform infinite level
439of tunneling. Please be warned.
440
441gif can be configured to be ECN-friendly. See 4.5 for ECN-friendliness
442of tunnels, and gif(4) manpage for how to configure.
443
444If you would like to configure an IPv4-in-IPv6 tunnel with gif interface,
445read gif(4) carefully. You may need to remove IPv6 link-local address
446automatically assigned to the gif interface.
447
4481.6 Source Address Selection
449
450KAME's source address selection takes care of the following
451conditions:
452- address scope
453- prefix matching against the destination
454- outgoing interface
455- whether an address is deprecated
456
457Roughly speaking, the selection policy is as follows:
458- always use an address that belongs to the same scope zone as the
459 destination.
460- addresses that have equal or larger scope than the scope of the
461 destination are preferred.
462- if multiple addresses have the equal scope, one which is longest
463 prefix matching against the destination is preferred.
464- a deprecated address is not used in new communications if an
465 alternate (non-deprecated) address is available and has sufficient
466 scope.
467- if none of above conditions tie-breaks, addresses assigned on the
468 outgoing interface are preferred.
469
470For instance, ::1 is selected for ff01::1,
471fe80::200:f8ff:fe01:6317%ne0 for fe80::2a0:24ff:feab:839b%ne0.
472To see how longest-matching works, suppose that
4733ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317
474are given on the outgoing interface. Then the former is chosen as the
475source for the destination 3ffe:501:800::1. Note that even if all
476available addresses have smaller scope than the scope of the
477destination, we choose one anyway. For example, if we have link-local
478and site-local addresses only, we choose a site-local addresses for a
479global destination. If the packet is going to break a site boundary,
480the boundary router will return an ICMPv6 destination unreachable
481error with code 2 - beyond scope of source address.
482
483The precise desripction of the algorithm is quite complicated. To
484describe the algorithm, we introduce the following notation:
485
486For a given destination D,
487 samescope(D): A set of addresses that have the same scope as D.
488 largerscope(D): A set of addresses that have a larger scope than D.
489 smallerscope(D): A set of addresses that have a smaller scope than D.
490
491For a given set of addresses A,
492 DEP(A): a set of deprecated addresses in A.
493 nonDEP(A): A - DEP(A).
494
495Also, the algorithm assumes that the outgoing interface for the
496destination D is determined. We call the interface "I".
497
498The algorithm is as follows. Selection proceeds step by step as
499described; For example, if an address is selected by item 1, item 2 or
500later are not considered at all.
501
502 0. If there is no address in the same scope zone as D, just give up;
503 the packet will not be sent.
504 1. If nonDEP(samescope(D)) is not empty,
505 choose a longest matching address against D. If more than one
506 address is longest matching, choose arbitrary one provided that
507 an address on I is always preferred.
508 2. If nonDEP(largerscope(D)) is not empty,
509 choose an address that has the smallest scope. If more than one
510 address has the smallest scope, choose arbitrary one provided
511 that an address on I is always preferred.
512 3. If DEP(samescope(D)) is not empty,
513 choose a longest matching address against D. If more than one
514 address is longest matching, choose arbitrary one provided that
515 an address on I is always preferred.
516 4. If DEP(largerscope(D)) is not empty,
517 choose an address that has the smallest scope. If more than one
518 address has the smallest scope, choose arbitrary one provided
519 that an address on I is always preferred.
520 5. if nonDEP(smallerscope(D)) is not empty,
521 choose an address that has the largest scope. If more than one
522 address has the largest scope, choose arbitrary one provided
523 that an address on I is always preferred.
524 6. if DEP(smallerscope(D)) is not empty,
525 choose an address that has the largest scope. If more than one
526 address has the largest scope, choose arbitrary one provided
527 that an address on I is always preferred.
528
529There exists a document about source address selection
530(draft-ietf-ipngwg-default-addr-select-xx.txt). KAME's algorithm
531described above takes a similar approach to the document, but there
532are some differences. See the document for more details.
533
534There are some cases where we do not use the above rule. One
535example is connected TCP session, and we use the address kept in TCP
536protocol control block (tcb) as the source.
537Another example is source address for Neighbor Advertisement.
538Under the spec (RFC2461 7.2.2) NA's source should be the target
539address of the corresponding NS's target. In this case we follow
540the spec rather than the above longest-match rule.
541
542If you would like to prohibit the use of deprecated address for some
543reason, configure net.inet6.ip6.use_deprecated to 0. The issue
544related to deprecated address is described in RFC2462 5.5.4 (NOTE:
545there is some debate underway in IETF ipngwg on how to use
546"deprecated" address).
547
5481.7 Jumbo Payload
549
550KAME supports the Jumbo Payload hop-by-hop option used to send IPv6
551packets with payloads longer than 65,535 octets. But since currently
552KAME does not support any physical interface whose MTU is more than
55365,535, such payloads can be seen only on the loopback interface(i.e.
554lo0).
555
556If you want to try jumbo payloads, you first have to reconfigure the
557kernel so that the MTU of the loopback interface is more than 65,535
558bytes; add the following to the kernel configuration file:
559 options "LARGE_LOMTU" #To test jumbo payload
560and recompile the new kernel.
561
562Then you can test jumbo payloads by the ping6 command with -b and -s
563options. The -b option must be specified to enlarge the size of the
564socket buffer and the -s option specifies the length of the packet,
565which should be more than 65,535. For example, type as follows;
566 % ping6 -b 70000 -s 68000 ::1
567
568The IPv6 specification requires that the Jumbo Payload option must not
569be used in a packet that carries a fragment header. If this condition
570is broken, an ICMPv6 Parameter Problem message must be sent to the
571sender. KAME kernel follows the specification, but you cannot usually
572see an ICMPv6 error caused by this requirement.
573
--- 19 unchanged lines hidden (view full) ---
593need this.
594
595IPsec does not work on jumbograms. This is due to some specification twists
596in supporting AH with jumbograms (AH header size influences payload length,
597and this makes it real hard to authenticate inbound packet with jumbo payload
598option as well as AH).
599
600There are fundamental issues in *BSD support for jumbograms. We would like to
601address those, but we need more time to finalize the task. To name a few:
602- mbuf pkthdr.len field is typed as "int" in 4.4BSD, so it cannot hold
603 jumbogram with len > 2G on 32bit architecture CPUs. If we would like to
604 support jumbogram properly, the field must be expanded to hold 4G +
605 IPv6 header + link-layer header. Therefore, it must be expanded to at least
606 int64_t (u_int32_t is NOT enough).
607- We mistakingly use "int" to hold packet length in many places. We need
608 to convert them into larger numeric type. It needs a great care, as we may
609 experience overflow during packet length computation.
610- We mistakingly check for ip6_plen field of IPv6 header for packet payload
611 length in various places. We should be checking mbuf pkthdr.len instead.
612 ip6_input() will perform sanity check on jumbo payload option on input,
613 and we can safely use mbuf pkthdr.len afterwards.
614- TCP code needs careful updates in bunch of places, of course.
615
6161.8 Loop prevention in header processing
617
618IPv6 specification allows arbitrary number of extension headers to
619be placed onto packets. If we implement IPv6 packet processing
620code in the way BSD IPv4 code is implemented, kernel stack may
621overflow due to long function call chain. KAME sys/netinet6 code
622is carefully designed to avoid kernel stack overflow. Because of
623this, KAME sys/netinet6 code defines its own protocol switch
624structure, as "struct ip6protosw" (see netinet6/ip6protosw.h).
625IPv4 part (sys/netinet) remains untouched for compatibility.
626Because of this, if you receive IPsec-over-IPv4 packet with massive
627number of IPsec headers, kernel stack may blow up. IPsec-over-IPv6 is okay.
628
6291.9 ICMPv6
630
631After RFC2463 was published, IETF ipngwg has decided to disallow ICMPv6 error
632packet against ICMPv6 redirect, to prevent ICMPv6 storm on a network medium.
633KAME already implements this into the kernel.
634
635RFC2463 requires rate limitation for ICMPv6 error packets generated by a
636node, to avoid possible DoS attacks. KAME kernel implements two rate-
637limitation mechanisms, tunable via sysctl:
638- Minimum time interval between ICMPv6 error packets
639 KAME kernel will generate no more than one ICMPv6 error packet,
640 during configured time interval. net.inet6.icmp6.errratelimit
641 controls the interval (default: disabled).
642- Maximum ICMPv6 error packet-per-second
643 KAME kernel will generate no more than the configured number of
644 packets in one second. net.inet6.icmp6.errppslimit controls the
645 maximum packet-per-second value (default: 200pps)
646Basically, we need to pick values that are suitable against the bandwidth
647of link layer devices directly attached to the node. In some cases the
648default values may not fit well. We are still unsure if the default value
649is sane or not. Comments are welcome.
650
6511.10 Applications
652
653For userland programming, we support IPv6 socket API as specified in
654RFC2553, RFC2292 and upcoming internet drafts.
655
656TCP/UDP over IPv6 is available and quite stable. You can enjoy "telnet",
657"ftp", "rlogin", "rsh", "ssh", etc. These applications are protocol
658independent. That is, they automatically chooses IPv4 or IPv6
--- 6 unchanged lines hidden (view full) ---
665
666The current KAME has escaped from the IPv4 netinet logic. While
667ip_forward() calls ip_output(), ip6_forward() directly calls
668if_output() since routers must not divide IPv6 packets into fragments.
669
670ICMPv6 should contain the original packet as long as possible up to
6711280. UDP6/IP6 port unreach, for instance, should contain all
672extension headers and the *unchanged* UDP6 and IP6 headers.
673So, all IP6 functions except TCP6 never convert network byte
674order into host byte order, to save the original packet.
675
676tcp6_input(), udp6_input() and icmp6_input() can't assume that IP6
677header is preceding the transport headers due to extension
678headers. So, in6_cksum() was implemented to handle packets whose IP6
679header and transport header is not continuous. TCP/IP6 nor UDP/IP6
680header structure don't exist for checksum calculation.
681
682To process IP6 header, extension headers and transport headers easily,
683KAME requires network drivers to store packets in one internal mbuf or
684one or more external mbufs. A typical old driver prepares two
685internal mbufs for 100 - 208 bytes data, however, KAME's reference
686implementation stores it in one external mbuf.
687
688"netstat -s -p ip6" tells you whether or not your driver conforms
689KAME's requirement. In the following example, "cce0" violates the
690requirement. (For more information, refer to Section 2.)
691
692 Mbuf statistics:
693 317 one mbuf
--- 5 unchanged lines hidden (view full) ---
699
700Each input function calls IP6_EXTHDR_CHECK in the beginning to check
701if the region between IP6 and its header is
702continuous. IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has
703M_LOOP flag, that is, the packet comes from the loopback
704interface. m_pullup() is never called for packets coming from physical
705network interfaces.
706
707TCP6 reassembly makes use of IP6 header to store reassemble
708information. IP6 is not supposed to be just before TCP6, so
709ip6tcpreass structure has a pointer to TCP6 header. Of course, it has
710also a pointer back to mbuf to avoid m_pullup().
711
712Like TCP6, both IP and IP6 reassemble functions never call m_pullup().
713
714xxx_ctlinput() calls in_mrejoin() on PRC_IFNEWADDR. We think this is
715one of 4.4BSD implementation flaws. Since 4.4BSD keeps ia_multiaddrs
716in in_ifaddr{}, it can't use multicast feature if the interface has no
717unicast address. So, if an application joins to an interface and then
718all unicast addresses are removed from the interface, the application
719can't send/receive any multicast packets. Moreover, if a new unicast
720address is assigned to the interface, in_mrejoin() must be called.
721KAME's interfaces, however, have ALWAYS one link-local unicast
722address. These extensions have thus not been implemented in KAME.
723
7241.12 IPv4 mapped address and IPv6 wildcard socket
725
726RFC2553 describes IPv4 mapped address (3.7) and special behavior
727of IPv6 wildcard bind socket (3.8). The spec allows you to:
728- Accept IPv4 connections by AF_INET6 wildcard bind socket.
729- Transmit IPv4 packet over AF_INET6 socket by using special form of
730 the address like ::ffff:10.1.1.1.
731but the spec itself is very complicated and does not specify how the
732socket layer should behave.
733Here we call the former one "listening side" and the latter one "initiating
734side", for reference purposes.
735
736Almost all KAME implementations treat tcp/udp port number space separately
737between IPv4 and IPv6. You can perform wildcard bind on both of the address
738families, on the same port.
739
740There are some OS-platform differences in KAME code, as we use tcp/udp
741code from different origin. The following table summarizes the behavior.
742
743 listening side initiating side
744 (AF_INET6 wildcard (connection to ::ffff:10.1.1.1)
745 socket gets IPv4 conn.)
746 --- ---
747KAME/BSDI3 not supported not supported
748KAME/FreeBSD228 not supported not supported
749KAME/FreeBSD3x configurable supported
750 default: enabled
751KAME/FreeBSD4x configurable supported
752 default: enabled
753KAME/NetBSD configurable supported
754 default: disabled
755KAME/BSDI4 enabled supported
756KAME/OpenBSD not supported not supported
757
758The following sections will give you more details, and how you can
759configure the behavior.
760
761Comments on listening side:
762
763It looks that RFC2553 talks too little on wildcard bind issue,
764specifically on (1) port space issue, (2) failure mode, (3) relationship
765between AF_INET/INET6 wildcard bind like ordering constraint, and (4) behavior
766when conflicting socket is opened/closed. There can be several separate
767interpretation for this RFC which conform to it but behaves differently.
768So, to implement portable application you should assume nothing
769about the behavior in the kernel. Using getaddrinfo() is the safest way.
770Port number space and wildcard bind issues were discussed in detail
771on ipv6imp mailing list, in mid March 1999 and it looks that there's
772no concrete consensus (means, up to implementers). You may want to
773check the mailing list archives.
774We supply a tool called "bindtest" that explores the behavior of
775kernel bind(2). The tool will not be compiled by default.
776
777If a server application would like to accept IPv4 and IPv6 connections,
778it should use AF_INET and AF_INET6 socket (you'll need two sockets).
779Use getaddrinfo() with AI_PASSIVE into ai_flags, and socket(2) and bind(2)
780to all the addresses returned.
781By opening multiple sockets, you can accept connections onto the socket with
782proper address family. IPv4 connections will be accepted by AF_INET socket,
783and IPv6 connections will be accepted by AF_INET6 socket (NOTE: KAME/BSDI4
784kernel sometimes violate this - we will fix it).
785
786If you try to support IPv6 traffic only and would like to reject IPv4
787traffic, always check the peer address when a connection is made toward
788AF_INET6 listening socket. If the address is IPv4 mapped address, you may
789want to reject the connection. You can check the condition by using
790IN6_IS_ADDR_V4MAPPED() macro. This is one of the reasons the author of
791the section (itojun) dislikes special behavior of AF_INET6 wildcard bind.
792
793Comments on initiating side:
794
795Advise to application implementers: to implement a portable IPv6 application
796(which works on multiple IPv6 kernels), we believe that the following
797is the key to the success:
798- NEVER hardcode AF_INET nor AF_INET6.
799- Use getaddrinfo() and getnameinfo() throughout the system.
800 Never use gethostby*(), getaddrby*(), inet_*() or getipnodeby*().
801- If you would like to connect to destination, use getaddrinfo() and try
802 all the destination returned, like telnet does.
803- Some of the IPv6 stack is shipped with buggy getaddrinfo(). Ship a minimal
804 working version with your application and use that as last resort.
805
806If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing
807connection, you will need tweaked implementation in DNS support libraries,
808as documented in RFC2553 6.1. KAME libinet6 includes the tweak in
809getipnodebyname(). Note that getipnodebyname() itself is not recommended as
810it does not handle scoped IPv6 addresses at all. For IPv6 name resolution
811getaddrinfo() is the preferred API. getaddrinfo() does not implement the
812tweak.
813
814When writing applications that make outgoing connections, story goes much
815simpler if you treat AF_INET and AF_INET6 as totally separate address family.
816{set,get}sockopt issue goes simpler, DNS issue will be made simpler. We do
817not recommend you to rely upon IPv4 mapped address.
818
8191.12.1 KAME/BSDI3 and KAME/FreeBSD228
820
821The platforms do not support IPv4 mapped address at all (both listening side
822and initiating side). AF_INET6 and AF_INET sockets are totally separated.
823
824Port number space is totally separate between AF_INET and AF_INET6 sockets.
825
8261.12.2 KAME/FreeBSD[34]x
827
828KAME/FreeBSD3x and KAME/FreeBSD4x use shared tcp4/6 code (from
829sys/netinet/tcp*) and shared udp4/6 code (from sys/netinet/udp*).
830They use unified inpcb/in6pcb structure.
831
8321.12.2.1 KAME/FreeBSD[34]x, listening side
833
834The platform can be configured to support IPv4 mapped address/special
835AF_INET6 wildcard bind (enabled by default). There is no kernel compilation
836option to disable it. You can enable/disable the behavior with sysctl
837(per-node), or setsockopt (per-socket).
838
839Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
840conditions are satisfied:
841- there's no AF_INET socket that matches the IPv4 connection
842- the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
843 getsockopt(IPV6_BINDV6ONLY) returns 0.
844
845(XXX need checking)
846
8471.12.2.2 KAME/FreeBSD[34]x, initiating side
848
849KAME/FreeBSD3x supports outgoing connection to IPv4 mapped address
850(::ffff:10.1.1.1), if the node is configured to accept IPv4 connections
851by AF_INET6 socket.
852
853(XXX need checking)
854
8551.12.3 KAME/NetBSD
856
857KAME/NetBSD uses shared tcp4/6 code (from sys/netinet/tcp*) and shared
858udp4/6 code (from sys/netinet/udp*). The implementation is made differently
859from KAME/FreeBSD[34]x. KAME/NetBSD uses separate inpcb/in6pcb structures,
860while KAME/FreeBSD[34]x uses merged inpcb structure.
861
8621.12.3.1 KAME/NetBSD, listening side
863
864The platform can be configured to support IPv4 mapped address/special AF_INET6
865wildcard bind (disabled by default). Kernel behavior can be summarized as
866follows:
867- default: special support code will be compiled in, but is disabled by
868 default. It can be controlled by sysctl (net.inet6.ip6.bindv6only),
869 or setsockopt(IPV6_BINDV6ONLY).
870- add "INET6_BINDV6ONLY": No special support code for AF_INET6 wildcard socket
871 will be compiled in. AF_INET6 sockets and AF_INET sockets are totally
872 separate. The behavior is similar to what described in 1.12.1.
873
874sysctl setting will affect per-socket configuration at in6pcb creation time
875only. In other words, per-socket configuration will be copied from sysctl
876configuration at in6pcb creation time. To change per-socket behavior, you
877must perform setsockopt or reopen the socket. Change in sysctl configuration
878will not change the behavior or sockets that are already opened.
879
880Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
881conditions are satisfied:
882- there's no AF_INET socket that matches the IPv4 connection
883- the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
884 getsockopt(IPV6_BINDV6ONLY) returns 0.
885
886You cannot bind(2) with IPv4 mapped address. This is a workaround for port
887number duplicate and other twists.
888
8891.12.3.2 KAME/NetBSD, initiating side
890
891When you initiate a connection, you can always connect to IPv4 destination
892over AF_INET6 socket, usin IPv4 mapped address destination (::ffff:10.1.1.1).
893This is enabled independently from the configuration for listening side, and
894always enabled.
895
8961.12.4 KAME/BSDI4
897
898KAME/BSDI4 uses NRL-based TCP/UDP stack and inpcb source code,
899which was derived from NRL IPv6/IPsec stack. We guess it supports IPv4 mapped
900address and speical AF_INET6 wildcard bind. The implementation is, again,
901different from other KAME/*BSDs.
902
9031.12.4.1 KAME/BSDI4, listening side
904
905NRL inpcb layer supports special behavior of AF_INET6 wildcard socket.
906There is no way to disable the behavior.
907
908Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
909condition is satisfied:
910- there's no AF_INET socket that matches the IPv4 connection
911
9121.12.4.2 KAME/BSDI4, initiating side
913
914KAME/BSDi4 supports connection initiation to IPv4 mapped address
915(like ::ffff:10.1.1.1).
916
9171.12.5 KAME/OpenBSD
918
919KAME/OpenBSD uses NRL-based TCP/UDP stack and inpcb source code,
920which was derived from NRL IPv6/IPsec stack.
921
9221.12.5.1 KAME/OpenBSD, listening side
923
924KAME/OpenBSD disables special behavior on AF_INET6 wildcard bind for
925security reasons (if IPv4 traffic toward AF_INET6 wildcard bind is allowed,
926access control will become much harder). KAME/BSDI4 uses NRL-based TCP/UDP
927stack as well, however, the behavior is different due to OpenBSD's security
928policy.
929
930As a result the behavior of KAME/OpenBSD is similar to KAME/BSDI3 and
931KAME/FreeBSD228 (see 1.12.1 for more detail).
932
9331.12.5.2 KAME/OpenBSD, initiating side
934
935KAME/OpenBSD does not support connection initiation to IPv4 mapped address
936(like ::ffff:10.1.1.1).
937
9381.12.6 More issues
939
940IPv4 mapped address support adds a big requirement to EVERY userland codebase.
941Every userland code should check if an AF_INET6 sockaddr contains IPv4
942mapped address or not. This adds many twists:
943
944- Access controls code becomes harder to write.
945 For example, if you would like to reject packets from 10.0.0.0/8,
946 you need to reject packets to AF_INET socket from 10.0.0.0/8,
947 and to AF_INET6 socket from ::ffff:10.0.0.0/104.
948- If a protocol on top of IPv4 is defined differently with IPv6, we need to be
949 really careful when we determine which protocol to use.
950 For example, with FTP protocol, we can not simply use sa_family to determine
951 FTP command sets. The following example is incorrect:
952 if (sa_family == AF_INET)
953 use EPSV/EPRT or PASV/PORT; /*IPv4*/
954 else if (sa_family == AF_INET6)
955 use EPSV/EPRT or LPSV/LPRT; /*IPv6*/
956 else
957 error;
958 Under SIIT environment, the correct code would be:
959 if (sa_family == AF_INET)
960 use EPSV/EPRT or PASV/PORT; /*IPv4*/
961 else if (sa_family == AF_INET6 && IPv4 mapped address)
962 use EPSV/EPRT or PASV/PORT; /*IPv4 command set on AF_INET6*/
963 else if (sa_family == AF_INET6 && !IPv4 mapped address)
964 use EPSV/EPRT or LPSV/LPRT; /*IPv6*/
965 else
966 error;
967 It is too much to ask for every body to be careful like this.
968 The problem is, we are not sure if the above code fragment is perfect for
969 all situations.
970- By enabling kernel support for IPv4 mapped address (outgoing direction),
971 servers on the kernel can be hosed by IPv6 native packet that has IPv4
972 mapped address in IPv6 header source, and can generate unwanted IPv4 packets.
973 http://playground.iijlab.net/i-d/draft-itojun-ipv6-transition-abuse-00.txt
974 talks more about this scenario.
975
976Due to the above twists, some of KAME userland programs has restrictions on
977the use of IPv4 mapped addresses:
978- rshd/rlogind do not accept connections from IPv4 mapped address.
979 This is to avoid malicious use of IPv4 mapped address in IPv6 native
980 packet, to bypass source-address based authentication.
981- ftp/ftpd does not support SIIT environment. IPv4 mapped address will be
982 decoded in userland, and will be passed to AF_INET sockets
983 (SIIT client should pass IPv4 mapped address as is, to AF_INET6 sockets).
984
9851.13 sockaddr_storage
986
987When RFC2553 was about to be finalized, there was discussion on how struct
988sockaddr_storage members are named. One proposal is to prepend "__" to the
989members (like "__ss_len") as they should not be touched. The other proposal
990was that don't prepend it (like "ss_len") as we need to touch those members
991directly. There was no clear consensus on it.
992
993As a result, RFC2553 defines struct sockaddr_storage as follows:
994 struct sockaddr_storage {
995 u_char __ss_len; /* address length */
--- 7 unchanged lines hidden (view full) ---
1003 /* and bunch of padding */
1004 };
1005
1006In December 1999, it was agreed that RFC2553bis should pick the latter (XNET)
1007definition.
1008
1009KAME kit prior to December 1999 used RFC2553 definition. KAME kit after
1010December 1999 (including December) will conform to XNET definition,
1011based on RFC2553bis discussion.
1012
1013If you look at multiple IPv6 implementations, you will be able to see
1014both definitions. As an userland programmer, the most portable way of
1015dealing with it is to:
1016(1) ensure ss_family and/or ss_len are available on the platform, by using
1017 GNU autoconf,
1018(2) have -Dss_family=__ss_family to unify all occurences (including header
1019 file) into __ss_family, or
1020(3) never touch __ss_family. cast to sockaddr * and use sa_family like:
1021 struct sockaddr_storage ss;
1022 family = ((struct sockaddr *)&ss)->sa_family
1023
10241.14 Invalid addresses on the wire
1025
1026Some of IPv6 transition technologies embed IPv4 address into IPv6 address.
1027These specifications themselves are fine, however, there can be certain
1028set of attacks enabled by these specifications. Recent speicifcation
1029documents covers up those issues, however, there are already-published RFCs
1030that does not have protection against those (like using source address of
1031::ffff:127.0.0.1 to bypass "reject packet from remote" filter).
1032
1033To name a few, these address ranges can be used to hose an IPv6 implementation,
1034or bypass security controls:
1035- IPv4 mapped address that embeds unspecified/multicast/loopback/broadcast
1036 IPv4 address (if they are in IPv6 native packet header, they are malicious)
1037 ::ffff:0.0.0.0/104 ::ffff:127.0.0.0/104
1038 ::ffff:224.0.0.0/100 ::ffff:255.0.0.0/104
1039- 6to4 prefix generated from unspecified/multicast/loopback/broadcast/private
1040 IPv4 address
1041 2002:0000::/24 2002:7f00::/24 2002:e000::/24
1042 2002:ff00::/24 2002:0a00::/24 2002:ac10::/28
1043 2002:c0a8::/32
1044
1045Also, since KAME does not support RFC1933 auto tunnels, seeing IPv4 compatible
1046is very rare. You should take caution if you see those on the wire.
1047
1048KAME code is carefully written to avoid such incidents. More specifically,
1049KAME kernel will reject packets with certain source/dstination address in IPv6
1050base header, or IPv6 routing header. Also, KAME default configuration file
1051is written carefully, to avoid those attacks.
1052
1053http://playground.iijlab.net/i-d/draft-itojun-ipv6-transition-abuse-00.txt
1054talks about more about this.
1055
10561.15 Node's required addresses
1057
1058RFC2373 section 2.8 talks about required addresses for an IPv6
1059node. The section talks about how KAME stack manages those required
1060addresses.
1061
10621.15.1 Host case
1063
1064The following items are automatically assigned to the node (or the node will
1065automatically joins the group), at bootstrap time:
1066- Loopback address
1067- All-nodes multicast addresses (ff01::1)
1068
1069The following items will be automatically handled when the interface becomes
1070IFF_UP:
1071- Its link-local address for each interface
1072- Solicited-node multicast address for link-local addresses
1073- Link-local allnodes multicast address (ff02::1)
1074
1075The following items need to be configured manually by ifconfig(8) or prefix(8).
1076Alternatively, these can be autoconfigured by using stateless address
1077autoconfiguration.
1078- Assigned unicast/anycast addresses
1079- Solicited-Node multicast address for assigned unicast address
1080
1081Users can join groups by using appropriate system calls like setsockopt(2).
1082
10831.15.2 Router case
1084
1085In addition to the above, routers needs to handle the following items.
1086
1087The following items need to be configured manually by using ifconfig(8).
1088o The subnet-router anycast addresses for the interfaces it is configured
1089 to act as a router on (prefix::/64)
1090o All other anycast addresses with which the router has been configured
1091
1092The router will join the following multicast group when rtadvd(8) is available
1093for the interface.
1094o All-Routers Multicast Addresses (ff02::2)
1095
1096Routing daemons will join appropriate multicast groups, as necessary,
1097like ff02::9 for RIPng.
1098
1099Users can join groups by using appropriate system calls like setsockopt(2).
1100
11012. Network Drivers
1102
1103KAME requires three items to be added into the standard drivers:
1104
1105(1) mbuf clustering requirement. In this stable release, we changed
1106 MINCLSIZE into MHLEN+1 for all the operating systems in order to make
1107 all the drivers behave as we expect.
1108
1109(2) multicast. If "ifmcstat" yields no multicast group for a
1110 interface, that interface has to be patched.
1111
1112To avoid troubles, we suggest you to comment out the device drivers
1113for unsupported/unnecessary cards, from the kernel configuration file.
1114If you accidentally enable unsupported drivers, some of the userland
1115tools may not work correctly (routing daemons are typical example).
1116
1117In the following sections, "official support" means that KAME developers
1118are using that ethernet card/driver frequently.
1119
1120(NOTE: In the past we required all pcmcia drivers to have a call to
1121in6_ifattach(). We have no such requirement any more)
1122
11232.1 FreeBSD 2.2.x-RELEASE
1124
1125Here is a list of FreeBSD 2.2.x-RELEASE drivers and its conditions:
1126
1127 driver mbuf(1) multicast(2) official support?
1128 --- --- --- ---
1129 (Ethernet)
1130 ar looks ok - -
1131 cnw ok ok yes (*)
1132 ed ok ok yes
1133 ep ok ok yes
1134 fe ok ok yes
1135 sn looks ok - - (*)
1136 vx looks ok - -
1137 wlp ok ok - (*)
1138 xl ok ok yes
1139 zp ok ok -
1140 (FDDI)
1141 fpa looks ok ? -
1142 (ATM)
1143 en ok ok yes
1144 (Serial)
1145 lp ? - not work
1146 sl ? - not work
1147 sr looks ok ok - (**)
1148
1149You may want to add an invocation of "rtsol" in "/etc/pccard_ether",
1150if you are using notebook computers and PCMCIA ethernet card.
1151
1152(*) These drivers are distributed with PAO (http://www.jp.freebsd.org/PAO/).
1153
1154(**) There was some report says that, if you make sr driver up and down and
1155then up, the kernel may hang up. We have disabled frame-relay support from
1156sr driver and after that this looks to be working fine. If you need
1157frame-relay support to come back, please contact KAME developers.
1158
11592.2 BSD/OS 3.x
1160
1161The following lists BSD/OS 3.x device drivers and its conditions:
1162
1163 driver mbuf(1) multicast(2) official support?
1164 --- --- --- ---
1165 (Ethernet)
1166 cnw ok ok yes
1167 de ok ok -
1168 df ok ok -
1169 eb ok ok -
1170 ef ok ok yes
1171 exp ok ok -
1172 mz ok ok yes
1173 ne ok ok yes
1174 we ok ok -
1175 (FDDI)
1176 fpa ok ok -
1177 (ATM)
1178 en maybe ok -
1179 (Serial)
1180 ntwo ok ok yes
1181 sl ? - not work
1182 appp ? - not work
1183
1184You may want to use "@insert" directive in /etc/pccard.conf to invoke
1185"rtsol" command right after dynamic insertion of PCMCIA ethernet cards.
1186
11872.3 NetBSD
1188
1189The following table lists the network drivers we have tried so far.
1190
1191 driver mbuf(1) multicast(2) official support?
1192 --- --- --- ---
1193 (Ethernet)
1194 awi pcmcia/i386 ok ok -
1195 bah zbus/amiga NG(*)
1196 cnw pcmcia/i386 ok ok yes
1197 ep pcmcia/i386 ok ok -
1198 le sbus/sparc ok ok yes
1199 ne pci/i386 ok ok yes
1200 ne pcmcia/i386 ok ok yes
1201 wi pcmcia/i386 ok ok yes
1202 (ATM)
1203 en pci/i386 ok ok -
1204
1205(*) This may need some fix, but I'm not sure what arcnet interfaces assume...
1206
12072.4 FreeBSD 3.x-RELEASE
1208
1209Here is a list of FreeBSD 3.x-RELEASE drivers and its conditions:
1210
1211 driver mbuf(1) multicast(2) official support?
1212 --- --- --- ---
1213 (Ethernet)
1214 cnw ok ok -(*)
1215 ed ? ok -
1216 ep ok ok -
1217 fe ok ok yes
1218 fxp ?(**)
1219 lnc ? ok -
1220 sn ? ? -(*)
1221 wi ok ok yes
1222 xl ? ok -
1223
1224(*) These drivers are distributed with PAO as PAO3
1225 (http://www.jp.freebsd.org/PAO/).
1226(**) there are trouble reports with multicast filter initialization.
1227
1228More drivers will just simply work on KAME FreeBSD 3.x-RELEASE but have not
1229been checked yet.
1230
12312.5 OpenBSD 2.x
1232
1233Here is a list of OpenBSD 2.x drivers and its conditions:
1234
1235 driver mbuf(1) multicast(2) official support?
1236 --- --- --- ---
1237 (Ethernet)
1238 de pci/i386 ok ok yes
1239 fxp pci/i386 ?(*)
1240 le sbus/sparc ok ok yes
1241 ne pci/i386 ok ok yes
1242 ne pcmcia/i386 ok ok yes
1243 wi pcmcia/i386 ok ok yes
1244
1245(*) There seem to be some problem in driver, with multicast filter
1246configuration. This happens with certain revision of chipset on the card.
1247Should be fixed by now by workaround in sys/net/if.c, but still not sure.
1248
12492.6 BSD/OS 4.x
1250
1251The following lists BSD/OS 4.x device drivers and its conditions:
1252
1253 driver mbuf(1) multicast(2) official support?
1254 --- --- --- ---
1255 (Ethernet)
1256 de ok ok yes
1257 exp (*)
1258
1259You may want to use "@insert" directive in /etc/pccard.conf to invoke
1260"rtsol" command right after dynamic insertion of PCMCIA ethernet cards.
1261
1262(*) exp driver has serious conflict with KAME initialization sequence.
1263A workaround is committed into sys/i386/pci/if_exp.c, and should be okay by now.
1264
12653. Translator
1266
1267We categorize IPv4/IPv6 translator into 4 types.
1268
1269Translator A --- It is used in the early stage of transition to make
1270it possible to establish a connection from an IPv6 host in an IPv6
1271island to an IPv4 host in the IPv4 ocean.
1272
--- 6 unchanged lines hidden (view full) ---
1279to an IPv6 host in the IPv6 ocean.
1280
1281Translator D --- It is used in the late stage of transition to make it
1282possible to establish a connection from an IPv6 host in the IPv6 ocean
1283to an IPv4 host in an IPv4 island.
1284
1285KAME provides an TCP relay translator for category A. This is called
1286"FAITH". We also provide IP header translator for category A.
1287
12883.1 FAITH TCP relay translator
1289
1290FAITH system uses TCP relay daemon called "faithd" helped by the KAME kernel.
1291FAITH will reserve an IPv6 address prefix, and relay TCP connection
1292toward that prefix to IPv4 destination.
1293
1294For example, if the reserved IPv6 prefix is 3ffe:0501:0200:ffff::, and
--- 5 unchanged lines hidden (view full) ---
1300 | IPv4 tcp toward 163.221.202.12
1301 FAITH-relay dual stack node
1302 ^
1303 | IPv6 TCP toward 3ffe:0501:0200:ffff::163.221.202.12
1304 source IPv6 node
1305
1306faithd must be invoked on FAITH-relay dual stack node.
1307
1308For more details, consult kame/kame/faithd/README and
1309draft-ietf-ngtrans-tcpudp-relay-01.txt.
1310
13113.2 IPv6-to-IPv4 header translator
1312
1313# removed since it is not imported to FreeBSD-current
1314
13154. IPsec
1316
1317IPsec is implemented as the following three components.
1318
1319(1) Policy Management
1320(2) Key Management
1321(3) AH, ESP and IPComp handling in kernel
1322
1323Note that KAME/OpenBSD does NOT include support for KAME IPsec code,
1324as OpenBSD team has their home-brew IPsec stack and they have no plan
1325to replace it. IPv6 support for IPsec is, therefore, lacking on KAME/OpenBSD.
1326
13274.1 Policy Management
1328
1329The kernel implements experimental policy management code. There are two way
1330to manage security policy. One is to configure per-socket policy using
1331setsockopt(3). In this cases, policy configuration is described in
1332ipsec_set_policy(3). The other is to configure kernel packet filter-based
1333policy using PF_KEY interface, via setkey(8).
1334
1335The policy entry will be matched in order. The order of entries makes
1336difference in behavior.
1337
13384.2 Key Management
1339
1340The key management code implemented in this kit (sys/netkey) is a
1341home-brew PFKEY v2 implementation. This conforms to RFC2367.
1342
1343The home-brew IKE daemon, "racoon" is included in the kit (kame/kame/racoon,
1344or usr.sbin/racoon).
1345Basically you'll need to run racoon as daemon, then setup a policy
1346to require keys (like ping -P 'out ipsec esp/transport//use').
1347The kernel will contact racoon daemon as necessary to exchange keys.
1348
1349In IKE spec, there's ambiguity about interpretation of "tunnel" proposal.
1350For example, if we would like to propose the use of following packet:
1351 IP AH ESP IP payload
1352some implementation proposes it as "AH transport and ESP tunnel", since
1353this is more logical from packet construction point of view. Some
1354implementation proposes it as "AH tunnel and ESP tunnel".
1355Racoon follows the former route.
1356This raises real interoperability issue. We hope this to be resolved quickly.
1357
13584.3 AH and ESP handling
1359
1360IPsec module is implemented as "hooks" to the standard IPv4/IPv6
1361processing. When sending a packet, ip{,6}_output() checks if ESP/AH
1362processing is required by checking if a matching SPD (Security
1363Policy Database) is found. If ESP/AH is needed,
1364{esp,ah}{4,6}_output() will be called and mbuf will be updated
1365accordingly. When a packet is received, {esp,ah}4_input() will be
--- 7 unchanged lines hidden (view full) ---
1373extra daisy-chained headers inserted by ESP/AH. Our code takes care of
1374the case.
1375
1376Basic crypto functions can be found in directory "sys/crypto". ESP/AH
1377transform are listed in {esp,ah}_core.c with wrapper functions. If you
1378wish to add some algorithm, add wrapper function in {esp,ah}_core.c, and
1379add your crypto algorithm code into sys/crypto.
1380
1381Tunnel mode works basically fine, but comes with the following restrictions:
1382- You cannot run routing daemon across IPsec tunnel, since we do not model
1383 IPsec tunnel as pseudo interfaces.
1384- Authentication model for AH tunnel must be revisited. We'll need to
1385 improve the policy management engine, eventually.
1386- Tunnelling for IPv6 IPsec is still incomplete. This is disabled by default.
1387 If you need to perform experiments, add "options IPSEC_IPV6FWD" into
1388 the kernel configuration file. Note that path MTU discovery does not work
1389 across IPv6 IPsec tunnel gateway due to insufficient code.
1390
1391AH specificaton does not talk much about "multiple AH on a packet" case.
1392We incrementally compute AH checksum, from inside to outside. Also, we
1393treat inner AH to be immutable.
1394For example, if we are to create the following packet:
1395 IP AH1 AH2 AH3 payload
1396we do it incrementally. As a result, we get crypto checksums like below:
1397 AH3 has checksum against "IP AH3' payload".
1398 where AH3' = AH3 with checksum field filled with 0.
1399 AH2 has checksum against "IP AH2' AH3 payload".
1400 AH1 has checksum against "IP AH1' AH2 AH3 payload",
1401Also note that AH3 has the smallest sequence number, and AH1 has the largest
1402sequence number.
1403
14044.4 IPComp handling
1405
1406IPComp stands for IP payload compression protocol. This is aimed for
1407payload compression, not the header compression like PPP VJ compression.
1408This may be useful when you are using slow serial link (say, cell phone)
1409with powerful CPU (well, recent notebook PCs are really powerful...).
1410The protocol design of IPComp is very similar to IPsec, though it was
1411defined separately from IPsec itself.
1412
1413Here are some points to be noted:
1414- IPComp is treated as part of IPsec protocol suite, and SPI and
1415 CPI space is unified. Spec says that there's no relationship
1416 between two so they are assumed to be separate in specs.
1417- IPComp association (IPCA) is kept in SAD.
1418- It is possible to use well-known CPI (CPI=2 for DEFLATE for example),
1419 for outbound/inbound packet, but for indexing purposes one element from
1420 SPI/CPI space will be occupied anyway.
1421- pfkey is modified to support IPComp. However, there's no official
1422 SA type number assignment yet. Portability with other IPComp
1423 stack is questionable (anyway, who else implement IPComp on UN*X?).
1424- Spec says that IPComp output processing must be performed before AH/ESP
1425 output processing, to achieve better compression ratio and "stir" data
1426 stream before encryption. The most meaningful processing order is:
1427 (1) compress payload by IPComp, (2) encrypt payload by ESP, then (3) attach
1428 authentication data by AH.
1429 However, with manual SPD setting, you are able to violate the ordering
1430 (KAME code is too generic, maybe). Also, it is just okay to use IPComp
1431 alone, without AH/ESP.
1432- Though the packet size can be significantly decreased by using IPComp, no
1433 special consideration is made about path MTU (spec talks nothing about MTU
1434 consideration). IPComp is designed for serial links, not ethernet-like
1435 medium, it seems.
1436- You can change compression ratio on outbound packet, by changing
1437 deflate_policy in sys/netinet6/ipcomp_core.c. You can also change outbound
1438 history buffer size by changing deflate_window_out in the same source code.
1439 (should it be sysctl accessible, or per-SAD configurable?)
1440- Tunnel mode IPComp is not working right. KAME box can generate tunnelled
1441 IPComp packet, however, cannot accept tunneled IPComp packet.
1442- You can negotiate IPComp association with racoon IKE daemon.
1443- KAME code does not attach Adler32 checksum to compressed data.
1444 see ipsec wg mailing list discussion in Jan 2000 for details.
1445
14464.5 Conformance to RFCs and IDs
1447
1448The IPsec code in the kernel conforms (or, tries to conform) to the
1449following standards:
1450 "old IPsec" specification documented in rfc182[5-9].txt
1451 "new IPsec" specification documented in rfc240[1-6].txt, rfc241[01].txt,
1452 rfc2451.txt and draft-mcdonald-simple-ipsec-api-01.txt (draft expired,
1453 but you can take from ftp://ftp.kame.net/pub/internet-drafts/).
1454 (NOTE: IKE specifications, rfc240[7-9].txt are implemented in userland,
1455 as "racoon" IKE daemon)
1456 IPComp:
1457 RFC2393: IP Payload Compression Protocol (IPComp)
1458
1459Currently supported algorithms are:
1460 old IPsec AH
1461 null crypto checksum (no document, just for debugging)
1462 keyed MD5 with 128bit crypto checksum (rfc1828.txt)
1463 keyed SHA1 with 128bit crypto checksum (no document)
1464 HMAC MD5 with 128bit crypto checksum (rfc2085.txt)
1465 HMAC SHA1 with 128bit crypto checksum (no document)
--- 13 unchanged lines hidden (view full) ---
1479 DES-CBC with explicit IV (rfc2405.txt)
1480 3DES-CBC with explicit IV (rfc2451.txt)
1481 BLOWFISH CBC (rfc2451.txt)
1482 CAST128 CBC (rfc2451.txt)
1483 RC5 CBC (rfc2451.txt)
1484 each of the above can be combined with:
1485 ESP authentication with HMAC-MD5(96bit)
1486 ESP authentication with HMAC-SHA1(96bit)
1487 IPComp
1488 RFC2394: IP Payload Compression Using DEFLATE
1489
1490The following algorithms are NOT supported:
1491 old IPsec AH
1492 HMAC MD5 with 128bit crypto checksum + 64bit replay prevention
1493 (rfc2085.txt)
1494 keyed SHA1 with 160bit crypto checksum + 32bit padding (rfc1852.txt)
1495
1496The key/policy management API is based on the following document, with fair
1497amount of extensions:
1498 RFC2367: PF_KEY key management API
1499
15004.6 ECN consideration on IPsec tunnels
1501
1502KAME IPsec implements ECN-friendly IPsec tunnel, described in
1503draft-ietf-ipsec-ecn-02.txt.
1504Normal IPsec tunnel is described in RFC2401. On encapsulation,
1505IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner
1506IP header to outer IP header. On decapsulation outer IP header
1507will be simply dropped. The decapsulation rule is not compatible
1508with ECN, since ECN bit on the outer IP TOS/traffic class field will be
1509lost.
1510To make IPsec tunnel ECN-friendly, we should modify encapsulation
1511and decapsulation procedure. This is described in
1512draft-ietf-ipsec-ecn-02.txt, chapter 3.3.
1513
1514KAME IPsec tunnel implementation can give you three behaviors, by setting
1515net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some value:
1516- RFC2401: no consideration for ECN (sysctl value -1)
1517- ECN forbidden (sysctl value 0)
1518- ECN allowed (sysctl value 1)
1519Note that the behavior is configurable in per-node manner, not per-SA manner
1520(draft-ietf-ipsec-ecn-02 wants per-SA configuration, but it looks too much
1521for me).
1522
1523The behavior is summarized as follows (see source code for more detail):
1524
1525 encapsulate decapsulate
1526 --- ---
1527RFC2401 copy all TOS bits drop TOS bits on outer
1528 from inner to outer. (use inner TOS bits as is)
1529
--- 10 unchanged lines hidden (view full) ---
1540- if both IPsec tunnel endpoint are capable of ECN-friendly behavior,
1541 you'd better configure both end to "ECN allowed" (sysctl value 1).
1542- if the other end is very strict about TOS bit, use "RFC2401"
1543 (sysctl value -1).
1544- in other cases, use "ECN forbidden" (sysctl value 0).
1545The default behavior is "ECN forbidden" (sysctl value 0).
1546
1547For more information, please refer to:
1548 draft-ietf-ipsec-ecn-02.txt
1549 RFC2481 (Explicit Congestion Notification)
1550 KAME sys/netinet6/{ah,esp}_input.c
1551
1552(Thanks goes to Kenjiro Cho <kjc@csl.sony.co.jp> for detailed analysis)
1553
15544.7 Interoperability
1555
1556IPsec, IPComp (in kernel) and IKE (in userland as "racoon") has been tested
1557at several interoperability test events, and it is known to interoperate
1558with many other implementations well. Also, KAME IPsec has quite wide
1559coverage for IPsec crypto algorithms documented in RFC (we do not cover
1560algorithms with intellectual property issues, though).
1561
1562Here are (some of) platforms we have tested IPsec/IKE interoperability
1563in the past, in no particular order. Note that both ends (KAME and
1564others) may have modified their implementation, so use the following
1565list just for reference purposes.
1566 Altiga, Ashley-laurent (vpcom.com), Data Fellows (F-Secure),
1567 BlueSteel, CISCO, Ericsson, ACC, Fitel, FreeS/WAN, HITACHI, IBM
1568 AIX, IIJ, Intel, Microsoft WinNT, NAI PGPnet,
1569 NIST (linux IPsec + plutoplus), Netscreen, OpenBSD isakmpd, Radguard,
1570 RedCreek, Routerware, SSH, Secure Computing, Soliton, Toshiba,
1571 TIS/NAI Gauntret, VPNet, Yamaha RT100i
1572
1573Here are (some of) platforms we have tested IPComp/IKE interoperability
1574in the past, in no particular order.
1575 IRE
1576
15775. ALTQ
1578
1579# removed since it is not imported to FreeBSD-current
1580
15816. mobile-ip6
1582
1583# removed since it is not imported to FreeBSD-current
1584
1585 <end of IMPLEMENTATION>