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 $ |
6 $FreeBSD: head/share/doc/IPv6/IMPLEMENTATION 122115 2003-11-05 12:00:32Z ume $ |
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 |
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 |
119 * see RFC3542 |
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 |
138 * See 1.9 in this document for details. |
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 |
152RFC2553: (see RFC3493) |
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. |
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. |
203 * Some of the updates in the draft are not implemented yet. See 204 TODO.2292bis for more details. |
205draft-ietf-ipngwg-icmp-name-lookups-09: IPv6 Name Lookups Through ICMP |
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. |
225draft-itojun-ipv6-tcp-to-anycast-01.txt: 226 Disconnecting TCP connection toward IPv6 anycast address 227draft-itojun-ipv6-transition-abuse-01.txt: |
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. |
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 |
406advanced API (RFC2292 or RFC3542) can specify |
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 |
422sockaddr_in6 structure, defined in RFC2553. The KAME kernel 423interprets the sin6_scope_id field properly in order to disambiguate scoped |
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 |
464syntax, as documented in draft-ietf-ipv6-scoping-arch-xx.txt. You can |
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 |
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. |
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 |
6371.6 Address Selection |
638 |
6391.6.1 Source Address Selection |
640 |
641The KAME kernel chooses the source address for an outgoing packet 642sent from a user application as follows: |
643 |
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. |
648 |
6492. if the corresponding socket is bound, use the bound address. |
650 |
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. |
655 |
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. |
661 |
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): |
666 |
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. |
671 |
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. |
675 |
676When the procedure above fails, the kernel usually returns 677EADDRNOTAVAIL to the application. |
678 |
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. |
682Under the spec (RFC2461 7.2.2) NA's source should be the target |
683address of the corresponding NS's target. In this case we follow the 684spec rather than the above rule. |
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 |
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 |
897RFC2553/3493 describes IPv4 mapped address (3.7) and special behavior |
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 |
934It looks that RFC2553/3493 talks too little on wildcard bind issue, |
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, |
979as documented in RFC2553/3493 6.1. KAME libinet6 includes the tweak in |
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 |
998to RFC2553/3493 section 3.7 and 3.8. It is due to code sharing reasons. |
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 |
1037conformant to RFC2553/3493 section 3.8. It is intentionally turned off by 1038default for security reasons. |
1039 |
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). |
1046- add "INET6_BINDV6ONLY": No special support code for AF_INET6 wildcard socket |
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 |
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 |
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). |
1072 |
1073When getsockopt(IPV6_V6ONLY) is 1 for a socket, you cannot use IPv4 mapped 1074address for outgoing traffic. 1075 |
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 |
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. |
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. |
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. |
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 |
1214In December 1999, it was agreed that RFC2553bis (RFC3493) should pick the 1215latter (XNET) definition. |
1216 1217KAME kit prior to December 1999 used RFC2553 definition. KAME kit after 1218December 1999 (including December) will conform to XNET definition, |
1219based on RFC3493 discussion. |
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 |
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. |
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 |
1336Current KAME kernel implements RFC3542 API. It also implements RFC2292 API, |
1337for backward compatibility purposes with *BSD-integrated codebase. |
1338KAME tree ships with RFC3542 headers. 1339*BSD-integrated codebase implements either RFC2292, or RFC3542, API. |
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. |
1345- KAME binaries, compiled using RFC3542, will not work on *BSD-integrated |
1346 kenrel. For example, KAME /usr/local/v6/sbin/rtsol will not work on 1347 OpenBSD 2.7 kernel. |
1348- RFC3542 API is not compatible with RFC2292 API. RFC3542 #define symbols |
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 |
1352 issue. For example, Solaris 8 implements RFC3542 API. If you compile |
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 |
1361 strict/loose bitmap. RFC3542 document is based on RFC2460 IPv6, and it has |
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 |
13842. Network Drivers 1385 1386KAME requires three items to be added into the standard drivers: 1387 |
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. |
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 |
1624The kernel implements experimental policy management code. There are two ways |
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". |
1650Racoon follows the latter route (previously it followed the former, and 1651the latter interpretation seems to be popular/consensus). |
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 |
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: |
1759 rfc240[1-6].txt rfc241[01].txt rfc2451.txt rfc3602.txt |
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 |
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. |
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. |
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. |
2098 (this is for C. For other language, you should use its own comment |
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; |
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 |
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 |
2198 <end of IMPLEMENTATION> |