Remove remainings of the oltr(4).
[dragonfly.git] / share / doc / IPv6 / IMPLEMENTATION
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         $KAME: IMPLEMENTATION,v 1.216 2001/05/25 07:43:01 jinmei Exp $
10         $FreeBSD: src/share/doc/IPv6/IMPLEMENTATION,v 1.1.2.2 2001/07/03 11:01:21 ume Exp $
11         $DragonFly: src/share/doc/IPv6/IMPLEMENTATION,v 1.2 2003/06/17 04:36:56 dillon Exp $
12
13 1. IPv6
14
15 1.1 Conformance
16
17 The KAME kit conforms, or tries to conform, to the latest set of IPv6
18 specifications.  For future reference we list some of the relevant documents
19 below (NOTE: this is not a complete list - this is too hard to maintain...).
20 For details please refer to specific chapter in the document, RFCs, manpages
21 come with KAME, or comments in the source code.
22
23 Conformance tests have been performed on past and latest KAME STABLE kit,
24 at TAHI project.  Results can be viewed at http://www.tahi.org/report/KAME/.
25 We also attended Univ. of New Hampshire IOL tests (http://www.iol.unh.edu/)
26 in the past, with our past snapshots.
27
28 RFC1639: FTP Operation Over Big Address Records (FOOBAR)
29     * RFC2428 is preferred over RFC1639.  ftp clients will first try RFC2428,
30       then RFC1639 if failed.
31 RFC1886: DNS Extensions to support IPv6
32 RFC1933: (see RFC2893)
33 RFC1981: Path MTU Discovery for IPv6
34 RFC2080: RIPng for IPv6
35     * KAME-supplied route6d, bgpd and hroute6d support this.
36 RFC2283: Multiprotocol Extensions for BGP-4
37     * so-called "BGP4+".
38     * KAME-supplied bgpd supports this.
39 RFC2292: Advanced Sockets API for IPv6
40     * For supported library functions/kernel APIs, see sys/netinet6/ADVAPI.
41 RFC2362: Protocol Independent Multicast-Sparse Mode (PIM-SM)
42     * RFC2362 defines the packet formats and the protcol of PIM-SM.
43 RFC2373: IPv6 Addressing Architecture
44     * KAME supports node required addresses, and conforms to the scope
45       requirement.
46 RFC2374: An IPv6 Aggregatable Global Unicast Address Format
47     * KAME supports 64-bit length of Interface ID.
48 RFC2375: IPv6 Multicast Address Assignments
49     * Userland applications use the well-known addresses assigned in the RFC.
50 RFC2428: FTP Extensions for IPv6 and NATs
51     * RFC2428 is preferred over RFC1639.  ftp clients will first try RFC2428,
52       then RFC1639 if failed.
53 RFC2460: IPv6 specification
54 RFC2461: Neighbor discovery for IPv6
55     * See 1.2 in this document for details.
56 RFC2462: IPv6 Stateless Address Autoconfiguration
57     * See 1.4 in this document for details.
58 RFC2463: ICMPv6 for IPv6 specification
59     * See 1.8 in this document for details.
60 RFC2464: Transmission of IPv6 Packets over Ethernet Networks
61 RFC2465: MIB for IPv6: Textual Conventions and General Group
62     * Necessary statistics are gathered by the kernel.  Actual IPv6 MIB
63       support is provided as patchkit for ucd-snmp.
64 RFC2466: MIB for IPv6: ICMPv6 group
65     * Necessary statistics are gathered by the kernel.  Actual IPv6 MIB
66       support is provided as patchkit for ucd-snmp.
67 RFC2467: Transmission of IPv6 Packets over FDDI Networks
68 RFC2472: IPv6 over PPP
69 RFC2492: IPv6 over ATM Networks
70     * only PVC is supported.
71 RFC2497: Transmission of IPv6 packet over ARCnet Networks
72 RFC2545: Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing
73 RFC2553: Basic Socket Interface Extensions for IPv6
74     * IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind
75       socket (3.8) are,
76         - supported and turned on by default on KAME/FreeBSD[34]x
77           and KAME/BSDI4,
78         - supported but turned off by default on KAME/NetBSD,
79         - not supported on KAME/FreeBSD228, KAME/OpenBSD and KAME/BSDI3.
80       see 1.12 in this document for details.
81 RFC2671: Extension Mechanisms for DNS (EDNS0)
82     * see USAGE for how to use it.
83     * not supported on kame/freebsd4 and kame/bsdi4.
84 RFC2673: Binary Labels in the Domain Name System
85     * KAME/bsdi4 supports A6, DNAME and binary label to some extent.
86     * KAME apps/bind8 repository has resolver library with partial A6, DNAME
87       and binary label support.
88 RFC2675: IPv6 Jumbograms
89     * See 1.7 in this document for details.
90 RFC2710: Multicast Listener Discovery for IPv6
91 RFC2711: IPv6 router alert option
92 RFC2732: Format for Literal IPv6 Addresses in URL's
93     * The spec is implemented in programs that handle URLs
94       (like freebsd ftpio(3) and fetch(1), or netbsd ftp(1))
95 RFC2766: Network Address Translation - Protocol Translation (NAT-PT)
96     * Section 4.2 is implemented by totd (see ports/totd, or pkgsrc/net/totd).
97 RFC2874: DNS Extensions to Support IPv6 Address Aggregation and Renumbering
98     * KAME/bsdi4 supports A6, DNAME and binary label to some extent.
99     * KAME apps/bind8 repository has resolver library with partial A6, DNAME
100       and binary label support.
101 RFC2893: Transition Mechanisms for IPv6 Hosts and Routers
102     * IPv4 compatible address is not supported.
103     * automatic tunneling (4.3) is not supported.
104     * "gif" interface implements IPv[46]-over-IPv[46] tunnel in a generic way,
105       and it covers "configured tunnel" described in the spec.
106       See 1.5 in this document for details.
107 RFC2894: Router renumbering for IPv6
108 RFC3041: Privacy Extensions for Stateless Address Autoconfiguration in IPv6
109 RFC3056: Connection of IPv6 Domains via IPv4 Clouds
110     * So-called "6to4".
111     * "stf" interface implements it.  Be sure to read
112       draft-itojun-ipv6-transition-abuse-01.txt
113       below before configuring it, there can be security issues.
114 draft-ietf-ipngwg-icmp-name-lookups-07: IPv6 Name Lookups Through ICMP
115 draft-ietf-dhc-dhcpv6-15.txt: DHCPv6
116 draft-ietf-dhc-dhcpv6exts-12.txt: Extensions for DHCPv6
117     * kame/dhcp6 has test implementation, which will not be compiled in
118       default compilation.
119     * 15/12 drafts are not explicit about padding and string termination.
120       at IETF48, the author confirmed that there's no padding/termination
121       (and extensions can appear unaligned).  our code follows the comment.
122 draft-itojun-ipv6-tcp-to-anycast-00.txt:
123         Disconnecting TCP connection toward IPv6 anycast address
124 draft-ietf-ipngwg-rfc2553bis-03.txt:
125         Basic Socket Interface Extensions for IPv6 (revised)
126 draft-ietf-ipngwg-rfc2292bis-02.txt:
127         Advanced Sockets API for IPv6 (revised)
128     * Some of the updates in the draft are not implemented yet.  See
129       TODO.2292bis for more details.
130 draft-ietf-mobileip-ipv6-13.txt: Mobility Support in IPv6
131     * See section 6.
132 draft-ietf-ngtrans-tcpudp-relay-04.txt:
133         An IPv6-to-IPv4 transport relay translator
134     * FAITH tcp relay translator (faithd) implements this.  See 3.1 for more
135       details.
136 draft-ietf-ipngwg-router-selection-01.txt:
137         Default Router Preferences and More-Specific Routes
138     * router-side only.
139 draft-ietf-ipngwg-scoping-arch-02.txt:
140         The architecture, text representation, and usage of IPv6
141         scoped addresses.
142     * some part of the documentation (especially about the routing
143       model) is not supported yet.
144 draft-ietf-pim-sm-v2-new-02.txt
145         A revised version of RFC2362, which includes the IPv6 specific
146         packet format and protocol descriptions.
147 draft-ietf-dnsext-mdns-00.txt: Multicast DNS
148     * kame/mdnsd has test implementation, which will not be built in
149       default compilation.  The draft will experience a major change in the
150       near future, so don't rely upon it.
151 draft-itojun-ipv6-transition-abuse-02.txt:
152         Possible abuse against IPv6 transition technologies (expired)
153     * KAME does not implement RFC1933/2893 automatic tunnel.
154     * "stf" interface implements some address filters.  Refer to stf(4)
155       for details.  Since there's no way to make 6to4 interface 100% secure,
156       we do not include "stf" interface into GENERIC.v6 compilation.
157     * kame/openbsd completely disables IPv4 mapped address support.
158     * kame/netbsd makes IPv4 mapped address support off by default.
159     * See section 1.12.6 and 1.14 for more details.
160 draft-itojun-ipv6-tclass-api-02.txt: Socket API for IPv6 traffic class field
161 draft-itojun-ipv6-flowlabel-api-01.txt: Socket API for IPv6 flow label field
162     * no consideration is made against the use of routing headers and such.
163
164 1.2 Neighbor Discovery
165
166 Neighbor Discovery is fairly stable.  Currently Address Resolution,
167 Duplicated Address Detection, and Neighbor Unreachability Detection
168 are supported.  In the near future we will be adding Unsolicited Neighbor
169 Advertisement transmission command as admin tool.
170
171 Duplicated Address Detection (DAD) will be performed when an IPv6 address
172 is assigned to a network interface, or the network interface is enabled
173 (ifconfig up).  It is documented in RFC2462 5.4.
174 If DAD fails, the address will be marked "duplicated" and message will be
175 generated to syslog (and usually to console).  The "duplicated" mark
176 can be checked with ifconfig.  It is administrators' responsibility to check
177 for and recover from DAD failures.  We may try to improve failure recovery
178 in future KAME code.
179 DAD procedure may not be effective on certain network interfaces/drivers.
180 If a network driver needs long initialization time (with wireless network
181 interfaces this situation is popular), and the driver mistakingly raises
182 IFF_RUNNING before the driver becomes ready, DAD code will try to transmit
183 DAD probes to not-really-ready network driver and the packet will not go out
184 from the interface.  In such cases, network drivers should be corrected.
185
186 Some of network drivers loop multicast packets back to themselves,
187 even if instructed not to do so (especially in promiscuous mode).
188 In such cases DAD may fail, because DAD engine sees inbound NS packet
189 (actually from the node itself) and considers it as a sign of duplicate.
190 In this case, drivers should be corrected to honor IFF_SIMPLEX behavior.
191 For example, you may need to check source MAC address on a inbound packet,
192 and reject it if it is from the node itself.
193 You may also want to look at #if condition marked "heuristics" in
194 sys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note that the code
195 fragment in "heuristics" section is not spec conformant).
196
197 Neighbor Discovery specification (RFC2461) does not talk about neighbor
198 cache handling in the following cases:
199 (1) when there was no neighbor cache entry, node received unsolicited
200     RS/NS/NA/redirect packet without link-layer address
201 (2) neighbor cache handling on medium without link-layer address
202     (we need a neighbor cache entry for IsRouter bit)
203 For (1), we implemented workaround based on discussions on IETF ipngwg mailing
204 list.  For more details, see the comments in the source code and email
205 thread started from (IPng 7155), dated Feb 6 1999.
206
207 IPv6 on-link determination rule (RFC2461) is quite different from assumptions
208 in BSD IPv4 network code.  To implement behavior in RFC2461 section 5.2
209 (when default router list is empty), the kernel needs to know the default
210 outgoing interface.  To configure the default outgoing interface, use
211 commands like "ndp -I de0" as root.  Note that the spec misuse the word
212 "host" and "node" in several places in the section.
213
214 To avoid possible DoS attacks and infinite loops, KAME stack will accept
215 only 10 options on ND packet.  Therefore, if you have 20 prefix options
216 attached to RA, only the first 10 prefixes will be recognized.
217 If this troubles you, please contact KAME team and/or modify
218 nd6_maxndopt in sys/netinet6/nd6.c.  If there are high demands we may
219 provide sysctl knob for the variable.
220
221 Proxy Neighbor Advertisement support is implemented in the kernel.
222 For instance, you can configure it by using the following command:
223         # ndp -s fe80::1234%ne0 0:1:2:3:4:5 proxy
224 where ne0 is the interface which attaches to the same link as the
225 proxy target.
226 There are certain limitations, though:
227 - It does not send unsolicited multicast NA on configuration.  This is MAY
228   behavior in RFC2461.
229 - It does not add random delay before transmission of solicited NA.  This is
230   SHOULD behavior in RFC2461.
231 - We cannot configure proxy NDP for off-link address.  The target address for
232   proxying must be link-local address, or must be in prefixes configured to
233   node which does proxy NDP.
234 - RFC2461 is unclear about if it is legal for a host to perform proxy ND.
235   We do not prohibit hosts from doing proxy ND, but there will be very limited
236   use in it.
237
238 Starting mid March 2000, we support Neighbor Unreachability Detection (NUD)
239 on p2p interfaces, including tunnel interfaces (gif).  NUD is turned on by
240 default.  Before March 2000 KAME stack did not perform NUD on p2p interfaces.
241 If the change raises any interoperability issues, you can turn off/on NUD
242 by per-interface basis.  Use "ndp -i interface -nud" to turn it off.
243 Consult ndp(8) for details.
244
245 RFC2461 specifies upper-layer reachability confirmation hint.  Whenever
246 upper-layer reachability confirmation hint comes, ND process can use it
247 to optimize neighbor discovery process - ND process can omit real ND exchange
248 and keep the neighbor cache state in REACHABLE.
249 We currently have two sources for hints: (1) setsockopt(IPV6_REACHCONF)
250 defined by 2292bis API, and (2) hints from tcp_input.
251 It is questionable if they are really trustworthy.  For example, a rogue
252 userland program can use IPV6_REACHCONF to confuse ND process.  Neighbor
253 cache is a system-wide information pool, and it is bad to allow single process
254 to affect others.  Also, tcp_input can be hosed by hijack attempts.  It is
255 wrong to allow hijack attempts to affect ND process.
256 Starting June 2000, ND code has a protection mechanism against incorrect
257 upper-layer reachability confirmation.  ND code counts subsequent upper-layer
258 hints.  If the number of hints reaches maximum, ND code will ignore further
259 upper-layer hints and run real ND process to confirm reachability to the peer.
260 sysctl net.inet6.icmp6.nd6_maxnudhint defines maximum # of subsequent
261 upper-layer hints to be accepted.
262 (from April 2000 to June 2000, we rejected setsockopt(IPV6_REACHCONF) from
263 non-root process - after local discussion, it looks that hints are not
264 that trustworthy even if they are from privileged processes)
265
266 If inbound ND packets carry invalid values, the KAME kernel will
267 drop these packet and increment statistics variable.  See
268 "netstat -sn", icmp6 section.  For detailed debugging session, you can
269 turn on syslog output from the kernel on errors, by turning on sysctl MIB
270 net.inet6.icmp6.nd6_debug.  nd6_debug can be turned on at bootstrap
271 time, by defining ND6_DEBUG kernel compilation option (so you can
272 debug behavior during bootstrap).  nd6_debug configuration should
273 only be used for test/debug purposes - for production environment,
274 nd6_debug must be set to 0.  If you leave it to 1, malicious parties
275 can inject broken packet and fill up /var/log partition.
276
277 1.3 Scope Zone Index
278
279 IPv6 uses scoped addresses.  It is therefore very important to
280 specify the scope zone index (link index for a link-local address, or
281 site index for a site-local address) with an IPv6 address.  Without a
282 zone index, a scoped IPv6 address is ambiguous to the kernel, and
283 the kernel would not be able to determine the outbound link for a
284 packet to the scoped address.  KAME code tries to address the issue in
285 several ways.
286
287 The entire architecture of scoped addresses is documented in
288 draft-ietf-ipngwg-scoping-arch-xx.txt.  One non-trivial point of the
289 architecture is that the link scope is (theoretically) larger than the
290 interface scope.  That is, two different interfaces can belong to a
291 same single link.  However, in a normal operation, we can assume that
292 there is 1-to-1 relationship between links and interfaces.  In
293 other words, we can usually put links and interfaces in the same scope
294 type.  The current KAME implementation assumes the 1-to-1
295 relationship.  In particular, we use interface names such as "ne1" as
296 unique link identifiers.  This would be much more human-readable and
297 intuitive than numeric identifiers, but please keep your mind on the
298 theoretical difference between links and interfaces.
299
300 Site-local addresses are very vaguely defined in the specs, and both
301 the specification and the KAME code need tons of improvements to
302 enable its actual use.  For example, it is still very unclear how we
303 define a site, or how we resolve host names in a site.  There is work
304 underway to define behavior of routers at site border, but, we have
305 almost no code for site boundary node support (both forwarding nor
306 routing) and we bet almost noone has.  We recommend, at this moment,
307 you to use global addresses for experiments - there are way too many
308 pitfalls if you use site-local addresses.
309
310 1.3.1 Kernel internal
311
312 In the kernel, the link index for a link-local scope address is
313 embedded into the 2nd 16bit-word (the 3rd and 4th bytes) in the IPv6
314 address.
315 For example, you may see something like:
316         fe80:1::200:f8ff:fe01:6317
317 in the routing table and the interface address structure (struct
318 in6_ifaddr).  The address above is a link-local unicast address which
319 belongs to a network link whose link identifier is 1 (note that it
320 eqauls to the interface index by the assumption of our
321 implementation).  The embedded index enables us to identify IPv6
322 link-local addresses over multiple links effectively and with only a
323 little code change.
324
325 1.3.2 Interaction with API
326
327 There are several candidates of API to deal with scoped addresses
328 without ambiguity.
329
330 The IPV6_PKTINFO ancillary data type or socket option defined in the
331 advanced API (RFC2292 or draft-ietf-ipngwg-rfc2292bis-xx) can specify
332 the outgoing interface of a packet.  Similarly, the IPV6_PKTINFO or
333 IPV6_RECVPKTINFO socket options tell kernel to pass the incoming
334 interface to user applications.
335
336 These options are enough to disambiguate scoped addresses of an
337 incoming packet, because we can uniquely identify the corresponding
338 zone of the scoped address(es) by the incoming interface.  However,
339 they are too strong for outgoing packets.  For example, consider a
340 multi-sited node and suppose that more than one interface of the node
341 belongs to a same site.  When we want to send a packet to the site,
342 we can only specify one of the interfaces for the outgoing packet with
343 these options; we cannot just say "send the packet to (one of the
344 interfaces of) the site."
345
346 Another kind of candidates is to use the sin6_scope_id member in the
347 sockaddr_in6 structure, defined in RFC2553 and
348 draft-ietf-ipngwg-rfc2553bis-xx.txt.  The KAME kernel interprets the
349 sin6_scope_id field properly in order to disambiguate scoped
350 addresses.  For example, if an application passes a sockaddr_in6
351 structure that has a non-zero sin6_scope_id value to the sendto(2)
352 system call, the kernel should send the packet to the appropriate zone
353 according to the sin6_scope_id field.  Similarly, when the source or
354 the destination address of an incoming packet is a scoped one, the
355 kernel should detect the correct zone identifier based on the address
356 and the receiving interface, fill the identifier in the sin6_scope_id
357 field of a sockaddr_in6 structure, and then pass the packet to an
358 application via the recvfrom(2) system call, etc.
359
360 However, the semantics of the sin6_scope_id is still vague and on the
361 way to standardization.  Additionally, not so many operating systems
362 support the behavior above at this moment.
363
364 In summary,
365 - If your target system is limited to KAME based ones (i.e. BSD
366   variants and KAME snaps), use the sin6_scope_id field assuming the
367   kernel behavior described above.
368 - Otherwise, (i.e. if your program should be portable on other systems
369   than BSDs)
370   + Use the advanced API to disambiguate scoped addresses of incoming
371     packets.
372   + To disambiguate scoped addresses of outgoing packets,
373     * if it is okay to just specify the outgoing interface, use the
374       advanced API.  This would be the case, for example, when you
375       should only consider link-local addresses and your system
376       assumes 1-to-1 relationship between links and interfaces.
377     * otherwise, sorry but you lose.  Please rush the IETF IPv6
378       community into standardizing the semantics of the sin6_scope_id
379       field.
380
381 Routing daemons and configuration programs, like route6d and ifconfig,
382 will need to manipulate the "embedded" zone index.  These programs use
383 routing sockets and ioctls (like SIOCGIFADDR_IN6) and the kernel API
384 will return IPv6 addresses with the 2nd 16bit-word filled in.  The
385 APIs are for manipulating kernel internal structure.  Programs that
386 use these APIs have to be prepared about differences in kernels
387 anyway.
388
389 getaddrinfo(3) and getnameinfo(3) support an extended numeric IPv6
390 syntax, as documented in draft-ietf-ipngwg-rfc2553bis-xx.txt.  You can
391 specify the outgoing link, by using the name of the outgoing interface
392 as the link, like "fe80::1%ne0" (again, note that we assume there is
393 1-to-1 relationship between links and interfaces.)  This way you will
394 be able to specify a link-local scoped address without much trouble.
395
396 Other APIs like inet_pton(3) and inet_ntop(3) are inherently
397 unfriendly with scoped addresses, since they are unable to annotate
398 addresses with zone identifier.
399
400 1.3.3 Interaction with users (command line)
401
402 Most of user applications now support the extended numeric IPv6
403 syntax.  In this case, you can specify outgoing link, by using the name
404 of the outgoing interface like "fe80::1%ne0" (sorry for the duplicated
405 notice, but please recall again that we assume 1-to-1 relationship
406 between links and interfaces).  This is even the case for some
407 management tools such as route(8) or ndp(8).  For example, to install
408 the IPv6 default route by hand, you can type like
409         # route add -inet6 default fe80::9876:5432:1234:abcd%ne0
410 (Although we suggest you to run dynamic routing instead of static
411 routes, in order to avoid configuration mistakes.)
412
413 Some applications have command line options for specifying an
414 appropriate zone of a scoped address (like "ping6 -I ne0 ff02::1" to
415 specify the outgoing interface).  However, you can't always expect such
416 options.  Thus, we recommend you to use the extended format described
417 above.
418
419 In any case, when you specify a scoped address to the command line,
420 NEVER write the embedded form (such as ff02:1::1 or fe80:2::fedc),
421 which should only be used inside the kernel (see Section 1.3.1), and 
422 is not supposed to work.
423
424 1.4 Plug and Play
425
426 The KAME kit implements most of the IPv6 stateless address
427 autoconfiguration in the kernel.
428 Neighbor Discovery functions are implemented in the kernel as a whole.
429 Router Advertisement (RA) input for hosts is implemented in the
430 kernel.  Router Solicitation (RS) output for endhosts, RS input
431 for routers, and RA output for routers are implemented in the
432 userland.
433
434 1.4.1 Assignment of link-local, and special addresses
435
436 IPv6 link-local address is generated from IEEE802 address (ethernet MAC
437 address).  Each of interface is assigned an IPv6 link-local address
438 automatically, when the interface becomes up (IFF_UP).  Also, direct route
439 for the link-local address is added to routing table.
440
441 Here is an output of netstat command:
442
443 Internet6:
444 Destination                   Gateway                   Flags      Netif Expire
445 fe80::%ed0/64                 link#1                    UC           ed0
446 fe80::%ep0/64                 link#2                    UC           ep0
447
448 Interfaces that has no IEEE802 address (pseudo interfaces like tunnel
449 interfaces, or ppp interfaces) will borrow IEEE802 address from other
450 interfaces, such as ethernet interfaces, whenever possible.
451 If there is no IEEE802 hardware attached, last-resort pseudorandom value,
452 which is from MD5(hostname), will be used as source of link-local address.
453 If it is not suitable for your usage, you will need to configure the
454 link-local address manually.
455
456 If an interface is not capable of handling IPv6 (such as lack of multicast
457 support), link-local address will not be assigned to that interface.
458 See section 2 for details.
459
460 Each interface joins the solicited multicast address and the
461 link-local all-nodes multicast addresses (e.g.  fe80::1:ff01:6317
462 and ff02::1, respectively, on the link the interface is attached).
463 In addition to a link-local address, the loopback address (::1) will be
464 assigned to the loopback interface.  Also, ::1/128 and ff01::/32 are
465 automatically added to routing table, and loopback interface joins
466 node-local multicast group ff01::1.
467
468 1.4.2 Stateless address autoconfiguration on hosts
469
470 In IPv6 specification, nodes are separated into two categories:
471 routers and hosts.  Routers forward packets addressed to others, hosts does
472 not forward the packets.  net.inet6.ip6.forwarding defines whether this
473 node is a router or a host (router if it is 1, host if it is 0).
474
475 It is NOT recommended to change net.inet6.ip6.forwarding while the node
476 is in operation.   IPv6 specification defines behavior for "host" and "router"
477 quite differently, and switching from one to another can cause serious
478 troubles.  It is recommended to configure the variable at bootstrap time only.
479
480 The first step in stateless address configuration is Duplicated Address
481 Detection (DAD).  See 1.2 for more detail on DAD.
482
483 When a host hears Router Advertisement from the router, a host may
484 autoconfigure itself by stateless address autoconfiguration.
485 This behavior can be controlled by net.inet6.ip6.accept_rtadv
486 (host autoconfigures itself if it is set to 1).
487 By autoconfiguration, network address prefix for the receiving interface
488 (usually global address prefix) is added. The default route is also
489 configured.
490
491 Routers periodically generate Router Advertisement packets.  To
492 request an adjacent router to generate RA packet, a host can transmit
493 Router Solicitation.  To generate an RS packet at any time, use the
494 "rtsol" command. The "rtsold" daemon is also available. "rtsold"
495 generates Router Solicitation whenever necessary, and it works great
496 for nomadic usage (notebooks/laptops).  If one wishes to ignore Router
497 Advertisements, use sysctl to set net.inet6.ip6.accept_rtadv to 0.
498
499 To generate Router Advertisement from a router, use the "rtadvd" daemon.
500
501 Note that the IPv6 specification assumes the following items and that
502 nonconforming cases are left unspecified:
503 - Only hosts will listen to router advertisements
504 - Hosts have single network interface (except loopback)
505 This is therefore unwise to enable net.inet6.ip6.accept_rtadv on routers,
506 or multi-interface host.  A misconfigured node can behave strange
507 (KAME code allows nonconforming configuration, for those who would like
508 to do some experiments).
509
510 To summarize the sysctl knob:
511         accept_rtadv    forwarding      role of the node
512         ---             ---             ---
513         0               0               host (to be manually configured)
514         0               1               router
515         1               0               autoconfigured host
516                                         (spec assumes that host has single
517                                         interface only, autoconfigred host with
518                                         multiple interface is out-of-scope)
519         1               1               invalid, or experimental
520                                         (out-of-scope of spec)
521
522 See 1.2 in the document for relationship between DAD and autoconfiguration.
523
524 1.4.3 DHCPv6
525
526 We supply a tiny DHCPv6 server/client in kame/dhcp6. However, the
527 implementation is premature (for example, this does NOT implement
528 address lease/release), and it is not in default compilation tree on
529 some platforms. If you want to do some experiment, compile it on your
530 own.
531
532 DHCPv6 and autoconfiguration also needs more work.  "Managed" and "Other"
533 bits in RA have no special effect to stateful autoconfiguration procedure
534 in DHCPv6 client program ("Managed" bit actually prevents stateless
535 autoconfiguration, but no special action will be taken for DHCPv6 client).
536
537 1.5 Generic tunnel interface
538
539 GIF (Generic InterFace) is a pseudo interface for configured tunnel.
540 Details are described in gif(4) manpage.
541 Currently
542         v6 in v6
543         v6 in v4
544         v4 in v6
545         v4 in v4
546 are available.  Use "gifconfig" to assign physical (outer) source
547 and destination address to gif interfaces.
548 Configuration that uses same address family for inner and outer IP
549 header (v4 in v4, or v6 in v6) is dangerous.  It is very easy to
550 configure interfaces and routing tables to perform infinite level
551 of tunneling.  Please be warned.
552
553 gif can be configured to be ECN-friendly.  See 4.5 for ECN-friendliness
554 of tunnels, and gif(4) manpage for how to configure.
555
556 If you would like to configure an IPv4-in-IPv6 tunnel with gif interface,
557 read gif(4) carefully.  You may need to remove IPv6 link-local address
558 automatically assigned to the gif interface.
559
560 1.6 Source Address Selection
561
562 KAME's source address selection takes care of the following
563 conditions:
564 - address scope
565 - outgoing interface
566 - whether an address is deprecated
567 - whether an address is temporary (in terms of RFC 3041)
568 - prefix matching against the destination
569
570 Roughly speaking, the selection policy is as follows:
571 - always use an address that belongs to the same scope zone as the
572   destination.
573 - addresses that have equal or larger scope than the scope of the
574   destination are preferred.
575 - a deprecated address is not used in new communications if an
576   alternate (non-deprecated) address is available and has sufficient
577   scope.
578 - a temporary address (in terms of RFC 3041 privacy extension) are
579   preferred to a public address.
580 - if none of above conditions tie-breaks, addresses assigned on the
581   outgoing interface are preferred.
582 - if none of above conditions tie-breaks, one which is longest prefix
583   matching against the destination is preferred as the last resort.
584
585 For instance, ::1 is selected for ff01::1,
586 fe80::200:f8ff:fe01:6317%ne0 for fe80::2a0:24ff:feab:839b%ne0.
587 To see how longest-matching works, suppose that
588 3ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317
589 are given on the outgoing interface. Then the former is chosen as the
590 source for the destination 3ffe:501:800::1. Note that even if all
591 available addresses have smaller scope than the scope of the
592 destination, we choose one anyway. For example, if we have link-local
593 and site-local addresses only, we choose a site-local addresses for a
594 global destination. If the packet is going to break a site boundary,
595 the boundary router will return an ICMPv6 destination unreachable
596 error with code 2 - beyond scope of source address.
597
598 The precise desripction of the algorithm is quite complicated. To
599 describe the algorithm, we introduce the following notation:
600
601 For a given destination D,
602   samescope(D): The set of addresses that have the same scope as D.
603   largerscope(D): The set of addresses that have a larger scope than D.
604   smallerscope(D): The set of addresses that have a smaller scope than D.
605
606 For a given set of addresses A,
607   DEP(A): the set of deprecated addresses in A.
608   nonDEP(A): A - DEP(A).
609
610 For a given set of addresses A,
611   tmp(A): the set of preferred temporary-autoconfigured or
612           manually-configure addresses in A.
613
614 Also, the algorithm assumes that the outgoing interface for the
615 destination D is determined. We call the interface "I".
616
617 The algorithm is as follows. Selection proceeds step by step as
618 described; For example, if an address is selected by item 1, item 2 and
619 later are not considered at all.
620
621   0. If there is no address in the same scope zone as D, just give up;
622      the packet will not be sent.
623   1. If we do not prefer temporary addresses, go to 3.
624      Otherwise, and if tmp(samescope(D)) is not empty, 
625      then choose an address that is on the interface I.  If every
626      address is on I, or every address is on a different interface
627      from I, choose an arbitrary one provided that an address longest
628      matching against D is always preferred.
629   2. If tmp(largerscope(D)) is not empty,
630      then choose an address that has the smallest scope. If more than one
631      address has the smallest scope, choose an arbitrary one provided
632      that addresses on I are always preferred.
633   3. If nonDEP(samescope(D)) is not empty,
634      then apply the same logic as of 1.
635   4. If nonDEP(largerscope(D)) is not empty,
636      then apply the same logic as of 2.
637   5. If we do not prefer temporary addresses, go to 7.
638      Otherwise, and if tmp(DEP(samescope(D))) is not empty,
639      then choose an address that is on the interface I.  If every
640      address is on I, or every address is on a different interface
641      from I, choose an arbitrary one provided that an address longest
642      matching against D is always preferred.
643   6. If tmp(DEP(largerscope(D))) is not empty,
644      then choose an address that has the smallest scope. If more than
645      one address has the smallest scope, choose an arbitrary one provided
646      that an address on I is always preferred.
647   7. If DEP(samescope(D)) is not empty,
648      then apply the same logic as of 5.
649   8. If DEP(largerscope(D)) is not empty,
650      then apply the same logic as of 6.
651   9. If we do not prefer temporary addresses, go to 11.
652      Otherwise, and if tmp(nonDEP(smallerscope(D))) is not empty,
653      then choose an address that has the largest scope. If more than
654      one address has the largest scope, choose an arbitrary one provided
655      that an address on I is always preferred.
656  10. If tmp(DEP(smallerscope(D))) is not empty,
657      then choose an address that has the largest scope. If more than
658      one address has the largest scope, choose an arbitrary one provided
659      that an address on I is always preferred.
660  11. If nonDEP(smallerscope(D)) is not empty,
661      then apply the same logic as of 9.
662  12. If DEP(smallerscope(D)) is not empty,
663      then apply the same logic as of 10.
664
665 There exists a document about source address selection
666 (draft-ietf-ipngwg-default-addr-select-xx.txt). KAME's algorithm
667 described above takes a similar approach to the document, but there
668 are some differences. See the document for more details.
669
670 There are some cases where we do not use the above rule.  One
671 example is connected TCP session, and we use the address kept in TCP
672 protocol control block (tcb) as the source.
673 Another example is source address for Neighbor Advertisement.
674 Under the spec (RFC2461 7.2.2) NA's source should be the target
675 address of the corresponding NS's target.  In this case we follow
676 the spec rather than the above longest-match rule.
677
678 If you would like to prohibit the use of deprecated address for some
679 reason, configure net.inet6.ip6.use_deprecated to 0.  The issue
680 related to deprecated address is described in RFC2462 5.5.4 (NOTE:
681 there is some debate underway in IETF ipngwg on how to use
682 "deprecated" address).
683
684 1.7 Jumbo Payload
685
686 KAME supports the Jumbo Payload hop-by-hop option used to send IPv6
687 packets with payloads longer than 65,535 octets.  But since currently
688 KAME does not support any physical interface whose MTU is more than
689 65,535, such payloads can be seen only on the loopback interface(i.e.
690 lo0).
691
692 If you want to try jumbo payloads, you first have to reconfigure the
693 kernel so that the MTU of the loopback interface is more than 65,535
694 bytes; add the following to the kernel configuration file:
695         options         "LARGE_LOMTU"           #To test jumbo payload
696 and recompile the new kernel.
697
698 Then you can test jumbo payloads by the ping6 command with -b and -s
699 options.  The -b option must be specified to enlarge the size of the
700 socket buffer and the -s option specifies the length of the packet,
701 which should be more than 65,535.  For example, type as follows; 
702         % ping6 -b 70000 -s 68000 ::1
703
704 The IPv6 specification requires that the Jumbo Payload option must not
705 be used in a packet that carries a fragment header.  If this condition
706 is broken, an ICMPv6 Parameter Problem message must be sent to the
707 sender.  KAME kernel follows the specification, but you cannot usually
708 see an ICMPv6 error caused by this requirement.
709
710 If KAME kernel receives an IPv6 packet, it checks the frame length of
711 the packet and compares it to the length specified in the payload
712 length field of the IPv6 header or in the value of the Jumbo Payload
713 option, if any.  If the former is shorter than the latter, KAME kernel
714 discards the packet and increments the statistics. You can see the
715 statistics as output of netstat command with `-s -p ip6' option:
716         % netstat -s -p ip6
717         ip6:
718                 (snip)
719                 1 with data size < data length
720
721 So, KAME kernel does not send an ICMPv6 error unless the erroneous
722 packet is an actual Jumbo Payload, that is, its packet size is more
723 than 65,535 bytes.  As described above, KAME kernel currently does not
724 support physical interface with such a huge MTU, so it rarely returns an
725 ICMPv6 error.
726
727 TCP/UDP over jumbogram is not supported at this moment.  This is because
728 we have no medium (other than loopback) to test this.  Contact us if you
729 need this.
730
731 IPsec does not work on jumbograms.  This is due to some specification twists
732 in supporting AH with jumbograms (AH header size influences payload length,
733 and this makes it real hard to authenticate inbound packet with jumbo payload
734 option as well as AH).
735
736 There are fundamental issues in *BSD support for jumbograms.  We would like to
737 address those, but we need more time to finalize the task.  To name a few:
738 - mbuf pkthdr.len field is typed as "int" in 4.4BSD, so it cannot hold
739   jumbogram with len > 2G on 32bit architecture CPUs.  If we would like to
740   support jumbogram properly, the field must be expanded to hold 4G +
741   IPv6 header + link-layer header.  Therefore, it must be expanded to at least
742   int64_t (u_int32_t is NOT enough).
743 - We mistakingly use "int" to hold packet length in many places.  We need
744   to convert them into larger numeric type.  It needs a great care, as we may
745   experience overflow during packet length computation.
746 - We mistakingly check for ip6_plen field of IPv6 header for packet payload
747   length in various places.  We should be checking mbuf pkthdr.len instead.
748   ip6_input() will perform sanity check on jumbo payload option on input,
749   and we can safely use mbuf pkthdr.len afterwards.
750 - TCP code needs careful updates in bunch of places, of course.
751
752 1.8 Loop prevention in header processing
753
754 IPv6 specification allows arbitrary number of extension headers to
755 be placed onto packets.  If we implement IPv6 packet processing
756 code in the way BSD IPv4 code is implemented, kernel stack may
757 overflow due to long function call chain.  KAME sys/netinet6 code
758 is carefully designed to avoid kernel stack overflow.  Because of
759 this, KAME sys/netinet6 code defines its own protocol switch
760 structure, as "struct ip6protosw" (see netinet6/ip6protosw.h).
761
762 In addition to this, we restrict the number of extension headers
763 (including the IPv6 header) in each incoming packet, in order to
764 prevent a DoS attack that tries to send packets with a massive number
765 of extension headers.  The upper limit can be configured by the sysctl
766 value net.inet6.ip6.hdrnestlimit. In particular, if the value is 0,
767 the node will allow an arbitrary number of headers. As of writing this
768 document, the default value is 50.
769
770 IPv4 part (sys/netinet) remains untouched for compatibility.
771 Because of this, if you receive IPsec-over-IPv4 packet with massive
772 number of IPsec headers, kernel stack may blow up.  IPsec-over-IPv6 is okay.
773
774 1.9 ICMPv6
775
776 After RFC2463 was published, IETF ipngwg has decided to disallow ICMPv6 error
777 packet against ICMPv6 redirect, to prevent ICMPv6 storm on a network medium.
778 KAME already implements this into the kernel.
779
780 RFC2463 requires rate limitation for ICMPv6 error packets generated by a
781 node, to avoid possible DoS attacks.  KAME kernel implements two rate-
782 limitation mechanisms, tunable via sysctl:
783 - Minimum time interval between ICMPv6 error packets
784         KAME kernel will generate no more than one ICMPv6 error packet,
785         during configured time interval.  net.inet6.icmp6.errratelimit
786         controls the interval (default: disabled).
787 - Maximum ICMPv6 error packet-per-second
788         KAME kernel will generate no more than the configured number of
789         packets in one second.  net.inet6.icmp6.errppslimit controls the
790         maximum packet-per-second value (default: 200pps)
791 Basically, we need to pick values that are suitable against the bandwidth
792 of link layer devices directly attached to the node.  In some cases the
793 default values may not fit well.  We are still unsure if the default value
794 is sane or not.  Comments are welcome.
795
796 1.10 Applications
797
798 For userland programming, we support IPv6 socket API as specified in
799 RFC2553, RFC2292 and upcoming internet drafts.
800
801 TCP/UDP over IPv6 is available and quite stable.  You can enjoy "telnet",
802 "ftp", "rlogin", "rsh", "ssh", etc.  These applications are protocol
803 independent.  That is, they automatically chooses IPv4 or IPv6
804 according to DNS.
805
806 1.11 Kernel Internals
807
808  (*) TCP/UDP part is handled differently between operating system platforms.
809      See 1.12 for details.
810
811 The current KAME has escaped from the IPv4 netinet logic.  While
812 ip_forward() calls ip_output(), ip6_forward() directly calls
813 if_output() since routers must not divide IPv6 packets into fragments.
814
815 ICMPv6 should contain the original packet as long as possible up to
816 1280.  UDP6/IP6 port unreach, for instance, should contain all
817 extension headers and the *unchanged* UDP6 and IP6 headers.
818 So, all IP6 functions except TCP6 never convert network byte
819 order into host byte order, to save the original packet.
820
821 tcp6_input(), udp6_input() and icmp6_input() can't assume that IP6
822 header is preceding the transport headers due to extension
823 headers.  So, in6_cksum() was implemented to handle packets whose IP6
824 header and transport header is not continuous.  TCP/IP6 nor UDP/IP6
825 header structure don't exist for checksum calculation.
826
827 To process IP6 header, extension headers and transport headers easily,
828 KAME requires network drivers to store packets in one internal mbuf or
829 one or more external mbufs.  A typical old driver prepares two
830 internal mbufs for 100 - 208 bytes data, however, KAME's reference
831 implementation stores it in one external mbuf.
832
833 "netstat -s -p ip6" tells you whether or not your driver conforms
834 KAME's requirement.  In the following example, "cce0" violates the
835 requirement. (For more information, refer to Section 2.)
836
837         Mbuf statistics:
838                 317 one mbuf
839                 two or more mbuf::
840                         lo0 = 8
841                         cce0 = 10
842                 3282 one ext mbuf
843                 0 two or more ext mbuf
844
845 Each input function calls IP6_EXTHDR_CHECK in the beginning to check
846 if the region between IP6 and its header is
847 continuous.  IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has
848 M_LOOP flag, that is, the packet comes from the loopback
849 interface.  m_pullup() is never called for packets coming from physical
850 network interfaces.
851
852 TCP6 reassembly makes use of IP6 header to store reassemble
853 information.  IP6 is not supposed to be just before TCP6, so
854 ip6tcpreass structure has a pointer to TCP6 header.  Of course, it has
855 also a pointer back to mbuf to avoid m_pullup().
856
857 Like TCP6, both IP and IP6 reassemble functions never call m_pullup().
858
859 xxx_ctlinput() calls in_mrejoin() on PRC_IFNEWADDR.  We think this is
860 one of 4.4BSD implementation flaws.  Since 4.4BSD keeps ia_multiaddrs
861 in in_ifaddr{}, it can't use multicast feature if the interface has no
862 unicast address.  So, if an application joins to an interface and then
863 all unicast addresses are removed from the interface, the application
864 can't send/receive any multicast packets.  Moreover, if a new unicast
865 address is assigned to the interface, in_mrejoin() must be called.
866 KAME's interfaces, however, have ALWAYS one link-local unicast
867 address.  These extensions have thus not been implemented in KAME.
868
869 1.12 IPv4 mapped address and IPv6 wildcard socket
870
871 RFC2553 describes IPv4 mapped address (3.7) and special behavior
872 of IPv6 wildcard bind socket (3.8).  The spec allows you to:
873 - Accept IPv4 connections by AF_INET6 wildcard bind socket.
874 - Transmit IPv4 packet over AF_INET6 socket by using special form of
875   the address like ::ffff:10.1.1.1.
876 but the spec itself is very complicated and does not specify how the
877 socket layer should behave.
878 Here we call the former one "listening side" and the latter one "initiating
879 side", for reference purposes.
880
881 Almost all KAME implementations treat tcp/udp port number space separately
882 between IPv4 and IPv6.  You can perform wildcard bind on both of the address
883 families, on the same port.
884
885 There are some OS-platform differences in KAME code, as we use tcp/udp
886 code from different origin.  The following table summarizes the behavior.
887
888                 listening side          initiating side
889                 (AF_INET6 wildcard      (connection to ::ffff:10.1.1.1)
890                 socket gets IPv4 conn.)
891                 ---                     ---
892 KAME/BSDI3      not supported           not supported
893 KAME/FreeBSD228 not supported           not supported
894 KAME/FreeBSD3x  configurable            supported
895                 default: enabled
896 KAME/FreeBSD4x  configurable            supported
897                 default: enabled
898 KAME/NetBSD     configurable            supported
899                 default: disabled 
900 KAME/BSDI4      enabled                 supported
901 KAME/OpenBSD    not supported           not supported
902
903 The following sections will give you more details, and how you can
904 configure the behavior.
905
906 Comments on listening side:
907
908 It looks that RFC2553 talks too little on wildcard bind issue,
909 specifically on (1) port space issue, (2) failure mode, (3) relationship
910 between AF_INET/INET6 wildcard bind like ordering constraint, and (4) behavior
911 when conflicting socket is opened/closed.  There can be several separate
912 interpretation for this RFC which conform to it but behaves differently.
913 So, to implement portable application you should assume nothing
914 about the behavior in the kernel.  Using getaddrinfo() is the safest way.
915 Port number space and wildcard bind issues were discussed in detail
916 on ipv6imp mailing list, in mid March 1999 and it looks that there's
917 no concrete consensus (means, up to implementers).  You may want to
918 check the mailing list archives.
919 We supply a tool called "bindtest" that explores the behavior of
920 kernel bind(2).  The tool will not be compiled by default.
921
922 If a server application would like to accept IPv4 and IPv6 connections,
923 it should use AF_INET and AF_INET6 socket (you'll need two sockets).
924 Use getaddrinfo() with AI_PASSIVE into ai_flags, and socket(2) and bind(2)
925 to all the addresses returned.
926 By opening multiple sockets, you can accept connections onto the socket with
927 proper address family.  IPv4 connections will be accepted by AF_INET socket,
928 and IPv6 connections will be accepted by AF_INET6 socket (NOTE: KAME/BSDI4
929 kernel sometimes violate this - we will fix it).
930
931 If you try to support IPv6 traffic only and would like to reject IPv4
932 traffic, always check the peer address when a connection is made toward
933 AF_INET6 listening socket.  If the address is IPv4 mapped address, you may
934 want to reject the connection.  You can check the condition by using
935 IN6_IS_ADDR_V4MAPPED() macro.  This is one of the reasons the author of
936 the section (itojun) dislikes special behavior of AF_INET6 wildcard bind.
937
938 Comments on initiating side:
939
940 Advise to application implementers: to implement a portable IPv6 application
941 (which works on multiple IPv6 kernels), we believe that the following
942 is the key to the success:
943 - NEVER hardcode AF_INET nor AF_INET6.
944 - Use getaddrinfo() and getnameinfo() throughout the system.
945   Never use gethostby*(), getaddrby*(), inet_*() or getipnodeby*().
946 - If you would like to connect to destination, use getaddrinfo() and try
947   all the destination returned, like telnet does.
948 - Some of the IPv6 stack is shipped with buggy getaddrinfo().  Ship a minimal
949   working version with your application and use that as last resort.
950
951 If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing
952 connection, you will need tweaked implementation in DNS support libraries,
953 as documented in RFC2553 6.1.  KAME libinet6 includes the tweak in
954 getipnodebyname().  Note that getipnodebyname() itself is not recommended as
955 it does not handle scoped IPv6 addresses at all.  For IPv6 name resolution
956 getaddrinfo() is the preferred API.  getaddrinfo() does not implement the
957 tweak.
958
959 When writing applications that make outgoing connections, story goes much
960 simpler if you treat AF_INET and AF_INET6 as totally separate address family.
961 {set,get}sockopt issue goes simpler, DNS issue will be made simpler.  We do
962 not recommend you to rely upon IPv4 mapped address.
963
964 1.12.1 KAME/BSDI3 and KAME/FreeBSD228
965
966 The platforms do not support IPv4 mapped address at all (both listening side
967 and initiating side).  AF_INET6 and AF_INET sockets are totally separated.
968
969 Port number space is totally separate between AF_INET and AF_INET6 sockets. 
970
971 It should be noted that KAME/BSDI3 and KAME/FreeBSD228 are not conformant
972 to RFC2553 section 3.7 and 3.8.  It is due to code sharing reasons.
973
974 1.12.2 KAME/FreeBSD[34]x
975
976 KAME/FreeBSD3x and KAME/FreeBSD4x use shared tcp4/6 code (from
977 sys/netinet/tcp*) and shared udp4/6 code (from sys/netinet/udp*).
978 They use unified inpcb/in6pcb structure.
979
980 1.12.2.1 KAME/FreeBSD[34]x, listening side
981
982 The platform can be configured to support IPv4 mapped address/special
983 AF_INET6 wildcard bind (enabled by default).  There is no kernel compilation
984 option to disable it.  You can enable/disable the behavior with sysctl
985 (per-node), or setsockopt (per-socket).
986
987 Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following 
988 conditions are satisfied:
989 - there's no AF_INET socket that matches the IPv4 connection
990 - the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
991   getsockopt(IPV6_V6ONLY) returns 0.
992
993 (XXX need checking)
994
995 1.12.2.2 KAME/FreeBSD[34]x, initiating side
996
997 KAME/FreeBSD3x supports outgoing connection to IPv4 mapped address
998 (::ffff:10.1.1.1), if the node is configured to accept IPv4 connections
999 by AF_INET6 socket.
1000
1001 (XXX need checking)
1002
1003 1.12.3 KAME/NetBSD
1004
1005 KAME/NetBSD uses shared tcp4/6 code (from sys/netinet/tcp*) and shared
1006 udp4/6 code (from sys/netinet/udp*).  The implementation is made differently
1007 from KAME/FreeBSD[34]x.  KAME/NetBSD uses separate inpcb/in6pcb structures,
1008 while KAME/FreeBSD[34]x uses merged inpcb structure.
1009
1010 It should be noted that the default configuration of KAME/NetBSD is not
1011 conformant to RFC2553 section 3.8.  It is intentionally turned off by default
1012 for security reasons.
1013
1014 1.12.3.1 KAME/NetBSD, listening side
1015
1016 The platform can be configured to support IPv4 mapped address/special AF_INET6
1017 wildcard bind (disabled by default).  Kernel behavior can be summarized as
1018 follows:
1019 - default: special support code will be compiled in, but is disabled by
1020   default.  It can be controlled by sysctl (net.inet6.ip6.v6only),
1021   or setsockopt(IPV6_V6ONLY).
1022 - add "INET6_V6ONLY": No special support code for AF_INET6 wildcard socket
1023   will be compiled in.  AF_INET6 sockets and AF_INET sockets are totally
1024   separate.  The behavior is similar to what described in 1.12.1.
1025
1026 sysctl setting will affect per-socket configuration at in6pcb creation time
1027 only.  In other words, per-socket configuration will be copied from sysctl
1028 configuration at in6pcb creation time.  To change per-socket behavior, you
1029 must perform setsockopt or reopen the socket.  Change in sysctl configuration
1030 will not change the behavior or sockets that are already opened.
1031
1032 Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following 
1033 conditions are satisfied:
1034 - there's no AF_INET socket that matches the IPv4 connection
1035 - the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
1036   getsockopt(IPV6_V6ONLY) returns 0.
1037
1038 You cannot bind(2) with IPv4 mapped address.  This is a workaround for port
1039 number duplicate and other twists.
1040
1041 1.12.3.2 KAME/NetBSD, initiating side
1042
1043 When you initiate a connection, you can always connect to IPv4 destination
1044 over AF_INET6 socket, usin IPv4 mapped address destination (::ffff:10.1.1.1).
1045 This is enabled independently from the configuration for listening side, and
1046 always enabled.
1047
1048 1.12.4 KAME/BSDI4
1049
1050 KAME/BSDI4 uses NRL-based TCP/UDP stack and inpcb source code,
1051 which was derived from NRL IPv6/IPsec stack.  We guess it supports IPv4 mapped
1052 address and speical AF_INET6 wildcard bind.  The implementation is, again,
1053 different from other KAME/*BSDs.
1054
1055 1.12.4.1 KAME/BSDI4, listening side
1056
1057 NRL inpcb layer supports special behavior of AF_INET6 wildcard socket.
1058 There is no way to disable the behavior.
1059
1060 Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following 
1061 condition is satisfied:
1062 - there's no AF_INET socket that matches the IPv4 connection
1063
1064 1.12.4.2 KAME/BSDI4, initiating side
1065
1066 KAME/BSDi4 supports connection initiation to IPv4 mapped address
1067 (like ::ffff:10.1.1.1).
1068
1069 1.12.5 KAME/OpenBSD
1070
1071 KAME/OpenBSD uses NRL-based TCP/UDP stack and inpcb source code,
1072 which was derived from NRL IPv6/IPsec stack.
1073
1074 It should be noted that KAME/OpenBSD is not conformant to RFC2553 section 3.7
1075 and 3.8.  It is intentionally omitted for security reasons.
1076
1077 1.12.5.1 KAME/OpenBSD, listening side
1078
1079 KAME/OpenBSD disables special behavior on AF_INET6 wildcard bind for
1080 security reasons (if IPv4 traffic toward AF_INET6 wildcard bind is allowed,
1081 access control will become much harder).  KAME/BSDI4 uses NRL-based TCP/UDP
1082 stack as well, however, the behavior is different due to OpenBSD's security
1083 policy.
1084
1085 As a result the behavior of KAME/OpenBSD is similar to KAME/BSDI3 and
1086 KAME/FreeBSD228 (see 1.12.1 for more detail).
1087
1088 1.12.5.2 KAME/OpenBSD, initiating side
1089
1090 KAME/OpenBSD does not support connection initiation to IPv4 mapped address
1091 (like ::ffff:10.1.1.1).
1092
1093 1.12.6 More issues
1094
1095 IPv4 mapped address support adds a big requirement to EVERY userland codebase.
1096 Every userland code should check if an AF_INET6 sockaddr contains IPv4
1097 mapped address or not.  This adds many twists:
1098
1099 - Access controls code becomes harder to write.
1100   For example, if you would like to reject packets from 10.0.0.0/8,
1101   you need to reject packets to AF_INET socket from 10.0.0.0/8,
1102   and to AF_INET6 socket from ::ffff:10.0.0.0/104.
1103 - If a protocol on top of IPv4 is defined differently with IPv6, we need to be
1104   really careful when we determine which protocol to use.
1105   For example, with FTP protocol, we can not simply use sa_family to determine
1106   FTP command sets.  The following example is incorrect:
1107         if (sa_family == AF_INET)
1108                 use EPSV/EPRT or PASV/PORT;     /*IPv4*/
1109         else if (sa_family == AF_INET6)
1110                 use EPSV/EPRT or LPSV/LPRT;     /*IPv6*/
1111         else
1112                 error;
1113   The correct code, with consideration to IPv4 mapped address, would be:
1114         if (sa_family == AF_INET)
1115                 use EPSV/EPRT or PASV/PORT;     /*IPv4*/
1116         else if (sa_family == AF_INET6 && IPv4 mapped address)
1117                 use EPSV/EPRT or PASV/PORT;     /*IPv4 command set on AF_INET6*/
1118         else if (sa_family == AF_INET6 && !IPv4 mapped address)
1119                 use EPSV/EPRT or LPSV/LPRT;     /*IPv6*/
1120         else
1121                 error;
1122   It is too much to ask for every body to be careful like this.
1123   The problem is, we are not sure if the above code fragment is perfect for
1124   all situations.
1125 - By enabling kernel support for IPv4 mapped address (outgoing direction),
1126   servers on the kernel can be hosed by IPv6 native packet that has IPv4
1127   mapped address in IPv6 header source, and can generate unwanted IPv4 packets.
1128   draft-itojun-ipv6-transition-abuse-01.txt talks more about this scenario.
1129
1130 Due to the above twists, some of KAME userland programs has restrictions on
1131 the use of IPv4 mapped addresses:
1132 - rshd/rlogind do not accept connections from IPv4 mapped address.
1133   This is to avoid malicious use of IPv4 mapped address in IPv6 native
1134   packet, to bypass source-address based authentication.
1135 - ftp/ftpd assume that you are on dual stack network.  IPv4 mapped address
1136   will be decoded in userland, and will be passed to AF_INET sockets
1137   (in other words, ftp/ftpd do not support SIIT environment).
1138
1139 1.12.7 Interaction with SIIT translator
1140
1141 SIIT translator is specified in RFC2765.  KAME node cannot become a SIIT
1142 translator box, nor SIIT end node (a node in SIIT cloud).
1143
1144 To become a SIIT translator box, we need to put additional code for that.
1145 We do not have the code in our tree at this moment.
1146
1147 There are multiple reasons that we are unable to become SIIT end node.
1148 (1) SIIT translators require end nodes in the SIIT cloud to be IPv6-only.
1149 Since we are unable to compile INET-less kernel, we are unable to become
1150 SIIT end node.  (2) As presented in 1.12.6, some of our userland code assumes
1151 dual stack network.  (3) KAME stack filters out IPv6 packets with IPv4
1152 mapped address in the header, to secure non-SIIT case (which is much more
1153 common).  Effectively KAME node will reject any packets via SIIT translator
1154 box.  See section 1.14 for more detail about the last item.
1155
1156 There are documentation issues too - SIIT document requires very strange
1157 things.  For example, SIIT document asks IPv6-only (meaning no IPv4 code)
1158 node to be able to construct IPv4 IPsec headers.  If a node knows how to
1159 construct IPv4 IPsec headers, that is not an IPv6-only node, it is a dual-stack
1160 node.  The requirements imposed in SIIT document contradict with the other
1161 part of the document itself.
1162
1163 1.13 sockaddr_storage
1164
1165 When RFC2553 was about to be finalized, there was discussion on how struct
1166 sockaddr_storage members are named.  One proposal is to prepend "__" to the
1167 members (like "__ss_len") as they should not be touched.  The other proposal
1168 was that don't prepend it (like "ss_len") as we need to touch those members
1169 directly.  There was no clear consensus on it.
1170
1171 As a result, RFC2553 defines struct sockaddr_storage as follows:
1172         struct sockaddr_storage {
1173                 u_char  __ss_len;       /* address length */
1174                 u_char  __ss_family;    /* address family */
1175                 /* and bunch of padding */
1176         };
1177 On the contrary, XNET draft defines as follows:
1178         struct sockaddr_storage {
1179                 u_char  ss_len;         /* address length */
1180                 u_char  ss_family;      /* address family */
1181                 /* and bunch of padding */
1182         };
1183
1184 In December 1999, it was agreed that RFC2553bis should pick the latter (XNET)
1185 definition.
1186
1187 KAME kit prior to December 1999 used RFC2553 definition.  KAME kit after
1188 December 1999 (including December) will conform to XNET definition,
1189 based on RFC2553bis discussion.
1190
1191 If you look at multiple IPv6 implementations, you will be able to see
1192 both definitions.  As an userland programmer, the most portable way of
1193 dealing with it is to:
1194 (1) ensure ss_family and/or ss_len are available on the platform, by using
1195     GNU autoconf,
1196 (2) have -Dss_family=__ss_family to unify all occurences (including header
1197     file) into __ss_family, or
1198 (3) never touch __ss_family.  cast to sockaddr * and use sa_family like:
1199         struct sockaddr_storage ss;
1200         family = ((struct sockaddr *)&ss)->sa_family
1201
1202 1.14 Invalid addresses on the wire
1203
1204 Some of IPv6 transition technologies embed IPv4 address into IPv6 address.
1205 These specifications themselves are fine, however, there can be certain
1206 set of attacks enabled by these specifications.  Recent speicifcation
1207 documents covers up those issues, however, there are already-published RFCs
1208 that does not have protection against those (like using source address of
1209 ::ffff:127.0.0.1 to bypass "reject packet from remote" filter).
1210
1211 To name a few, these address ranges can be used to hose an IPv6 implementation,
1212 or bypass security controls:
1213 - IPv4 mapped address that embeds unspecified/multicast/loopback/broadcast
1214   IPv4 address (if they are in IPv6 native packet header, they are malicious)
1215         ::ffff:0.0.0.0/104      ::ffff:127.0.0.0/104
1216         ::ffff:224.0.0.0/100    ::ffff:255.0.0.0/104 
1217 - 6to4 (RFC3056) prefix generated from unspecified/multicast/loopback/
1218   broadcast/private IPv4 address
1219         2002:0000::/24          2002:7f00::/24          2002:e000::/24
1220         2002:ff00::/24          2002:0a00::/24          2002:ac10::/28  
1221         2002:c0a8::/32
1222 - IPv4 compatible address that embeds unspecified/multicast/loopback/broadcast
1223   IPv4 address (if they are in IPv6 native packet header, they are malicious).
1224   Note that, since KAME doe snot support RFC1933/2893 auto tunnels, KAME nodes
1225   are not vulnerable to these packets.
1226         ::0.0.0.0/104   ::127.0.0.0/104 ::224.0.0.0/100 ::255.0.0.0/104 
1227
1228 Also, since KAME does not support RFC1933/2893 auto tunnels, seeing IPv4
1229 compatible is very rare.  You should take caution if you see those on the wire.
1230
1231 If we see IPv6 packets with IPv4 mapped address (::ffff:0.0.0.0/96) in the
1232 header in dual-stack environment (not in SIIT environment), they indicate
1233 that someone is trying to inpersonate IPv4 peer.  The packet should be dropped.
1234
1235 IPv6 specifications do not talk very much about IPv6 unspecified address (::)
1236 in the IPv6 source address field.  Clarification is in progress.
1237 Here are couple of comments:
1238 - IPv6 unspecified address can be used in IPv6 source address field, if and
1239   only if we have no legal source address for the node.  The legal situations
1240   include, but may not be limited to, (1) MLD while no IPv6 address is assigned
1241   to the node and (2) DAD.
1242 - If IPv6 TCP packet has IPv6 unspecified address, it is an attack attempt.
1243   The form can be used as a trigger for TCP DoS attack.  KAME code already
1244   filters them out.
1245 - The following examples are seemingly illegal.  It seems that there's general
1246   consensus among ipngwg for those.  (1) mobile-ip6 home address option,
1247   (2) offlink packets (so routers should not forward them).
1248   KAME implmements (2) already.
1249
1250 KAME code is carefully written to avoid such incidents.  More specifically,
1251 KAME kernel will reject packets with certain source/dstination address in IPv6
1252 base header, or IPv6 routing header.  Also, KAME default configuration file
1253 is written carefully, to avoid those attacks.
1254
1255 draft-itojun-ipv6-transition-abuse-01.txt talks about more about this.
1256
1257 1.15 Node's required addresses
1258
1259 RFC2373 section 2.8 talks about required addresses for an IPv6
1260 node.  The section talks about how KAME stack manages those required
1261 addresses.
1262
1263 1.15.1 Host case
1264
1265 The following items are automatically assigned to the node (or the node will
1266 automatically joins the group), at bootstrap time:
1267 - Loopback address
1268 - All-nodes multicast addresses (ff01::1)
1269
1270 The following items will be automatically handled when the interface becomes
1271 IFF_UP:
1272 - Its link-local address for each interface
1273 - Solicited-node multicast address for link-local addresses
1274 - Link-local allnodes multicast address (ff02::1)
1275
1276 The following items need to be configured manually by ifconfig(8) or prefix(8).
1277 Alternatively, these can be autoconfigured by using stateless address
1278 autoconfiguration.
1279 - Assigned unicast/anycast addresses
1280 - Solicited-Node multicast address for assigned unicast address
1281
1282 Users can join groups by using appropriate system calls like setsockopt(2).
1283
1284 1.15.2 Router case
1285
1286 In addition to the above, routers needs to handle the following items.
1287
1288 The following items need to be configured manually by using ifconfig(8).
1289 o The subnet-router anycast addresses for the interfaces it is configured
1290   to act as a router on (prefix::/64)
1291 o All other anycast addresses with which the router has been configured
1292
1293 The router will join the following multicast group when rtadvd(8) is available
1294 for the interface.
1295 o All-Routers Multicast Addresses (ff02::2)
1296
1297 Routing daemons will join appropriate multicast groups, as necessary,
1298 like ff02::9 for RIPng.
1299
1300 Users can join groups by using appropriate system calls like setsockopt(2).
1301
1302 1.16 Advanced API
1303
1304 Current KAME kernel implements 2292bis API, documented in
1305 draft-ietf-ipngwg-rfc2292bis-xx.txt.  It also implements RFC2292 API,
1306 for backward compatibility purposes with *BSD-integrated codebase.
1307 KAME tree ships with 2292bis headers.
1308 *BSD-integrated codebase implements either RFC2292, or 2292bis, API.
1309 see "COVERAGE" document for detailed implementation status.
1310
1311 Here are couple of issues to mention:
1312 - *BSD-integrated binaries, compiled for RFC2292, will work on KAME kernel.
1313   For example, OpenBSD 2.7 /sbin/rtsol will work on KAME/openbsd kernel.
1314 - KAME binaries, compiled using 2292bis, will not work on *BSD-integrated
1315   kenrel.  For example, KAME /usr/local/v6/sbin/rtsol will not work on
1316   OpenBSD 2.7 kernel.
1317 - 2292bis API is not compatible with RFC2292 API.  2292bis #define symbols
1318   conflict with RFC2292 symbols.  Therefore, if you compile programs that
1319   assume RFC2292 API, the compilation itself goes fine, however, the compiled
1320   binary will not work correctly.  The problem is not KAME issue, but API
1321   issue.  For example, Solaris 8 implements 2292bis API.  If you compile
1322   RFC2292-based code on Solaris 8, the binary can behave strange.
1323
1324 There are few (or couple of) incompatible behavior in RFC2292 binary backward
1325 compatibility support in KAME tree.  To enumerate:
1326 - Type 0 routing header lacks support for strict/loose bitmap.
1327   Even if we see packets with "strict" bit set, those bits will not be made
1328   visible to the userland.
1329   Background: RFC2292 document is based on RFC1883 IPv6, and it uses
1330   strict/loose bitmap.  2292bis document is based on RFC2460 IPv6, and it has
1331   no strict/loose bitmap (it was removed from RFC2460).  KAME tree obeys
1332   RFC2460 IPv6, and lacks support for strict/loose bitmap.
1333
1334 2. Network Drivers
1335
1336 KAME requires three items to be added into the standard drivers:
1337
1338 (1) mbuf clustering requirement. In this stable release, we changed
1339     MINCLSIZE into MHLEN+1 for all the operating systems in order to make
1340     all the drivers behave as we expect.  
1341
1342 (2) multicast.  If "ifmcstat" yields no multicast group for a
1343     interface, that interface has to be patched.
1344
1345 To avoid troubles, we suggest you to comment out the device drivers
1346 for unsupported/unnecessary cards, from the kernel configuration file.
1347 If you accidentally enable unsupported drivers, some of the userland
1348 tools may not work correctly (routing daemons are typical example).
1349
1350 In the following sections, "official support" means that KAME developers
1351 are using that ethernet card/driver frequently.
1352
1353 (NOTE: In the past we required all pcmcia drivers to have a call to
1354 in6_ifattach().  We have no such requirement any more)
1355
1356 2.1 FreeBSD 2.2.x-RELEASE
1357
1358 Here is a list of FreeBSD 2.2.x-RELEASE drivers and its conditions:
1359
1360         driver  mbuf(1)         multicast(2)    official support?
1361         ---     ---             ---             ---
1362         (Ethernet)
1363         ar      looks ok        -               -
1364         cnw     ok              ok              yes (*)
1365         ed      ok              ok              yes
1366         ep      ok              ok              yes
1367         fe      ok              ok              yes
1368         sn      looks ok        -               -   (*)
1369         vx      looks ok        -               -
1370         wlp     ok              ok              -   (*)
1371         xl      ok              ok              yes
1372         zp      ok              ok              -
1373         (FDDI)
1374         fpa     looks ok        ?               -
1375         (ATM)
1376         en      ok              ok              yes
1377         (Serial)
1378         lp      ?               -               not work
1379         sl      ?               -               not work
1380         sr      looks ok        ok              -   (**)
1381
1382 You may want to add an invocation of "rtsol" in "/etc/pccard_ether",
1383 if you are using notebook computers and PCMCIA ethernet card.
1384
1385 (*) These drivers are distributed with PAO (http://www.jp.freebsd.org/PAO/).
1386
1387 (**) There was some report says that, if you make sr driver up and down and
1388 then up, the kernel may hang up.  We have disabled frame-relay support from
1389 sr driver and after that this looks to be working fine.  If you need
1390 frame-relay support to come back, please contact KAME developers.
1391
1392 2.2 BSD/OS 3.x
1393
1394 The following lists BSD/OS 3.x device drivers and its conditions:
1395
1396         driver  mbuf(1)         multicast(2)    official support?
1397         ---     ---             ---             ---
1398         (Ethernet)
1399         cnw     ok              ok              yes
1400         de      ok              ok              -
1401         df      ok              ok              -
1402         eb      ok              ok              -
1403         ef      ok              ok              yes
1404         exp     ok              ok              -
1405         mz      ok              ok              yes
1406         ne      ok              ok              yes
1407         we      ok              ok              -
1408         (FDDI)
1409         fpa     ok              ok              -
1410         (ATM)
1411         en      maybe           ok              -
1412         (Serial)
1413         ntwo    ok              ok              yes
1414         sl      ?               -               not work
1415         appp    ?               -               not work
1416
1417 You may want to use "@insert" directive in /etc/pccard.conf to invoke
1418 "rtsol" command right after dynamic insertion of PCMCIA ethernet cards.
1419
1420 2.3 NetBSD
1421
1422 The following table lists the network drivers we have tried so far.
1423
1424         driver          mbuf(1) multicast(2)    official support?
1425         ---             ---     ---             ---
1426         (Ethernet)
1427         awi pcmcia/i386 ok      ok              -
1428         bah zbus/amiga  NG(*)
1429         cnw pcmcia/i386 ok      ok              yes
1430         ep pcmcia/i386  ok      ok              -
1431         le sbus/sparc   ok      ok              yes
1432         ne pci/i386     ok      ok              yes
1433         ne pcmcia/i386  ok      ok              yes
1434         wi pcmcia/i386  ok      ok              yes
1435         (ATM)
1436         en pci/i386     ok      ok              -
1437
1438 (*) This may need some fix, but I'm not sure what arcnet interfaces assume...
1439
1440 2.4 FreeBSD 3.x-RELEASE
1441
1442 Here is a list of FreeBSD 3.x-RELEASE drivers and its conditions:
1443
1444         driver  mbuf(1)         multicast(2)    official support?
1445         ---     ---             ---             ---
1446         (Ethernet)
1447         cnw     ok              ok              -(*)
1448         ed      ?               ok              -
1449         ep      ok              ok              -
1450         fe      ok              ok              yes
1451         fxp     ?(**)
1452         lnc     ?               ok              -
1453         sn      ?               ?               -(*)
1454         wi      ok              ok              yes
1455         xl      ?               ok              -
1456
1457 (*) These drivers are distributed with PAO as PAO3
1458     (http://www.jp.freebsd.org/PAO/).
1459 (**) there are trouble reports with multicast filter initialization.
1460
1461 More drivers will just simply work on KAME FreeBSD 3.x-RELEASE but have not
1462 been checked yet.
1463
1464 2.5 FreeBSD 4.x-RELEASE
1465
1466 Here is a list of FreeBSD 4.x-RELEASE drivers and its conditions:
1467
1468         driver          multicast
1469         ---             ---
1470         (Ethernet)
1471         lnc/vmware      ok
1472
1473 2.6 OpenBSD 2.x
1474
1475 Here is a list of OpenBSD 2.x drivers and its conditions:
1476
1477         driver          mbuf(1)         multicast(2)    official support?
1478         ---             ---             ---             ---
1479         (Ethernet)
1480         de pci/i386     ok              ok              yes
1481         fxp pci/i386    ?(*)
1482         le sbus/sparc   ok              ok              yes
1483         ne pci/i386     ok              ok              yes
1484         ne pcmcia/i386  ok              ok              yes
1485         wi pcmcia/i386  ok              ok              yes
1486
1487 (*) There seem to be some problem in driver, with multicast filter
1488 configuration.  This happens with certain revision of chipset on the card.
1489 Should be fixed by now by workaround in sys/net/if.c, but still not sure.
1490
1491 2.7 BSD/OS 4.x
1492
1493 The following lists BSD/OS 4.x device drivers and its conditions:
1494
1495         driver  mbuf(1)         multicast(2)    official support?
1496         ---     ---             ---             ---
1497         (Ethernet)
1498         de      ok              ok              yes
1499         exp     (*)
1500
1501 You may want to use "@insert" directive in /etc/pccard.conf to invoke
1502 "rtsol" command right after dynamic insertion of PCMCIA ethernet cards.
1503
1504 (*) exp driver has serious conflict with KAME initialization sequence.
1505 A workaround is committed into sys/i386/pci/if_exp.c, and should be okay by now.
1506
1507 3. Translator
1508
1509 We categorize IPv4/IPv6 translator into 4 types.
1510
1511 Translator A --- It is used in the early stage of transition to make
1512 it possible to establish a connection from an IPv6 host in an IPv6
1513 island to an IPv4 host in the IPv4 ocean.
1514
1515 Translator B --- It is used in the early stage of transition to make
1516 it possible to establish a connection from an IPv4 host in the IPv4
1517 ocean to an IPv6 host in an IPv6 island.
1518
1519 Translator C --- It is used in the late stage of transition to make it
1520 possible to establish a connection from an IPv4 host in an IPv4 island
1521 to an IPv6 host in the IPv6 ocean.
1522
1523 Translator D --- It is used in the late stage of transition to make it
1524 possible to establish a connection from an IPv6 host in the IPv6 ocean
1525 to an IPv4 host in an IPv4 island.
1526
1527 KAME provides an TCP relay translator for category A.  This is called
1528 "FAITH".  We also provide IP header translator for category A.
1529
1530 3.1 FAITH TCP relay translator
1531
1532 FAITH system uses TCP relay daemon called "faithd" helped by the KAME kernel.
1533 FAITH will reserve an IPv6 address prefix, and relay TCP connection
1534 toward that prefix to IPv4 destination.
1535
1536 For example, if the reserved IPv6 prefix is 3ffe:0501:0200:ffff::, and
1537 the IPv6 destination for TCP connection is 3ffe:0501:0200:ffff::163.221.202.12,
1538 the connection will be relayed toward IPv4 destination 163.221.202.12.
1539
1540         destination IPv4 node (163.221.202.12)
1541           ^
1542           | IPv4 tcp toward 163.221.202.12
1543         FAITH-relay dual stack node
1544           ^
1545           | IPv6 TCP toward 3ffe:0501:0200:ffff::163.221.202.12
1546         source IPv6 node
1547
1548 faithd must be invoked on FAITH-relay dual stack node.
1549
1550 For more details, consult kame/kame/faithd/README and
1551 draft-ietf-ngtrans-tcpudp-relay-04.txt.
1552
1553 3.2 IPv6-to-IPv4 header translator
1554
1555 (to be written)
1556
1557 4. IPsec
1558
1559 IPsec is implemented as the following three components.
1560
1561 (1) Policy Management
1562 (2) Key Management
1563 (3) AH, ESP and IPComp handling in kernel
1564
1565 Note that KAME/OpenBSD does NOT include support for KAME IPsec code,
1566 as OpenBSD team has their home-brew IPsec stack and they have no plan
1567 to replace it.  IPv6 support for IPsec is, therefore, lacking on KAME/OpenBSD.
1568
1569 http://www.netbsd.org/Documentation/network/ipsec/ has more information
1570 including usage examples.
1571
1572 4.1 Policy Management
1573
1574 The kernel implements experimental policy management code.  There are two way
1575 to manage security policy.  One is to configure per-socket policy using
1576 setsockopt(3).  In this cases, policy configuration is described in
1577 ipsec_set_policy(3).  The other is to configure kernel packet filter-based
1578 policy using PF_KEY interface, via setkey(8).
1579
1580 The policy entry will be matched in order.  The order of entries makes
1581 difference in behavior.
1582
1583 4.2 Key Management
1584
1585 The key management code implemented in this kit (sys/netkey) is a
1586 home-brew PFKEY v2 implementation.  This conforms to RFC2367.
1587
1588 The home-brew IKE daemon, "racoon" is included in the kit (kame/kame/racoon,
1589 or usr.sbin/racoon).
1590 Basically you'll need to run racoon as daemon, then setup a policy
1591 to require keys (like ping -P 'out ipsec esp/transport//use').
1592 The kernel will contact racoon daemon as necessary to exchange keys.
1593
1594 In IKE spec, there's ambiguity about interpretation of "tunnel" proposal.
1595 For example, if we would like to propose the use of following packet:
1596         IP AH ESP IP payload
1597 some implementation proposes it as "AH transport and ESP tunnel", since
1598 this is more logical from packet construction point of view.  Some
1599 implementation proposes it as "AH tunnel and ESP tunnel".
1600 Racoon follows the former route.
1601 This raises real interoperability issue.  We hope this to be resolved quickly.
1602
1603 4.3 AH and ESP handling
1604
1605 IPsec module is implemented as "hooks" to the standard IPv4/IPv6
1606 processing.  When sending a packet, ip{,6}_output() checks if ESP/AH
1607 processing is required by checking if a matching SPD (Security
1608 Policy Database) is found.  If ESP/AH is needed,
1609 {esp,ah}{4,6}_output() will be called and mbuf will be updated
1610 accordingly.  When a packet is received, {esp,ah}4_input() will be
1611 called based on protocol number, i.e. (*inetsw[proto])().
1612 {esp,ah}4_input() will decrypt/check authenticity of the packet,
1613 and strips off daisy-chained header and padding for ESP/AH.  It is
1614 safe to strip off the ESP/AH header on packet reception, since we
1615 will never use the received packet in "as is" form.
1616
1617 By using ESP/AH, TCP4/6 effective data segment size will be affected by
1618 extra daisy-chained headers inserted by ESP/AH.  Our code takes care of
1619 the case.
1620
1621 Basic crypto functions can be found in directory "sys/crypto".  ESP/AH
1622 transform are listed in {esp,ah}_core.c with wrapper functions.  If you
1623 wish to add some algorithm, add wrapper function in {esp,ah}_core.c, and
1624 add your crypto algorithm code into sys/crypto.
1625
1626 Tunnel mode works basically fine, but comes with the following restrictions:
1627 - You cannot run routing daemon across IPsec tunnel, since we do not model
1628   IPsec tunnel as pseudo interfaces.
1629 - Authentication model for AH tunnel must be revisited.  We'll need to
1630   improve the policy management engine, eventually.
1631 - Path MTU discovery does not work across IPv6 IPsec tunnel gateway due to
1632   insufficient code.
1633
1634 AH specificaton does not talk much about "multiple AH on a packet" case.
1635 We incrementally compute AH checksum, from inside to outside.  Also, we
1636 treat inner AH to be immutable.
1637 For example, if we are to create the following packet:
1638         IP AH1 AH2 AH3 payload
1639 we do it incrementally.  As a result, we get crypto checksums like below:
1640         AH3 has checksum against "IP AH3' payload".
1641                 where AH3' = AH3 with checksum field filled with 0.
1642         AH2 has checksum against "IP AH2' AH3 payload".
1643         AH1 has checksum against "IP AH1' AH2 AH3 payload",
1644 Also note that AH3 has the smallest sequence number, and AH1 has the largest
1645 sequence number.
1646
1647 To avoid traffic analysis on shorter packets, ESP output logic supports
1648 random length padding.  By setting net.inet.ipsec.esp_randpad (or
1649 net.inet6.ipsec6.esp_randpad) to positive value N, you can ask the kernel
1650 to randomly pad packets shorter than N bytes, to random length smaller than
1651 or equal to N.  Note that N does not include ESP authentication data length.
1652 Also note that the random padding is not included in TCP segment
1653 size computation.  Negative value will turn off the functionality.
1654 Recommeded value for N is like 128, or 256.  If you use a too big number
1655 as N, you may experience inefficiency due to fragmented packtes.
1656
1657 4.4 IPComp handling
1658
1659 IPComp stands for IP payload compression protocol.  This is aimed for
1660 payload compression, not the header compression like PPP VJ compression.
1661 This may be useful when you are using slow serial link (say, cell phone)
1662 with powerful CPU (well, recent notebook PCs are really powerful...).
1663 The protocol design of IPComp is very similar to IPsec, though it was
1664 defined separately from IPsec itself.
1665
1666 Here are some points to be noted:
1667 - IPComp is treated as part of IPsec protocol suite, and SPI and
1668   CPI space is unified.  Spec says that there's no relationship
1669   between two so they are assumed to be separate in specs.
1670 - IPComp association (IPCA) is kept in SAD.
1671 - It is possible to use well-known CPI (CPI=2 for DEFLATE for example),
1672   for outbound/inbound packet, but for indexing purposes one element from
1673   SPI/CPI space will be occupied anyway.
1674 - pfkey is modified to support IPComp.  However, there's no official
1675   SA type number assignment yet.  Portability with other IPComp
1676   stack is questionable (anyway, who else implement IPComp on UN*X?).
1677 - Spec says that IPComp output processing must be performed before AH/ESP
1678   output processing, to achieve better compression ratio and "stir" data
1679   stream before encryption.  The most meaningful processing order is:
1680   (1) compress payload by IPComp, (2) encrypt payload by ESP, then (3) attach
1681   authentication data by AH.
1682   However, with manual SPD setting, you are able to violate the ordering
1683   (KAME code is too generic, maybe).  Also, it is just okay to use IPComp
1684   alone, without AH/ESP.
1685 - Though the packet size can be significantly decreased by using IPComp, no
1686   special consideration is made about path MTU (spec talks nothing about MTU
1687   consideration).  IPComp is designed for serial links, not ethernet-like
1688   medium, it seems.
1689 - You can change compression ratio on outbound packet, by changing
1690   deflate_policy in sys/netinet6/ipcomp_core.c.  You can also change outbound
1691   history buffer size by changing deflate_window_out in the same source code.
1692   (should it be sysctl accessible, or per-SAD configurable?)
1693 - Tunnel mode IPComp is not working right.  KAME box can generate tunnelled
1694   IPComp packet, however, cannot accept tunneled IPComp packet.
1695 - You can negotiate IPComp association with racoon IKE daemon.
1696 - KAME code does not attach Adler32 checksum to compressed data.
1697   see ipsec wg mailing list discussion in Jan 2000 for details.
1698
1699 4.5 Conformance to RFCs and IDs
1700
1701 The IPsec code in the kernel conforms (or, tries to conform) to the
1702 following standards:
1703     "old IPsec" specification documented in rfc182[5-9].txt
1704     "new IPsec" specification documented in:
1705         rfc240[1-6].txt rfc241[01].txt rfc2451.txt
1706         draft-mcdonald-simple-ipsec-api-01.txt
1707                 (expired, available in ftp://ftp.kame.net/pub/internet-drafts/)
1708         draft-ietf-ipsec-ciph-aes-cbc-00.txt
1709     IPComp:
1710         RFC2393: IP Payload Compression Protocol (IPComp)
1711 IKE specifications (rfc240[7-9].txt) are implemented in userland
1712 as "racoon" IKE daemon.
1713
1714 Currently supported algorithms are:
1715     old IPsec AH
1716         null crypto checksum (no document, just for debugging)
1717         keyed MD5 with 128bit crypto checksum (rfc1828.txt)
1718         keyed SHA1 with 128bit crypto checksum (no document)
1719         HMAC MD5 with 128bit crypto checksum (rfc2085.txt)
1720         HMAC SHA1 with 128bit crypto checksum (no document)
1721     old IPsec ESP
1722         null encryption (no document, similar to rfc2410.txt)
1723         DES-CBC mode (rfc1829.txt)
1724     new IPsec AH
1725         null crypto checksum (no document, just for debugging)
1726         keyed MD5 with 96bit crypto checksum (no document)
1727         keyed SHA1 with 96bit crypto checksum (no document)
1728         HMAC MD5 with 96bit crypto checksum (rfc2403.txt
1729         HMAC SHA1 with 96bit crypto checksum (rfc2404.txt)
1730         HMAC SHA2-256 with 96bit crypto checksum (no document)
1731         HMAC SHA2-384 with 96bit crypto checksum (no document)
1732         HMAC SHA2-512 with 96bit crypto checksum (no document)
1733     new IPsec ESP
1734         null encryption (rfc2410.txt)
1735         DES-CBC with derived IV
1736                 (draft-ietf-ipsec-ciph-des-derived-01.txt, draft expired)
1737         DES-CBC with explicit IV (rfc2405.txt)
1738         3DES-CBC with explicit IV (rfc2451.txt)
1739         BLOWFISH CBC (rfc2451.txt)
1740         CAST128 CBC (rfc2451.txt)
1741         RIJNDAEL/AES CBC (draft-ietf-ipsec-ciph-aes-cbc-00.txt,
1742                 uses IANA-assigned protocol number)
1743         TWOFISH CBC (draft-ietf-ipsec-ciph-aes-cbc-00.txt)
1744         each of the above can be combined with:
1745             ESP authentication with HMAC-MD5(96bit)
1746             ESP authentication with HMAC-SHA1(96bit)
1747     IPComp
1748         RFC2394: IP Payload Compression Using DEFLATE
1749
1750 The following algorithms are NOT supported:
1751     old IPsec AH
1752         HMAC MD5 with 128bit crypto checksum + 64bit replay prevention
1753                 (rfc2085.txt)
1754         keyed SHA1 with 160bit crypto checksum + 32bit padding (rfc1852.txt)
1755
1756 The key/policy management API is based on the following document, with fair
1757 amount of extensions:
1758         RFC2367: PF_KEY key management API
1759
1760 4.6 ECN consideration on IPsec tunnels
1761
1762 KAME IPsec implements ECN-friendly IPsec tunnel, described in
1763 draft-ietf-ipsec-ecn-02.txt.
1764 Normal IPsec tunnel is described in RFC2401.  On encapsulation,
1765 IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner
1766 IP header to outer IP header.  On decapsulation outer IP header
1767 will be simply dropped.  The decapsulation rule is not compatible
1768 with ECN, since ECN bit on the outer IP TOS/traffic class field will be
1769 lost.
1770 To make IPsec tunnel ECN-friendly, we should modify encapsulation
1771 and decapsulation procedure.  This is described in
1772 draft-ietf-ipsec-ecn-02.txt, chapter 3.3.
1773
1774 KAME IPsec tunnel implementation can give you three behaviors, by setting
1775 net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some value:
1776 - RFC2401: no consideration for ECN (sysctl value -1)
1777 - ECN forbidden (sysctl value 0)
1778 - ECN allowed (sysctl value 1)
1779 Note that the behavior is configurable in per-node manner, not per-SA manner
1780 (draft-ietf-ipsec-ecn-02 wants per-SA configuration, but it looks too much
1781 for me).
1782
1783 The behavior is summarized as follows (see source code for more detail):
1784
1785                 encapsulate                     decapsulate
1786                 ---                             ---
1787 RFC2401         copy all TOS bits               drop TOS bits on outer
1788                 from inner to outer.            (use inner TOS bits as is)
1789
1790 ECN forbidden   copy TOS bits except for ECN    drop TOS bits on outer
1791                 (masked with 0xfc) from inner   (use inner TOS bits as is)
1792                 to outer.  set ECN bits to 0.
1793
1794 ECN allowed     copy TOS bits except for ECN    use inner TOS bits with some
1795                 CE (masked with 0xfe) from      change.  if outer ECN CE bit
1796                 inner to outer.                 is 1, enable ECN CE bit on
1797                 set ECN CE bit to 0.            the inner.
1798
1799 General strategy for configuration is as follows:
1800 - if both IPsec tunnel endpoint are capable of ECN-friendly behavior,
1801   you'd better configure both end to "ECN allowed" (sysctl value 1).
1802 - if the other end is very strict about TOS bit, use "RFC2401"
1803   (sysctl value -1).
1804 - in other cases, use "ECN forbidden" (sysctl value 0).
1805 The default behavior is "ECN forbidden" (sysctl value 0).
1806
1807 For more information, please refer to:
1808         draft-ietf-ipsec-ecn-02.txt
1809         RFC2481 (Explicit Congestion Notification)
1810         KAME sys/netinet6/{ah,esp}_input.c
1811
1812 (Thanks goes to Kenjiro Cho <kjc@csl.sony.co.jp> for detailed analysis)
1813
1814 4.7 Interoperability
1815
1816 IPsec, IPComp (in kernel) and IKE (in userland as "racoon") has been tested
1817 at several interoperability test events, and it is known to interoperate
1818 with many other implementations well.  Also, KAME IPsec has quite wide
1819 coverage for IPsec crypto algorithms documented in RFC (we do not cover
1820 algorithms with intellectual property issues, though).
1821
1822 Here are (some of) platforms we have tested IPsec/IKE interoperability
1823 in the past, no particular order.  Note that both ends (KAME and
1824 others) may have modified their implementation, so use the following
1825 list just for reference purposes.
1826         ACC, allied-telesis, Altiga, Ashley-laurent (vpcom.com), BlueSteel,
1827         CISCO IOS, Cryptek, Checkpoint FW-1, Data Fellows (F-Secure),
1828         Ericsson, Fitel, FreeS/WAN, HiFn, HITACHI, IBM AIX, IIJ, Intel Canada,
1829         Intel Packet Protect, MEW NetCocoon, MGCS, Microsoft WinNT/2000,
1830         NAI PGPnet, NetLock, NIST (linux IPsec + plutoplus), NEC IX5000,
1831         Netscreen, NxNetworks, OpenBSD isakmpd, Pivotal, Radguard, RapidStream,
1832         RedCreek, Routerware, RSA, SSH (both IPv4/IPv6), Secure Computing,
1833         Soliton, Sun Solaris8, TIS/NAI Gauntret, Toshiba, VPNet,
1834         Yamaha RT series
1835
1836 Here are (some of) platforms we have tested IPComp/IKE interoperability
1837 in the past, in no particular order.
1838         IRE, SSH (both IPv4/IPv6), NetLock
1839
1840 VPNC (vpnc.org) provides IPsec conformance tests, using KAME and OpenBSD
1841 IPsec/IKE implementations.  Their test results are available at
1842 http://www.vpnc.org/conformance.html, and it may give you more idea
1843 about which implementation interoperates with KAME IPsec/IKE implementation.
1844
1845 5. ALTQ
1846
1847 KAME kit includes ALTQ 2.1 code, which supports FreeBSD2, FreeBSD3,
1848 NetBSD and OpenBSD.  For BSD/OS, ALTQ does not work.
1849 ALTQ in KAME supports (or tries to support) IPv6.
1850 (actually, ALTQ is developed on KAME repository since ALTQ 2.1 - Jan 2000)
1851
1852 ALTQ occupies single character device number.  For FreeBSD, it is officially
1853 allocated.  For OpenBSD and NetBSD, we use the number which is not
1854 currently allocated (will eventually get an official number).
1855 The character device is enabled for i386 architecture only.  To enable and
1856 compile ALTQ-ready kernel for other archititectures, take the following steps:
1857 - assume that your architecture is FOOBAA.
1858 - modify sys/arch/FOOBAA/FOOBAA/conf.c (or somewhere that defines cdevsw),
1859   to include a line for ALTQ.  look at sys/arch/i386/i386/conf.c for
1860   example.  The major number must be same as i386 case.
1861 - copy kernel configuration file (like ALTQ.v6 or GENERIC.v6) from i386,
1862   and modify accordingly.
1863 - build a kernel.
1864 - before building userland, change netbsd/{lib,usr.sbin,usr.bin}/Makefile
1865   (or openbsd/foobaa) so that it will visit altq-related sub directories.
1866
1867 6. mobile-ip6
1868
1869 6.1 KAME node as correspondent node
1870
1871 Default installation recognizes home address option (in destination
1872 options header).  No sub-options are supported.  interaction with
1873 IPsec, and/or 2292bis API, needs further study.
1874
1875 6.2 KAME node as home agent/mobile node
1876
1877 KAME kit includes Ericsson mobile-ip6 code.  The integration is just started
1878 (in Feb 2000), and we will need some more time to integrate it better.
1879
1880 See kame/mip6config/{QUICKSTART,README_MIP6.txt} for more details.
1881
1882 The Ericsson code implements revision 09 of the mobile-ip6 draft.  There
1883 are other implementations available:
1884         NEC: http://www.6bone.nec.co.jp/mipv6/internal-dist/ (-13 draft)
1885         SFC: http://neo.sfc.wide.ad.jp/~mip6/ (-13 draft)
1886
1887 7. Coding style
1888
1889 The KAME developers basically do not make a bother about coding
1890 style.  However, there is still some agreement on the style, in order
1891 to make the distributed develoment smooth.
1892
1893 - the tab character should be 8 columns wide (tabstops are at 8, 16, 24, ...
1894   column).  With vi, use ":set ts=8 sw=8".
1895 - each line should be within 80 characters.
1896 - keep a single open/close bracket in a comment such as in the following
1897   line:
1898         putchar('(');   /* ) */
1899   without this, some vi users would have a hard time to match a pair of
1900   brackets.  Although this type of bracket seems clumsy and is even
1901   harmful for some other type of vi users and Emacs users, the
1902   agreement in the KAME developers is to allow it.
1903 - add the following line to the head of every KAME-derived file:
1904   /*    (dollar)KAME(dollar)    */
1905   where "(dollar)" is the dollar character ($), and around "$" are tabs.
1906   (this is for C. For other language, you should use its own comment
1907   line.)
1908   Once commited to the CVS repository, this line will contain its
1909   version number (see, for example, at the top of this file).  This
1910   would make it easy to report a bug.
1911 - when creating a new file with the WIDE copyright, tap "make copyright.c" at
1912   the top-level, and use copyright.c as a template.  KAME RCS tag will be
1913   included automatically.
1914 - when editting a third-party package, keep its own coding style as
1915   much as possible, even if the style does not follow the items above.
1916
1917 When you want to contribute something to the KAME project, and if *you
1918 do not mind* the agreement, it would be helpful for the project to
1919 keep these rules.  Note, however, that we would never intend to force
1920 you to adopt our rules.  We would rather regard your own style,
1921 especially when you have a policy about the style.
1922
1923                                                  <end of IMPLEMENTATION>