IMPLEMENTATION revision 108533
11541Srgrimes# NOTE: this is from original KAME distribution. 21541Srgrimes# Some portion of this document is not applicable to the code merged into 31541Srgrimes# FreeBSD-current (for example, section 5). 41541Srgrimes 51541Srgrimes Implementation Note 61541Srgrimes 71541Srgrimes KAME Project 81541Srgrimes http://www.kame.net/ 91541Srgrimes $KAME: IMPLEMENTATION,v 1.216 2001/05/25 07:43:01 jinmei Exp $ 101541Srgrimes $FreeBSD: head/share/doc/IPv6/IMPLEMENTATION 108533 2003-01-01 18:49:04Z schweikh $ 111541Srgrimes 121541Srgrimes1. IPv6 131541Srgrimes 141541Srgrimes1.1 Conformance 151541Srgrimes 161541SrgrimesThe KAME kit conforms, or tries to conform, to the latest set of IPv6 171541Srgrimesspecifications. For future reference we list some of the relevant documents 181541Srgrimesbelow (NOTE: this is not a complete list - this is too hard to maintain...). 191541SrgrimesFor details please refer to specific chapter in the document, RFCs, manpages 201541Srgrimescome with KAME, or comments in the source code. 211541Srgrimes 221541SrgrimesConformance tests have been performed on past and latest KAME STABLE kit, 231541Srgrimesat TAHI project. Results can be viewed at http://www.tahi.org/report/KAME/. 241541SrgrimesWe also attended Univ. of New Hampshire IOL tests (http://www.iol.unh.edu/) 251541Srgrimesin the past, with our past snapshots. 261541Srgrimes 271541SrgrimesRFC1639: FTP Operation Over Big Address Records (FOOBAR) 281541Srgrimes * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428, 291541Srgrimes then RFC1639 if failed. 301541SrgrimesRFC1886: DNS Extensions to support IPv6 311541SrgrimesRFC1933: (see RFC2893) 321541SrgrimesRFC1981: Path MTU Discovery for IPv6 331541SrgrimesRFC2080: RIPng for IPv6 341541Srgrimes * KAME-supplied route6d, bgpd and hroute6d support this. 351541SrgrimesRFC2283: Multiprotocol Extensions for BGP-4 361541Srgrimes * so-called "BGP4+". 37116182Sobrien * KAME-supplied bgpd supports this. 38116182SobrienRFC2292: Advanced Sockets API for IPv6 39116182Sobrien * For supported library functions/kernel APIs, see sys/netinet6/ADVAPI. 40170075SemasteRFC2362: Protocol Independent Multicast-Sparse Mode (PIM-SM) 41150968Sglebius * RFC2362 defines the packet formats and the protcol of PIM-SM. 42147565SpeterRFC2373: IPv6 Addressing Architecture 4344666Sphk * KAME supports node required addresses, and conforms to the scope 44116874Ssmkelly requirement. 4544666SphkRFC2374: An IPv6 Aggregatable Global Unicast Address Format 461541Srgrimes * KAME supports 64-bit length of Interface ID. 471541SrgrimesRFC2375: IPv6 Multicast Address Assignments 481541Srgrimes * Userland applications use the well-known addresses assigned in the RFC. 49131927SmarcelRFC2428: FTP Extensions for IPv6 and NATs 501541Srgrimes * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428, 5174914Sjhb then RFC1639 if failed. 5284812SjhbRFC2460: IPv6 specification 5367365SjhbRFC2461: Neighbor discovery for IPv6 541541Srgrimes * See 1.2 in this document for details. 55111024SjeffRFC2462: IPv6 Stateless Address Autoconfiguration 561541Srgrimes * See 1.4 in this document for details. 57104964SjeffRFC2463: ICMPv6 for IPv6 specification 583308Sphk * See 1.8 in this document for details. 5976078SjhbRFC2464: Transmission of IPv6 Packets over Ethernet Networks 602320SdgRFC2465: MIB for IPv6: Textual Conventions and General Group 6112662Sdg * Necessary statistics are gathered by the kernel. Actual IPv6 MIB 6212662Sdg support is provided as patchkit for ucd-snmp. 633308SphkRFC2466: MIB for IPv6: ICMPv6 group 6467551Sjhb * Necessary statistics are gathered by the kernel. Actual IPv6 MIB 6567551Sjhb support is provided as patchkit for ucd-snmp. 66114216SkanRFC2467: Transmission of IPv6 Packets over FDDI Networks 67102926SphkRFC2472: IPv6 over PPP 681541SrgrimesRFC2492: IPv6 over ATM Networks 691541Srgrimes * only PVC is supported. 701541SrgrimesRFC2497: Transmission of IPv6 packet over ARCnet Networks 711541SrgrimesRFC2545: Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing 721541SrgrimesRFC2553: Basic Socket Interface Extensions for IPv6 73146799Sjkoshy * IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind 74146799Sjkoshy socket (3.8) are, 75146799Sjkoshy - supported and turned on by default on KAME/FreeBSD[34]x 76146799Sjkoshy and KAME/BSDI4, 7787902Sluigi - supported but turned off by default on KAME/NetBSD, 7887902Sluigi - not supported on KAME/FreeBSD228, KAME/OpenBSD and KAME/BSDI3. 7987902Sluigi see 1.12 in this document for details. 8031639SfsmpRFC2671: Extension Mechanisms for DNS (EDNS0) 8192723Salfred * see USAGE for how to use it. 8210358Sjulian * not supported on kame/freebsd4 and kame/bsdi4. 8310358SjulianRFC2673: Binary Labels in the Domain Name System 84169803Sjeff * KAME/bsdi4 supports A6, DNAME and binary label to some extent. 85170468Sattilio * KAME apps/bind8 repository has resolver library with partial A6, DNAME 86169803Sjeff and binary label support. 87147692SpeterRFC2675: IPv6 Jumbograms 88147692Speter * See 1.7 in this document for details. 89147692SpeterRFC2710: Multicast Listener Discovery for IPv6 90147692SpeterRFC2711: IPv6 router alert option 91174070SpeterRFC2732: Format for Literal IPv6 Addresses in URL's 92147703Sps * The spec is implemented in programs that handle URLs 93147692Speter (like freebsd ftpio(3) and fetch(1), or netbsd ftp(1)) 94147692SpeterRFC2766: Network Address Translation - Protocol Translation (NAT-PT) 95174070Speter * Section 4.2 is implemented by totd (see ports/totd, or pkgsrc/net/totd). 96157822SjhbRFC2874: DNS Extensions to Support IPv6 Address Aggregation and Renumbering 97174070Speter * KAME/bsdi4 supports A6, DNAME and binary label to some extent. 98174070Speter * KAME apps/bind8 repository has resolver library with partial A6, DNAME 99147703Sps and binary label support. 100147692SpeterRFC2893: Transition Mechanisms for IPv6 Hosts and Routers 101147692Speter * IPv4 compatible address is not supported. 102147692Speter * automatic tunneling (4.3) is not supported. 103147692Speter * "gif" interface implements IPv[46]-over-IPv[46] tunnel in a generic way, 104147692Speter and it covers "configured tunnel" described in the spec. 105147692Speter See 1.5 in this document for details. 106147692SpeterRFC2894: Router renumbering for IPv6 107147692SpeterRFC3041: Privacy Extensions for Stateless Address Autoconfiguration in IPv6 108147692SpeterRFC3056: Connection of IPv6 Domains via IPv4 Clouds 109147692Speter * So-called "6to4". 110147692Speter * "stf" interface implements it. Be sure to read 111147692Speter draft-itojun-ipv6-transition-abuse-01.txt 112147692Speter below before configuring it, there can be security issues. 113147692Speterdraft-ietf-ipngwg-icmp-name-lookups-07: IPv6 Name Lookups Through ICMP 114147692Speterdraft-ietf-dhc-dhcpv6-15.txt: DHCPv6 115157822Sjhbdraft-ietf-dhc-dhcpv6exts-12.txt: Extensions for DHCPv6 116147692Speter * kame/dhcp6 has test implementation, which will not be compiled in 117147692Speter default compilation. 118174070Speter * 15/12 drafts are not explicit about padding and string termination. 119174070Speter at IETF48, the author confirmed that there's no padding/termination 120174070Speter (and extensions can appear unaligned). our code follows the comment. 121174070Speterdraft-itojun-ipv6-tcp-to-anycast-00.txt: 122174070Speter Disconnecting TCP connection toward IPv6 anycast address 123174070Speterdraft-ietf-ipngwg-rfc2553bis-03.txt: 124174070Speter Basic Socket Interface Extensions for IPv6 (revised) 125174072Srwatsondraft-ietf-ipngwg-rfc2292bis-02.txt: 126174070Speter Advanced Sockets API for IPv6 (revised) 127174070Speter * Some of the updates in the draft are not implemented yet. See 128174070Speter TODO.2292bis for more details. 129174072Srwatsondraft-ietf-mobileip-ipv6-13.txt: Mobility Support in IPv6 130174070Speter * See section 6. 131174070Speterdraft-ietf-ngtrans-tcpudp-relay-04.txt: 132174070Speter An IPv6-to-IPv4 transport relay translator 133174070Speter * FAITH tcp relay translator (faithd) implements this. See 3.1 for more 134174070Speter details. 135174070Speterdraft-ietf-ipngwg-router-selection-01.txt: 136174070Speter Default Router Preferences and More-Specific Routes 137174070Speter * router-side only. 138174070Speterdraft-ietf-ipngwg-scoping-arch-02.txt: 139174070Speter The architecture, text representation, and usage of IPv6 140174070Speter scoped addresses. 141174070Speter * some part of the documentation (especially about the routing 142174070Speter model) is not supported yet. 143174070Speterdraft-ietf-pim-sm-v2-new-02.txt 144174070Speter A revised version of RFC2362, which includes the IPv6 specific 145174070Speter packet format and protocol descriptions. 146174070Speterdraft-ietf-dnsext-mdns-00.txt: Multicast DNS 147174070Speter * kame/mdnsd has test implementation, which will not be built in 148174070Speter default compilation. The draft will experience a major change in the 149174070Speter near future, so don't rely upon it. 150174070Speterdraft-itojun-ipv6-transition-abuse-02.txt: 151174070Speter Possible abuse against IPv6 transition technologies (expired) 152174070Speter * KAME does not implement RFC1933/2893 automatic tunnel. 153174070Speter * "stf" interface implements some address filters. Refer to stf(4) 154174070Speter for details. Since there's no way to make 6to4 interface 100% secure, 155174070Speter we do not include "stf" interface into GENERIC.v6 compilation. 156174070Speter * kame/openbsd completely disables IPv4 mapped address support. 157174070Speter * kame/netbsd makes IPv4 mapped address support off by default. 158174070Speter * See section 1.12.6 and 1.14 for more details. 159174070Speterdraft-itojun-ipv6-tclass-api-02.txt: Socket API for IPv6 traffic class field 160174070Speterdraft-itojun-ipv6-flowlabel-api-01.txt: Socket API for IPv6 flow label field 161174070Speter * no consideration is made against the use of routing headers and such. 162174070Speter 163174070Speter1.2 Neighbor Discovery 164174070Speter 165174070SpeterNeighbor Discovery is fairly stable. Currently Address Resolution, 166174070SpeterDuplicated Address Detection, and Neighbor Unreachability Detection 167174070Speterare supported. In the near future we will be adding Unsolicited Neighbor 168174070SpeterAdvertisement transmission command as admin tool. 169174070Speter 170174070SpeterDuplicated Address Detection (DAD) will be performed when an IPv6 address 171174070Speteris assigned to a network interface, or the network interface is enabled 172174070Speter(ifconfig up). It is documented in RFC2462 5.4. 173174070SpeterIf DAD fails, the address will be marked "duplicated" and message will be 174174070Spetergenerated to syslog (and usually to console). The "duplicated" mark 175174070Spetercan be checked with ifconfig. It is administrators' responsibility to check 176174070Speterfor and recover from DAD failures. We may try to improve failure recovery 177174070Speterin future KAME code. 178174070SpeterDAD procedure may not be effective on certain network interfaces/drivers. 179126383SphkIf a network driver needs long initialization time (with wireless network 180126383Sphkinterfaces this situation is popular), and the driver mistakingly raises 181116874SsmkellyIFF_RUNNING before the driver becomes ready, DAD code will try to transmit 182126383SphkDAD probes to not-really-ready network driver and the packet will not go out 183116874Ssmkellyfrom the interface. In such cases, network drivers should be corrected. 184126383Sphk 185126383SphkSome of network drivers loop multicast packets back to themselves, 186126383Sphkeven if instructed not to do so (especially in promiscuous mode). 187116874SsmkellyIn such cases DAD may fail, because DAD engine sees inbound NS packet 1881541Srgrimes(actually from the node itself) and considers it as a sign of duplicate. 1891541SrgrimesIn this case, drivers should be corrected to honor IFF_SIMPLEX behavior. 1901541SrgrimesFor example, you may need to check source MAC address on an inbound packet, 19134618Sphkand reject it if it is from the node itself. 19234618SphkYou may also want to look at #if condition marked "heuristics" in 19333690Sphksys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note that the code 19434618Sphkfragment in "heuristics" section is not spec conformant). 19534618Sphk 19633690SphkNeighbor Discovery specification (RFC2461) does not talk about neighbor 19734618Sphkcache handling in the following cases: 19834618Sphk(1) when there was no neighbor cache entry, node received unsolicited 19934618Sphk RS/NS/NA/redirect packet without link-layer address 20034618Sphk(2) neighbor cache handling on medium without link-layer address 2011541Srgrimes (we need a neighbor cache entry for IsRouter bit) 2021541SrgrimesFor (1), we implemented workaround based on discussions on IETF ipngwg mailing 20334618Sphklist. For more details, see the comments in the source code and email 20434618Sphkthread started from (IPng 7155), dated Feb 6 1999. 20534618Sphk 20634618SphkIPv6 on-link determination rule (RFC2461) is quite different from assumptions 20734618Sphkin BSD IPv4 network code. To implement behavior in RFC2461 section 5.2 2081541Srgrimes(when default router list is empty), the kernel needs to know the default 20934618Sphkoutgoing interface. To configure the default outgoing interface, use 21034618Sphkcommands like "ndp -I de0" as root. Note that the spec misuse the word 2111541Srgrimes"host" and "node" in several places in the section. 21234618Sphk 21334618SphkTo avoid possible DoS attacks and infinite loops, KAME stack will accept 21434618Sphkonly 10 options on ND packet. Therefore, if you have 20 prefix options 21533690Sphkattached to RA, only the first 10 prefixes will be recognized. 21633690SphkIf this troubles you, please contact KAME team and/or modify 21733690Sphknd6_maxndopt in sys/netinet6/nd6.c. If there are high demands we may 2181541Srgrimesprovide sysctl knob for the variable. 2191541Srgrimes 2201541SrgrimesProxy Neighbor Advertisement support is implemented in the kernel. 2211541SrgrimesFor instance, you can configure it by using the following command: 222110296Sjake # ndp -s fe80::1234%ne0 0:1:2:3:4:5 proxy 2231541Srgrimeswhere ne0 is the interface which attaches to the same link as the 224110296Sjakeproxy target. 2251541SrgrimesThere are certain limitations, though: 2261541Srgrimes- It does not send unsolicited multicast NA on configuration. This is MAY 2271541Srgrimes behavior in RFC2461. 2281541Srgrimes- It does not add random delay before transmission of solicited NA. This is 22910358Sjulian SHOULD behavior in RFC2461. 23010358Sjulian- We cannot configure proxy NDP for off-link address. The target address for 23112569Sbde proxying must be link-local address, or must be in prefixes configured to 23212569Sbde node which does proxy NDP. 2331541Srgrimes- RFC2461 is unclear about if it is legal for a host to perform proxy ND. 2341541Srgrimes We do not prohibit hosts from doing proxy ND, but there will be very limited 2351541Srgrimes use in it. 2361541Srgrimes 2371541SrgrimesStarting mid March 2000, we support Neighbor Unreachability Detection (NUD) 2381541Srgrimeson p2p interfaces, including tunnel interfaces (gif). NUD is turned on by 2391541Srgrimesdefault. Before March 2000 KAME stack did not perform NUD on p2p interfaces. 240169906SrwatsonIf the change raises any interoperability issues, you can turn off/on NUD 2411541Srgrimesby per-interface basis. Use "ndp -i interface -nud" to turn it off. 2421541SrgrimesConsult ndp(8) for details. 2431541Srgrimes 2441541SrgrimesRFC2461 specifies upper-layer reachability confirmation hint. Whenever 2451541Srgrimesupper-layer reachability confirmation hint comes, ND process can use it 2461541Srgrimesto optimize neighbor discovery process - ND process can omit real ND exchange 2471541Srgrimesand keep the neighbor cache state in REACHABLE. 2481541SrgrimesWe currently have two sources for hints: (1) setsockopt(IPV6_REACHCONF) 2491541Srgrimesdefined by 2292bis API, and (2) hints from tcp_input. 250126383SphkIt is questionable if they are really trustworthy. For example, a rogue 251126383Sphkuserland program can use IPV6_REACHCONF to confuse ND process. Neighbor 252126383Sphkcache is a system-wide information pool, and it is bad to allow single process 2531541Srgrimesto affect others. Also, tcp_input can be hosed by hijack attempts. It is 2541541Srgrimeswrong to allow hijack attempts to affect ND process. 2551541SrgrimesStarting June 2000, ND code has a protection mechanism against incorrect 256110296Sjakeupper-layer reachability confirmation. ND code counts subsequent upper-layer 257153666Sjhbhints. If the number of hints reaches maximum, ND code will ignore further 258110296Sjakeupper-layer hints and run real ND process to confirm reachability to the peer. 25976078Sjhbsysctl net.inet6.icmp6.nd6_maxnudhint defines maximum # of subsequent 26076078Sjhbupper-layer hints to be accepted. 261153666Sjhb(from April 2000 to June 2000, we rejected setsockopt(IPV6_REACHCONF) from 26276078Sjhbnon-root process - after local discussion, it looks that hints are not 26376078Sjhbthat trustworthy even if they are from privileged processes) 264110296Sjake 26583366SjulianIf inbound ND packets carry invalid values, the KAME kernel will 266172207Sjeffdrop these packet and increment statistics variable. See 26776078Sjhb"netstat -sn", icmp6 section. For detailed debugging session, you can 26876078Sjhbturn on syslog output from the kernel on errors, by turning on sysctl MIB 26976078Sjhbnet.inet6.icmp6.nd6_debug. nd6_debug can be turned on at bootstrap 27076078Sjhbtime, by defining ND6_DEBUG kernel compilation option (so you can 271163709Sjbdebug behavior during bootstrap). nd6_debug configuration should 272172207Sjeffonly be used for test/debug purposes - for production environment, 273163709Sjbnd6_debug must be set to 0. If you leave it to 1, malicious parties 274170297Sjeffcan inject broken packet and fill up /var/log partition. 275170297Sjeff 276172207Sjeff1.3 Scope Zone Index 277172207Sjeff 278170297SjeffIPv6 uses scoped addresses. It is therefore very important to 279163709Sjbspecify the scope zone index (link index for a link-local address, or 280170297Sjeffsite index for a site-local address) with an IPv6 address. Without a 281170297Sjeffzone index, a scoped IPv6 address is ambiguous to the kernel, and 282172207Sjeffthe kernel would not be able to determine the outbound link for a 283172207Sjeffpacket to the scoped address. KAME code tries to address the issue in 284170297Sjeffseveral ways. 285170297Sjeff 286170297SjeffThe entire architecture of scoped addresses is documented in 287170297Sjeffdraft-ietf-ipngwg-scoping-arch-xx.txt. One non-trivial point of the 288172207Sjeffarchitecture is that the link scope is (theoretically) larger than the 289170297Sjeffinterface scope. That is, two different interfaces can belong to a 290146799Sjkoshysame single link. However, in a normal operation, we can assume that 291146799Sjkoshythere is 1-to-1 relationship between links and interfaces. In 292146799Sjkoshyother words, we can usually put links and interfaces in the same scope 293146799Sjkoshytype. The current KAME implementation assumes the 1-to-1 294146799Sjkoshyrelationship. In particular, we use interface names such as "ne1" as 29576078Sjhbunique link identifiers. This would be much more human-readable and 29676078Sjhbintuitive than numeric identifiers, but please keep your mind on the 29776078Sjhbtheoretical difference between links and interfaces. 2981541Srgrimes 2991541SrgrimesSite-local addresses are very vaguely defined in the specs, and both 3001541Srgrimesthe specification and the KAME code need tons of improvements to 301153666Sjhbenable its actual use. For example, it is still very unclear how we 3021541Srgrimesdefine a site, or how we resolve host names in a site. There is work 30368889Sjakeunderway to define behavior of routers at site border, but, we have 3041541Srgrimesalmost no code for site boundary node support (both forwarding nor 305153666Sjhbrouting) and we bet almost noone has. We recommend, at this moment, 3061541Srgrimesyou to use global addresses for experiments - there are way too many 307102926Sphkpitfalls if you use site-local addresses. 3081541Srgrimes 3091541Srgrimes1.3.1 Kernel internal 31076078Sjhb 31176078SjhbIn the kernel, the link index for a link-local scope address is 3121541Srgrimesembedded into the 2nd 16bit-word (the 3rd and 4th bytes) in the IPv6 313110296Sjakeaddress. 314153666SjhbFor example, you may see something like: 315153666Sjhb fe80:1::200:f8ff:fe01:6317 316110296Sjakein the routing table and the interface address structure (struct 3171541Srgrimesin6_ifaddr). The address above is a link-local unicast address which 31887902Sluigibelongs to a network link whose link identifier is 1 (note that it 31990550Sluigieqauls to the interface index by the assumption of our 32087902Sluigiimplementation). The embedded index enables us to identify IPv6 3212858Swollmanlink-local addresses over multiple links effectively and with only a 32234618Sphklittle code change. 32334618Sphk 32434618Sphk1.3.2 Interaction with API 32534618Sphk 32686423SjhbThere are several candidates of API to deal with scoped addresses 32768889Sjakewithout ambiguity. 328159598Sdelphij 32968889SjakeThe IPV6_PKTINFO ancillary data type or socket option defined in the 33034618Sphkadvanced API (RFC2292 or draft-ietf-ipngwg-rfc2292bis-xx) can specify 33134618Sphkthe outgoing interface of a packet. Similarly, the IPV6_PKTINFO or 33286423SjhbIPV6_RECVPKTINFO socket options tell kernel to pass the incoming 33368889Sjakeinterface to user applications. 33468889Sjake 335170297SjeffThese options are enough to disambiguate scoped addresses of an 336170297Sjeffincoming packet, because we can uniquely identify the corresponding 33768889Sjakezone of the scoped address(es) by the incoming interface. However, 33868889Sjakethey are too strong for outgoing packets. For example, consider a 33988900Sjhbmulti-sited node and suppose that more than one interface of the node 340116874Ssmkellybelongs to a same site. When we want to send a packet to the site, 341126383Sphkwe can only specify one of the interfaces for the outgoing packet with 342126383Sphkthese options; we cannot just say "send the packet to (one of the 343116874Ssmkellyinterfaces of) the site." 344126383Sphk 3451541SrgrimesAnother kind of candidates is to use the sin6_scope_id member in the 3461541Srgrimessockaddr_in6 structure, defined in RFC2553 and 3471541Srgrimesdraft-ietf-ipngwg-rfc2553bis-xx.txt. The KAME kernel interprets the 34834961Sphksin6_scope_id field properly in order to disambiguate scoped 3491541Srgrimesaddresses. For example, if an application passes a sockaddr_in6 3501541Srgrimesstructure that has a non-zero sin6_scope_id value to the sendto(2) 35134961Sphksystem call, the kernel should send the packet to the appropriate zone 3521541Srgrimesaccording to the sin6_scope_id field. Similarly, when the source or 3531541Srgrimesthe destination address of an incoming packet is a scoped one, the 3545081Sbdekernel should detect the correct zone identifier based on the address 3555081Sbdeand the receiving interface, fill the identifier in the sin6_scope_id 3561541Srgrimesfield of a sockaddr_in6 structure, and then pass the packet to an 3571541Srgrimesapplication via the recvfrom(2) system call, etc. 3585081Sbde 3595081SbdeHowever, the semantics of the sin6_scope_id is still vague and on the 3605081Sbdeway to standardization. Additionally, not so many operating systems 3615081Sbdesupport the behavior above at this moment. 3625081Sbde 3635081SbdeIn summary, 3641541Srgrimes- If your target system is limited to KAME based ones (i.e. BSD 3655081Sbde variants and KAME snaps), use the sin6_scope_id field assuming the 3665081Sbde kernel behavior described above. 3675081Sbde- Otherwise, (i.e. if your program should be portable on other systems 3685081Sbde than BSDs) 3695081Sbde + Use the advanced API to disambiguate scoped addresses of incoming 3705081Sbde packets. 3715081Sbde + To disambiguate scoped addresses of outgoing packets, 3725081Sbde * if it is okay to just specify the outgoing interface, use the 3735081Sbde advanced API. This would be the case, for example, when you 3745081Sbde should only consider link-local addresses and your system 3755081Sbde assumes 1-to-1 relationship between links and interfaces. 3761541Srgrimes * otherwise, sorry but you lose. Please rush the IETF IPv6 37734961Sphk community into standardizing the semantics of the sin6_scope_id 37834961Sphk field. 3795081Sbde 3805081SbdeRouting daemons and configuration programs, like route6d and ifconfig, 3815081Sbdewill need to manipulate the "embedded" zone index. These programs use 3825081Sbderouting sockets and ioctls (like SIOCGIFADDR_IN6) and the kernel API 3835081Sbdewill return IPv6 addresses with the 2nd 16bit-word filled in. The 3845081SbdeAPIs are for manipulating kernel internal structure. Programs that 38534618Sphkuse these APIs have to be prepared about differences in kernels 38633690Sphkanyway. 38733690Sphk 38833690Sphkgetaddrinfo(3) and getnameinfo(3) support an extended numeric IPv6 38934961Sphksyntax, as documented in draft-ietf-ipngwg-rfc2553bis-xx.txt. You can 3905081Sbdespecify the outgoing link, by using the name of the outgoing interface 3915081Sbdeas the link, like "fe80::1%ne0" (again, note that we assume there is 3925081Sbde1-to-1 relationship between links and interfaces.) This way you will 3935081Sbdebe able to specify a link-local scoped address without much trouble. 3945081Sbde 3955081SbdeOther APIs like inet_pton(3) and inet_ntop(3) are inherently 3965081Sbdeunfriendly with scoped addresses, since they are unable to annotate 3975081Sbdeaddresses with zone identifier. 3985081Sbde 3991541Srgrimes1.3.3 Interaction with users (command line) 4005081Sbde 4015081SbdeMost of user applications now support the extended numeric IPv6 4025081Sbdesyntax. In this case, you can specify outgoing link, by using the name 40340012Salexof the outgoing interface like "fe80::1%ne0" (sorry for the duplicated 4041541Srgrimesnotice, but please recall again that we assume 1-to-1 relationship 4051541Srgrimesbetween links and interfaces). This is even the case for some 4061541Srgrimesmanagement tools such as route(8) or ndp(8). For example, to install 4071541Srgrimesthe IPv6 default route by hand, you can type like 4081541Srgrimes # route add -inet6 default fe80::9876:5432:1234:abcd%ne0 4091541Srgrimes(Although we suggest you to run dynamic routing instead of static 4101541Srgrimesroutes, in order to avoid configuration mistakes.) 4111541Srgrimes 4121541SrgrimesSome applications have command line options for specifying an 4131541Srgrimesappropriate zone of a scoped address (like "ping6 -I ne0 ff02::1" to 4141541Srgrimesspecify the outgoing interface). However, you can't always expect such 4151541Srgrimesoptions. Thus, we recommend you to use the extended format described 4161541Srgrimesabove. 417113874Sjhb 418113874SjhbIn any case, when you specify a scoped address to the command line, 419110530SjulianNEVER write the embedded form (such as ff02:1::1 or fe80:2::fedc), 420113874Sjhbwhich should only be used inside the kernel (see Section 1.3.1), and 421113874Sjhbis not supposed to work. 422169803Sjeff 423110296Sjake1.4 Plug and Play 424110296Sjake 425169803SjeffThe KAME kit implements most of the IPv6 stateless address 4261541Srgrimesautoconfiguration in the kernel. 4271541SrgrimesNeighbor Discovery functions are implemented in the kernel as a whole. 4281541SrgrimesRouter Advertisement (RA) input for hosts is implemented in the 4291541Srgrimeskernel. Router Solicitation (RS) output for endhosts, RS input 4301541Srgrimesfor routers, and RA output for routers are implemented in the 4311541Srgrimesuserland. 4321541Srgrimes 4331541Srgrimes1.4.1 Assignment of link-local, and special addresses 4341541Srgrimes 4351541SrgrimesIPv6 link-local address is generated from IEEE802 address (ethernet MAC 4361541Srgrimesaddress). Each of interface is assigned an IPv6 link-local address 437110530Sjulianautomatically, when the interface becomes up (IFF_UP). Also, direct route 438113874Sjhbfor the link-local address is added to routing table. 439113874Sjhb 440113874SjhbHere is an output of netstat command: 441113874Sjhb 442113874SjhbInternet6: 443123740SpeterDestination Gateway Flags Netif Expire 444113874Sjhbfe80::%ed0/64 link#1 UC ed0 445110530Sjulianfe80::%ep0/64 link#2 UC ep0 446128852Scperciva 447128852ScpercivaInterfaces that has no IEEE802 address (pseudo interfaces like tunnel 448113874Sjhbinterfaces, or ppp interfaces) will borrow IEEE802 address from other 449169803Sjeffinterfaces, such as ethernet interfaces, whenever possible. 450110296SjakeIf there is no IEEE802 hardware attached, last-resort pseudorandom value, 451110296Sjakewhich is from MD5(hostname), will be used as source of link-local address. 452169803SjeffIf it is not suitable for your usage, you will need to configure the 4531541Srgrimeslink-local address manually. 4541541Srgrimes 4551541SrgrimesIf an interface is not capable of handling IPv6 (such as lack of multicast 4561541Srgrimessupport), link-local address will not be assigned to that interface. 457170174SjeffSee section 2 for details. 458170174Sjeff 459170174SjeffEach interface joins the solicited multicast address and the 460110296Sjakelink-local all-nodes multicast addresses (e.g. fe80::1:ff01:6317 4611541Srgrimesand ff02::1, respectively, on the link the interface is attached). 4621541SrgrimesIn addition to a link-local address, the loopback address (::1) will be 463153666Sjhbassigned to the loopback interface. Also, ::1/128 and ff01::/32 are 4641541Srgrimesautomatically added to routing table, and loopback interface joins 46517342Sbdenode-local multicast group ff01::1. 46617342Sbde 467110296Sjake1.4.2 Stateless address autoconfiguration on hosts 468110296Sjake 469110296SjakeIn IPv6 specification, nodes are separated into two categories: 470174070Speterrouters and hosts. Routers forward packets addressed to others, hosts does 4711541Srgrimesnot forward the packets. net.inet6.ip6.forwarding defines whether this 472110296Sjakenode is a router or a host (router if it is 1, host if it is 0). 473110296Sjake 474110296SjakeIt is NOT recommended to change net.inet6.ip6.forwarding while the node 475174070Speteris in operation. IPv6 specification defines behavior for "host" and "router" 476153666Sjhbquite differently, and switching from one to another can cause serious 47753751Sbdetroubles. It is recommended to configure the variable at bootstrap time only. 47853751Sbde 4791541SrgrimesThe first step in stateless address configuration is Duplicated Address 480163709SjbDetection (DAD). See 1.2 for more detail on DAD. 481116361Sdavidxu 482111028SjeffWhen a host hears Router Advertisement from the router, a host may 483163709Sjbautoconfigure itself by stateless address autoconfiguration. 484155534SphkThis behavior can be controlled by net.inet6.ip6.accept_rtadv 485130551Sjulian(host autoconfigures itself if it is set to 1). 486174070SpeterBy autoconfiguration, network address prefix for the receiving interface 4871541Srgrimes(usually global address prefix) is added. The default route is also 488174070Speterconfigured. 4891541Srgrimes 4901541SrgrimesRouters periodically generate Router Advertisement packets. To 4911541Srgrimesrequest an adjacent router to generate RA packet, a host can transmit 4921541SrgrimesRouter Solicitation. To generate an RS packet at any time, use the 4931541Srgrimes"rtsol" command. The "rtsold" daemon is also available. "rtsold" 4941541Srgrimesgenerates Router Solicitation whenever necessary, and it works great 4951541Srgrimesfor nomadic usage (notebooks/laptops). If one wishes to ignore Router 4961541SrgrimesAdvertisements, use sysctl to set net.inet6.ip6.accept_rtadv to 0. 4971541Srgrimes 4981541SrgrimesTo generate Router Advertisement from a router, use the "rtadvd" daemon. 4991541Srgrimes 5001541SrgrimesNote that the IPv6 specification assumes the following items and that 5011541Srgrimesnonconforming cases are left unspecified: 502151658Sjhb- Only hosts will listen to router advertisements 503151658Sjhb- Hosts have single network interface (except loopback) 504155534SphkThis is therefore unwise to enable net.inet6.ip6.accept_rtadv on routers, 505174070Speteror multi-interface host. A misconfigured node can behave strange 50665557Sjasone(KAME code allows nonconforming configuration, for those who would like 507163709Sjbto do some experiments). 508116361Sdavidxu 509111028SjeffTo summarize the sysctl knob: 510163709Sjb accept_rtadv forwarding role of the node 511155455Sphk --- --- --- 512155534Sphk 0 0 host (to be manually configured) 513167327Sjulian 0 1 router 514174070Speter 1 0 autoconfigured host 51565557Sjasone (spec assumes that host has single 516174070Speter interface only, autoconfigred host with 51765557Sjasone multiple interface is out-of-scope) 5181541Srgrimes 1 1 invalid, or experimental 5191541Srgrimes (out-of-scope of spec) 52065782Sjhb 521131436SjhbSee 1.2 in the document for relationship between DAD and autoconfiguration. 522131436Sjhb 523170174Sjeff1.4.3 DHCPv6 524131436Sjhb 525131436SjhbWe supply a tiny DHCPv6 server/client in kame/dhcp6. However, the 526131436Sjhbimplementation is premature (for example, this does NOT implement 527131436Sjhbaddress lease/release), and it is not in default compilation tree on 528131436Sjhbsome platforms. If you want to do some experiment, compile it on your 529131436Sjhbown. 530170297Sjeff 531173600SjulianDHCPv6 and autoconfiguration also needs more work. "Managed" and "Other" 532174070Speterbits in RA have no special effect to stateful autoconfiguration procedure 533170297Sjeffin DHCPv6 client program ("Managed" bit actually prevents stateless 534170297Sjeffautoconfiguration, but no special action will be taken for DHCPv6 client). 53576078Sjhb 53666716Sjhb1.5 Generic tunnel interface 53776078Sjhb 538153666SjhbGIF (Generic InterFace) is a pseudo interface for configured tunnel. 53976078SjhbDetails are described in gif(4) manpage. 540110296SjakeCurrently 541110296Sjake v6 in v6 542110296Sjake v6 in v4 543153490Sjhb v4 in v6 544110296Sjake v4 in v4 54576078Sjhbare available. Use "gifconfig" to assign physical (outer) source 546111032Sjulianand destination address to gif interfaces. 547153666SjhbConfiguration that uses same address family for inner and outer IP 548110296Sjakeheader (v4 in v4, or v6 in v6) is dangerous. It is very easy to 549110296Sjakeconfigure interfaces and routing tables to perform infinite level 550110296Sjakeof tunneling. Please be warned. 551110530Sjulian 552110530Sjuliangif can be configured to be ECN-friendly. See 4.5 for ECN-friendliness 553110296Sjakeof tunnels, and gif(4) manpage for how to configure. 554113874Sjhb 555153666SjhbIf you would like to configure an IPv4-in-IPv6 tunnel with gif interface, 556110296Sjakeread gif(4) carefully. You may need to remove IPv6 link-local address 557110296Sjakeautomatically assigned to the gif interface. 558110296Sjake 559110296Sjake1.6 Source Address Selection 560110296Sjake 561110296SjakeKAME's source address selection takes care of the following 562110296Sjakeconditions: 563153666Sjhb- address scope 564153666Sjhb- outgoing interface 565110296Sjake- whether an address is deprecated 566153666Sjhb- whether an address is temporary (in terms of RFC 3041) 567110296Sjake- prefix matching against the destination 568110296Sjake 569110296SjakeRoughly speaking, the selection policy is as follows: 570110296Sjake- always use an address that belongs to the same scope zone as the 5711541Srgrimes destination. 5721541Srgrimes- addresses that have equal or larger scope than the scope of the 5731541Srgrimes destination are preferred. 5741541Srgrimes- a deprecated address is not used in new communications if an 5751541Srgrimes alternate (non-deprecated) address is available and has sufficient 57612152Sphk scope. 57762573Sphk- a temporary address (in terms of RFC 3041 privacy extension) are 5781541Srgrimes preferred to a public address. 5791541Srgrimes- if none of above conditions tie-breaks, addresses assigned on the 5801541Srgrimes outgoing interface are preferred. 5811541Srgrimes- if none of above conditions tie-breaks, one which is longest prefix 5821541Srgrimes matching against the destination is preferred as the last resort. 58396052Sbde 5841541SrgrimesFor instance, ::1 is selected for ff01::1, 5851541Srgrimesfe80::200:f8ff:fe01:6317%ne0 for fe80::2a0:24ff:feab:839b%ne0. 5861541SrgrimesTo see how longest-matching works, suppose that 5871541Srgrimes3ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317 58812243Sphkare given on the outgoing interface. Then the former is chosen as the 5891541Srgrimessource for the destination 3ffe:501:800::1. Note that even if all 5902858Swollmanavailable addresses have smaller scope than the scope of the 59112623Sphkdestination, we choose one anyway. For example, if we have link-local 59288019Sluigiand site-local addresses only, we choose a site-local addresses for a 59388019Sluigiglobal destination. If the packet is going to break a site boundary, 594116874Ssmkellythe boundary router will return an ICMPv6 destination unreachable 595126383Sphkerror with code 2 - beyond scope of source address. 596126383Sphk 597126383SphkThe precise desripction of the algorithm is quite complicated. To 598165260Sn_hibmadescribe the algorithm, we introduce the following notation: 599116874Ssmkelly 600126383SphkFor a given destination D, 601116874Ssmkelly samescope(D): The set of addresses that have the same scope as D. 602126386Sphk largerscope(D): The set of addresses that have a larger scope than D. 603165260Sn_hibma smallerscope(D): The set of addresses that have a smaller scope than D. 604126383Sphk 605126383SphkFor a given set of addresses A, 606165260Sn_hibma DEP(A): the set of deprecated addresses in A. 607126383Sphk nonDEP(A): A - DEP(A). 608126383Sphk 609126383SphkFor a given set of addresses A, 610116874Ssmkelly tmp(A): the set of preferred temporary-autoconfigured or 611116874Ssmkelly manually-configure addresses in A. 612116874Ssmkelly 613116874SsmkellyAlso, the algorithm assumes that the outgoing interface for the 614170075Semastedestination D is determined. We call the interface "I". 615116874Ssmkelly 616116874SsmkellyThe algorithm is as follows. Selection proceeds step by step as 617116874Ssmkellydescribed; For example, if an address is selected by item 1, item 2 and 618116874Ssmkellylater are not considered at all. 619116874Ssmkelly 620116874Ssmkelly 0. If there is no address in the same scope zone as D, just give up; 621116874Ssmkelly the packet will not be sent. 622116874Ssmkelly 1. If we do not prefer temporary addresses, go to 3. 623116874Ssmkelly Otherwise, and if tmp(samescope(D)) is not empty, 624116874Ssmkelly then choose an address that is on the interface I. If every 625116874Ssmkelly address is on I, or every address is on a different interface 626116874Ssmkelly from I, choose an arbitrary one provided that an address longest 627116874Ssmkelly matching against D is always preferred. 628157822Sjhb 2. If tmp(largerscope(D)) is not empty, 629116874Ssmkelly then choose an address that has the smallest scope. If more than one 630116874Ssmkelly address has the smallest scope, choose an arbitrary one provided 631116874Ssmkelly that addresses on I are always preferred. 632116874Ssmkelly 3. If nonDEP(samescope(D)) is not empty, 633116874Ssmkelly then apply the same logic as of 1. 634116874Ssmkelly 4. If nonDEP(largerscope(D)) is not empty, 635116874Ssmkelly then apply the same logic as of 2. 636116908Ssmkelly 5. If we do not prefer temporary addresses, go to 7. 637170075Semaste Otherwise, and if tmp(DEP(samescope(D))) is not empty, 638170075Semaste then choose an address that is on the interface I. If every 639170075Semaste address is on I, or every address is on a different interface 640174898Srwatson from I, choose an arbitrary one provided that an address longest 641170075Semaste matching against D is always preferred. 642116874Ssmkelly 6. If tmp(DEP(largerscope(D))) is not empty, 643170075Semaste then choose an address that has the smallest scope. If more than 644116874Ssmkelly one address has the smallest scope, choose an arbitrary one provided 645116874Ssmkelly that an address on I is always preferred. 646126383Sphk 7. If DEP(samescope(D)) is not empty, 647 then apply the same logic as of 5. 648 8. If DEP(largerscope(D)) is not empty, 649 then apply the same logic as of 6. 650 9. If we do not prefer temporary addresses, go to 11. 651 Otherwise, and if tmp(nonDEP(smallerscope(D))) is not empty, 652 then choose an address that has the largest scope. If more than 653 one address has the largest scope, choose an arbitrary one provided 654 that an address on I is always preferred. 655 10. If tmp(DEP(smallerscope(D))) is not empty, 656 then choose an address that has the largest scope. If more than 657 one address has the largest scope, choose an arbitrary one provided 658 that an address on I is always preferred. 659 11. If nonDEP(smallerscope(D)) is not empty, 660 then apply the same logic as of 9. 661 12. If DEP(smallerscope(D)) is not empty, 662 then apply the same logic as of 10. 663 664There exists a document about source address selection 665(draft-ietf-ipngwg-default-addr-select-xx.txt). KAME's algorithm 666described above takes a similar approach to the document, but there 667are some differences. See the document for more details. 668 669There are some cases where we do not use the above rule. One 670example is connected TCP session, and we use the address kept in TCP 671protocol control block (tcb) as the source. 672Another example is source address for Neighbor Advertisement. 673Under the spec (RFC2461 7.2.2) NA's source should be the target 674address of the corresponding NS's target. In this case we follow 675the spec rather than the above longest-match rule. 676 677If you would like to prohibit the use of deprecated address for some 678reason, configure net.inet6.ip6.use_deprecated to 0. The issue 679related to deprecated address is described in RFC2462 5.5.4 (NOTE: 680there is some debate underway in IETF ipngwg on how to use 681"deprecated" address). 682 6831.7 Jumbo Payload 684 685KAME supports the Jumbo Payload hop-by-hop option used to send IPv6 686packets with payloads longer than 65,535 octets. But since currently 687KAME does not support any physical interface whose MTU is more than 68865,535, such payloads can be seen only on the loopback interface(i.e. 689lo0). 690 691If you want to try jumbo payloads, you first have to reconfigure the 692kernel so that the MTU of the loopback interface is more than 65,535 693bytes; add the following to the kernel configuration file: 694 options "LARGE_LOMTU" #To test jumbo payload 695and recompile the new kernel. 696 697Then you can test jumbo payloads by the ping6 command with -b and -s 698options. The -b option must be specified to enlarge the size of the 699socket buffer and the -s option specifies the length of the packet, 700which should be more than 65,535. For example, type as follows; 701 % ping6 -b 70000 -s 68000 ::1 702 703The IPv6 specification requires that the Jumbo Payload option must not 704be used in a packet that carries a fragment header. If this condition 705is broken, an ICMPv6 Parameter Problem message must be sent to the 706sender. KAME kernel follows the specification, but you cannot usually 707see an ICMPv6 error caused by this requirement. 708 709If KAME kernel receives an IPv6 packet, it checks the frame length of 710the packet and compares it to the length specified in the payload 711length field of the IPv6 header or in the value of the Jumbo Payload 712option, if any. If the former is shorter than the latter, KAME kernel 713discards the packet and increments the statistics. You can see the 714statistics as output of netstat command with `-s -p ip6' option: 715 % netstat -s -p ip6 716 ip6: 717 (snip) 718 1 with data size < data length 719 720So, KAME kernel does not send an ICMPv6 error unless the erroneous 721packet is an actual Jumbo Payload, that is, its packet size is more 722than 65,535 bytes. As described above, KAME kernel currently does not 723support physical interface with such a huge MTU, so it rarely returns an 724ICMPv6 error. 725 726TCP/UDP over jumbogram is not supported at this moment. This is because 727we have no medium (other than loopback) to test this. Contact us if you 728need this. 729 730IPsec does not work on jumbograms. This is due to some specification twists 731in supporting AH with jumbograms (AH header size influences payload length, 732and this makes it real hard to authenticate inbound packet with jumbo payload 733option as well as AH). 734 735There are fundamental issues in *BSD support for jumbograms. We would like to 736address those, but we need more time to finalize the task. To name a few: 737- mbuf pkthdr.len field is typed as "int" in 4.4BSD, so it cannot hold 738 jumbogram with len > 2G on 32bit architecture CPUs. If we would like to 739 support jumbogram properly, the field must be expanded to hold 4G + 740 IPv6 header + link-layer header. Therefore, it must be expanded to at least 741 int64_t (u_int32_t is NOT enough). 742- We mistakingly use "int" to hold packet length in many places. We need 743 to convert them into larger numeric type. It needs a great care, as we may 744 experience overflow during packet length computation. 745- We mistakingly check for ip6_plen field of IPv6 header for packet payload 746 length in various places. We should be checking mbuf pkthdr.len instead. 747 ip6_input() will perform sanity check on jumbo payload option on input, 748 and we can safely use mbuf pkthdr.len afterwards. 749- TCP code needs careful updates in bunch of places, of course. 750 7511.8 Loop prevention in header processing 752 753IPv6 specification allows arbitrary number of extension headers to 754be placed onto packets. If we implement IPv6 packet processing 755code in the way BSD IPv4 code is implemented, kernel stack may 756overflow due to long function call chain. KAME sys/netinet6 code 757is carefully designed to avoid kernel stack overflow. Because of 758this, KAME sys/netinet6 code defines its own protocol switch 759structure, as "struct ip6protosw" (see netinet6/ip6protosw.h). 760 761In addition to this, we restrict the number of extension headers 762(including the IPv6 header) in each incoming packet, in order to 763prevent a DoS attack that tries to send packets with a massive number 764of extension headers. The upper limit can be configured by the sysctl 765value net.inet6.ip6.hdrnestlimit. In particular, if the value is 0, 766the node will allow an arbitrary number of headers. As of writing this 767document, the default value is 50. 768 769IPv4 part (sys/netinet) remains untouched for compatibility. 770Because of this, if you receive IPsec-over-IPv4 packet with massive 771number of IPsec headers, kernel stack may blow up. IPsec-over-IPv6 is okay. 772 7731.9 ICMPv6 774 775After RFC2463 was published, IETF ipngwg has decided to disallow ICMPv6 error 776packet against ICMPv6 redirect, to prevent ICMPv6 storm on a network medium. 777KAME already implements this into the kernel. 778 779RFC2463 requires rate limitation for ICMPv6 error packets generated by a 780node, to avoid possible DoS attacks. KAME kernel implements two rate- 781limitation mechanisms, tunable via sysctl: 782- Minimum time interval between ICMPv6 error packets 783 KAME kernel will generate no more than one ICMPv6 error packet, 784 during configured time interval. net.inet6.icmp6.errratelimit 785 controls the interval (default: disabled). 786- Maximum ICMPv6 error packet-per-second 787 KAME kernel will generate no more than the configured number of 788 packets in one second. net.inet6.icmp6.errppslimit controls the 789 maximum packet-per-second value (default: 200pps) 790Basically, we need to pick values that are suitable against the bandwidth 791of link layer devices directly attached to the node. In some cases the 792default values may not fit well. We are still unsure if the default value 793is sane or not. Comments are welcome. 794 7951.10 Applications 796 797For userland programming, we support IPv6 socket API as specified in 798RFC2553, RFC2292 and upcoming internet drafts. 799 800TCP/UDP over IPv6 is available and quite stable. You can enjoy "telnet", 801"ftp", "rlogin", "rsh", "ssh", etc. These applications are protocol 802independent. That is, they automatically chooses IPv4 or IPv6 803according to DNS. 804 8051.11 Kernel Internals 806 807 (*) TCP/UDP part is handled differently between operating system platforms. 808 See 1.12 for details. 809 810The current KAME has escaped from the IPv4 netinet logic. While 811ip_forward() calls ip_output(), ip6_forward() directly calls 812if_output() since routers must not divide IPv6 packets into fragments. 813 814ICMPv6 should contain the original packet as long as possible up to 8151280. UDP6/IP6 port unreach, for instance, should contain all 816extension headers and the *unchanged* UDP6 and IP6 headers. 817So, all IP6 functions except TCP6 never convert network byte 818order into host byte order, to save the original packet. 819 820tcp6_input(), udp6_input() and icmp6_input() can't assume that IP6 821header is preceding the transport headers due to extension 822headers. So, in6_cksum() was implemented to handle packets whose IP6 823header and transport header is not continuous. TCP/IP6 nor UDP/IP6 824header structure don't exist for checksum calculation. 825 826To process IP6 header, extension headers and transport headers easily, 827KAME requires network drivers to store packets in one internal mbuf or 828one or more external mbufs. A typical old driver prepares two 829internal mbufs for 100 - 208 bytes data, however, KAME's reference 830implementation stores it in one external mbuf. 831 832"netstat -s -p ip6" tells you whether or not your driver conforms 833KAME's requirement. In the following example, "cce0" violates the 834requirement. (For more information, refer to Section 2.) 835 836 Mbuf statistics: 837 317 one mbuf 838 two or more mbuf:: 839 lo0 = 8 840 cce0 = 10 841 3282 one ext mbuf 842 0 two or more ext mbuf 843 844Each input function calls IP6_EXTHDR_CHECK in the beginning to check 845if the region between IP6 and its header is 846continuous. IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has 847M_LOOP flag, that is, the packet comes from the loopback 848interface. m_pullup() is never called for packets coming from physical 849network interfaces. 850 851TCP6 reassembly makes use of IP6 header to store reassemble 852information. IP6 is not supposed to be just before TCP6, so 853ip6tcpreass structure has a pointer to TCP6 header. Of course, it has 854also a pointer back to mbuf to avoid m_pullup(). 855 856Like TCP6, both IP and IP6 reassemble functions never call m_pullup(). 857 858xxx_ctlinput() calls in_mrejoin() on PRC_IFNEWADDR. We think this is 859one of 4.4BSD implementation flaws. Since 4.4BSD keeps ia_multiaddrs 860in in_ifaddr{}, it can't use multicast feature if the interface has no 861unicast address. So, if an application joins to an interface and then 862all unicast addresses are removed from the interface, the application 863can't send/receive any multicast packets. Moreover, if a new unicast 864address is assigned to the interface, in_mrejoin() must be called. 865KAME's interfaces, however, have ALWAYS one link-local unicast 866address. These extensions have thus not been implemented in KAME. 867 8681.12 IPv4 mapped address and IPv6 wildcard socket 869 870RFC2553 describes IPv4 mapped address (3.7) and special behavior 871of IPv6 wildcard bind socket (3.8). The spec allows you to: 872- Accept IPv4 connections by AF_INET6 wildcard bind socket. 873- Transmit IPv4 packet over AF_INET6 socket by using special form of 874 the address like ::ffff:10.1.1.1. 875but the spec itself is very complicated and does not specify how the 876socket layer should behave. 877Here we call the former one "listening side" and the latter one "initiating 878side", for reference purposes. 879 880Almost all KAME implementations treat tcp/udp port number space separately 881between IPv4 and IPv6. You can perform wildcard bind on both of the address 882families, on the same port. 883 884There are some OS-platform differences in KAME code, as we use tcp/udp 885code from different origin. The following table summarizes the behavior. 886 887 listening side initiating side 888 (AF_INET6 wildcard (connection to ::ffff:10.1.1.1) 889 socket gets IPv4 conn.) 890 --- --- 891KAME/BSDI3 not supported not supported 892KAME/FreeBSD228 not supported not supported 893KAME/FreeBSD3x configurable supported 894 default: enabled 895KAME/FreeBSD4x configurable supported 896 default: enabled 897KAME/NetBSD configurable supported 898 default: disabled 899KAME/BSDI4 enabled supported 900KAME/OpenBSD not supported not supported 901 902The following sections will give you more details, and how you can 903configure the behavior. 904 905Comments on listening side: 906 907It looks that RFC2553 talks too little on wildcard bind issue, 908specifically on (1) port space issue, (2) failure mode, (3) relationship 909between AF_INET/INET6 wildcard bind like ordering constraint, and (4) behavior 910when conflicting socket is opened/closed. There can be several separate 911interpretation for this RFC which conform to it but behaves differently. 912So, to implement portable application you should assume nothing 913about the behavior in the kernel. Using getaddrinfo() is the safest way. 914Port number space and wildcard bind issues were discussed in detail 915on ipv6imp mailing list, in mid March 1999 and it looks that there's 916no concrete consensus (means, up to implementers). You may want to 917check the mailing list archives. 918We supply a tool called "bindtest" that explores the behavior of 919kernel bind(2). The tool will not be compiled by default. 920 921If a server application would like to accept IPv4 and IPv6 connections, 922it should use AF_INET and AF_INET6 socket (you'll need two sockets). 923Use getaddrinfo() with AI_PASSIVE into ai_flags, and socket(2) and bind(2) 924to all the addresses returned. 925By opening multiple sockets, you can accept connections onto the socket with 926proper address family. IPv4 connections will be accepted by AF_INET socket, 927and IPv6 connections will be accepted by AF_INET6 socket (NOTE: KAME/BSDI4 928kernel sometimes violate this - we will fix it). 929 930If you try to support IPv6 traffic only and would like to reject IPv4 931traffic, always check the peer address when a connection is made toward 932AF_INET6 listening socket. If the address is IPv4 mapped address, you may 933want to reject the connection. You can check the condition by using 934IN6_IS_ADDR_V4MAPPED() macro. This is one of the reasons the author of 935the section (itojun) dislikes special behavior of AF_INET6 wildcard bind. 936 937Comments on initiating side: 938 939Advise to application implementers: to implement a portable IPv6 application 940(which works on multiple IPv6 kernels), we believe that the following 941is the key to the success: 942- NEVER hardcode AF_INET nor AF_INET6. 943- Use getaddrinfo() and getnameinfo() throughout the system. 944 Never use gethostby*(), getaddrby*(), inet_*() or getipnodeby*(). 945- If you would like to connect to destination, use getaddrinfo() and try 946 all the destination returned, like telnet does. 947- Some of the IPv6 stack is shipped with buggy getaddrinfo(). Ship a minimal 948 working version with your application and use that as last resort. 949 950If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing 951connection, you will need tweaked implementation in DNS support libraries, 952as documented in RFC2553 6.1. KAME libinet6 includes the tweak in 953getipnodebyname(). Note that getipnodebyname() itself is not recommended as 954it does not handle scoped IPv6 addresses at all. For IPv6 name resolution 955getaddrinfo() is the preferred API. getaddrinfo() does not implement the 956tweak. 957 958When writing applications that make outgoing connections, story goes much 959simpler if you treat AF_INET and AF_INET6 as totally separate address family. 960{set,get}sockopt issue goes simpler, DNS issue will be made simpler. We do 961not recommend you to rely upon IPv4 mapped address. 962 9631.12.1 KAME/BSDI3 and KAME/FreeBSD228 964 965The platforms do not support IPv4 mapped address at all (both listening side 966and initiating side). AF_INET6 and AF_INET sockets are totally separated. 967 968Port number space is totally separate between AF_INET and AF_INET6 sockets. 969 970It should be noted that KAME/BSDI3 and KAME/FreeBSD228 are not conformant 971to RFC2553 section 3.7 and 3.8. It is due to code sharing reasons. 972 9731.12.2 KAME/FreeBSD[34]x 974 975KAME/FreeBSD3x and KAME/FreeBSD4x use shared tcp4/6 code (from 976sys/netinet/tcp*) and shared udp4/6 code (from sys/netinet/udp*). 977They use unified inpcb/in6pcb structure. 978 9791.12.2.1 KAME/FreeBSD[34]x, listening side 980 981The platform can be configured to support IPv4 mapped address/special 982AF_INET6 wildcard bind (enabled by default). There is no kernel compilation 983option to disable it. You can enable/disable the behavior with sysctl 984(per-node), or setsockopt (per-socket). 985 986Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following 987conditions are satisfied: 988- there's no AF_INET socket that matches the IPv4 connection 989- the AF_INET6 socket is configured to accept IPv4 traffic, i.e. 990 getsockopt(IPV6_V6ONLY) returns 0. 991 992(XXX need checking) 993 9941.12.2.2 KAME/FreeBSD[34]x, initiating side 995 996KAME/FreeBSD3x supports outgoing connection to IPv4 mapped address 997(::ffff:10.1.1.1), if the node is configured to accept IPv4 connections 998by AF_INET6 socket. 999 1000(XXX need checking) 1001 10021.12.3 KAME/NetBSD 1003 1004KAME/NetBSD uses shared tcp4/6 code (from sys/netinet/tcp*) and shared 1005udp4/6 code (from sys/netinet/udp*). The implementation is made differently 1006from KAME/FreeBSD[34]x. KAME/NetBSD uses separate inpcb/in6pcb structures, 1007while KAME/FreeBSD[34]x uses merged inpcb structure. 1008 1009It should be noted that the default configuration of KAME/NetBSD is not 1010conformant to RFC2553 section 3.8. It is intentionally turned off by default 1011for security reasons. 1012 10131.12.3.1 KAME/NetBSD, listening side 1014 1015The platform can be configured to support IPv4 mapped address/special AF_INET6 1016wildcard bind (disabled by default). Kernel behavior can be summarized as 1017follows: 1018- default: special support code will be compiled in, but is disabled by 1019 default. It can be controlled by sysctl (net.inet6.ip6.v6only), 1020 or setsockopt(IPV6_V6ONLY). 1021- add "INET6_V6ONLY": No special support code for AF_INET6 wildcard socket 1022 will be compiled in. AF_INET6 sockets and AF_INET sockets are totally 1023 separate. The behavior is similar to what described in 1.12.1. 1024 1025sysctl setting will affect per-socket configuration at in6pcb creation time 1026only. In other words, per-socket configuration will be copied from sysctl 1027configuration at in6pcb creation time. To change per-socket behavior, you 1028must perform setsockopt or reopen the socket. Change in sysctl configuration 1029will not change the behavior or sockets that are already opened. 1030 1031Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following 1032conditions are satisfied: 1033- there's no AF_INET socket that matches the IPv4 connection 1034- the AF_INET6 socket is configured to accept IPv4 traffic, i.e. 1035 getsockopt(IPV6_V6ONLY) returns 0. 1036 1037You cannot bind(2) with IPv4 mapped address. This is a workaround for port 1038number duplicate and other twists. 1039 10401.12.3.2 KAME/NetBSD, initiating side 1041 1042When you initiate a connection, you can always connect to IPv4 destination 1043over AF_INET6 socket, usin IPv4 mapped address destination (::ffff:10.1.1.1). 1044This is enabled independently from the configuration for listening side, and 1045always enabled. 1046 10471.12.4 KAME/BSDI4 1048 1049KAME/BSDI4 uses NRL-based TCP/UDP stack and inpcb source code, 1050which was derived from NRL IPv6/IPsec stack. We guess it supports IPv4 mapped 1051address and speical AF_INET6 wildcard bind. The implementation is, again, 1052different from other KAME/*BSDs. 1053 10541.12.4.1 KAME/BSDI4, listening side 1055 1056NRL inpcb layer supports special behavior of AF_INET6 wildcard socket. 1057There is no way to disable the behavior. 1058 1059Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following 1060condition is satisfied: 1061- there's no AF_INET socket that matches the IPv4 connection 1062 10631.12.4.2 KAME/BSDI4, initiating side 1064 1065KAME/BSDi4 supports connection initiation to IPv4 mapped address 1066(like ::ffff:10.1.1.1). 1067 10681.12.5 KAME/OpenBSD 1069 1070KAME/OpenBSD uses NRL-based TCP/UDP stack and inpcb source code, 1071which was derived from NRL IPv6/IPsec stack. 1072 1073It should be noted that KAME/OpenBSD is not conformant to RFC2553 section 3.7 1074and 3.8. It is intentionally omitted for security reasons. 1075 10761.12.5.1 KAME/OpenBSD, listening side 1077 1078KAME/OpenBSD disables special behavior on AF_INET6 wildcard bind for 1079security reasons (if IPv4 traffic toward AF_INET6 wildcard bind is allowed, 1080access control will become much harder). KAME/BSDI4 uses NRL-based TCP/UDP 1081stack as well, however, the behavior is different due to OpenBSD's security 1082policy. 1083 1084As a result the behavior of KAME/OpenBSD is similar to KAME/BSDI3 and 1085KAME/FreeBSD228 (see 1.12.1 for more detail). 1086 10871.12.5.2 KAME/OpenBSD, initiating side 1088 1089KAME/OpenBSD does not support connection initiation to IPv4 mapped address 1090(like ::ffff:10.1.1.1). 1091 10921.12.6 More issues 1093 1094IPv4 mapped address support adds a big requirement to EVERY userland codebase. 1095Every userland code should check if an AF_INET6 sockaddr contains IPv4 1096mapped address or not. This adds many twists: 1097 1098- Access controls code becomes harder to write. 1099 For example, if you would like to reject packets from 10.0.0.0/8, 1100 you need to reject packets to AF_INET socket from 10.0.0.0/8, 1101 and to AF_INET6 socket from ::ffff:10.0.0.0/104. 1102- If a protocol on top of IPv4 is defined differently with IPv6, we need to be 1103 really careful when we determine which protocol to use. 1104 For example, with FTP protocol, we can not simply use sa_family to determine 1105 FTP command sets. The following example is incorrect: 1106 if (sa_family == AF_INET) 1107 use EPSV/EPRT or PASV/PORT; /*IPv4*/ 1108 else if (sa_family == AF_INET6) 1109 use EPSV/EPRT or LPSV/LPRT; /*IPv6*/ 1110 else 1111 error; 1112 The correct code, with consideration to IPv4 mapped address, would be: 1113 if (sa_family == AF_INET) 1114 use EPSV/EPRT or PASV/PORT; /*IPv4*/ 1115 else if (sa_family == AF_INET6 && IPv4 mapped address) 1116 use EPSV/EPRT or PASV/PORT; /*IPv4 command set on AF_INET6*/ 1117 else if (sa_family == AF_INET6 && !IPv4 mapped address) 1118 use EPSV/EPRT or LPSV/LPRT; /*IPv6*/ 1119 else 1120 error; 1121 It is too much to ask for every body to be careful like this. 1122 The problem is, we are not sure if the above code fragment is perfect for 1123 all situations. 1124- By enabling kernel support for IPv4 mapped address (outgoing direction), 1125 servers on the kernel can be hosed by IPv6 native packet that has IPv4 1126 mapped address in IPv6 header source, and can generate unwanted IPv4 packets. 1127 draft-itojun-ipv6-transition-abuse-01.txt talks more about this scenario. 1128 1129Due to the above twists, some of KAME userland programs has restrictions on 1130the use of IPv4 mapped addresses: 1131- rshd/rlogind do not accept connections from IPv4 mapped address. 1132 This is to avoid malicious use of IPv4 mapped address in IPv6 native 1133 packet, to bypass source-address based authentication. 1134- ftp/ftpd assume that you are on dual stack network. IPv4 mapped address 1135 will be decoded in userland, and will be passed to AF_INET sockets 1136 (in other words, ftp/ftpd do not support SIIT environment). 1137 11381.12.7 Interaction with SIIT translator 1139 1140SIIT translator is specified in RFC2765. KAME node cannot become a SIIT 1141translator box, nor SIIT end node (a node in SIIT cloud). 1142 1143To become a SIIT translator box, we need to put additional code for that. 1144We do not have the code in our tree at this moment. 1145 1146There are multiple reasons that we are unable to become SIIT end node. 1147(1) SIIT translators require end nodes in the SIIT cloud to be IPv6-only. 1148Since we are unable to compile INET-less kernel, we are unable to become 1149SIIT end node. (2) As presented in 1.12.6, some of our userland code assumes 1150dual stack network. (3) KAME stack filters out IPv6 packets with IPv4 1151mapped address in the header, to secure non-SIIT case (which is much more 1152common). Effectively KAME node will reject any packets via SIIT translator 1153box. See section 1.14 for more detail about the last item. 1154 1155There are documentation issues too - SIIT document requires very strange 1156things. For example, SIIT document asks IPv6-only (meaning no IPv4 code) 1157node to be able to construct IPv4 IPsec headers. If a node knows how to 1158construct IPv4 IPsec headers, that is not an IPv6-only node, it is a dual-stack 1159node. The requirements imposed in SIIT document contradict with the other 1160part of the document itself. 1161 11621.13 sockaddr_storage 1163 1164When RFC2553 was about to be finalized, there was discussion on how struct 1165sockaddr_storage members are named. One proposal is to prepend "__" to the 1166members (like "__ss_len") as they should not be touched. The other proposal 1167was that don't prepend it (like "ss_len") as we need to touch those members 1168directly. There was no clear consensus on it. 1169 1170As a result, RFC2553 defines struct sockaddr_storage as follows: 1171 struct sockaddr_storage { 1172 u_char __ss_len; /* address length */ 1173 u_char __ss_family; /* address family */ 1174 /* and bunch of padding */ 1175 }; 1176On the contrary, XNET draft defines as follows: 1177 struct sockaddr_storage { 1178 u_char ss_len; /* address length */ 1179 u_char ss_family; /* address family */ 1180 /* and bunch of padding */ 1181 }; 1182 1183In December 1999, it was agreed that RFC2553bis should pick the latter (XNET) 1184definition. 1185 1186KAME kit prior to December 1999 used RFC2553 definition. KAME kit after 1187December 1999 (including December) will conform to XNET definition, 1188based on RFC2553bis discussion. 1189 1190If you look at multiple IPv6 implementations, you will be able to see 1191both definitions. As an userland programmer, the most portable way of 1192dealing with it is to: 1193(1) ensure ss_family and/or ss_len are available on the platform, by using 1194 GNU autoconf, 1195(2) have -Dss_family=__ss_family to unify all occurences (including header 1196 file) into __ss_family, or 1197(3) never touch __ss_family. cast to sockaddr * and use sa_family like: 1198 struct sockaddr_storage ss; 1199 family = ((struct sockaddr *)&ss)->sa_family 1200 12011.14 Invalid addresses on the wire 1202 1203Some of IPv6 transition technologies embed IPv4 address into IPv6 address. 1204These specifications themselves are fine, however, there can be certain 1205set of attacks enabled by these specifications. Recent speicifcation 1206documents covers up those issues, however, there are already-published RFCs 1207that does not have protection against those (like using source address of 1208::ffff:127.0.0.1 to bypass "reject packet from remote" filter). 1209 1210To name a few, these address ranges can be used to hose an IPv6 implementation, 1211or bypass security controls: 1212- IPv4 mapped address that embeds unspecified/multicast/loopback/broadcast 1213 IPv4 address (if they are in IPv6 native packet header, they are malicious) 1214 ::ffff:0.0.0.0/104 ::ffff:127.0.0.0/104 1215 ::ffff:224.0.0.0/100 ::ffff:255.0.0.0/104 1216- 6to4 (RFC3056) prefix generated from unspecified/multicast/loopback/ 1217 broadcast/private IPv4 address 1218 2002:0000::/24 2002:7f00::/24 2002:e000::/24 1219 2002:ff00::/24 2002:0a00::/24 2002:ac10::/28 1220 2002:c0a8::/32 1221- IPv4 compatible address that embeds unspecified/multicast/loopback/broadcast 1222 IPv4 address (if they are in IPv6 native packet header, they are malicious). 1223 Note that, since KAME doe snot support RFC1933/2893 auto tunnels, KAME nodes 1224 are not vulnerable to these packets. 1225 ::0.0.0.0/104 ::127.0.0.0/104 ::224.0.0.0/100 ::255.0.0.0/104 1226 1227Also, since KAME does not support RFC1933/2893 auto tunnels, seeing IPv4 1228compatible is very rare. You should take caution if you see those on the wire. 1229 1230If we see IPv6 packets with IPv4 mapped address (::ffff:0.0.0.0/96) in the 1231header in dual-stack environment (not in SIIT environment), they indicate 1232that someone is trying to inpersonate IPv4 peer. The packet should be dropped. 1233 1234IPv6 specifications do not talk very much about IPv6 unspecified address (::) 1235in the IPv6 source address field. Clarification is in progress. 1236Here are couple of comments: 1237- IPv6 unspecified address can be used in IPv6 source address field, if and 1238 only if we have no legal source address for the node. The legal situations 1239 include, but may not be limited to, (1) MLD while no IPv6 address is assigned 1240 to the node and (2) DAD. 1241- If IPv6 TCP packet has IPv6 unspecified address, it is an attack attempt. 1242 The form can be used as a trigger for TCP DoS attack. KAME code already 1243 filters them out. 1244- The following examples are seemingly illegal. It seems that there's general 1245 consensus among ipngwg for those. (1) mobile-ip6 home address option, 1246 (2) offlink packets (so routers should not forward them). 1247 KAME implmements (2) already. 1248 1249KAME code is carefully written to avoid such incidents. More specifically, 1250KAME kernel will reject packets with certain source/dstination address in IPv6 1251base header, or IPv6 routing header. Also, KAME default configuration file 1252is written carefully, to avoid those attacks. 1253 1254draft-itojun-ipv6-transition-abuse-01.txt talks about more about this. 1255 12561.15 Node's required addresses 1257 1258RFC2373 section 2.8 talks about required addresses for an IPv6 1259node. The section talks about how KAME stack manages those required 1260addresses. 1261 12621.15.1 Host case 1263 1264The following items are automatically assigned to the node (or the node will 1265automatically joins the group), at bootstrap time: 1266- Loopback address 1267- All-nodes multicast addresses (ff01::1) 1268 1269The following items will be automatically handled when the interface becomes 1270IFF_UP: 1271- Its link-local address for each interface 1272- Solicited-node multicast address for link-local addresses 1273- Link-local allnodes multicast address (ff02::1) 1274 1275The following items need to be configured manually by ifconfig(8) or prefix(8). 1276Alternatively, these can be autoconfigured by using stateless address 1277autoconfiguration. 1278- Assigned unicast/anycast addresses 1279- Solicited-Node multicast address for assigned unicast address 1280 1281Users can join groups by using appropriate system calls like setsockopt(2). 1282 12831.15.2 Router case 1284 1285In addition to the above, routers needs to handle the following items. 1286 1287The following items need to be configured manually by using ifconfig(8). 1288o The subnet-router anycast addresses for the interfaces it is configured 1289 to act as a router on (prefix::/64) 1290o All other anycast addresses with which the router has been configured 1291 1292The router will join the following multicast group when rtadvd(8) is available 1293for the interface. 1294o All-Routers Multicast Addresses (ff02::2) 1295 1296Routing daemons will join appropriate multicast groups, as necessary, 1297like ff02::9 for RIPng. 1298 1299Users can join groups by using appropriate system calls like setsockopt(2). 1300 13011.16 Advanced API 1302 1303Current KAME kernel implements 2292bis API, documented in 1304draft-ietf-ipngwg-rfc2292bis-xx.txt. It also implements RFC2292 API, 1305for backward compatibility purposes with *BSD-integrated codebase. 1306KAME tree ships with 2292bis headers. 1307*BSD-integrated codebase implements either RFC2292, or 2292bis, API. 1308see "COVERAGE" document for detailed implementation status. 1309 1310Here are couple of issues to mention: 1311- *BSD-integrated binaries, compiled for RFC2292, will work on KAME kernel. 1312 For example, OpenBSD 2.7 /sbin/rtsol will work on KAME/openbsd kernel. 1313- KAME binaries, compiled using 2292bis, will not work on *BSD-integrated 1314 kenrel. For example, KAME /usr/local/v6/sbin/rtsol will not work on 1315 OpenBSD 2.7 kernel. 1316- 2292bis API is not compatible with RFC2292 API. 2292bis #define symbols 1317 conflict with RFC2292 symbols. Therefore, if you compile programs that 1318 assume RFC2292 API, the compilation itself goes fine, however, the compiled 1319 binary will not work correctly. The problem is not KAME issue, but API 1320 issue. For example, Solaris 8 implements 2292bis API. If you compile 1321 RFC2292-based code on Solaris 8, the binary can behave strange. 1322 1323There are few (or couple of) incompatible behavior in RFC2292 binary backward 1324compatibility support in KAME tree. To enumerate: 1325- Type 0 routing header lacks support for strict/loose bitmap. 1326 Even if we see packets with "strict" bit set, those bits will not be made 1327 visible to the userland. 1328 Background: RFC2292 document is based on RFC1883 IPv6, and it uses 1329 strict/loose bitmap. 2292bis document is based on RFC2460 IPv6, and it has 1330 no strict/loose bitmap (it was removed from RFC2460). KAME tree obeys 1331 RFC2460 IPv6, and lacks support for strict/loose bitmap. 1332 13332. Network Drivers 1334 1335KAME requires three items to be added into the standard drivers: 1336 1337(1) mbuf clustering requirement. In this stable release, we changed 1338 MINCLSIZE into MHLEN+1 for all the operating systems in order to make 1339 all the drivers behave as we expect. 1340 1341(2) multicast. If "ifmcstat" yields no multicast group for a 1342 interface, that interface has to be patched. 1343 1344To avoid troubles, we suggest you to comment out the device drivers 1345for unsupported/unnecessary cards, from the kernel configuration file. 1346If you accidentally enable unsupported drivers, some of the userland 1347tools may not work correctly (routing daemons are typical example). 1348 1349In the following sections, "official support" means that KAME developers 1350are using that ethernet card/driver frequently. 1351 1352(NOTE: In the past we required all pcmcia drivers to have a call to 1353in6_ifattach(). We have no such requirement any more) 1354 13552.1 FreeBSD 2.2.x-RELEASE 1356 1357Here is a list of FreeBSD 2.2.x-RELEASE drivers and its conditions: 1358 1359 driver mbuf(1) multicast(2) official support? 1360 --- --- --- --- 1361 (Ethernet) 1362 ar looks ok - - 1363 cnw ok ok yes (*) 1364 ed ok ok yes 1365 ep ok ok yes 1366 fe ok ok yes 1367 sn looks ok - - (*) 1368 vx looks ok - - 1369 wlp ok ok - (*) 1370 xl ok ok yes 1371 zp ok ok - 1372 (FDDI) 1373 fpa looks ok ? - 1374 (ATM) 1375 en ok ok yes 1376 (Serial) 1377 lp ? - not work 1378 sl ? - not work 1379 sr looks ok ok - (**) 1380 1381You may want to add an invocation of "rtsol" in "/etc/pccard_ether", 1382if you are using notebook computers and PCMCIA ethernet card. 1383 1384(*) These drivers are distributed with PAO (http://www.jp.freebsd.org/PAO/). 1385 1386(**) There was some report says that, if you make sr driver up and down and 1387then up, the kernel may hang up. We have disabled frame-relay support from 1388sr driver and after that this looks to be working fine. If you need 1389frame-relay support to come back, please contact KAME developers. 1390 13912.2 BSD/OS 3.x 1392 1393The following lists BSD/OS 3.x device drivers and its conditions: 1394 1395 driver mbuf(1) multicast(2) official support? 1396 --- --- --- --- 1397 (Ethernet) 1398 cnw ok ok yes 1399 de ok ok - 1400 df ok ok - 1401 eb ok ok - 1402 ef ok ok yes 1403 exp ok ok - 1404 mz ok ok yes 1405 ne ok ok yes 1406 we ok ok - 1407 (FDDI) 1408 fpa ok ok - 1409 (ATM) 1410 en maybe ok - 1411 (Serial) 1412 ntwo ok ok yes 1413 sl ? - not work 1414 appp ? - not work 1415 1416You may want to use "@insert" directive in /etc/pccard.conf to invoke 1417"rtsol" command right after dynamic insertion of PCMCIA ethernet cards. 1418 14192.3 NetBSD 1420 1421The following table lists the network drivers we have tried so far. 1422 1423 driver mbuf(1) multicast(2) official support? 1424 --- --- --- --- 1425 (Ethernet) 1426 awi pcmcia/i386 ok ok - 1427 bah zbus/amiga NG(*) 1428 cnw pcmcia/i386 ok ok yes 1429 ep pcmcia/i386 ok ok - 1430 le sbus/sparc ok ok yes 1431 ne pci/i386 ok ok yes 1432 ne pcmcia/i386 ok ok yes 1433 wi pcmcia/i386 ok ok yes 1434 (ATM) 1435 en pci/i386 ok ok - 1436 1437(*) This may need some fix, but I'm not sure what arcnet interfaces assume... 1438 14392.4 FreeBSD 3.x-RELEASE 1440 1441Here is a list of FreeBSD 3.x-RELEASE drivers and its conditions: 1442 1443 driver mbuf(1) multicast(2) official support? 1444 --- --- --- --- 1445 (Ethernet) 1446 cnw ok ok -(*) 1447 ed ? ok - 1448 ep ok ok - 1449 fe ok ok yes 1450 fxp ?(**) 1451 lnc ? ok - 1452 sn ? ? -(*) 1453 wi ok ok yes 1454 xl ? ok - 1455 1456(*) These drivers are distributed with PAO as PAO3 1457 (http://www.jp.freebsd.org/PAO/). 1458(**) there are trouble reports with multicast filter initialization. 1459 1460More drivers will just simply work on KAME FreeBSD 3.x-RELEASE but have not 1461been checked yet. 1462 14632.5 FreeBSD 4.x-RELEASE 1464 1465Here is a list of FreeBSD 4.x-RELEASE drivers and its conditions: 1466 1467 driver multicast 1468 --- --- 1469 (Ethernet) 1470 lnc/vmware ok 1471 14722.6 OpenBSD 2.x 1473 1474Here is a list of OpenBSD 2.x drivers and its conditions: 1475 1476 driver mbuf(1) multicast(2) official support? 1477 --- --- --- --- 1478 (Ethernet) 1479 de pci/i386 ok ok yes 1480 fxp pci/i386 ?(*) 1481 le sbus/sparc ok ok yes 1482 ne pci/i386 ok ok yes 1483 ne pcmcia/i386 ok ok yes 1484 wi pcmcia/i386 ok ok yes 1485 1486(*) There seem to be some problem in driver, with multicast filter 1487configuration. This happens with certain revision of chipset on the card. 1488Should be fixed by now by workaround in sys/net/if.c, but still not sure. 1489 14902.7 BSD/OS 4.x 1491 1492The following lists BSD/OS 4.x device drivers and its conditions: 1493 1494 driver mbuf(1) multicast(2) official support? 1495 --- --- --- --- 1496 (Ethernet) 1497 de ok ok yes 1498 exp (*) 1499 1500You may want to use "@insert" directive in /etc/pccard.conf to invoke 1501"rtsol" command right after dynamic insertion of PCMCIA ethernet cards. 1502 1503(*) exp driver has serious conflict with KAME initialization sequence. 1504A workaround is committed into sys/i386/pci/if_exp.c, and should be okay by now. 1505 15063. Translator 1507 1508We categorize IPv4/IPv6 translator into 4 types. 1509 1510Translator A --- It is used in the early stage of transition to make 1511it possible to establish a connection from an IPv6 host in an IPv6 1512island to an IPv4 host in the IPv4 ocean. 1513 1514Translator B --- It is used in the early stage of transition to make 1515it possible to establish a connection from an IPv4 host in the IPv4 1516ocean to an IPv6 host in an IPv6 island. 1517 1518Translator C --- It is used in the late stage of transition to make it 1519possible to establish a connection from an IPv4 host in an IPv4 island 1520to an IPv6 host in the IPv6 ocean. 1521 1522Translator D --- It is used in the late stage of transition to make it 1523possible to establish a connection from an IPv6 host in the IPv6 ocean 1524to an IPv4 host in an IPv4 island. 1525 1526KAME provides an TCP relay translator for category A. This is called 1527"FAITH". We also provide IP header translator for category A. 1528 15293.1 FAITH TCP relay translator 1530 1531FAITH system uses TCP relay daemon called "faithd" helped by the KAME kernel. 1532FAITH will reserve an IPv6 address prefix, and relay TCP connection 1533toward that prefix to IPv4 destination. 1534 1535For example, if the reserved IPv6 prefix is 3ffe:0501:0200:ffff::, and 1536the IPv6 destination for TCP connection is 3ffe:0501:0200:ffff::163.221.202.12, 1537the connection will be relayed toward IPv4 destination 163.221.202.12. 1538 1539 destination IPv4 node (163.221.202.12) 1540 ^ 1541 | IPv4 tcp toward 163.221.202.12 1542 FAITH-relay dual stack node 1543 ^ 1544 | IPv6 TCP toward 3ffe:0501:0200:ffff::163.221.202.12 1545 source IPv6 node 1546 1547faithd must be invoked on FAITH-relay dual stack node. 1548 1549For more details, consult kame/kame/faithd/README and 1550draft-ietf-ngtrans-tcpudp-relay-04.txt. 1551 15523.2 IPv6-to-IPv4 header translator 1553 1554(to be written) 1555 15564. IPsec 1557 1558IPsec is implemented as the following three components. 1559 1560(1) Policy Management 1561(2) Key Management 1562(3) AH, ESP and IPComp handling in kernel 1563 1564Note that KAME/OpenBSD does NOT include support for KAME IPsec code, 1565as OpenBSD team has their home-brew IPsec stack and they have no plan 1566to replace it. IPv6 support for IPsec is, therefore, lacking on KAME/OpenBSD. 1567 1568http://www.netbsd.org/Documentation/network/ipsec/ has more information 1569including usage examples. 1570 15714.1 Policy Management 1572 1573The kernel implements experimental policy management code. There are two way 1574to manage security policy. One is to configure per-socket policy using 1575setsockopt(3). In this cases, policy configuration is described in 1576ipsec_set_policy(3). The other is to configure kernel packet filter-based 1577policy using PF_KEY interface, via setkey(8). 1578 1579The policy entry will be matched in order. The order of entries makes 1580difference in behavior. 1581 15824.2 Key Management 1583 1584The key management code implemented in this kit (sys/netkey) is a 1585home-brew PFKEY v2 implementation. This conforms to RFC2367. 1586 1587The home-brew IKE daemon, "racoon" is included in the kit (kame/kame/racoon, 1588or usr.sbin/racoon). 1589Basically you'll need to run racoon as daemon, then setup a policy 1590to require keys (like ping -P 'out ipsec esp/transport//use'). 1591The kernel will contact racoon daemon as necessary to exchange keys. 1592 1593In IKE spec, there's ambiguity about interpretation of "tunnel" proposal. 1594For example, if we would like to propose the use of following packet: 1595 IP AH ESP IP payload 1596some implementation proposes it as "AH transport and ESP tunnel", since 1597this is more logical from packet construction point of view. Some 1598implementation proposes it as "AH tunnel and ESP tunnel". 1599Racoon follows the former route. 1600This raises real interoperability issue. We hope this to be resolved quickly. 1601 16024.3 AH and ESP handling 1603 1604IPsec module is implemented as "hooks" to the standard IPv4/IPv6 1605processing. When sending a packet, ip{,6}_output() checks if ESP/AH 1606processing is required by checking if a matching SPD (Security 1607Policy Database) is found. If ESP/AH is needed, 1608{esp,ah}{4,6}_output() will be called and mbuf will be updated 1609accordingly. When a packet is received, {esp,ah}4_input() will be 1610called based on protocol number, i.e. (*inetsw[proto])(). 1611{esp,ah}4_input() will decrypt/check authenticity of the packet, 1612and strips off daisy-chained header and padding for ESP/AH. It is 1613safe to strip off the ESP/AH header on packet reception, since we 1614will never use the received packet in "as is" form. 1615 1616By using ESP/AH, TCP4/6 effective data segment size will be affected by 1617extra daisy-chained headers inserted by ESP/AH. Our code takes care of 1618the case. 1619 1620Basic crypto functions can be found in directory "sys/crypto". ESP/AH 1621transform are listed in {esp,ah}_core.c with wrapper functions. If you 1622wish to add some algorithm, add wrapper function in {esp,ah}_core.c, and 1623add your crypto algorithm code into sys/crypto. 1624 1625Tunnel mode works basically fine, but comes with the following restrictions: 1626- You cannot run routing daemon across IPsec tunnel, since we do not model 1627 IPsec tunnel as pseudo interfaces. 1628- Authentication model for AH tunnel must be revisited. We'll need to 1629 improve the policy management engine, eventually. 1630- Path MTU discovery does not work across IPv6 IPsec tunnel gateway due to 1631 insufficient code. 1632 1633AH specificaton does not talk much about "multiple AH on a packet" case. 1634We incrementally compute AH checksum, from inside to outside. Also, we 1635treat inner AH to be immutable. 1636For example, if we are to create the following packet: 1637 IP AH1 AH2 AH3 payload 1638we do it incrementally. As a result, we get crypto checksums like below: 1639 AH3 has checksum against "IP AH3' payload". 1640 where AH3' = AH3 with checksum field filled with 0. 1641 AH2 has checksum against "IP AH2' AH3 payload". 1642 AH1 has checksum against "IP AH1' AH2 AH3 payload", 1643Also note that AH3 has the smallest sequence number, and AH1 has the largest 1644sequence number. 1645 1646To avoid traffic analysis on shorter packets, ESP output logic supports 1647random length padding. By setting net.inet.ipsec.esp_randpad (or 1648net.inet6.ipsec6.esp_randpad) to positive value N, you can ask the kernel 1649to randomly pad packets shorter than N bytes, to random length smaller than 1650or equal to N. Note that N does not include ESP authentication data length. 1651Also note that the random padding is not included in TCP segment 1652size computation. Negative value will turn off the functionality. 1653Recommeded value for N is like 128, or 256. If you use a too big number 1654as N, you may experience inefficiency due to fragmented packtes. 1655 16564.4 IPComp handling 1657 1658IPComp stands for IP payload compression protocol. This is aimed for 1659payload compression, not the header compression like PPP VJ compression. 1660This may be useful when you are using slow serial link (say, cell phone) 1661with powerful CPU (well, recent notebook PCs are really powerful...). 1662The protocol design of IPComp is very similar to IPsec, though it was 1663defined separately from IPsec itself. 1664 1665Here are some points to be noted: 1666- IPComp is treated as part of IPsec protocol suite, and SPI and 1667 CPI space is unified. Spec says that there's no relationship 1668 between two so they are assumed to be separate in specs. 1669- IPComp association (IPCA) is kept in SAD. 1670- It is possible to use well-known CPI (CPI=2 for DEFLATE for example), 1671 for outbound/inbound packet, but for indexing purposes one element from 1672 SPI/CPI space will be occupied anyway. 1673- pfkey is modified to support IPComp. However, there's no official 1674 SA type number assignment yet. Portability with other IPComp 1675 stack is questionable (anyway, who else implement IPComp on UN*X?). 1676- Spec says that IPComp output processing must be performed before AH/ESP 1677 output processing, to achieve better compression ratio and "stir" data 1678 stream before encryption. The most meaningful processing order is: 1679 (1) compress payload by IPComp, (2) encrypt payload by ESP, then (3) attach 1680 authentication data by AH. 1681 However, with manual SPD setting, you are able to violate the ordering 1682 (KAME code is too generic, maybe). Also, it is just okay to use IPComp 1683 alone, without AH/ESP. 1684- Though the packet size can be significantly decreased by using IPComp, no 1685 special consideration is made about path MTU (spec talks nothing about MTU 1686 consideration). IPComp is designed for serial links, not ethernet-like 1687 medium, it seems. 1688- You can change compression ratio on outbound packet, by changing 1689 deflate_policy in sys/netinet6/ipcomp_core.c. You can also change outbound 1690 history buffer size by changing deflate_window_out in the same source code. 1691 (should it be sysctl accessible, or per-SAD configurable?) 1692- Tunnel mode IPComp is not working right. KAME box can generate tunnelled 1693 IPComp packet, however, cannot accept tunneled IPComp packet. 1694- You can negotiate IPComp association with racoon IKE daemon. 1695- KAME code does not attach Adler32 checksum to compressed data. 1696 see ipsec wg mailing list discussion in Jan 2000 for details. 1697 16984.5 Conformance to RFCs and IDs 1699 1700The IPsec code in the kernel conforms (or, tries to conform) to the 1701following standards: 1702 "old IPsec" specification documented in rfc182[5-9].txt 1703 "new IPsec" specification documented in: 1704 rfc240[1-6].txt rfc241[01].txt rfc2451.txt 1705 draft-mcdonald-simple-ipsec-api-01.txt 1706 (expired, available in ftp://ftp.kame.net/pub/internet-drafts/) 1707 draft-ietf-ipsec-ciph-aes-cbc-00.txt 1708 IPComp: 1709 RFC2393: IP Payload Compression Protocol (IPComp) 1710IKE specifications (rfc240[7-9].txt) are implemented in userland 1711as "racoon" IKE daemon. 1712 1713Currently supported algorithms are: 1714 old IPsec AH 1715 null crypto checksum (no document, just for debugging) 1716 keyed MD5 with 128bit crypto checksum (rfc1828.txt) 1717 keyed SHA1 with 128bit crypto checksum (no document) 1718 HMAC MD5 with 128bit crypto checksum (rfc2085.txt) 1719 HMAC SHA1 with 128bit crypto checksum (no document) 1720 old IPsec ESP 1721 null encryption (no document, similar to rfc2410.txt) 1722 DES-CBC mode (rfc1829.txt) 1723 new IPsec AH 1724 null crypto checksum (no document, just for debugging) 1725 keyed MD5 with 96bit crypto checksum (no document) 1726 keyed SHA1 with 96bit crypto checksum (no document) 1727 HMAC MD5 with 96bit crypto checksum (rfc2403.txt 1728 HMAC SHA1 with 96bit crypto checksum (rfc2404.txt) 1729 HMAC SHA2-256 with 96bit crypto checksum (no document) 1730 HMAC SHA2-384 with 96bit crypto checksum (no document) 1731 HMAC SHA2-512 with 96bit crypto checksum (no document) 1732 new IPsec ESP 1733 null encryption (rfc2410.txt) 1734 DES-CBC with derived IV 1735 (draft-ietf-ipsec-ciph-des-derived-01.txt, draft expired) 1736 DES-CBC with explicit IV (rfc2405.txt) 1737 3DES-CBC with explicit IV (rfc2451.txt) 1738 BLOWFISH CBC (rfc2451.txt) 1739 CAST128 CBC (rfc2451.txt) 1740 RIJNDAEL/AES CBC (draft-ietf-ipsec-ciph-aes-cbc-00.txt, 1741 uses IANA-assigned protocol number) 1742 TWOFISH CBC (draft-ietf-ipsec-ciph-aes-cbc-00.txt) 1743 each of the above can be combined with: 1744 ESP authentication with HMAC-MD5(96bit) 1745 ESP authentication with HMAC-SHA1(96bit) 1746 IPComp 1747 RFC2394: IP Payload Compression Using DEFLATE 1748 1749The following algorithms are NOT supported: 1750 old IPsec AH 1751 HMAC MD5 with 128bit crypto checksum + 64bit replay prevention 1752 (rfc2085.txt) 1753 keyed SHA1 with 160bit crypto checksum + 32bit padding (rfc1852.txt) 1754 1755The key/policy management API is based on the following document, with fair 1756amount of extensions: 1757 RFC2367: PF_KEY key management API 1758 17594.6 ECN consideration on IPsec tunnels 1760 1761KAME IPsec implements ECN-friendly IPsec tunnel, described in 1762draft-ietf-ipsec-ecn-02.txt. 1763Normal IPsec tunnel is described in RFC2401. On encapsulation, 1764IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner 1765IP header to outer IP header. On decapsulation outer IP header 1766will be simply dropped. The decapsulation rule is not compatible 1767with ECN, since ECN bit on the outer IP TOS/traffic class field will be 1768lost. 1769To make IPsec tunnel ECN-friendly, we should modify encapsulation 1770and decapsulation procedure. This is described in 1771draft-ietf-ipsec-ecn-02.txt, chapter 3.3. 1772 1773KAME IPsec tunnel implementation can give you three behaviors, by setting 1774net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some value: 1775- RFC2401: no consideration for ECN (sysctl value -1) 1776- ECN forbidden (sysctl value 0) 1777- ECN allowed (sysctl value 1) 1778Note that the behavior is configurable in per-node manner, not per-SA manner 1779(draft-ietf-ipsec-ecn-02 wants per-SA configuration, but it looks too much 1780for me). 1781 1782The behavior is summarized as follows (see source code for more detail): 1783 1784 encapsulate decapsulate 1785 --- --- 1786RFC2401 copy all TOS bits drop TOS bits on outer 1787 from inner to outer. (use inner TOS bits as is) 1788 1789ECN forbidden copy TOS bits except for ECN drop TOS bits on outer 1790 (masked with 0xfc) from inner (use inner TOS bits as is) 1791 to outer. set ECN bits to 0. 1792 1793ECN allowed copy TOS bits except for ECN use inner TOS bits with some 1794 CE (masked with 0xfe) from change. if outer ECN CE bit 1795 inner to outer. is 1, enable ECN CE bit on 1796 set ECN CE bit to 0. the inner. 1797 1798General strategy for configuration is as follows: 1799- if both IPsec tunnel endpoint are capable of ECN-friendly behavior, 1800 you'd better configure both end to "ECN allowed" (sysctl value 1). 1801- if the other end is very strict about TOS bit, use "RFC2401" 1802 (sysctl value -1). 1803- in other cases, use "ECN forbidden" (sysctl value 0). 1804The default behavior is "ECN forbidden" (sysctl value 0). 1805 1806For more information, please refer to: 1807 draft-ietf-ipsec-ecn-02.txt 1808 RFC2481 (Explicit Congestion Notification) 1809 KAME sys/netinet6/{ah,esp}_input.c 1810 1811(Thanks goes to Kenjiro Cho <kjc@csl.sony.co.jp> for detailed analysis) 1812 18134.7 Interoperability 1814 1815IPsec, IPComp (in kernel) and IKE (in userland as "racoon") has been tested 1816at several interoperability test events, and it is known to interoperate 1817with many other implementations well. Also, KAME IPsec has quite wide 1818coverage for IPsec crypto algorithms documented in RFC (we do not cover 1819algorithms with intellectual property issues, though). 1820 1821Here are (some of) platforms we have tested IPsec/IKE interoperability 1822in the past, no particular order. Note that both ends (KAME and 1823others) may have modified their implementation, so use the following 1824list just for reference purposes. 1825 ACC, allied-telesis, Altiga, Ashley-laurent (vpcom.com), BlueSteel, 1826 CISCO IOS, Cryptek, Checkpoint FW-1, Data Fellows (F-Secure), 1827 Ericsson, Fitel, FreeS/WAN, HiFn, HITACHI, IBM AIX, IIJ, Intel Canada, 1828 Intel Packet Protect, MEW NetCocoon, MGCS, Microsoft WinNT/2000, 1829 NAI PGPnet, NetLock, NIST (linux IPsec + plutoplus), NEC IX5000, 1830 Netscreen, NxNetworks, OpenBSD isakmpd, Pivotal, Radguard, RapidStream, 1831 RedCreek, Routerware, RSA, SSH (both IPv4/IPv6), Secure Computing, 1832 Soliton, Sun Solaris8, TIS/NAI Gauntret, Toshiba, VPNet, 1833 Yamaha RT series 1834 1835Here are (some of) platforms we have tested IPComp/IKE interoperability 1836in the past, in no particular order. 1837 IRE, SSH (both IPv4/IPv6), NetLock 1838 1839VPNC (vpnc.org) provides IPsec conformance tests, using KAME and OpenBSD 1840IPsec/IKE implementations. Their test results are available at 1841http://www.vpnc.org/conformance.html, and it may give you more idea 1842about which implementation interoperates with KAME IPsec/IKE implementation. 1843 18445. ALTQ 1845 1846KAME kit includes ALTQ 2.1 code, which supports FreeBSD2, FreeBSD3, 1847NetBSD and OpenBSD. For BSD/OS, ALTQ does not work. 1848ALTQ in KAME supports (or tries to support) IPv6. 1849(actually, ALTQ is developed on KAME repository since ALTQ 2.1 - Jan 2000) 1850 1851ALTQ occupies single character device number. For FreeBSD, it is officially 1852allocated. For OpenBSD and NetBSD, we use the number which is not 1853currently allocated (will eventually get an official number). 1854The character device is enabled for i386 architecture only. To enable and 1855compile ALTQ-ready kernel for other archititectures, take the following steps: 1856- assume that your architecture is FOOBAA. 1857- modify sys/arch/FOOBAA/FOOBAA/conf.c (or somewhere that defines cdevsw), 1858 to include a line for ALTQ. look at sys/arch/i386/i386/conf.c for 1859 example. The major number must be same as i386 case. 1860- copy kernel configuration file (like ALTQ.v6 or GENERIC.v6) from i386, 1861 and modify accordingly. 1862- build a kernel. 1863- before building userland, change netbsd/{lib,usr.sbin,usr.bin}/Makefile 1864 (or openbsd/foobaa) so that it will visit altq-related sub directories. 1865 18666. mobile-ip6 1867 18686.1 KAME node as correspondent node 1869 1870Default installation recognizes home address option (in destination 1871options header). No sub-options are supported. interaction with 1872IPsec, and/or 2292bis API, needs further study. 1873 18746.2 KAME node as home agent/mobile node 1875 1876KAME kit includes Ericsson mobile-ip6 code. The integration is just started 1877(in Feb 2000), and we will need some more time to integrate it better. 1878 1879See kame/mip6config/{QUICKSTART,README_MIP6.txt} for more details. 1880 1881The Ericsson code implements revision 09 of the mobile-ip6 draft. There 1882are other implementations available: 1883 NEC: http://www.6bone.nec.co.jp/mipv6/internal-dist/ (-13 draft) 1884 SFC: http://neo.sfc.wide.ad.jp/~mip6/ (-13 draft) 1885 18867. Coding style 1887 1888The KAME developers basically do not make a bother about coding 1889style. However, there is still some agreement on the style, in order 1890to make the distributed develoment smooth. 1891 1892- the tab character should be 8 columns wide (tabstops are at 8, 16, 24, ... 1893 column). With vi, use ":set ts=8 sw=8". 1894- each line should be within 80 characters. 1895- keep a single open/close bracket in a comment such as in the following 1896 line: 1897 putchar('('); /* ) */ 1898 without this, some vi users would have a hard time to match a pair of 1899 brackets. Although this type of bracket seems clumsy and is even 1900 harmful for some other type of vi users and Emacs users, the 1901 agreement in the KAME developers is to allow it. 1902- add the following line to the head of every KAME-derived file: 1903 /* (dollar)KAME(dollar) */ 1904 where "(dollar)" is the dollar character ($), and around "$" are tabs. 1905 (this is for C. For other language, you should use its own comment 1906 line.) 1907 Once commited to the CVS repository, this line will contain its 1908 version number (see, for example, at the top of this file). This 1909 would make it easy to report a bug. 1910- when creating a new file with the WIDE copyright, tap "make copyright.c" at 1911 the top-level, and use copyright.c as a template. KAME RCS tag will be 1912 included automatically. 1913- when editting a third-party package, keep its own coding style as 1914 much as possible, even if the style does not follow the items above. 1915 1916When you want to contribute something to the KAME project, and if *you 1917do not mind* the agreement, it would be helpful for the project to 1918keep these rules. Note, however, that we would never intend to force 1919you to adopt our rules. We would rather regard your own style, 1920especially when you have a policy about the style. 1921 1922 <end of IMPLEMENTATION> 1923