IMPLEMENTATION revision 57522
1234285Sdim Implementation Note 2234285Sdim 3234285Sdim KAME Project 4234285Sdim http://www.kame.net/ 5234285Sdim $FreeBSD: head/share/doc/IPv6/IMPLEMENTATION 57522 2000-02-26 19:44:12Z shin $ 6234285Sdim 7234285Sdim1. IPv6 8234285Sdim 9234285Sdim1.1 Conformance 10234285Sdim 11234285SdimThe KAME kit conforms, or tries to conform, to the latest set of IPv6 12234285Sdimspecifications. For future reference we list some of the relevant documents 13234285Sdimbelow (NOTE: this is not a complete list - this is too hard to maintain...). 14234285SdimFor details please refer to specific chapter in the document, RFCs, manpages 15234285Sdimcome with KAME, or comments in the source code. 16234285Sdim 17234285SdimConformance tests have been performed on the KAME STABLE kit 18234285Sdimat TAHI project. Results can be viewed at http://www.tahi.org/report/KAME/. 19234285SdimWe also attended Univ. of New Hampshire IOL tests (http://www.iol.unh.edu/) 20234285Sdimin the past, with our past snapshots. 21234285Sdim 22234285SdimRFC1639: FTP Operation Over Big Address Records (FOOBAR) 23249423Sdim * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428, 24234285Sdim then RFC1639 if failed. 25234285SdimRFC1886: DNS Extensions to support IPv6 26234285SdimRFC1933: Transition Mechanisms for IPv6 Hosts and Routers 27234285Sdim * IPv4 compatible address is not supported. 28251662Sdim * automatic tunneling (4.3) is not supported. 29234285Sdim * "gif" interface implements IPv[46]-over-IPv[46] tunnel in a generic way, 30234285Sdim and it covers "configured tunnel" described in the spec. 31234285Sdim See 1.5 in this document for details. 32234285SdimRFC1981: Path MTU Discovery for IPv6 33234285SdimRFC2080: RIPng for IPv6 34234285Sdim * KAME-supplied route6d, bgpd and hroute6d support this. 35234285SdimRFC2283: Multiprotocol Extensions for BGP-4 36234285Sdim * so-called "BGP4+". 37234285Sdim * KAME-supplied bgpd supports this. 38234285SdimRFC2292: Advanced Sockets API for IPv6 39234285Sdim * For supported library functions/kernel APIs, see sys/netinet6/ADVAPI. 40234285SdimRFC2362: Protocol Independent Multicast-Sparse Mode (PIM-SM) 41234285Sdim * RFC2362 defines packet formats for PIM-SM. draft-ietf-pim-ipv6-01.txt 42234285Sdim is written based on this. 43234285SdimRFC2373: IPv6 Addressing Architecture 44234285Sdim * KAME supports node required addresses, and conforms to the scope 45234285Sdim requirement. 46234285SdimRFC2374: An IPv6 Aggregatable Global Unicast Address Format 47234285Sdim * KAME supports 64-bit length of Interface ID. 48234285SdimRFC2375: IPv6 Multicast Address Assignments 49234285Sdim * Userland applications use the well-known addresses assigned in the RFC. 50234285SdimRFC2428: FTP Extensions for IPv6 and NATs 51234285Sdim * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428, 52234285Sdim then RFC1639 if failed. 53234285SdimRFC2460: IPv6 specification 54234285SdimRFC2461: Neighbor discovery for IPv6 55234285Sdim * See 1.2 in this document for details. 56234285SdimRFC2462: IPv6 Stateless Address Autoconfiguration 57234285Sdim * See 1.4 in this document for details. 58234285SdimRFC2463: ICMPv6 for IPv6 specification 59234285Sdim * See 1.8 in this document for details. 60263508SdimRFC2464: Transmission of IPv6 Packets over Ethernet Networks 61234285SdimRFC2465: MIB for IPv6: Textual Conventions and General Group 62234285Sdim * Necessary statistics are gathered by the kernel. Actual IPv6 MIB 63234285Sdim support is provided as patchkit for ucd-snmp. 64234285SdimRFC2466: MIB for IPv6: ICMPv6 group 65263508Sdim * Necessary statistics are gathered by the kernel. Actual IPv6 MIB 66263508Sdim support is provided as patchkit for ucd-snmp. 67263508SdimRFC2467: Transmission of IPv6 Packets over FDDI Networks 68263508SdimRFC2472: IPv6 over PPP 69263508SdimRFC2492: IPv6 over ATM Networks 70263508Sdim * only PVC is supported. 71263508SdimRFC2497: Transmission of IPv6 packet over ARCnet Networks 72263508SdimRFC2545: Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing 73263508SdimRFC2553: Basic Socket Interface Extensions for IPv6 74263508Sdim * IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind 75234285Sdim socket (3.8) are supported. 76234285Sdim see 1.12 in this document for details. 77234285SdimRFC2675: IPv6 Jumbograms 78234285Sdim * See 1.7 in this document for details. 79234285SdimRFC2710: Multicast Listener Discovery for IPv6 80234285SdimRFC2711: IPv6 router alert option 81234285Sdimdraft-ietf-ipngwg-router-renum-08: Router renumbering for IPv6 82234285Sdimdraft-ietf-ipngwg-icmp-namelookups-02: IPv6 Name Lookups Through ICMP 83234285Sdimdraft-ietf-ipngwg-icmp-name-lookups-03: IPv6 Name Lookups Through ICMP 84234285Sdimdraft-ietf-pim-ipv6-01.txt: PIM for IPv6 85234285Sdim * pim6dd implements dense mode. pim6sd implements sparse mode. 86234285Sdimdraft-ietf-dhc-dhcpv6-14.txt: DHCPv6 87234285Sdimdraft-ietf-dhc-v6exts-11.txt: Extensions for DHCPv6 88234285Sdim * kame/dhcp6 has test implementation, which will not be compiled in 89234285Sdim default compilation. 90234285Sdimdraft-itojun-ipv6-tcp-to-anycast-00: 91234285Sdim Disconnecting TCP connection toward IPv6 anycast address 92263508Sdimdraft-yamamoto-wideipv6-comm-model-00 93263508Sdim * See 1.6 in this document for details. 94263508Sdimdraft-ietf-ipngwg-scopedaddr-format-00.txt: 95234285Sdim An Extension of Format for IPv6 Scoped Addresses 96234285Sdim 97234285Sdim1.2 Neighbor Discovery 98234285Sdim 99234285SdimNeighbor Discovery is fairly stable. Currently Address Resolution, 100234285SdimDuplicated Address Detection, and Neighbor Unreachability Detection 101234285Sdimare supported. In the near future we will be adding Proxy Neighbor 102234285SdimAdvertisement support in the kernel and Unsolicited Neighbor Advertisement 103234285Sdimtransmission command as admin tool. 104234285Sdim 105234285SdimIf DAD fails, the address will be marked "duplicated" and message will be 106234285Sdimgenerated to syslog (and usually to console). The "duplicated" mark 107234285Sdimcan be checked with ifconfig. It is administrators' responsibility to check 108234285Sdimfor and recover from DAD failures. 109234285SdimThe behavior should be improved in the near future. 110234285Sdim 111234285SdimSome of the network driver loops multicast packets back to itself, 112234285Sdimeven if instructed not to do so (especially in promiscuous mode). 113234285SdimIn such cases DAD may fail, because DAD engine sees inbound NS packet 114234285Sdim(actually from the node itself) and considers it as a sign of duplicate. 115234285SdimYou may want to look at #if condition marked "heuristics" in 116234285Sdimsys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note that the code 117234285Sdimfragment in "heuristics" section is not spec conformant). 118243830Sdim 119234285SdimNeighbor Discovery specification (RFC2461) does not talk about neighbor 120234285Sdimcache handling in the following cases: 121263508Sdim(1) when there was no neighbor cache entry, node received unsolicited 122263508Sdim RS/NS/NA/redirect packet without link-layer address 123263508Sdim(2) neighbor cache handling on medium without link-layer address 124263508Sdim (we need a neighbor cache entry for IsRouter bit) 125234285SdimFor (1), we implemented workaround based on discussions on IETF ipngwg mailing 126234285Sdimlist. For more details, see the comments in the source code and email 127234285Sdimthread started from (IPng 7155), dated Feb 6 1999. 128234285Sdim 129234285SdimIPv6 on-link determination rule (RFC2461) is quite different from assumptions 130234285Sdimin BSD network code. At this moment, KAME does not implement on-link 131251662Sdimdetermination rule when default router list is empty (RFC2461, section 5.2, 132251662Sdimlast sentence in 2nd paragraph - note that the spec misuse the word "host" 133251662Sdimand "node" in several places in the section). 134263508Sdim 135263508SdimTo avoid possible DoS attacks and infinite loops, KAME stack will accept 136263508Sdimonly 10 options on ND packet. Therefore, if you have 20 prefix options 137263508Sdimattached to RA, only the first 10 prefixes will be recognized. 138263508SdimIf this troubles you, please contact KAME team and/or modify 139263508Sdimnd6_maxndopt in sys/netinet6/nd6.c. If there are high demands we may 140234285Sdimprovide sysctl knob for the variable. 141234285Sdim 142234285Sdim1.3 Scope Index 143234285Sdim 144234285SdimIPv6 uses scoped addresses. Therefore, it is very important to 145specify scope index (interface index for link-local address, or 146site index for site-local address) with an IPv6 address. Without 147scope index, scoped IPv6 address is ambiguous to the kernel, and 148kernel will not be able to determine the outbound interface for a 149packet. 150 151Ordinary userland applications should use advanced API (RFC2292) to 152specify scope index, or interface index. For similar purpose, 153sin6_scope_id member in sockaddr_in6 structure is defined in RFC2553. 154However, the semantics for sin6_scope_id is rather vague. If you 155care about portability of your application, we suggest you to use 156advanced API rather than sin6_scope_id. 157 158In the kernel, an interface index for link-local scoped address is 159embedded into 2nd 16bit-word (3rd and 4th byte) in IPv6 address. 160For example, you may see something like: 161 fe80:1::200:f8ff:fe01:6317 162in the routing table and interface address structure (struct 163in6_ifaddr). The address above is a link-local unicast address 164which belongs to a network interface whose interface identifier is 1. 165The embedded index enables us to identify IPv6 link local 166addresses over multiple interfaces effectively and with only a 167little code change. 168Routing daemons and configuration programs, like route6d and 169ifconfig, will need to manipulate the "embedded" scope index. 170These programs use routing sockets and ioctls (like SIOCGIFADDR_IN6) 171and the kernel API will return IPv6 addresses with 2nd 16bit-word 172filled in. The APIs are for manipulating kernel internal structure. 173Programs that use these APIs have to be prepared about differences 174in kernels anyway. 175 176When you specify scoped address to the command line, NEVER write the 177embedded form (such as ff02:1::1 or fe80:2::fedc). This is not supposed 178to work. Always use standard form, like ff02::1 or fe80::fedc, with 179command line option for specifying interface (like "ping6 -I ne0 ff02::1). 180In general, if a command does not have command line option to specify 181outgoing interface, that command is not ready to accept scoped address. 182This may seem to be opposite from IPv6's premise to support "dentist office" 183situation. We believe that specifications need some improvements for this. 184 185Some of the userland tools support extended numeric IPv6 syntax, as 186documented in draft-ietf-ipngwg-scopedaddr-format-00.txt. You can specify 187outgoing link, by using name of the outgoing interface like "fe80::1%ne0". 188This way you will be able to specify link-local scoped address without much 189trouble. 190To use this extension in your program, you'll need to use getaddrinfo(3), 191and getnameinfo(3) with NI_WITHSCOPEID. 192The implementation currently assumes 1-to-1 relationship between a link and an 193interface, which is stronger than what specs say. 194 1951.4 Plug and Play 196 197The KAME kit implements most of the IPv6 stateless address 198autoconfiguration in the kernel. 199Neighbor Discovery functions are implemented in the kernel as a whole. 200Router Advertisement (RA) input for hosts is implemented in the 201kernel. Router Solicitation (RS) output for endhosts, RS input 202for routers, and RA output for routers are implemented in the 203userland. 204 2051.4.1 Assignment of link-local, and special addresses 206 207IPv6 link-local address is generated from IEEE802 adddress (ethernet MAC 208address). Each of interface is assigned an IPv6 link-local address 209automatically, when the interface becomes up (IFF_UP). Also, direct route 210for the link-local address is added to routing table. 211 212Here is an output of netstat command: 213 214Internet6: 215Destination Gateway Flags Netif Expire 216fe80:1::%ed0/64 link#1 UC ed0 217fe80:2::%ep0/64 link#2 UC ep0 218 219Interfaces that has no IEEE802 address (pseudo interfaces like tunnel 220interfaces, or ppp interfaces) will borrow IEEE802 address from other 221interfaces, such as ethernet interfaces, whenever possible. 222If there is no IEEE802 hardware attached, last-resort pseudorandom value, 223which is from MD5(hostname), will be used as source of link-local address. 224If it is not suitable for your usage, you will need to configure the 225link-local address manually. 226 227If an interface is not capable of handling IPv6 (such as lack of multicast 228support), link-local address will not be assigned to that interface. 229See section 2 for details. 230 231Each interface joins the solicited multicast address and the 232link-local all-nodes multicast addresses (e.g. fe80::1:ff01:6317 233and ff02::1, respectively, on the link the interface is attached). 234In addition to a link-local address, the loopback address (::1) will be 235assigned to the loopback interface. Also, ::1/128 and ff01::/32 are 236automatically added to routing table, and loopback interface joins 237node-local multicast group ff01::1. 238 2391.4.2 Stateless address autoconfiguration on hosts 240 241In IPv6 specification, nodes are separated into two categories: 242routers and hosts. Routers forward packets addressed to others, hosts does 243not forward the packets. net.inet6.ip6.forwarding defines whether this 244node is router or host (router if it is 1, host if it is 0). 245 246When a host hears Router Advertisement from the router, a host may 247autoconfigure itself by stateless address autoconfiguration. 248This behavior can be controlled by net.inet6.ip6.accept_rtadv 249(host autoconfigures itself if it is set to 1). 250By autoconfiguration, network address prefix for the receiving interface 251(usually global address prefix) is added. Default route is also configured. 252Routers periodically generate Router Advertisement packets. To request 253an adjacent router to generate RA packet, a host can transmit Router 254Solicitation. To generate a RS packet at any time, use the "rtsol" command. 255"rtsold" daemon is also available. "rtsold" generates Router Solicitation 256whenever necessary, and it works great for nomadic usage (notebooks/laptops). 257If one wishes to ignore Router Advertisements, use sysctl to set 258net.inet6.ip6.accept_rtadv to 0. 259 260To generate Router Advertisement from a router, use the "rtadvd" daemon. 261 262Note that, IPv6 specification assumes the following items, and nonconforming 263cases are left unspecified: 264- Only hosts will listen to router advertisements 265- Hosts have single network interface (except loopback) 266Therefore, this is unwise to enable net.inet6.ip6.accept_rtadv on routers, 267or multi-interface host. A misconfigured node can behave strange 268(KAME code allows nonconforming configuration, for those who would like 269to do some experiments). 270 271To summarize the sysctl knob: 272 accept_rtadv forwarding role of the node 273 --- --- --- 274 0 0 host (to be manually configured) 275 0 1 router 276 1 0 autoconfigured host 277 (spec assumes that host has single 278 interface only, autoconfigured host 279 with multiple interface is 280 out-of-scope) 281 1 1 invalid, or experimental 282 (out-of-scope of spec) 283 284RFC2462 has validation rule against incoming RA prefix information option, 285in 5.5.3 (e). This is to protect hosts from malicious (or misconfigured) 286routers that advertise very short prefix lifetime. 287There was an update from Jim Bound to ipngwg mailing list (look 288for "(ipng 6712)" in the archive) and KAME implements Jim's update. 289 290See 1.2 in the document for relationship between DAD and autoconfiguration. 291 2921.4.3 DHCPv6 (not yet put into freebsd4.0) 293 294We supply a tiny DHCPv6 server/client in kame/dhcp6. However, the 295implementation is very premature (for example, this does NOT 296implement address lease/release), and it is not in default compilation 297tree. If you want to do some experiment, compile it on your own. 298 299DHCPv6 and autoconfiguration also needs more work. "Managed" and "Other" 300bits in RA have no special effect to stateful autoconfiguration procedure 301in DHCPv6 client program ("Managed" bit actually prevents stateless 302autoconfiguration, but no special action will be taken for DHCPv6 client). 303 3041.5 Generic tunnel interface 305 306GIF (Generic InterFace) is a pseudo interface for configured tunnel. 307Details are described in gif(4) manpage. 308Currently 309 v6 in v6 310 v6 in v4 311 v4 in v6 312 v4 in v4 313are available. Use "gifconfig" to assign physical (outer) source 314and destination address to gif interfaces. 315Configuration that uses same address family for inner and outer IP 316header (v4 in v4, or v6 in v6) is dangerous. It is very easy to 317configure interfaces and routing tables to perform infinite level 318of tunneling. Please be warned. 319 320gif can be configured to be ECN-friendly. See 4.5 for ECN-friendliness 321of tunnels, and gif(4) manpage for how to configure. 322 323If you would like to configure an IPv4-in-IPv6 tunnel with gif interface, 324read gif(4) carefully. You will need to remove IPv6 link-local address 325automatically assigned to the gif interface. 326 3271.6 Source Address Selection 328 329Source selection of KAME is scope oriented (there are some exceptions - 330see below). For a given destination, a source IPv6 address is selected 331by the following rule: 332 1. If the source address is explicitly specified by the user 333 (e.g. via the advanced API), the specified address is used. 334 2. If there is an address assigned to the outgoing interface 335 (which is usually determined by looking up the routing table) 336 that has the same scope as the destination address, the address 337 is used. 338 This is the most typical case. 339 3. If there is no address that satisfies the above condition, 340 choose a global address assigned to one of the interfaces 341 on the sending node. 342 4. If there is no address that satisfies the above condition, 343 and destination address is site local scope, 344 choose a site local address assigned to one of the interfaces 345 on the sending node. 346 5. If there is no address that satisfies the above condition, 347 choose the address associated with the routing table 348 entry for the destination. 349 This is the last resort, which may cause scope violation. 350 351For instance, ::1 is selected for ff01::1, fe80:1::200:f8ff:fe01:6317 352for fe80:1::2a0:24ff:feab:839b (note that embedded interface index - 353described in 1.3 - helps us choose the right source address. Those 354embedded indices will not be on the wire). 355If the outgoing interface has multiple address for the scope, 356a source is selected longest match basis (rule 3). Suppose 3573ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317 358are given to the outgoing interface. 3ffe:501:808:1:200:f8ff:fe01:6317 359is chosen as the source for the destination 3ffe:501:800::1. 360 361Note that the above rule is not documented in the IPv6 spec. It is 362considered "up to implementation" item. 363There are some cases where we do not use the above rule. One 364example is connected TCP session, and we use the address kept in tcb 365as the source. 366Another example is source address for Neighbor Advertisement. 367Under the spec (RFC2461 7.2.2) NA's source should be the target 368address of the corresponding NS's target. In this case we follow 369the spec rather than the above longest-match rule. 370 371For new connections (when rule 1 does not apply), deprecated addresses 372(addresses with preferred lifetime = 0) will not be chosen as source address 373if other choises are available. If no other choices are available, 374deprecated address will be used as a last resort. If there are multiple 375choice of deprecated addresses, the above scope rule will be used to choose 376from those deprecated addreses. If you would like to prohibit the use 377of deprecated address for some reason, configure net.inet6.ip6.use_deprecated 378to 0. The issue related to deprecated address is described in RFC2462 5.5.4 379(NOTE: there is some debate underway in IETF ipngwg on how to use 380"deprecated" address). 381 3821.7 Jumbo Payload 383 384KAME supports the Jumbo Payload hop-by-hop option used to send IPv6 385packets with payloads longer than 65,535 octets. But since currently 386KAME does not support any physical interface whose MTU is more than 38765,535, such payloads can be seen only on the loopback interface(i.e. 388lo0). 389 390If you want to try jumbo payloads, you first have to reconfigure the 391kernel so that the MTU of the loopback interface is more than 65,535 392bytes; add the following to the kernel configuration file: 393 options "LARGE_LOMTU" #To test jumbo payload 394and recompile the new kernel. 395 396Then you can test jumbo payloads by the ping6 command with -b and -s 397options. The -b option must be specified to enlarge the size of the 398socket buffer and the -s option specifies the length of the packet, 399which should be more than 65,535. For example, type as follows; 400 % ping6 -b 70000 -s 68000 ::1 401 402The IPv6 specification requires that the Jumbo Payload option must not 403be used in a packet that carries a fragment header. If this condition 404is broken, an ICMPv6 Parameter Problem message must be sent to the 405sender. KAME kernel follows the specification, but you cannot usually 406see an ICMPv6 error caused by this requirement. 407 408If KAME kernel receives an IPv6 packet, it checks the frame length of 409the packet and compares it to the length specified in the payload 410length field of the IPv6 header or in the value of the Jumbo Payload 411option, if any. If the former is shorter than the latter, KAME kernel 412discards the packet and increments the statistics. You can see the 413statistics as output of netstat command with `-s -p ip6' option: 414 % netstat -s -p ip6 415 ip6: 416 (snip) 417 1 with data size < data length 418 419So, KAME kernel does not send an ICMPv6 error unless the erroneous 420packet is an actual Jumbo Payload, that is, its packet size is more 421than 65,535 bytes. As described above, KAME kernel currently does not 422support physical interface with such a huge MTU, so it rarely returns an 423ICMPv6 error. 424 425TCP/UDP over jumbogram is not supported at this moment. This is because 426we have no medium (other than loopback) to test this. Contact us if you 427need this. 428 429IPsec does not work on jumbograms. This is due to some specification twists 430in supporting AH with jumbograms (AH header size influences payload length, 431and this makes it real hard to authenticate inbound packet with jumbo payload 432option as well as AH). 433 434There are fundamental issues in *BSD support for jumbograms. We would like to 435address those, but we need more time to finalize these. To name a few: 436- mbuf pkthdr.len field is typed as "int" in 4.4BSD, so it will not hold 437 jumbogram with len > 2G on 32bit architecture CPUs. If we would like to 438 support jumbogram properly, the field must be expanded to hold 4G + 439 IPv6 header + link-layer header. Therefore, it must be expanded to at least 440 int64_t (u_int32_t is NOT enough). 441- We mistakingly use "int" to hold packet length in many places. We need 442 to convert them into larger integral type. It needs a great care, as we may 443 experience overflow during packet length computation. 444- We mistakingly check for ip6_plen field of IPv6 header for packet payload 445 length in various places. We should be checking mbuf pkthdr.len instead. 446 ip6_input() will perform sanity check on jumbo payload option on input, 447 and we can safely use mbuf pkthdr.len afterwards. 448- TCP code needs a careful update in bunch of places, of course. 449 4501.8 Loop prevention in header processing 451 452IPv6 specification allows arbitrary number of extension headers to 453be placed onto packets. If we implement IPv6 packet processing 454code in the way BSD IPv4 code is implemented, kernel stack may 455overflow due to long function call chain. KAME sys/netinet6 code 456is carefully designed to avoid kernel stack overflow. Because of 457this, KAME sys/netinet6 code defines its own protocol switch 458structure, as "struct ip6protosw" (see netinet6/ip6protosw.h). 459There is no such update to IPv4 part (sys/netinet) for 460compatibility, but small change is added to its pr_input() 461prototype. So "struct ipprotosw" is also defined. 462Because of this, if you receive IPsec-over-IPv4 packet with massive 463number of IPsec headers, kernel stack may blow up. IPsec-over-IPv6 is okay. 464(Off-course, for those all IPsec headers to be processed, each 465such IPsec header must pass each IPsec check. So an anonymous 466attacker won't be able to do such an attack.) 467 4681.9 ICMPv6 469 470After RFC2463 was published, IETF ipngwg has decided to disallow ICMPv6 error 471packet against ICMPv6 redirect, to prevent ICMPv6 storm on a network medium. 472KAME already implements this into the kernel. 473 4741.10 Applications 475 476For userland programming, we support IPv6 socket API as specified in 477RFC2553, RFC2292 and upcoming internet drafts. 478 479TCP/UDP over IPv6 is available and quite stable. You can enjoy "telnet", 480"ftp", "rlogin", "rsh", "ssh", etc. These applications are protocol 481independent. That is, they automatically chooses IPv4 or IPv6 482according to DNS. 483 4841.11 Kernel Internals 485 486 (*) TCP/UDP part is handled differently between operating system platforms. 487 See 1.12 for details. 488 489The current KAME has escaped from the IPv4 netinet logic. While 490ip_forward() calls ip_output(), ip6_forward() directly calls 491if_output() since routers must not divide IPv6 packets into fragments. 492 493ICMPv6 should contain the original packet as long as possible up to 4941280. UDP6/IP6 port unreach, for instance, should contain all 495extension headers and the *unchanged* UDP6 and IP6 headers. 496So, all IP6 functions except TCP never convert network byte 497order into host byte order, to save the original packet. 498 499tcp_input(), udp6_input() and icmp6_input() can't assume that IP6 500header is preceding the transport headers due to extension 501headers. So, in6_cksum() was implemented to handle packets whose IP6 502header and transport header is not continuous. TCP/IP6 nor UDP6/IP6 503header structure don't exist for checksum calculation. 504 505To process IP6 header, extension headers and transport headers easily, 506KAME requires network drivers to store packets in one internal mbuf or 507one or more external mbufs. A typical old driver prepares two 508internal mbufs for 96 - 204 bytes data, however, KAME's reference 509implementation stores it in one external mbuf. 510 511"netstat -s -p ip6" tells you whether or not your driver conforms 512KAME's requirement. In the following example, "cce0" violates the 513requirement. (For more information, refer to Section 2.) 514 515 Mbuf statistics: 516 317 one mbuf 517 two or more mbuf:: 518 lo0 = 8 519 cce0 = 10 520 3282 one ext mbuf 521 0 two or more ext mbuf 522 523Each input function calls IP6_EXTHDR_CHECK in the beginning to check 524if the region between IP6 and its header is 525continuous. IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has 526M_LOOP flag, that is, the packet comes from the loopback 527interface. m_pullup() is never called for packets coming from physical 528network interfaces. 529 530Both IP and IP6 reassemble functions never call m_pullup(). 531 5321.12 IPv4 mapped address and IPv6 wildcard socket 533 534RFC2553 describes IPv4 mapped address (3.7) and special behavior 535of IPv6 wildcard bind socket (3.8). The spec allows you to: 536- Accept IPv4 connections by AF_INET6 wildcard bind socket. 537- Transmit IPv4 packet over AF_INET6 socket by using special form of 538 the address like ::ffff:10.1.1.1. 539but the spec itself is very complicated and does not specify how the 540socket layer should behave. 541Here we call the former one "listening side" and the latter one "initiating 542side", for reference purposes. 543 544Almost all KAME implementations treat tcp/udp port number space separately 545between IPv4 and IPv6. You can perform wildcard bind on both of the adderss 546families, on the same port. 547 548The following table show the behavior of FreeBSD4x. 549 550 listening side initiating side 551 (AF_INET6 wildcard (connetion to ::ffff:10.1.1.1) 552 socket gets IPv4 conn.) 553 --- --- 554FreeBSD4x configurable supported 555 default: enabled 556 557The following sections will give you more details, and how you can 558configure the behavior. 559 560Comments on listening side: 561 562It looks that RFC2553 talks too little on wildcard bind issue, 563especially on the port space issue, failure mode and relationship 564between AF_INET/INET6 wildcard bind. There can be several separate 565interpretation for this RFC which conform to it but behaves differently. 566So, to implement portable application you should assume nothing 567about the behavior in the kernel. Using getaddrinfo() is the safest way. 568Port number space and wildcard bind issues were discussed in detail 569on ipv6imp mailing list, in mid March 1999 and it looks that there's 570no concrete consensus (means, up to implementers). You may want to 571check the mailing list archives. 572 573If a server application would like to accept IPv4 and IPv6 connections, 574there will be two alternatives. 575 576One is using AF_INET and AF_INET6 socket (you'll need two sockets). 577Use getaddrinfo() with AI_PASSIVE into ai_flags, and socket(2) and bind(2) 578to all the addresses returned. 579By opening multiple sockets, you can accept connections onto the socket with 580proper address family. IPv4 connections will be accepted by AF_INET socket, 581and IPv6 connections will be accepted by AF_INET6 socket. 582 583Another way is using one AF_INET6 wildcard bind socket. 584Use getaddrinfo() with AI_PASSIVE into ai_flags and with 585AF_INET6 into ai_family, and set the 1st argument hostname to 586NULL. And socket(2) and bind(2) to the address returned. 587(should be IPv6 unspecified addr) 588You can accept either of IPv4 and IPv6 packet via this one socket. 589 590To support only IPv6 traffic on AF_INET6 wildcard binded socket portably, 591always check the peer address when a connection is made toward 592AF_INET6 listening socket. If the address is IPv4 mapped address, you may 593want to reject the connection. You can check the condition by using 594IN6_IS_ADDR_V4MAPPED() macro. 595To resolv this issue more easily, there is system dependent setsockopt() 596option, IPV6_BINDV6ONLY, used like below. 597 int on; 598 599 setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY, 600 (char *)&on, sizeof (on)) < 0)); 601When this call succeed, then this socket only receive IPv6 packets. 602 603 604Comments on initiating side: 605 606Advise to application implementers: to implement a portable IPv6 application 607(which works on multiple IPv6 kernels), we believe that the following 608is the key to the success: 609- NEVER hardcode AF_INET nor AF_INET6. 610- Use getaddrinfo() and getnameinfo() throughout the system. 611 Never use gethostby*(), getaddrby*(), inet_*() or getipnodeby*(). 612 (To update existing applications to be IPv6 aware easily, 613 sometime getipnodeby*() will be useful. But if possible, try to 614 rewrite the code to use getaddrinfo() and getnameinfo().) 615- If you would like to connect to destination, use getaddrinfo() and try 616 all the destination returned, like telnet does. 617- Some of the IPv6 stack is shipped with buggy getaddrinfo(). Ship a minimal 618 working version with your application and use that as last resort. 619 620If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing 621connection, you will need to use getipnodebyname(). When you would like to 622update your existing appication to be IPv6 aware with minimal effort, 623this approach might be choosed. But please note that it is a temporal 624solution, because getipnodebyname() itself is not recommended as it does 625not handle scoped IPv6 addresses at all. For IPv6 name resolution, 626getaddrinfo() is the preferred API. So you should rewrite your 627application to use getaddrinfo(), when you get the time to do it. 628 629When writing applications that make outgoing connections, story goes much 630simpler if you treat AF_INET and AF_INET6 as totally seaprate address family. 631{set,get}sockopt issue goes simpler, DNS issue will be made simpler. We do 632not recommend you to rely upon IPv4 mapped address. 633 6341.12.1 FreeBSD4x 635 636FreeBSD4x uses shared tcp4/6 code (from sys/netinet/tcp*) and separete 637udp4/6 code. It uses unified inpcb/in6pcb structure. 638 639The platform can be configured to support IPv4 mapped address. 640Kernel configuration is summarized as follows: 641- By default, AF_INET6 socket will grab IPv4 connections in certain condition, 642 and can initiate connection to IPv4 destination embedded in 643 IPv4 mapped IPv6 address. 644- You can disable it on entire system with sysctl like below. 645 sysctl -w net.inet6.ip6.mapped_addr=0 646 6471.12.1.1 FreeBSD4x, listening side 648 649Each socket can be configured to support special AF_INET6 wildcard bind 650(enabled by default). 651You can disable it on each socket basis with setsockopt() like below. 652 int on; 653 654 setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY, 655 (char *)&on, sizeof (on)) < 0)); 656 657Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following 658conditions are satisfied: 659- there's no AF_INET socket that matches the IPv4 connection 660- the AF_INET6 socket is configured to accept IPv4 traffic, i.e. 661 getsockopt(IPV6_BINDV6ONLY) returns 0. 662There's no problem with open/close ordering. 663 6641.12.1.2 FreeBSD4x, initiating side 665 666FreeBSD4x supports outgoing connetion to IPv4 mapped address 667(::ffff:10.1.1.1), if the node is configured to support IPv4 mapped address. 668 6691.13 sockaddr_storage 670 671When RFC2553 was about to be finalized, there was discusson on how struct 672sockaddr_storage members are named. One proposal is to prepend "__" to the 673members (like "__ss_len") as they should not be touched. The other proposal 674was that don't prepend it (like "ss_len") as we need to touch those members 675directly. There was no clear consensus on it. 676 677As a result, RFC2553 defines struct sockaddr_storage as follows: 678 struct sockaddr_storage { 679 u_char __ss_len; /* address length */ 680 u_char __ss_family; /* address family */ 681 /* and bunch of padding */ 682 }; 683On the contrary, XNET draft defines as follows: 684 struct sockaddr_storage { 685 u_char ss_len; /* address length */ 686 u_char ss_family; /* address family */ 687 /* and bunch of padding */ 688 }; 689 690In December 1999, it was agreed that RFC2553bis should pick the latter (XNET) 691definition. 692 693KAME kit prior to December 1999 used RFC2553 definition. KAME kit after 694December 1999 (including December) will conform to XNET definition, 695based on RFC2553bis discusson. 696 697If you look at multiple IPv6 implementations, you will be able to see 698both definitions. As an userland programmer, the most portable way of 699dealing with it is to: 700(1) ensure ss_family and/or ss_len are available on the platform, by using 701 GNU autoconf, 702(2) have -Dss_family=__ss_family to unify all occurences (including header 703 file) into __ss_family, or 704(3) never touch __ss_family. cast to sockaddr * and use sa_family like: 705 struct sockaddr_storage ss; 706 family = ((struct sockaddr *)&ss)->sa_family 707 7082. Network Drivers 709 710KAME requires two items to be added into the standard drivers: 711 712(1) mbuf clustering requirement. In this stable release, we changed 713 MINCLSIZE into MHLEN+1 for all the operating systems in order to make 714 all the drivers behave as we expect. 715 716(2) multicast. If "ifmcstat" yields no multicast group for a 717 interface, that interface has to be patched. 718 719If any of the driver don't support the requirements, then the driver 720can't be used for IPv6 and/or IPsec communication. If you find any 721problem with your card using IPv6/IPsec, then, please report it to 722freebsd-bugs@freebsd.org. 723 724(NOTE: In the past we required all pcmcia drivers to have a call to 725in6_ifattach(). We have no such requirement any more) 726 7273. Translator 728 729We categorize IPv4/IPv6 translator into 4 types. 730 731Translator A --- It is used in the early stage of transition to make 732it possible to establish a connection from an IPv6 host in an IPv6 733island to an IPv4 host in the IPv4 ocean. 734 735Translator B --- It is used in the early stage of transition to make 736it possible to establish a connection from an IPv4 host in the IPv4 737ocean to an IPv6 host in an IPv6 island. 738 739Translator C --- It is used in the late stage of transition to make it 740possible to establish a connection from an IPv4 host in an IPv4 island 741to an IPv6 host in the IPv6 ocean. 742 743Translator D --- It is used in the late stage of transition to make it 744possible to establish a connection from an IPv6 host in the IPv6 ocean 745to an IPv4 host in an IPv4 island. 746 747KAME provides an TCP relay translator for category A. This is called 748"FAITH". We also provide IP header translator for category A. 749(The latter is not yet put into FreeBSD4.x yet.) 750 7513.1 FAITH TCP relay translator 752 753FAITH system uses TCP relay daemon called "faithd" helped by the KAME kernel. 754FAITH will reserve an IPv6 address prefix, and relay TCP connection 755toward that prefix to IPv4 destination. 756 757For example, if the reserved IPv6 prefix is 3ffe:0501:0200:ffff::, and 758the IPv6 destination for TCP connection is 3ffe:0501:0200:ffff::163.221.202.12, 759the connection will be relayed toward IPv4 destination 163.221.202.12. 760 761 destination IPv4 node (163.221.202.12) 762 ^ 763 | IPv4 tcp toward 163.221.202.12 764 FAITH-relay dual stack node 765 ^ 766 | IPv6 TCP toward 3ffe:0501:0200:ffff::163.221.202.12 767 source IPv6 node 768 769faithd must be invoked on FAITH-relay dual stack node. 770 771For more details, consult src/usr.sbin/faithd/README. 772 7733.2 IPv6-to-IPv4 header translator 774 775(to be written) 776 7774. IPsec 778 779IPsec is mainly organized by three components. 780 781(1) Policy Management 782(2) Key Management 783(3) AH and ESP handling 784 7854.1 Policy Management 786 787The kernel implements experimental policy management code. There are two way 788to manage security policy. One is to configure per-socket policy using 789setsockopt(3). In this cases, policy configuration is described in 790ipsec_set_policy(3). The other is to configure kernel packet filter-based 791policy using PF_KEY interface, via setkey(8). 792 793The policy entry is not re-ordered with its 794indexes, so the order of entry when you add is very significant. 795 7964.2 Key Management 797 798The key management code implemented in this kit (sys/netkey) is a 799home-brew PFKEY v2 implementation. This conforms to RFC2367. 800 801The home-brew IKE daemon, "racoon" is included in the kit 802(kame/kame/racoon). 803Basically you'll need to run racoon as daemon, then setup a policy 804to require keys (like ping -P 'out ipsec esp/transport//use'). 805The kernel will contact racoon daemon as necessary to exchange keys. 806 8074.3 AH and ESP handling 808 809IPsec module is implemented as "hooks" to the standard IPv4/IPv6 810processing. When sending a packet, ip{,6}_output() checks if ESP/AH 811processing is required by checking if a matching SPD (Security 812Policy Database) is found. If ESP/AH is needed, 813{esp,ah}{4,6}_output() will be called and mbuf will be updated 814accordingly. When a packet is received, {esp,ah}4_input() will be 815called based on protocol number, i.e. (*inetsw[proto])(). 816{esp,ah}4_input() will decrypt/check authenticity of the packet, 817and strips off daisy-chained header and padding for ESP/AH. It is 818safe to strip off the ESP/AH header on packet reception, since we 819will never use the received packet in "as is" form. 820 821By using ESP/AH, TCP4/6 effective data segment size will be affected by 822extra daisy-chained headers inserted by ESP/AH. Our code takes care of 823the case. 824 825Basic crypto functions can be found in directory "sys/crypto". ESP/AH 826transform are listed in {esp,ah}_core.c with wrapper functions. If you 827wish to add some algorithm, add wrapper function in {esp,ah}_core.c, and 828add your crypto algorithm code into sys/crypto. 829 830Tunnel mode is partially supported in this release, with the following 831restrictions: 832- IPsec tunnel is not combined with GIF generic tunneling interface. 833 It needs a great care because we may create an infinite loop between 834 ip_output() and tunnelifp->if_output(). Opinion varies if it is better 835 to unify them, or not. 836- MTU and Don't Fragment bit (IPv4) considerations need more checking, but 837 basically works fine. 838- Authentication model for AH tunnel must be revisited. We'll need to 839 improve the policy management engine, eventually. 840 8414.4 Conformance to RFCs and IDs 842 843The IPsec code in the kernel conforms (or, tries to conform) to the 844following standards: 845 "old IPsec" specification documented in rfc182[5-9].txt 846 "new IPsec" specification documented in rfc240[1-6].txt, rfc241[01].txt, 847 rfc2451.txt and draft-mcdonald-simple-ipsec-api-01.txt (draft expired, 848 but you can take from ftp://ftp.kame.net/pub/internet-drafts/). 849 (NOTE: IKE specifications, rfc241[7-9].txt are implemented in userland, 850 as "racoon" IKE daemon) 851 852Currently supported algorithms are: 853 old IPsec AH 854 null crypto checksum (no document, just for debugging) 855 keyed MD5 with 128bit crypto checksum (rfc1828.txt) 856 keyed SHA1 with 128bit crypto checksum (no document) 857 HMAC MD5 with 128bit crypto checksum (rfc2085.txt) 858 HMAC SHA1 with 128bit crypto checksum (no document) 859 old IPsec ESP 860 null encryption (no document, similar to rfc2410.txt) 861 DES-CBC mode (rfc1829.txt) 862 new IPsec AH 863 null crypto checksum (no document, just for debugging) 864 keyed MD5 with 96bit crypto checksum (no document) 865 keyed SHA1 with 96bit crypto checksum (no document) 866 HMAC MD5 with 96bit crypto checksum (rfc2403.txt 867 HMAC SHA1 with 96bit crypto checksum (rfc2404.txt) 868 new IPsec ESP 869 null encryption (rfc2410.txt) 870 DES-CBC with derived IV 871 (draft-ietf-ipsec-ciph-des-derived-01.txt, draft expired) 872 DES-CBC with explicit IV (rfc2405.txt) 873 3DES-CBC with explicit IV (rfc2451.txt) 874 BLOWFISH CBC (rfc2451.txt) 875 CAST128 CBC (rfc2451.txt) 876 RC5 CBC (rfc2451.txt) 877 each of the above can be combined with: 878 ESP authentication with HMAC-MD5(96bit) 879 ESP authentication with HMAC-SHA1(96bit) 880 881The following algorithms are NOT supported: 882 old IPsec AH 883 HMAC MD5 with 128bit crypto checksum + 64bit replay prevention 884 (rfc2085.txt) 885 keyed SHA1 with 160bit crypto checksum + 32bit padding (rfc1852.txt) 886 887IPsec (in kernel) and IKE (in userland as "racoon") has been tested 888at several interoperability test events, and it is known to interoperate 889with many other implementations well. Also, KAME IPsec has quite wide 890coverage for IPsec crypto algorithms documented in RFC (we cover 891algorithms without intellectual property issues only). 892 8934.5 ECN consideration on IPsec tunnels 894 895KAME IPsec implements ECN-friendly IPsec tunnel, described in 896draft-ipsec-ecn-00.txt. 897Normal IPsec tunnel is described in RFC2401. On encapsulation, 898IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner 899IP header to outer IP header. On decapsulation outer IP header 900will be simply dropped. The decapsulation rule is not compatible 901with ECN, since ECN bit on the outer IP TOS/traffic class field will be 902lost. 903To make IPsec tunnel ECN-friendly, we should modify encapsulation 904and decapsulation procedure. This is described in 905http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt, chapter 3. 906 907KAME IPsec tunnel implementation can give you three behaviors, by setting 908net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some value: 909- RFC2401: no consideration for ECN (sysctl value -1) 910- ECN forbidden (sysctl value 0) 911- ECN allowed (sysctl value 1) 912Note that the behavior is configurable in per-node manner, not per-SA manner 913(draft-ipsec-ecn-00 wants per-SA configuration, but it looks too much for me). 914 915The behavior is summarized as follows (see source code for more detail): 916 917 encapsulate decapsulate 918 --- --- 919RFC2401 copy all TOS bits drop TOS bits on outer 920 from inner to outer. (use inner TOS bits as is) 921 922ECN forbidden copy TOS bits except for ECN drop TOS bits on outer 923 (masked with 0xfc) from inner (use inner TOS bits as is) 924 to outer. set ECN bits to 0. 925 926ECN allowed copy TOS bits except for ECN use inner TOS bits with some 927 CE (masked with 0xfe) from change. if outer ECN CE bit 928 inner to outer. is 1, enable ECN CE bit on 929 set ECN CE bit to 0. the inner. 930 931General strategy for configuration is as follows: 932- if both IPsec tunnel endpoint are capable of ECN-friendly behavior, 933 you'd better configure both end to "ECN allowed" (sysctl value 1). 934- if the other end is very strict about TOS bit, use "RFC2401" 935 (sysctl value -1). 936- in other cases, use "ECN forbidden" (sysctl value 0). 937The default behavior is "ECN forbidden" (sysctl value 0). 938 939For more information, please refer to: 940 http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt 941 RFC2481 (Explicit Congestion Notification) 942 KAME sys/netinet6/{ah,esp}_input.c 943 944(Thanks goes to Kenjiro Cho <kjc@csl.sony.co.jp> for detailed analysis) 945 9464.6 Interoperability 947 948Here are (some of) platforms we have tested IPsec/IKE interoperability 949in the past. Note that both ends (KAME and others) may have modified their 950implementation, so use the following list just for reference purposes. 951 Altiga, Ashley-laurent (vpcom.com), Data Fellows (F-Secure), Ericsson 952 ACC, FreeS/WAN, HITACHI, IBM AIX, IIJ, Intel, Microsoft WinNT, NIST 953 (linux IPsec + plutoplus), Netscreen, OpenBSD, RedCreek, Routerware, 954 SSH, Secure Computing, Soliton, Toshiba, VPNet, Yamaha RT100i 955 9565. IPComp 957(not yet put into FreeBSD4.x, due to inflate related changes in 4.x.) 958 959IPComp stands for IP payload compression protocol. This is aimed for 960payload compression, not the header compression like PPP VJ compression. 961This may be useful when you are using slow serial link (say, cell phone) 962with powerful CPU (well, recent notebook PCs are really powerful...). 963The protocol design of IPComp is very similar to IPsec. 964 965KAME implements the following specifications: 966- RFC2393: IP Payload Compression Protocol (IPComp) 967- RFC2394: IP Payload Compression Using DEFLATE 968 969Here are some points to be noted: 970- IPComp is treated as part of IPsec protocol suite, and SPI and 971 CPI space is unified. Spec says that there's no relationship 972 between two so they are assumed to be separate. 973- IPComp association (IPCA) is kept in SAD. 974- It is possible to use well-known CPI (CPI=2 for DEFLATE for example), 975 for outbound/inbound packet, but for indexing purposes one element from 976 SPI/CPI space will be occupied anyway. 977- pfkey is modified to support IPComp. However, there's no official 978 SA type number assignment yet. Portability with other IPComp 979 stack is questionable (anyway, who else implement IPComp on UN*X?). 980- Spec says that IPComp output processing must be performed before IPsec 981 output processing, to achieve better compression ratio and "stir" data 982 stream before encryption. However, with manual SPD setting, you are able to 983 violate the ordering requirement (KAME code is too generic, maybe). 984- Though MTU can be significantly decreased by using IPComp, no special 985 consideration is made about path MTU (spec talks nothing about MTU 986 consideration). IPComp is designed for serial links, not ethernet-like 987 medium, it seems. 988- You can change compression ratio on outbound packet, by changing 989 deflate_policy in sys/netinet6/ipcomp_core.c. You can also change history 990 buffer size by changing deflate_window in the same source code. 991 (should it be sysctl accessible? or per-SAD configurable?) 992- Tunnel mode IPComp is not working right. KAME box can generate tunnelled 993 IPComp packet, however, cannot accept tunneled IPComp packet. 994 9956. ALTQ 996 (not yet put into FreeBSD4.x) 997 998 <end of IMPLEMENTATION> 999