IMPLEMENTATION (121071) | IMPLEMENTATION (122115) |
---|---|
1# NOTE: this is from original KAME distribution. 2# Some portion of this document is not applicable to the code merged into 3# FreeBSD-current (for example, section 5). 4 | |
5 Implementation Note 6 7 KAME Project 8 http://www.kame.net/ 9 $KAME: IMPLEMENTATION,v 1.216 2001/05/25 07:43:01 jinmei Exp $ | 1 Implementation Note 2 3 KAME Project 4 http://www.kame.net/ 5 $KAME: IMPLEMENTATION,v 1.216 2001/05/25 07:43:01 jinmei Exp $ |
10 $FreeBSD: head/share/doc/IPv6/IMPLEMENTATION 121071 2003-10-13 14:57:41Z ume $ | 6 $FreeBSD: head/share/doc/IPv6/IMPLEMENTATION 122115 2003-11-05 12:00:32Z ume $ |
11 | 7 |
8NOTE: The document tries to describe behaviors/implementation choices 9of the latest KAME/*BSD stack (like KAME/NetBSD 1.5.1). The description 10here may not be applicable to KAME-integrated *BSD releases (like stock 11NetBSD 1.5.1), as we have certain amount of changes between them. Still, 12some of the content can be useful for KAME-integrated *BSD releases. 13 14Table of Contents 15 16 1. IPv6 17 1.1 Conformance 18 1.2 Neighbor Discovery 19 1.3 Scope Zone Index 20 1.3.1 Kernel internal 21 1.3.2 Interaction with API 22 1.3.3 Interaction with users (command line) 23 1.4 Plug and Play 24 1.4.1 Assignment of link-local, and special addresses 25 1.4.2 Stateless address autoconfiguration on hosts 26 1.4.3 DHCPv6 27 1.5 Generic tunnel interface 28 1.6 Address Selection 29 1.6.1 Source Address Selection 30 1.6.2 Destination Address Ordering 31 1.7 Jumbo Payload 32 1.8 Loop prevention in header processing 33 1.9 ICMPv6 34 1.10 Applications 35 1.11 Kernel Internals 36 1.12 IPv4 mapped address and IPv6 wildcard socket 37 1.12.1 KAME/BSDI3 and KAME/FreeBSD228 38 1.12.2 KAME/FreeBSD[34]x 39 1.12.2.1 KAME/FreeBSD[34]x, listening side 40 1.12.2.2 KAME/FreeBSD[34]x, initiating side 41 1.12.3 KAME/NetBSD 42 1.12.3.1 KAME/NetBSD, listening side 43 1.12.3.2 KAME/NetBSD, initiating side 44 1.12.4 KAME/BSDI4 45 1.12.4.1 KAME/BSDI4, listening side 46 1.12.4.2 KAME/BSDI4, initiating side 47 1.12.5 KAME/OpenBSD 48 1.12.5.1 KAME/OpenBSD, listening side 49 1.12.5.2 KAME/OpenBSD, initiating side 50 1.12.6 More issues 51 1.12.7 Interaction with SIIT translator 52 1.13 sockaddr_storage 53 1.14 Invalid addresses on the wire 54 1.15 Node's required addresses 55 1.15.1 Host case 56 1.15.2 Router case 57 1.16 Advanced API 58 1.17 DNS resolver 59 2. Network Drivers 60 2.1 FreeBSD 2.2.x-RELEASE 61 2.2 BSD/OS 3.x 62 2.3 NetBSD 63 2.4 FreeBSD 3.x-RELEASE 64 2.5 FreeBSD 4.x-RELEASE 65 2.6 OpenBSD 2.x 66 2.7 BSD/OS 4.x 67 3. Translator 68 3.1 FAITH TCP relay translator 69 3.2 IPv6-to-IPv4 header translator 70 4. IPsec 71 4.1 Policy Management 72 4.2 Key Management 73 4.3 AH and ESP handling 74 4.4 IPComp handling 75 4.5 Conformance to RFCs and IDs 76 4.6 ECN consideration on IPsec tunnels 77 4.7 Interoperability 78 4.8 Operations with IPsec tunnel mode 79 4.8.1 RFC2401 IPsec tunnel mode approach 80 4.8.2 draft-touch-ipsec-vpn approach 81 5. ALTQ 82 6. Mobile IPv6 83 6.1 KAME node as correspondent node 84 6.2 KAME node as home agent/mobile node 85 6.3 Old Mobile IPv6 code 86 7. Routing table extensions 87 7.1 ART routing table lookup algorithm 88 7.2 Multipath routing support 89 8. Coding style 90 9. Policy on technology with intellectual property right restriction 91 |
|
121. IPv6 13 141.1 Conformance 15 16The KAME kit conforms, or tries to conform, to the latest set of IPv6 17specifications. For future reference we list some of the relevant documents 18below (NOTE: this is not a complete list - this is too hard to maintain...). 19For details please refer to specific chapter in the document, RFCs, manpages --- 11 unchanged lines hidden (view full) --- 31RFC1933: (see RFC2893) 32RFC1981: Path MTU Discovery for IPv6 33RFC2080: RIPng for IPv6 34 * KAME-supplied route6d, bgpd and hroute6d support this. 35RFC2283: Multiprotocol Extensions for BGP-4 36 * so-called "BGP4+". 37 * KAME-supplied bgpd supports this. 38RFC2292: Advanced Sockets API for IPv6 | 921. IPv6 93 941.1 Conformance 95 96The KAME kit conforms, or tries to conform, to the latest set of IPv6 97specifications. For future reference we list some of the relevant documents 98below (NOTE: this is not a complete list - this is too hard to maintain...). 99For details please refer to specific chapter in the document, RFCs, manpages --- 11 unchanged lines hidden (view full) --- 111RFC1933: (see RFC2893) 112RFC1981: Path MTU Discovery for IPv6 113RFC2080: RIPng for IPv6 114 * KAME-supplied route6d, bgpd and hroute6d support this. 115RFC2283: Multiprotocol Extensions for BGP-4 116 * so-called "BGP4+". 117 * KAME-supplied bgpd supports this. 118RFC2292: Advanced Sockets API for IPv6 |
39 * For supported library functions/kernel APIs, see sys/netinet6/ADVAPI. | 119 * see RFC3542 |
40RFC2362: Protocol Independent Multicast-Sparse Mode (PIM-SM) 41 * RFC2362 defines the packet formats and the protcol of PIM-SM. 42RFC2373: IPv6 Addressing Architecture 43 * KAME supports node required addresses, and conforms to the scope 44 requirement. 45RFC2374: An IPv6 Aggregatable Global Unicast Address Format 46 * KAME supports 64-bit length of Interface ID. 47RFC2375: IPv6 Multicast Address Assignments 48 * Userland applications use the well-known addresses assigned in the RFC. 49RFC2428: FTP Extensions for IPv6 and NATs 50 * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428, 51 then RFC1639 if failed. 52RFC2460: IPv6 specification 53RFC2461: Neighbor discovery for IPv6 54 * See 1.2 in this document for details. 55RFC2462: IPv6 Stateless Address Autoconfiguration 56 * See 1.4 in this document for details. 57RFC2463: ICMPv6 for IPv6 specification | 120RFC2362: Protocol Independent Multicast-Sparse Mode (PIM-SM) 121 * RFC2362 defines the packet formats and the protcol of PIM-SM. 122RFC2373: IPv6 Addressing Architecture 123 * KAME supports node required addresses, and conforms to the scope 124 requirement. 125RFC2374: An IPv6 Aggregatable Global Unicast Address Format 126 * KAME supports 64-bit length of Interface ID. 127RFC2375: IPv6 Multicast Address Assignments 128 * Userland applications use the well-known addresses assigned in the RFC. 129RFC2428: FTP Extensions for IPv6 and NATs 130 * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428, 131 then RFC1639 if failed. 132RFC2460: IPv6 specification 133RFC2461: Neighbor discovery for IPv6 134 * See 1.2 in this document for details. 135RFC2462: IPv6 Stateless Address Autoconfiguration 136 * See 1.4 in this document for details. 137RFC2463: ICMPv6 for IPv6 specification |
58 * See 1.8 in this document for details. | 138 * See 1.9 in this document for details. |
59RFC2464: Transmission of IPv6 Packets over Ethernet Networks 60RFC2465: MIB for IPv6: Textual Conventions and General Group 61 * Necessary statistics are gathered by the kernel. Actual IPv6 MIB 62 support is provided as patchkit for ucd-snmp. 63RFC2466: MIB for IPv6: ICMPv6 group 64 * Necessary statistics are gathered by the kernel. Actual IPv6 MIB 65 support is provided as patchkit for ucd-snmp. 66RFC2467: Transmission of IPv6 Packets over FDDI Networks 67RFC2472: IPv6 over PPP 68RFC2492: IPv6 over ATM Networks 69 * only PVC is supported. 70RFC2497: Transmission of IPv6 packet over ARCnet Networks 71RFC2545: Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing | 139RFC2464: Transmission of IPv6 Packets over Ethernet Networks 140RFC2465: MIB for IPv6: Textual Conventions and General Group 141 * Necessary statistics are gathered by the kernel. Actual IPv6 MIB 142 support is provided as patchkit for ucd-snmp. 143RFC2466: MIB for IPv6: ICMPv6 group 144 * Necessary statistics are gathered by the kernel. Actual IPv6 MIB 145 support is provided as patchkit for ucd-snmp. 146RFC2467: Transmission of IPv6 Packets over FDDI Networks 147RFC2472: IPv6 over PPP 148RFC2492: IPv6 over ATM Networks 149 * only PVC is supported. 150RFC2497: Transmission of IPv6 packet over ARCnet Networks 151RFC2545: Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing |
72RFC2553: Basic Socket Interface Extensions for IPv6 73 * IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind 74 socket (3.8) are, 75 - supported and turned on by default on KAME/FreeBSD[34]x 76 and KAME/BSDI4, 77 - supported but turned off by default on KAME/NetBSD, 78 - not supported on KAME/FreeBSD228, KAME/OpenBSD and KAME/BSDI3. 79 see 1.12 in this document for details. | 152RFC2553: (see RFC3493) |
80RFC2671: Extension Mechanisms for DNS (EDNS0) 81 * see USAGE for how to use it. 82 * not supported on kame/freebsd4 and kame/bsdi4. 83RFC2673: Binary Labels in the Domain Name System 84 * KAME/bsdi4 supports A6, DNAME and binary label to some extent. 85 * KAME apps/bind8 repository has resolver library with partial A6, DNAME 86 and binary label support. 87RFC2675: IPv6 Jumbograms --- 17 unchanged lines hidden (view full) --- 105 See 1.5 in this document for details. 106RFC2894: Router renumbering for IPv6 107RFC3041: Privacy Extensions for Stateless Address Autoconfiguration in IPv6 108RFC3056: Connection of IPv6 Domains via IPv4 Clouds 109 * So-called "6to4". 110 * "stf" interface implements it. Be sure to read 111 draft-itojun-ipv6-transition-abuse-01.txt 112 below before configuring it, there can be security issues. | 153RFC2671: Extension Mechanisms for DNS (EDNS0) 154 * see USAGE for how to use it. 155 * not supported on kame/freebsd4 and kame/bsdi4. 156RFC2673: Binary Labels in the Domain Name System 157 * KAME/bsdi4 supports A6, DNAME and binary label to some extent. 158 * KAME apps/bind8 repository has resolver library with partial A6, DNAME 159 and binary label support. 160RFC2675: IPv6 Jumbograms --- 17 unchanged lines hidden (view full) --- 178 See 1.5 in this document for details. 179RFC2894: Router renumbering for IPv6 180RFC3041: Privacy Extensions for Stateless Address Autoconfiguration in IPv6 181RFC3056: Connection of IPv6 Domains via IPv4 Clouds 182 * So-called "6to4". 183 * "stf" interface implements it. Be sure to read 184 draft-itojun-ipv6-transition-abuse-01.txt 185 below before configuring it, there can be security issues. |
113draft-ietf-ipngwg-icmp-name-lookups-07: IPv6 Name Lookups Through ICMP 114draft-ietf-dhc-dhcpv6-15.txt: DHCPv6 115draft-ietf-dhc-dhcpv6exts-12.txt: Extensions for DHCPv6 116 * kame/dhcp6 has test implementation, which will not be compiled in 117 default compilation. 118 * 15/12 drafts are not explicit about padding and string termination. 119 at IETF48, the author confirmed that there's no padding/termination 120 (and extensions can appear unaligned). our code follows the comment. 121draft-itojun-ipv6-tcp-to-anycast-00.txt: 122 Disconnecting TCP connection toward IPv6 anycast address 123draft-ietf-ipngwg-rfc2553bis-03.txt: 124 Basic Socket Interface Extensions for IPv6 (revised) 125draft-ietf-ipngwg-rfc2292bis-02.txt: 126 Advanced Sockets API for IPv6 (revised) | 186RFC3152: Delegation of IP6.ARPA 187 * libinet6 resolvers contained in the KAME snaps support to use 188 the ip6.arpa domain (with the nibble format) for IPv6 reverse 189 lookups. 190RFC3484: Default Address Selection for IPv6 191 * the selection algorithm for both source and destination addresses 192 is implemented based on the RFC, though some rules are still omitted. 193RFC3493: Basic Socket Interface Extensions for IPv6 194 * IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind 195 socket (3.8) are, 196 - supported and turned on by default on KAME/FreeBSD[34] 197 and KAME/BSDI4, 198 - supported but turned off by default on KAME/NetBSD and KAME/FreeBSD5, 199 - not supported on KAME/FreeBSD228, KAME/OpenBSD and KAME/BSDI3. 200 see 1.12 in this document for details. 201RFC3542: Advanced Sockets API for IPv6 (revised) 202 * For supported library functions/kernel APIs, see sys/netinet6/ADVAPI. |
127 * Some of the updates in the draft are not implemented yet. See 128 TODO.2292bis for more details. | 203 * Some of the updates in the draft are not implemented yet. See 204 TODO.2292bis for more details. |
129draft-ietf-mobileip-ipv6-13.txt: Mobility Support in IPv6 130 * See section 6. | 205draft-ietf-ipngwg-icmp-name-lookups-09: IPv6 Name Lookups Through ICMP |
131draft-ietf-ngtrans-tcpudp-relay-04.txt: 132 An IPv6-to-IPv4 transport relay translator 133 * FAITH tcp relay translator (faithd) implements this. See 3.1 for more 134 details. 135draft-ietf-ipngwg-router-selection-01.txt: 136 Default Router Preferences and More-Specific Routes 137 * router-side only. 138draft-ietf-ipngwg-scoping-arch-02.txt: 139 The architecture, text representation, and usage of IPv6 140 scoped addresses. 141 * some part of the documentation (especially about the routing 142 model) is not supported yet. 143draft-ietf-pim-sm-v2-new-02.txt 144 A revised version of RFC2362, which includes the IPv6 specific 145 packet format and protocol descriptions. 146draft-ietf-dnsext-mdns-00.txt: Multicast DNS 147 * kame/mdnsd has test implementation, which will not be built in 148 default compilation. The draft will experience a major change in the 149 near future, so don't rely upon it. | 206draft-ietf-ngtrans-tcpudp-relay-04.txt: 207 An IPv6-to-IPv4 transport relay translator 208 * FAITH tcp relay translator (faithd) implements this. See 3.1 for more 209 details. 210draft-ietf-ipngwg-router-selection-01.txt: 211 Default Router Preferences and More-Specific Routes 212 * router-side only. 213draft-ietf-ipngwg-scoping-arch-02.txt: 214 The architecture, text representation, and usage of IPv6 215 scoped addresses. 216 * some part of the documentation (especially about the routing 217 model) is not supported yet. 218draft-ietf-pim-sm-v2-new-02.txt 219 A revised version of RFC2362, which includes the IPv6 specific 220 packet format and protocol descriptions. 221draft-ietf-dnsext-mdns-00.txt: Multicast DNS 222 * kame/mdnsd has test implementation, which will not be built in 223 default compilation. The draft will experience a major change in the 224 near future, so don't rely upon it. |
150draft-itojun-ipv6-transition-abuse-02.txt: | 225draft-itojun-ipv6-tcp-to-anycast-01.txt: 226 Disconnecting TCP connection toward IPv6 anycast address 227draft-itojun-ipv6-transition-abuse-01.txt: |
151 Possible abuse against IPv6 transition technologies (expired) 152 * KAME does not implement RFC1933/2893 automatic tunnel. 153 * "stf" interface implements some address filters. Refer to stf(4) 154 for details. Since there's no way to make 6to4 interface 100% secure, 155 we do not include "stf" interface into GENERIC.v6 compilation. 156 * kame/openbsd completely disables IPv4 mapped address support. 157 * kame/netbsd makes IPv4 mapped address support off by default. 158 * See section 1.12.6 and 1.14 for more details. | 228 Possible abuse against IPv6 transition technologies (expired) 229 * KAME does not implement RFC1933/2893 automatic tunnel. 230 * "stf" interface implements some address filters. Refer to stf(4) 231 for details. Since there's no way to make 6to4 interface 100% secure, 232 we do not include "stf" interface into GENERIC.v6 compilation. 233 * kame/openbsd completely disables IPv4 mapped address support. 234 * kame/netbsd makes IPv4 mapped address support off by default. 235 * See section 1.12.6 and 1.14 for more details. |
159draft-itojun-ipv6-tclass-api-02.txt: Socket API for IPv6 traffic class field | |
160draft-itojun-ipv6-flowlabel-api-01.txt: Socket API for IPv6 flow label field 161 * no consideration is made against the use of routing headers and such. 162 1631.2 Neighbor Discovery 164 165Neighbor Discovery is fairly stable. Currently Address Resolution, 166Duplicated Address Detection, and Neighbor Unreachability Detection 167are supported. In the near future we will be adding Unsolicited Neighbor --- 154 unchanged lines hidden (view full) --- 322little code change. 323 3241.3.2 Interaction with API 325 326There are several candidates of API to deal with scoped addresses 327without ambiguity. 328 329The IPV6_PKTINFO ancillary data type or socket option defined in the | 236draft-itojun-ipv6-flowlabel-api-01.txt: Socket API for IPv6 flow label field 237 * no consideration is made against the use of routing headers and such. 238 2391.2 Neighbor Discovery 240 241Neighbor Discovery is fairly stable. Currently Address Resolution, 242Duplicated Address Detection, and Neighbor Unreachability Detection 243are supported. In the near future we will be adding Unsolicited Neighbor --- 154 unchanged lines hidden (view full) --- 398little code change. 399 4001.3.2 Interaction with API 401 402There are several candidates of API to deal with scoped addresses 403without ambiguity. 404 405The IPV6_PKTINFO ancillary data type or socket option defined in the |
330advanced API (RFC2292 or draft-ietf-ipngwg-rfc2292bis-xx) can specify | 406advanced API (RFC2292 or RFC3542) can specify |
331the outgoing interface of a packet. Similarly, the IPV6_PKTINFO or 332IPV6_RECVPKTINFO socket options tell kernel to pass the incoming 333interface to user applications. 334 335These options are enough to disambiguate scoped addresses of an 336incoming packet, because we can uniquely identify the corresponding 337zone of the scoped address(es) by the incoming interface. However, 338they are too strong for outgoing packets. For example, consider a 339multi-sited node and suppose that more than one interface of the node 340belongs to a same site. When we want to send a packet to the site, 341we can only specify one of the interfaces for the outgoing packet with 342these options; we cannot just say "send the packet to (one of the 343interfaces of) the site." 344 345Another kind of candidates is to use the sin6_scope_id member in the | 407the outgoing interface of a packet. Similarly, the IPV6_PKTINFO or 408IPV6_RECVPKTINFO socket options tell kernel to pass the incoming 409interface to user applications. 410 411These options are enough to disambiguate scoped addresses of an 412incoming packet, because we can uniquely identify the corresponding 413zone of the scoped address(es) by the incoming interface. However, 414they are too strong for outgoing packets. For example, consider a 415multi-sited node and suppose that more than one interface of the node 416belongs to a same site. When we want to send a packet to the site, 417we can only specify one of the interfaces for the outgoing packet with 418these options; we cannot just say "send the packet to (one of the 419interfaces of) the site." 420 421Another kind of candidates is to use the sin6_scope_id member in the |
346sockaddr_in6 structure, defined in RFC2553 and 347draft-ietf-ipngwg-rfc2553bis-xx.txt. The KAME kernel interprets the 348sin6_scope_id field properly in order to disambiguate scoped | 422sockaddr_in6 structure, defined in RFC2553. The KAME kernel 423interprets the sin6_scope_id field properly in order to disambiguate scoped |
349addresses. For example, if an application passes a sockaddr_in6 350structure that has a non-zero sin6_scope_id value to the sendto(2) 351system call, the kernel should send the packet to the appropriate zone 352according to the sin6_scope_id field. Similarly, when the source or 353the destination address of an incoming packet is a scoped one, the 354kernel should detect the correct zone identifier based on the address 355and the receiving interface, fill the identifier in the sin6_scope_id 356field of a sockaddr_in6 structure, and then pass the packet to an --- 24 unchanged lines hidden (view full) --- 381will need to manipulate the "embedded" zone index. These programs use 382routing sockets and ioctls (like SIOCGIFADDR_IN6) and the kernel API 383will return IPv6 addresses with the 2nd 16bit-word filled in. The 384APIs are for manipulating kernel internal structure. Programs that 385use these APIs have to be prepared about differences in kernels 386anyway. 387 388getaddrinfo(3) and getnameinfo(3) support an extended numeric IPv6 | 424addresses. For example, if an application passes a sockaddr_in6 425structure that has a non-zero sin6_scope_id value to the sendto(2) 426system call, the kernel should send the packet to the appropriate zone 427according to the sin6_scope_id field. Similarly, when the source or 428the destination address of an incoming packet is a scoped one, the 429kernel should detect the correct zone identifier based on the address 430and the receiving interface, fill the identifier in the sin6_scope_id 431field of a sockaddr_in6 structure, and then pass the packet to an --- 24 unchanged lines hidden (view full) --- 456will need to manipulate the "embedded" zone index. These programs use 457routing sockets and ioctls (like SIOCGIFADDR_IN6) and the kernel API 458will return IPv6 addresses with the 2nd 16bit-word filled in. The 459APIs are for manipulating kernel internal structure. Programs that 460use these APIs have to be prepared about differences in kernels 461anyway. 462 463getaddrinfo(3) and getnameinfo(3) support an extended numeric IPv6 |
389syntax, as documented in draft-ietf-ipngwg-rfc2553bis-xx.txt. You can | 464syntax, as documented in draft-ietf-ipv6-scoping-arch-xx.txt. You can |
390specify the outgoing link, by using the name of the outgoing interface 391as the link, like "fe80::1%ne0" (again, note that we assume there is 3921-to-1 relationship between links and interfaces.) This way you will 393be able to specify a link-local scoped address without much trouble. 394 395Other APIs like inet_pton(3) and inet_ntop(3) are inherently 396unfriendly with scoped addresses, since they are unable to annotate 397addresses with zone identifier. --- 9 unchanged lines hidden (view full) --- 407the IPv6 default route by hand, you can type like 408 # route add -inet6 default fe80::9876:5432:1234:abcd%ne0 409(Although we suggest you to run dynamic routing instead of static 410routes, in order to avoid configuration mistakes.) 411 412Some applications have command line options for specifying an 413appropriate zone of a scoped address (like "ping6 -I ne0 ff02::1" to 414specify the outgoing interface). However, you can't always expect such | 465specify the outgoing link, by using the name of the outgoing interface 466as the link, like "fe80::1%ne0" (again, note that we assume there is 4671-to-1 relationship between links and interfaces.) This way you will 468be able to specify a link-local scoped address without much trouble. 469 470Other APIs like inet_pton(3) and inet_ntop(3) are inherently 471unfriendly with scoped addresses, since they are unable to annotate 472addresses with zone identifier. --- 9 unchanged lines hidden (view full) --- 482the IPv6 default route by hand, you can type like 483 # route add -inet6 default fe80::9876:5432:1234:abcd%ne0 484(Although we suggest you to run dynamic routing instead of static 485routes, in order to avoid configuration mistakes.) 486 487Some applications have command line options for specifying an 488appropriate zone of a scoped address (like "ping6 -I ne0 ff02::1" to 489specify the outgoing interface). However, you can't always expect such |
415options. Thus, we recommend you to use the extended format described 416above. | 490options. Additionally, specifying the outgoing "interface" is in 491theory an overspecification as a way to specify the outgoing "link" 492(see above). Thus, we recommend you to use the extended format 493described above. This should apply to the case where the outgoing 494interface is specified. |
417 418In any case, when you specify a scoped address to the command line, 419NEVER write the embedded form (such as ff02:1::1 or fe80:2::fedc), 420which should only be used inside the kernel (see Section 1.3.1), and 421is not supposed to work. 422 4231.4 Plug and Play 424 --- 126 unchanged lines hidden (view full) --- 551 552gif can be configured to be ECN-friendly. See 4.5 for ECN-friendliness 553of tunnels, and gif(4) manpage for how to configure. 554 555If you would like to configure an IPv4-in-IPv6 tunnel with gif interface, 556read gif(4) carefully. You may need to remove IPv6 link-local address 557automatically assigned to the gif interface. 558 | 495 496In any case, when you specify a scoped address to the command line, 497NEVER write the embedded form (such as ff02:1::1 or fe80:2::fedc), 498which should only be used inside the kernel (see Section 1.3.1), and 499is not supposed to work. 500 5011.4 Plug and Play 502 --- 126 unchanged lines hidden (view full) --- 629 630gif can be configured to be ECN-friendly. See 4.5 for ECN-friendliness 631of tunnels, and gif(4) manpage for how to configure. 632 633If you would like to configure an IPv4-in-IPv6 tunnel with gif interface, 634read gif(4) carefully. You may need to remove IPv6 link-local address 635automatically assigned to the gif interface. 636 |
5591.6 Source Address Selection | 6371.6 Address Selection |
560 | 638 |
561KAME's source address selection takes care of the following 562conditions: 563- address scope 564- outgoing interface 565- whether an address is deprecated 566- whether an address is temporary (in terms of RFC 3041) 567- prefix matching against the destination | 6391.6.1 Source Address Selection |
568 | 640 |
569Roughly speaking, the selection policy is as follows: 570- always use an address that belongs to the same scope zone as the 571 destination. 572- addresses that have equal or larger scope than the scope of the 573 destination are preferred. 574- a deprecated address is not used in new communications if an 575 alternate (non-deprecated) address is available and has sufficient 576 scope. 577- a temporary address (in terms of RFC 3041 privacy extension) are 578 preferred to a public address. 579- if none of above conditions tie-breaks, addresses assigned on the 580 outgoing interface are preferred. 581- if none of above conditions tie-breaks, one which is longest prefix 582 matching against the destination is preferred as the last resort. | 641The KAME kernel chooses the source address for an outgoing packet 642sent from a user application as follows: |
583 | 643 |
584For instance, ::1 is selected for ff01::1, 585fe80::200:f8ff:fe01:6317%ne0 for fe80::2a0:24ff:feab:839b%ne0. 586To see how longest-matching works, suppose that 5873ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317 588are given on the outgoing interface. Then the former is chosen as the 589source for the destination 3ffe:501:800::1. Note that even if all 590available addresses have smaller scope than the scope of the 591destination, we choose one anyway. For example, if we have link-local 592and site-local addresses only, we choose a site-local addresses for a 593global destination. If the packet is going to break a site boundary, 594the boundary router will return an ICMPv6 destination unreachable 595error with code 2 - beyond scope of source address. | 6441. if the source address is explicitly specified via an IPV6_PKTINFO 645 ancillary data item or the socket option of that name, just use it. 646 Note that this item/option overrides the bound address of the 647 corresponding (datagram) socket. |
596 | 648 |
597The precise desripction of the algorithm is quite complicated. To 598describe the algorithm, we introduce the following notation: | 6492. if the corresponding socket is bound, use the bound address. |
599 | 650 |
600For a given destination D, 601 samescope(D): The set of addresses that have the same scope as D. 602 largerscope(D): The set of addresses that have a larger scope than D. 603 smallerscope(D): The set of addresses that have a smaller scope than D. | 6513. otherwise, the kernel first tries to find the outgoing interface of 652 the packet. If it fails, the source address selection also fails. 653 If the kernel can find an interface, choose the most appropriate 654 address based on the algorithm described in RFC3484. |
604 | 655 |
605For a given set of addresses A, 606 DEP(A): the set of deprecated addresses in A. 607 nonDEP(A): A - DEP(A). | 656 The policy table used in this algorithm is stored in the kernel. 657 To install or view the policy, use the ip6addrctl(8) command. The 658 kernel does not have pre-installed policy. It is expected that the 659 default policy described in the draft should be installed at the 660 bootstrap time using this command. |
608 | 661 |
609For a given set of addresses A, 610 tmp(A): the set of preferred temporary-autoconfigured or 611 manually-configure addresses in A. | 662 This draft allows an implementation to add implementation-specific 663 rules with higher precedence than the rule "Use longest matching 664 prefix." KAME's implementation has the following additional rules 665 (that apply in the appeared order): |
612 | 666 |
613Also, the algorithm assumes that the outgoing interface for the 614destination D is determined. We call the interface "I". | 667 - prefer addresses on alive interfaces, that is, interfaces with 668 the UP flag being on. This rule is particularly useful for 669 routers, since some routing daemons stop advertising prefixes 670 (addresses) on interfaces that have become down. |
615 | 671 |
616The algorithm is as follows. Selection proceeds step by step as 617described; For example, if an address is selected by item 1, item 2 and 618later are not considered at all. | 672 In any case, addresses that break the scope zone of the 673 destination, or addresses whose zone do not contain the outgoing 674 interface are never chosen. |
619 | 675 |
620 0. If there is no address in the same scope zone as D, just give up; 621 the packet will not be sent. 622 1. If we do not prefer temporary addresses, go to 3. 623 Otherwise, and if tmp(samescope(D)) is not empty, 624 then choose an address that is on the interface I. If every 625 address is on I, or every address is on a different interface 626 from I, choose an arbitrary one provided that an address longest 627 matching against D is always preferred. 628 2. If tmp(largerscope(D)) is not empty, 629 then choose an address that has the smallest scope. If more than one 630 address has the smallest scope, choose an arbitrary one provided 631 that addresses on I are always preferred. 632 3. If nonDEP(samescope(D)) is not empty, 633 then apply the same logic as of 1. 634 4. If nonDEP(largerscope(D)) is not empty, 635 then apply the same logic as of 2. 636 5. If we do not prefer temporary addresses, go to 7. 637 Otherwise, and if tmp(DEP(samescope(D))) is not empty, 638 then choose an address that is on the interface I. If every 639 address is on I, or every address is on a different interface 640 from I, choose an arbitrary one provided that an address longest 641 matching against D is always preferred. 642 6. If tmp(DEP(largerscope(D))) is not empty, 643 then choose an address that has the smallest scope. If more than 644 one address has the smallest scope, choose an arbitrary one provided 645 that an address on I is always preferred. 646 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. | 676When the procedure above fails, the kernel usually returns 677EADDRNOTAVAIL to the application. |
663 | 678 |
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. | 679In some cases, the specification explicitly requires the 680implementation to choose a particular source address. The source 681address for a Neighbor Advertisement (NA) message is an example. |
673Under the spec (RFC2461 7.2.2) NA's source should be the target | 682Under 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. | 683address of the corresponding NS's target. In this case we follow the 684spec rather than the above 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 | 685 686If you would like to prohibit the use of deprecated address for some 687reason, configure net.inet6.ip6.use_deprecated to 0. The issue 688related to deprecated address is described in RFC2462 5.5.4 (NOTE: 689there is some debate underway in IETF ipngwg on how to use 690"deprecated" address). 691 |
692As documented in the source address selection document, temporary 693addresses for privacy extension are less preferred to public addresses 694by default. However, for administrators who are particularly aware of 695the privacy, there is a system-wide sysctl(3) variable 696"net.inet6.ip6.prefer_tempaddr". When the variable is set to 697non-zero, the kernel will rather prefer temporary addresses. The 698default value of this variable is 0. 699 7001.6.2 Destination Address Ordering 701 702KAME's getaddrinfo(3) supports the destination address ordering 703algorithm described in RFC3484. Getaddrinfo(3) needs to know the 704source address for each destination address and policy entries 705(described in the previous section) for the source and destination 706addresses. To get the source address, the library function opens a 707UDP socket and tries to connect(2) for the destination. To get the 708policy entry, the function issues sysctl(3). 709 |
|
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 --- 171 unchanged lines hidden (view full) --- 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 | 7101.7 Jumbo Payload 711 712KAME supports the Jumbo Payload hop-by-hop option used to send IPv6 713packets with payloads longer than 65,535 octets. But since currently 714KAME does not support any physical interface whose MTU is more than 71565,535, such payloads can be seen only on the loopback interface(i.e. 716lo0). 717 --- 171 unchanged lines hidden (view full) --- 889all unicast addresses are removed from the interface, the application 890can't send/receive any multicast packets. Moreover, if a new unicast 891address is assigned to the interface, in_mrejoin() must be called. 892KAME's interfaces, however, have ALWAYS one link-local unicast 893address. These extensions have thus not been implemented in KAME. 894 8951.12 IPv4 mapped address and IPv6 wildcard socket 896 |
870RFC2553 describes IPv4 mapped address (3.7) and special behavior | 897RFC2553/3493 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. --- 20 unchanged lines hidden (view full) --- 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 | 898of IPv6 wildcard bind socket (3.8). The spec allows you to: 899- Accept IPv4 connections by AF_INET6 wildcard bind socket. 900- Transmit IPv4 packet over AF_INET6 socket by using special form of 901 the address like ::ffff:10.1.1.1. 902but the spec itself is very complicated and does not specify how the 903socket layer should behave. 904Here we call the former one "listening side" and the latter one "initiating 905side", for reference purposes. --- 20 unchanged lines hidden (view full) --- 926KAME/BSDI4 enabled supported 927KAME/OpenBSD not supported not supported 928 929The following sections will give you more details, and how you can 930configure the behavior. 931 932Comments on listening side: 933 |
907It looks that RFC2553 talks too little on wildcard bind issue, | 934It looks that RFC2553/3493 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 --- 28 unchanged lines hidden (view full) --- 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, | 935specifically on (1) port space issue, (2) failure mode, (3) relationship 936between AF_INET/INET6 wildcard bind like ordering constraint, and (4) behavior 937when conflicting socket is opened/closed. There can be several separate 938interpretation for this RFC which conform to it but behaves differently. 939So, to implement portable application you should assume nothing 940about the behavior in the kernel. Using getaddrinfo() is the safest way. 941Port number space and wildcard bind issues were discussed in detail 942on ipv6imp mailing list, in mid March 1999 and it looks that there's --- 28 unchanged lines hidden (view full) --- 971 Never use gethostby*(), getaddrby*(), inet_*() or getipnodeby*(). 972- If you would like to connect to destination, use getaddrinfo() and try 973 all the destination returned, like telnet does. 974- Some of the IPv6 stack is shipped with buggy getaddrinfo(). Ship a minimal 975 working version with your application and use that as last resort. 976 977If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing 978connection, you will need tweaked implementation in DNS support libraries, |
952as documented in RFC2553 6.1. KAME libinet6 includes the tweak in | 979as documented in RFC2553/3493 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 | 980getipnodebyname(). Note that getipnodebyname() itself is not recommended as 981it does not handle scoped IPv6 addresses at all. For IPv6 name resolution 982getaddrinfo() is the preferred API. getaddrinfo() does not implement the 983tweak. 984 985When writing applications that make outgoing connections, story goes much 986simpler if you treat AF_INET and AF_INET6 as totally separate address family. 987{set,get}sockopt issue goes simpler, DNS issue will be made simpler. We do 988not recommend you to rely upon IPv4 mapped address. 989 9901.12.1 KAME/BSDI3 and KAME/FreeBSD228 991 992The platforms do not support IPv4 mapped address at all (both listening side 993and initiating side). AF_INET6 and AF_INET sockets are totally separated. 994 995Port number space is totally separate between AF_INET and AF_INET6 sockets. 996 997It 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. | 998to RFC2553/3493 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 --- 22 unchanged lines hidden (view full) --- 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 | 999 10001.12.2 KAME/FreeBSD[34]x 1001 1002KAME/FreeBSD3x and KAME/FreeBSD4x use shared tcp4/6 code (from 1003sys/netinet/tcp*) and shared udp4/6 code (from sys/netinet/udp*). 1004They use unified inpcb/in6pcb structure. 1005 10061.12.2.1 KAME/FreeBSD[34]x, listening side --- 22 unchanged lines hidden (view full) --- 10291.12.3 KAME/NetBSD 1030 1031KAME/NetBSD uses shared tcp4/6 code (from sys/netinet/tcp*) and shared 1032udp4/6 code (from sys/netinet/udp*). The implementation is made differently 1033from KAME/FreeBSD[34]x. KAME/NetBSD uses separate inpcb/in6pcb structures, 1034while KAME/FreeBSD[34]x uses merged inpcb structure. 1035 1036It 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. | 1037conformant to RFC2553/3493 section 3.8. It is intentionally turned off by 1038default for security reasons. |
1012 | 1039 |
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). | 1040The platform can be configured to support IPv4 mapped address/special AF_INET6 1041wildcard bind (disabled by default). Kernel behavior can be summarized as 1042follows: 1043- default: special support code will be compiled in, but is disabled by 1044 default. It can be controlled by sysctl (net.inet6.ip6.v6only), 1045 or setsockopt(IPV6_V6ONLY). |
1021- add "INET6_V6ONLY": No special support code for AF_INET6 wildcard socket | 1046- add "INET6_BINDV6ONLY": 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 | 1047 will be compiled in. AF_INET6 sockets and AF_INET sockets are totally 1048 separate. The behavior is similar to what described in 1.12.1. 1049 1050sysctl setting will affect per-socket configuration at in6pcb creation time 1051only. In other words, per-socket configuration will be copied from sysctl 1052configuration at in6pcb creation time. To change per-socket behavior, you 1053must perform setsockopt or reopen the socket. Change in sysctl configuration 1054will not change the behavior or sockets that are already opened. 1055 |
10561.12.3.1 KAME/NetBSD, listening side 1057 |
|
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 | 1058Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following 1059conditions are satisfied: 1060- there's no AF_INET socket that matches the IPv4 connection 1061- the AF_INET6 socket is configured to accept IPv4 traffic, i.e. 1062 getsockopt(IPV6_V6ONLY) returns 0. 1063 1064You cannot bind(2) with IPv4 mapped address. This is a workaround for port 1065number duplicate and other twists. 1066 10671.12.3.2 KAME/NetBSD, initiating side 1068 |
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. | 1069When getsockopt(IPV6_V6ONLY) is 0 for a socket, you can make an outgoing 1070traffic to IPv4 destination over AF_INET6 socket, using IPv4 mapped 1071address destination (::ffff:10.1.1.1). |
1046 | 1072 |
1073When getsockopt(IPV6_V6ONLY) is 1 for a socket, you cannot use IPv4 mapped 1074address for outgoing traffic. 1075 |
|
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 --- 10 unchanged lines hidden (view full) --- 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 | 10761.12.4 KAME/BSDI4 1077 1078KAME/BSDI4 uses NRL-based TCP/UDP stack and inpcb source code, 1079which was derived from NRL IPv6/IPsec stack. We guess it supports IPv4 mapped 1080address and speical AF_INET6 wildcard bind. The implementation is, again, 1081different from other KAME/*BSDs. 1082 10831.12.4.1 KAME/BSDI4, listening side --- 10 unchanged lines hidden (view full) --- 1094KAME/BSDi4 supports connection initiation to IPv4 mapped address 1095(like ::ffff:10.1.1.1). 1096 10971.12.5 KAME/OpenBSD 1098 1099KAME/OpenBSD uses NRL-based TCP/UDP stack and inpcb source code, 1100which was derived from NRL IPv6/IPsec stack. 1101 |
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. | 1102It should be noted that KAME/OpenBSD is not conformant to RFC2553/3493 section 11033.7 and 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. --- 36 unchanged lines hidden (view full) --- 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. | 1104 11051.12.5.1 KAME/OpenBSD, listening side 1106 1107KAME/OpenBSD disables special behavior on AF_INET6 wildcard bind for 1108security reasons (if IPv4 traffic toward AF_INET6 wildcard bind is allowed, 1109access control will become much harder). KAME/BSDI4 uses NRL-based TCP/UDP 1110stack as well, however, the behavior is different due to OpenBSD's security 1111policy. --- 36 unchanged lines hidden (view full) --- 1148 else 1149 error; 1150 It is too much to ask for every body to be careful like this. 1151 The problem is, we are not sure if the above code fragment is perfect for 1152 all situations. 1153- By enabling kernel support for IPv4 mapped address (outgoing direction), 1154 servers on the kernel can be hosed by IPv6 native packet that has IPv4 1155 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. | 1156 draft-itojun-ipv6-transition-abuse-01.txt, draft-cmetz-v6ops-v4mapped-api- 1157 harmful-00.txt, and draft-itojun-v6ops-v4mapped-harmful-01.txt 1158 has more on 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 --- 39 unchanged lines hidden (view full) --- 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 | 1159 1160Due to the above twists, some of KAME userland programs has restrictions on 1161the use of IPv4 mapped addresses: 1162- rshd/rlogind do not accept connections from IPv4 mapped address. 1163 This is to avoid malicious use of IPv4 mapped address in IPv6 native 1164 packet, to bypass source-address based authentication. 1165- ftp/ftpd assume that you are on dual stack network. IPv4 mapped address 1166 will be decoded in userland, and will be passed to AF_INET sockets --- 39 unchanged lines hidden (view full) --- 1206 }; 1207On the contrary, XNET draft defines as follows: 1208 struct sockaddr_storage { 1209 u_char ss_len; /* address length */ 1210 u_char ss_family; /* address family */ 1211 /* and bunch of padding */ 1212 }; 1213 |
1183In December 1999, it was agreed that RFC2553bis should pick the latter (XNET) 1184definition. | 1214In December 1999, it was agreed that RFC2553bis (RFC3493) should pick the 1215latter (XNET) definition. |
1185 1186KAME kit prior to December 1999 used RFC2553 definition. KAME kit after 1187December 1999 (including December) will conform to XNET definition, | 1216 1217KAME kit prior to December 1999 used RFC2553 definition. KAME kit after 1218December 1999 (including December) will conform to XNET definition, |
1188based on RFC2553bis discussion. | 1219based on RFC3493 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 --- 49 unchanged lines hidden (view full) --- 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 | 1220 1221If you look at multiple IPv6 implementations, you will be able to see 1222both definitions. As an userland programmer, the most portable way of 1223dealing with it is to: 1224(1) ensure ss_family and/or ss_len are available on the platform, by using 1225 GNU autoconf, 1226(2) have -Dss_family=__ss_family to unify all occurences (including header 1227 file) into __ss_family, or --- 49 unchanged lines hidden (view full) --- 1277 (2) offlink packets (so routers should not forward them). 1278 KAME implmements (2) already. 1279 1280KAME code is carefully written to avoid such incidents. More specifically, 1281KAME kernel will reject packets with certain source/dstination address in IPv6 1282base header, or IPv6 routing header. Also, KAME default configuration file 1283is written carefully, to avoid those attacks. 1284 |
1254draft-itojun-ipv6-transition-abuse-01.txt talks about more about this. | 1285draft-itojun-ipv6-transition-abuse-01.txt, draft-cmetz-v6ops-v4mapped-api- 1286harmful-00.txt and draft-itojun-v6ops-v4mapped-harmful-01.txt has more on 1287this issue. |
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 --- 32 unchanged lines hidden (view full) --- 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 | 1288 12891.15 Node's required addresses 1290 1291RFC2373 section 2.8 talks about required addresses for an IPv6 1292node. The section talks about how KAME stack manages those required 1293addresses. 1294 12951.15.1 Host case --- 32 unchanged lines hidden (view full) --- 1328 1329Routing daemons will join appropriate multicast groups, as necessary, 1330like ff02::9 for RIPng. 1331 1332Users can join groups by using appropriate system calls like setsockopt(2). 1333 13341.16 Advanced API 1335 |
1303Current KAME kernel implements 2292bis API, documented in 1304draft-ietf-ipngwg-rfc2292bis-xx.txt. It also implements RFC2292 API, | 1336Current KAME kernel implements RFC3542 API. It also implements RFC2292 API, |
1305for backward compatibility purposes with *BSD-integrated codebase. | 1337for backward compatibility purposes with *BSD-integrated codebase. |
1306KAME tree ships with 2292bis headers. 1307*BSD-integrated codebase implements either RFC2292, or 2292bis, API. | 1338KAME tree ships with RFC3542 headers. 1339*BSD-integrated codebase implements either RFC2292, or RFC3542, 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. | 1340see "COVERAGE" document for detailed implementation status. 1341 1342Here are couple of issues to mention: 1343- *BSD-integrated binaries, compiled for RFC2292, will work on KAME kernel. 1344 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 | 1345- KAME binaries, compiled using RFC3542, 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. | 1346 kenrel. For example, KAME /usr/local/v6/sbin/rtsol will not work on 1347 OpenBSD 2.7 kernel. |
1316- 2292bis API is not compatible with RFC2292 API. 2292bis #define symbols | 1348- RFC3542 API is not compatible with RFC2292 API. RFC3542 #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 | 1349 conflict with RFC2292 symbols. Therefore, if you compile programs that 1350 assume RFC2292 API, the compilation itself goes fine, however, the compiled 1351 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 | 1352 issue. For example, Solaris 8 implements RFC3542 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 | 1353 RFC2292-based code on Solaris 8, the binary can behave strange. 1354 1355There are few (or couple of) incompatible behavior in RFC2292 binary backward 1356compatibility support in KAME tree. To enumerate: 1357- Type 0 routing header lacks support for strict/loose bitmap. 1358 Even if we see packets with "strict" bit set, those bits will not be made 1359 visible to the userland. 1360 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 | 1361 strict/loose bitmap. RFC3542 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 | 1362 no strict/loose bitmap (it was removed from RFC2460). KAME tree obeys 1363 RFC2460 IPv6, and lacks support for strict/loose bitmap. 1364 |
1365The RFC3542 documents leave some particular cases unspecified. The 1366KAME implementation treats them as follows: 1367- The IPV6_DONTFRAG and IPV6_RECVPATHMTU socket options for TCP 1368 sockets are ignored. That is, the setsocktopt() call will succeed 1369 but the specified value will have no effect. 1370 13711.17 DNS resolver 1372 1373KAME ships with modified DNS resolver, in libinet6.a. 1374libinet6.a has a comple of extensions against libc DNS resolver: 1375- Can take "options insecure1" and "options insecure2" in /etc/resolv.conf, 1376 which toggles RES_INSECURE[12] option flag bit. 1377- EDNS0 receive buffer size notification support. It can be enabled by 1378 "options edns0" in /etc/resolv.conf. See USAGE for details. 1379- IPv6 transport support (queries/responses over IPv6). Most of BSD official 1380 releases now has it already. 1381- Partial A6 chain chasing/DNAME/bit string label support (KAME/BSDI4). 1382 1383 |
|
13332. Network Drivers 1334 1335KAME requires three items to be added into the standard drivers: 1336 | 13842. Network Drivers 1385 1386KAME requires three items to be added into the standard drivers: 1387 |
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. | 1388(1) (freebsd[234] and bsdi[34] only) mbuf clustering requirement. 1389 In this stable release, we changed MINCLSIZE into MHLEN+1 for all the 1390 operating systems in order to make 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). --- 217 unchanged lines hidden (view full) --- 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 | 1391 1392(2) multicast. If "ifmcstat" yields no multicast group for a 1393 interface, that interface has to be patched. 1394 1395To avoid troubles, we suggest you to comment out the device drivers 1396for unsupported/unnecessary cards, from the kernel configuration file. 1397If you accidentally enable unsupported drivers, some of the userland 1398tools may not work correctly (routing daemons are typical example). --- 217 unchanged lines hidden (view full) --- 1616as OpenBSD team has their home-brew IPsec stack and they have no plan 1617to replace it. IPv6 support for IPsec is, therefore, lacking on KAME/OpenBSD. 1618 1619http://www.netbsd.org/Documentation/network/ipsec/ has more information 1620including usage examples. 1621 16224.1 Policy Management 1623 |
1573The kernel implements experimental policy management code. There are two way | 1624The kernel implements experimental policy management code. There are two ways |
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 --- 9 unchanged lines hidden (view full) --- 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". | 1625to manage security policy. One is to configure per-socket policy using 1626setsockopt(3). In this cases, policy configuration is described in 1627ipsec_set_policy(3). The other is to configure kernel packet filter-based 1628policy using PF_KEY interface, via setkey(8). 1629 1630The policy entry will be matched in order. The order of entries makes 1631difference in behavior. 1632 --- 9 unchanged lines hidden (view full) --- 1642The kernel will contact racoon daemon as necessary to exchange keys. 1643 1644In IKE spec, there's ambiguity about interpretation of "tunnel" proposal. 1645For example, if we would like to propose the use of following packet: 1646 IP AH ESP IP payload 1647some implementation proposes it as "AH transport and ESP tunnel", since 1648this is more logical from packet construction point of view. Some 1649implementation proposes it as "AH tunnel and ESP tunnel". |
1599Racoon follows the former route. | 1650Racoon follows the latter route (previously it followed the former, and 1651the latter interpretation seems to be popular/consensus). |
1600This raises real interoperability issue. We hope this to be resolved quickly. 1601 | 1652This raises real interoperability issue. We hope this to be resolved quickly. 1653 |
1654racoon does not implement byte lifetime for both phase 1 and phase 2 1655(RFC2409 page 35, Life Type = kilobytes). 1656 |
|
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 --- 86 unchanged lines hidden (view full) --- 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: | 16574.3 AH and ESP handling 1658 1659IPsec module is implemented as "hooks" to the standard IPv4/IPv6 1660processing. When sending a packet, ip{,6}_output() checks if ESP/AH 1661processing is required by checking if a matching SPD (Security 1662Policy Database) is found. If ESP/AH is needed, 1663{esp,ah}{4,6}_output() will be called and mbuf will be updated 1664accordingly. When a packet is received, {esp,ah}4_input() will be --- 86 unchanged lines hidden (view full) --- 1751 see ipsec wg mailing list discussion in Jan 2000 for details. 1752 17534.5 Conformance to RFCs and IDs 1754 1755The IPsec code in the kernel conforms (or, tries to conform) to the 1756following standards: 1757 "old IPsec" specification documented in rfc182[5-9].txt 1758 "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 | 1759 rfc240[1-6].txt rfc241[01].txt rfc2451.txt rfc3602.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) --- 123 unchanged lines hidden (view full) --- 1839in the past, in no particular order. 1840 IRE, SSH (both IPv4/IPv6), NetLock 1841 1842VPNC (vpnc.org) provides IPsec conformance tests, using KAME and OpenBSD 1843IPsec/IKE implementations. Their test results are available at 1844http://www.vpnc.org/conformance.html, and it may give you more idea 1845about which implementation interoperates with KAME IPsec/IKE implementation. 1846 | 1760 IPComp: 1761 RFC2393: IP Payload Compression Protocol (IPComp) 1762IKE specifications (rfc240[7-9].txt) are implemented in userland 1763as "racoon" IKE daemon. 1764 1765Currently supported algorithms are: 1766 old IPsec AH 1767 null crypto checksum (no document, just for debugging) --- 123 unchanged lines hidden (view full) --- 1891in the past, in no particular order. 1892 IRE, SSH (both IPv4/IPv6), NetLock 1893 1894VPNC (vpnc.org) provides IPsec conformance tests, using KAME and OpenBSD 1895IPsec/IKE implementations. Their test results are available at 1896http://www.vpnc.org/conformance.html, and it may give you more idea 1897about which implementation interoperates with KAME IPsec/IKE implementation. 1898 |
18994.8 Operations with IPsec tunnel mode 1900 1901First of all, IPsec tunnel is a very hairy thing. It seems to do a neat thing 1902like VPN configuration or secure remote accesses, however, it comes with lots 1903of architectural twists. 1904 1905RFC2401 defines IPsec tunnel mode, within the context of IPsec. RFC2401 1906defines tunnel mode packet encapsulation/decapsulation on its own, and 1907does not refer other tunnelling specifications. Since RFC2401 advocates 1908filter-based SPD database matches, it would be natural for us to implement 1909IPsec IPsec tunnel mode as filters - not as pseudo interfaces. 1910 1911There are some people who are trying to separate IPsec "tunnel mode" from 1912the IPsec itself. They would like to implement IPsec transport mode only, 1913and combine it with tunneling pseudo devices. The prime example is found 1914in draft-touch-ipsec-vpn-01.txt. However, if you really define pseudo 1915interfaces separately from IPsec, IKE daemons would need to negotiate 1916transport mode SAs, instead of tunnel mode SAs. Therefore, we cannot 1917really mix RFC2401-based interpretation and draft-touch-ipsec-vpn-01.txt 1918interpretation. 1919 1920The KAME stack implements can be configured in two ways. You may need 1921to recompile your kernel to switch the behavior. 1922- RFC2401 IPsec tunnel mode appraoch (4.8.1) 1923- draft-touch-ipsec-vpn approach (4.8.2) 1924 Works in all kernel configuration, but racoon(8) may not interoperate. 1925 1926There are pros and cons on these approaches: 1927 1928RFC2401 IPsec tunnel mode (filter-like) approach 1929 PRO: SPD lookup fits nicely with packet filters (if you integrate them) 1930 CON: cannot run routing daemons across IPsec tunnels 1931 CON: it is very hard to control source address selection on originating 1932 cases 1933 ???: IPv6 scope zone is kept the same 1934draft-touch-ipsec-vpn (transportmode + Pseudo-interface) approach 1935 PRO: run routing daemons across IPsec tunnels 1936 PRO: source address selection can be done normally, by looking at 1937 IPsec tunnel pseudo devices 1938 CON: on outbound, possibility of infinite loops if routing setup 1939 is wrong 1940 CON: due to differences in encap/decap logic from RFC2401, it may not 1941 interoperate with very picky RFC2401 implementations 1942 (those who check TOS bits, for example) 1943 CON: cannot negotiate IKE with other IPsec tunnel-mode devices 1944 (the other end has to implement 1945 ???: IPv6 scope zone is likely to be different from the real ethernet 1946 interface 1947 1948The recommendation is different depending on the situation you have: 1949- use draft-touch-ipsec-vpn if you have the control over the other end. 1950 this one is the best in terms of simplicity. 1951- if the other end is normal IPsec device with RFC2401 implementation, 1952 you need to use RFC2401, otherwise you won't be able to run IKE. 1953- use RFC2401 approach if you just want to forward packets back and forth 1954 and there's no plan to use IPsec gateway itself as an originating device. 1955 19564.8.1 RFC2401 IPsec tunnel mode approach 1957 1958To configure your device as RFC2401 IPsec tunnel mode endpoint, you will 1959use "tunnel" keyword in setkey(8) "spdadd" directives. Let us assume the 1960following topology (A and B could be a network, like prefix/length): 1961 1962 ((((((((((((The internet)))))))))))) 1963 | | 1964 |C (global) |D 1965 your device peer's device 1966 |A (private) |B 1967 ==+===== VPN net ==+===== VPN net 1968 1969The policy configuration directive is like this. You will need manual 1970SAs, or IKE daemon, for actual encryption: 1971 1972 # setkey -c <<EOF 1973 spdadd A B any -P out ipsec esp/tunnel/C-D/use; 1974 spdadd B A any -P in ipsec esp/tunnel/D-C/use; 1975 ^D 1976 1977The inbound/outbound traffic is monitored/captured by SPD engine, which works 1978just like packet filters. 1979 1980With this, forwarding case should work flawlessly. However, troubles arise 1981when you have one of the following requirements: 1982- When you originate traffic from your VPN gateway device to VPN net on the 1983 other end (like B), you want your source address to be A (private side) 1984 so that the traffic would be protected by the policy. 1985 With this approach, however, the source address selection logic follows 1986 normal routing table, and C (global side) will be picked for any outgoing 1987 traffic, even if the destination is B. The resulting packet will be like 1988 this: 1989 IP[C -> B] payload 1990 and will not match the policy (= sent in clear). 1991- When you want to run routing protocols on top of the IPsec tunnel, it is 1992 not possible. As there is no pseudo device that identifies the IPsec tunnel, 1993 you cannot identify where the routing information came from. As a result, 1994 you can't run routing daemons. 1995 19964.8.2 draft-touch-ipsec-vpn approach 1997 1998With this approach, you will configure gif(4) tunnel interfaces, as well as 1999IPsec transport mode SAs. 2000 2001 # gifconfig gif0 C D 2002 # ifconfig gif0 A B 2003 # setkey -c <<EOF 2004 spdadd C D any -P out ipsec esp/transport//use; 2005 spdadd D C any -P in ipsec esp/transport//use; 2006 ^D 2007 2008Since we have a pseudo-interface "gif0", and it affects the routes and 2009the source address selection logic, we can have source address A, for 2010packets originated by the VPN gateway to B (and the VPN cloud). 2011We can also exchange routing information over the tunnel (gif0), as the tunnel 2012is represented as a pseudo interface (dynamic routes points to the 2013pseudo interface). 2014 2015There is a big drawbacks, however; with this, you can use IKE if and only if 2016the other end is using draft-touch-ipsec-vpn approach too. Since racoon(8) 2017grabs phase 2 IKE proposals from the kernel SPD database, you will be 2018negotiating IPsec transport-mode SAs with the other end, not tunnel-mode SAs. 2019Also, since the encapsulation mechanism is different from RFC2401, you may not 2020be able to interoperate with a picky RFC2401 implementations - if the other 2021end checks certain outer IP header fields (like TOS), you will not be able to 2022interoperate. 2023 2024 |
|
18475. ALTQ 1848 1849KAME kit includes ALTQ 2.1 code, which supports FreeBSD2, FreeBSD3, 1850NetBSD and OpenBSD. For BSD/OS, ALTQ does not work. 1851ALTQ in KAME supports (or tries to support) IPv6. 1852(actually, ALTQ is developed on KAME repository since ALTQ 2.1 - Jan 2000) 1853 1854ALTQ occupies single character device number. For FreeBSD, it is officially --- 32 unchanged lines hidden (view full) --- 1887 SFC: http://neo.sfc.wide.ad.jp/~mip6/ (-13 draft) 1888 18897. Coding style 1890 1891The KAME developers basically do not make a bother about coding 1892style. However, there is still some agreement on the style, in order 1893to make the distributed develoment smooth. 1894 | 20255. ALTQ 2026 2027KAME kit includes ALTQ 2.1 code, which supports FreeBSD2, FreeBSD3, 2028NetBSD and OpenBSD. For BSD/OS, ALTQ does not work. 2029ALTQ in KAME supports (or tries to support) IPv6. 2030(actually, ALTQ is developed on KAME repository since ALTQ 2.1 - Jan 2000) 2031 2032ALTQ occupies single character device number. For FreeBSD, it is officially --- 32 unchanged lines hidden (view full) --- 2065 SFC: http://neo.sfc.wide.ad.jp/~mip6/ (-13 draft) 2066 20677. Coding style 2068 2069The KAME developers basically do not make a bother about coding 2070style. However, there is still some agreement on the style, in order 2071to make the distributed develoment smooth. 2072 |
2073- follow *BSD KNF where possible. note: there are multiple KNF standards. |
|
1895- the tab character should be 8 columns wide (tabstops are at 8, 16, 24, ... 1896 column). With vi, use ":set ts=8 sw=8". | 2074- the tab character should be 8 columns wide (tabstops are at 8, 16, 24, ... 2075 column). With vi, use ":set ts=8 sw=8". |
2076 With GNU Emacs 20 and later, the easiest way is to use the "bsd" style of 2077 cc-mode with the variable "c-basic-offset" being 8; 2078 (add-hook 'c-mode-common-hook 2079 (function 2080 (lambda () 2081 (c-set-style "bsd") 2082 (setq c-basic-offset 8) ; XXX for Emacs 20 only 2083 ))) 2084 The "bsd" style in GNU Emacs 21 sets the variable to 8 by default, 2085 so the line marked by "XXX" is not necessary if you only use GNU 2086 Emacs 21. |
|
1897- each line should be within 80 characters. 1898- keep a single open/close bracket in a comment such as in the following 1899 line: 1900 putchar('('); /* ) */ 1901 without this, some vi users would have a hard time to match a pair of 1902 brackets. Although this type of bracket seems clumsy and is even 1903 harmful for some other type of vi users and Emacs users, the 1904 agreement in the KAME developers is to allow it. 1905- add the following line to the head of every KAME-derived file: 1906 /* (dollar)KAME(dollar) */ 1907 where "(dollar)" is the dollar character ($), and around "$" are tabs. | 2087- each line should be within 80 characters. 2088- keep a single open/close bracket in a comment such as in the following 2089 line: 2090 putchar('('); /* ) */ 2091 without this, some vi users would have a hard time to match a pair of 2092 brackets. Although this type of bracket seems clumsy and is even 2093 harmful for some other type of vi users and Emacs users, the 2094 agreement in the KAME developers is to allow it. 2095- add the following line to the head of every KAME-derived file: 2096 /* (dollar)KAME(dollar) */ 2097 where "(dollar)" is the dollar character ($), and around "$" are tabs. |
1908 (this is for C. For other language, you should use its own comment | 2098 (this is for C. For other language, you should use its own comment |
1909 line.) 1910 Once commited to the CVS repository, this line will contain its 1911 version number (see, for example, at the top of this file). This 1912 would make it easy to report a bug. 1913- when creating a new file with the WIDE copyright, tap "make copyright.c" at 1914 the top-level, and use copyright.c as a template. KAME RCS tag will be 1915 included automatically. 1916- when editting a third-party package, keep its own coding style as 1917 much as possible, even if the style does not follow the items above. | 2099 line.) 2100 Once commited to the CVS repository, this line will contain its 2101 version number (see, for example, at the top of this file). This 2102 would make it easy to report a bug. 2103- when creating a new file with the WIDE copyright, tap "make copyright.c" at 2104 the top-level, and use copyright.c as a template. KAME RCS tag will be 2105 included automatically. 2106- when editting a third-party package, keep its own coding style as 2107 much as possible, even if the style does not follow the items above. |
2108- it is recommended to always wrap an expression containing 2109 bitwise operators by parentheses, especially when the expression is 2110 combined with relational operators, in order to avoid unintentional 2111 mismatch of operators. Thus, we should write 2112 if ((a & b) == 0) /* (A) */ 2113 or 2114 if (a & (b == 0)) /* (B) */ 2115 instead of 2116 if (a & b == 0) /* (C) */ 2117 even if the programmer's intention was (C), which is equivalent to 2118 (B) according to the grammar of the language C. 2119 Thus, we should write a code to test if a bit-flag is set for a 2120 given variable as follows: 2121 if ((flag & FLAG_A) == 0) /* (D) the FLAG_A is NOT set */ 2122 if ((flag & FLAG_A) != 0) /* (E) the FLAG_A is set */ 2123 Some developers in the KAME project rather prefer the following style: 2124 if (!(flag & FLAG_A)) /* (F) the FLAG_A is NOT set */ 2125 if ((flag & FLAG_A)) /* (G) the FLAG_A is set */ 2126 because it would be more intuitive in terms of the relationship 2127 between the negation operator (!) and the semantics of the 2128 condition. The KAME developers have discussed the style, and have 2129 agreed that all the styles from (D) to (G) are valid. So, when you 2130 see styles like (D) and (E) in the KAME code and feel a bit strange, 2131 please just keep them. They are intentional. 2132- When inserting a separate block just to define some intra-block 2133 variables, add the level of indentation as if the block was in a 2134 control statement such as if-else, for, or while. For example, 2135 foo () 2136 { 2137 int a; |
|
1918 | 2138 |
2139 { 2140 int internal_a; 2141 ... 2142 } 2143 } 2144 should be used, instead of 2145 foo () 2146 { 2147 int a; 2148 2149 { 2150 int internal_a; 2151 ... 2152 } 2153 } 2154- Do not use printf() or log() in the packet input path of the kernel code. 2155 They can make the system vulnerable to packet flooding attacks (results in 2156 /var overflow). 2157- (not a style issue) 2158 To disable a module that is mistakenly imported (by CVS), just 2159 remove the source tree in the repository. Note, however, that the 2160 removal might annoy other developers who have already checked the 2161 module out, so you should announce the removal as soon as possible. 2162 Also, be 100% sure not to remove other modules. 2163 |
|
1919When you want to contribute something to the KAME project, and if *you 1920do not mind* the agreement, it would be helpful for the project to 1921keep these rules. Note, however, that we would never intend to force 1922you to adopt our rules. We would rather regard your own style, 1923especially when you have a policy about the style. 1924 | 2164When you want to contribute something to the KAME project, and if *you 2165do not mind* the agreement, it would be helpful for the project to 2166keep these rules. Note, however, that we would never intend to force 2167you to adopt our rules. We would rather regard your own style, 2168especially when you have a policy about the style. 2169 |
2170 21719. Policy on technology with intellectual property right restriction 2172 2173There are quite a few IETF documents/whatever which has intellectual property 2174right (IPR) restriction. KAME's stance is stated below. 2175 2176 The goal of KAME is to provide freely redistributable, BSD-licensed, 2177 implementation of Internet protocol technologies. 2178 For this purpose, we implement protocols that (1) do not need license 2179 contract with IPR holder, and (2) are royalty-free. 2180 The reason for (1) is, even if KAME contracts with the IPR holder in 2181 question, the users of KAME stack (usually implementers of some other 2182 codebase) would need to make a license contract with the IPR holder. 2183 It would damage the "freely redistributable" status of KAME codebase. 2184 2185 By doing so KAME is (implicitly) trying to advocate no-license-contract, 2186 royalty-free, release of IPRs. 2187 2188Note however, as documented in README, we do not guarantee that KAME code 2189is free of IPR infringement, you MUST check it if you are to integrate 2190KAME into your product (or whatever): 2191 READ CAREFULLY: Several countries have legal enforcement for 2192 export/import/use of cryptographic software. Check it before playing 2193 with the kit. We do not intend to be your legalease clearing house 2194 (NO WARRANTY). If you intend to include KAME stack into your product, 2195 you'll need to check if the licenses on each file fit your situations, 2196 and/or possible intellectual property right issues. 2197 |
|
1925 <end of IMPLEMENTATION> | 2198 <end of IMPLEMENTATION> |