From 8f336835e18ec8e52d205f9fbe2c8bc65a7861be Mon Sep 17 00:00:00 2001 From: Jun-ichiro itojun Hagino Date: Tue, 4 Jul 2000 16:35:31 +0000 Subject: [PATCH] sync with recent IMPLEMENTATION note from kame. --- share/doc/IPv6/IMPLEMENTATION | 1137 +++++++++++++++++++++++++-------- 1 file changed, 862 insertions(+), 275 deletions(-) diff --git a/share/doc/IPv6/IMPLEMENTATION b/share/doc/IPv6/IMPLEMENTATION index 5909a7262480..98150d5e0be4 100644 --- a/share/doc/IPv6/IMPLEMENTATION +++ b/share/doc/IPv6/IMPLEMENTATION @@ -1,3 +1,7 @@ +# NOTE: this is from original KAME distribution. +# Some portion of this document is not applicable to the code merged into +# FreeBSD-current (for example, section 5). + Implementation Note KAME Project @@ -14,7 +18,7 @@ below (NOTE: this is not a complete list - this is too hard to maintain...). For details please refer to specific chapter in the document, RFCs, manpages come with KAME, or comments in the source code. -Conformance tests have been performed on the KAME STABLE kit +Conformance tests have been performed on past and latest KAME STABLE kit, at TAHI project. Results can be viewed at http://www.tahi.org/report/KAME/. We also attended Univ. of New Hampshire IOL tests (http://www.iol.unh.edu/) in the past, with our past snapshots. @@ -72,43 +76,72 @@ RFC2497: Transmission of IPv6 packet over ARCnet Networks RFC2545: Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing RFC2553: Basic Socket Interface Extensions for IPv6 * IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind - socket (3.8) are supported. + socket (3.8) are, + - supported and turned on by default on KAME/FreeBSD[34]x + and KAME/BSDI4, + - supported but turned off by default on KAME/NetBSD, + - not supported on KAME/FreeBSD228, KAME/OpenBSD and KAME/BSDI3. see 1.12 in this document for details. RFC2675: IPv6 Jumbograms * See 1.7 in this document for details. RFC2710: Multicast Listener Discovery for IPv6 RFC2711: IPv6 router alert option -draft-ietf-ipngwg-router-renum-08: Router renumbering for IPv6 -draft-ietf-ipngwg-icmp-namelookups-02: IPv6 Name Lookups Through ICMP -draft-ietf-ipngwg-icmp-name-lookups-03: IPv6 Name Lookups Through ICMP -draft-ietf-pim-ipv6-01.txt: PIM for IPv6 +RFC2732: Format for Literal IPv6 Addresses in URL's + * The spec is implemented in programs that handle URLs + (like freebsd ftpio(3) and fetch(1), or netbsd ftp(1)) +draft-ietf-ipngwg-router-renum-10: Router renumbering for IPv6 +draft-ietf-ipngwg-icmp-name-lookups-05: IPv6 Name Lookups Through ICMP +draft-ietf-pim-ipv6-03.txt: PIM for IPv6 * pim6dd implements dense mode. pim6sd implements sparse mode. -draft-ietf-dhc-dhcpv6-14.txt: DHCPv6 -draft-ietf-dhc-v6exts-11.txt: Extensions for DHCPv6 +draft-ietf-dhc-dhcpv6-15.txt: DHCPv6 +draft-ietf-dhc-dhcpv6exts-12.txt: Extensions for DHCPv6 * kame/dhcp6 has test implementation, which will not be compiled in default compilation. -draft-itojun-ipv6-tcp-to-anycast-00: +draft-itojun-ipv6-tcp-to-anycast-00.txt: Disconnecting TCP connection toward IPv6 anycast address -draft-yamamoto-wideipv6-comm-model-00 - * See 1.6 in this document for details. -draft-ietf-ipngwg-scopedaddr-format-00.txt: +draft-ietf-ipngwg-scopedaddr-format-02.txt: An Extension of Format for IPv6 Scoped Addresses +draft-ietf-ngtrans-tcpudp-relay-01.txt: + An IPv6-to-IPv4 transport relay translator + * FAITH tcp relay translator (faithd) implements this. See 3.1 for more + details. +draft-ietf-ngtrans-6to4-06.txt: + Connection of IPv6 Domains via IPv4 Clouds without Explicit Tunnels + * "stf" interface implements it. Be sure to read the next item before + configuring it, there are security issues. +http://playground.iijlab.net/i-d/draft-itojun-ipv6-transition-abuse-00.txt: + Possible abuse against IPv6 transition technologies + * KAME does not implement RFC1933 automatic tunnel. + * "stf" interface implements some address filters. Refer to stf(4) + for details. Since there's no way to make 6to4 interface 100% secure, + we do not include "stf" interface into GENERIC.v6 compilation. + * kame/openbsd completely disables IPv4 mapped address support. + * kame/netbsd makes IPv4 mapped address support off by default. + * See section 12.6 and 14 for more details. 1.2 Neighbor Discovery Neighbor Discovery is fairly stable. Currently Address Resolution, Duplicated Address Detection, and Neighbor Unreachability Detection -are supported. In the near future we will be adding Proxy Neighbor -Advertisement support in the kernel and Unsolicited Neighbor Advertisement -transmission command as admin tool. +are supported. In the near future we will be adding Unsolicited Neighbor +Advertisement transmission command as admin tool. +Duplicated Address Detection (DAD) will be performed when an IPv6 address +is assigned to a network interface, or the network interface is enabled +(ifconfig up). It is documented in RFC2462 5.4. If DAD fails, the address will be marked "duplicated" and message will be generated to syslog (and usually to console). The "duplicated" mark can be checked with ifconfig. It is administrators' responsibility to check -for and recover from DAD failures. -The behavior should be improved in the near future. +for and recover from DAD failures. We may try to improve failure recovery +in future KAME code. +DAD procedure may not be effective on certain network interfaces/drivers. +If a network driver needs long initialization time (with wireless network +interfaces this situation is popular), and the driver mistakingly raises +IFF_RUNNING before the driver becomes ready, DAD code will try to transmit +DAD probes to not-really-ready network driver and the packet will not go out +from the interface. In such cases, network drivers should be corrected. -Some of the network driver loops multicast packets back to itself, +Some of network drivers loop multicast packets back to themselves, even if instructed not to do so (especially in promiscuous mode). In such cases DAD may fail, because DAD engine sees inbound NS packet (actually from the node itself) and considers it as a sign of duplicate. @@ -127,10 +160,11 @@ list. For more details, see the comments in the source code and email thread started from (IPng 7155), dated Feb 6 1999. IPv6 on-link determination rule (RFC2461) is quite different from assumptions -in BSD network code. At this moment, KAME does not implement on-link -determination rule when default router list is empty (RFC2461, section 5.2, -last sentence in 2nd paragraph - note that the spec misuse the word "host" -and "node" in several places in the section). +in BSD IPv4 network code. To implement behavior in RFC2461 section 5.2 +(when default router list is empty), the kernel needs to know the default +outgoing interface. To configure the default outgoing interface, use +commands like "ndp -I de0" as root. Note that the spec misuse the word +"host" and "node" in several places in the section. To avoid possible DoS attacks and infinite loops, KAME stack will accept only 10 options on ND packet. Therefore, if you have 20 prefix options @@ -139,32 +173,92 @@ If this troubles you, please contact KAME team and/or modify nd6_maxndopt in sys/netinet6/nd6.c. If there are high demands we may provide sysctl knob for the variable. +Proxy Neighbor Advertisement support is implemented in the kernel. +For instance, you can configure it by using the following command: + # ndp -s fe80::1234%ne0 0:1:2:3:4:5 proxy +where ne0 is the interface which attaches to the same link as the +proxy target. +There are certain limitations, though: +- It does not send unsolicited multicast NA on configuration. This is MAY + behavior in RFC2461. +- It does not add random delay before transmission of solicited NA. This is + SHOULD behavior in RFC2461. +- We cannot configure proxy NDP for off-link address. The target address for + proxying must be link-local address, or must be in prefixes configured to + node which does proxy NDP. +- RFC2461 is unclear about if it is legal for a host to perform proxy ND. + We do not prohibit hosts from doing proxy ND, but there will be very limited + use in it. + +Starting mid March 2000, we support Neighbor Unreachability Detection (NUD) +on p2p interfaces, including tunnel interfaces (gif). NUD is turned on by +default. Before March 2000 KAME stack did not perform NUD on p2p interfaces. +If the change raises any interoperability issues, you can turn off/on NUD +by per-interface basis. Use "ndp -i interface -nud" to turn it off. +Consult ndp(8) for details. + +RFC2461 specifies upper-layer reachability confirmation hint. Whenever +upper-layer reachability confirmation hint comes, ND process can use it +to optimize neighbor discovery process - ND process can omit real ND exchange +and keep the neighbor cache state in REACHABLE. +We currently have two sources for hints: (1) setsockopt(IPV6_REACHCONF) +defined by 2292bis API, and (2) hints from tcp_input. +It is questionable if they are really trustworthy. For example, a rogue +userland program can use IPV6_REACHCONF to confuse ND process. Neighbor +cache is a system-wide information pool, and it is bad to allow single process +to affect others. Also, tcp_input can be hosed by hijack attempts. It is +wrong to allow hijack attempts to affect ND process. +Starting June 2000, ND code has a protection mechanism against incorrect +upper-layer reachability confirmation. ND code counts subsequent upper-layer +hints. If the number of hints reaches maximum, ND code will ignore further +upper-layer hints and run real ND process to confirm reachability to the peer. +sysctl net.inet6.icmp6.nd6_maxnudhint defines maximum # of subsequent +upper-layer hints to be accepted. +(from April 2000 to June 2000, we rejected setsockopt(IPV6_REACHCONF) from +non-root process - after local discussion, it looks that hints are not +that trustworthy even if they are from privileged processes) + 1.3 Scope Index -IPv6 uses scoped addresses. Therefore, it is very important to +IPv6 uses scoped addresses. It is therefore very important to specify scope index (interface index for link-local address, or site index for site-local address) with an IPv6 address. Without -scope index, scoped IPv6 address is ambiguous to the kernel, and -kernel will not be able to determine the outbound interface for a -packet. +scope index, a scoped IPv6 address is ambiguous to the kernel, and +the kernel will not be able to determine the outbound interface for a +packet. KAME code tries to address the issue in several ways. -Ordinary userland applications should use advanced API (RFC2292) to -specify scope index, or interface index. For similar purpose, -sin6_scope_id member in sockaddr_in6 structure is defined in RFC2553. -However, the semantics for sin6_scope_id is rather vague. If you -care about portability of your application, we suggest you to use -advanced API rather than sin6_scope_id. +Site-local address is very vaguely defined in the specs, and both specification +and KAME code need tons of improvements to enable its actual use. +For example, it is still very unclear how we define a site, or how we resolve +hostnames in a site. There are work underway to define behavior of routers +at site border, however, we have almost no code for site boundary node support +(both forwarding nor routing) and we bet almost noone has. +We recommend, at this moment, you to use global addresses for experiments - +there are way too many pitfalls if you use site-local addresses. -In the kernel, an interface index for link-local scoped address is -embedded into 2nd 16bit-word (3rd and 4th byte) in IPv6 address. +1.3.1 Kernel internal + +In the kernel, the interface index for a link-local scope address is +embedded into the 2nd 16bit-word (the 3rd and 4th bytes) in the IPv6 +address. For example, you may see something like: fe80:1::200:f8ff:fe01:6317 in the routing table and interface address structure (struct -in6_ifaddr). The address above is a link-local unicast address +in6_ifaddr). The address above is a link-local unicast address which belongs to a network interface whose interface identifier is 1. The embedded index enables us to identify IPv6 link local addresses over multiple interfaces effectively and with only a little code change. + +1.3.2 Interaction with API + +Ordinary userland applications should use the advanced API (RFC2292) +to specify scope index, or interface index. For the similar purpose, +the sin6_scope_id member in the sockaddr_in6 structure is defined in +RFC2553. However, the semantics for sin6_scope_id is rather vague. +If you care about portability of your application, we suggest you to +use the advanced API rather than sin6_scope_id. + Routing daemons and configuration programs, like route6d and ifconfig, will need to manipulate the "embedded" scope index. These programs use routing sockets and ioctls (like SIOCGIFADDR_IN6) @@ -173,24 +267,41 @@ filled in. The APIs are for manipulating kernel internal structure. Programs that use these APIs have to be prepared about differences in kernels anyway. -When you specify scoped address to the command line, NEVER write the -embedded form (such as ff02:1::1 or fe80:2::fedc). This is not supposed -to work. Always use standard form, like ff02::1 or fe80::fedc, with -command line option for specifying interface (like "ping6 -I ne0 ff02::1). -In general, if a command does not have command line option to specify -outgoing interface, that command is not ready to accept scoped address. -This may seem to be opposite from IPv6's premise to support "dentist office" -situation. We believe that specifications need some improvements for this. - -Some of the userland tools support extended numeric IPv6 syntax, as -documented in draft-ietf-ipngwg-scopedaddr-format-00.txt. You can specify -outgoing link, by using name of the outgoing interface like "fe80::1%ne0". -This way you will be able to specify link-local scoped address without much -trouble. +getaddrinfo(3) and getnameinfo(3) are modified to support extended numeric +IPv6 syntax, as documented in draft-ietf-ipngwg-scopedaddr-format-xx.txt. +You can specify outgoing link, by using name of the outgoing interface +like "fe80::1%ne0". This way you will be able to specify link-local scoped +address without much trouble. To use this extension in your program, you'll need to use getaddrinfo(3), and getnameinfo(3) with NI_WITHSCOPEID. The implementation currently assumes 1-to-1 relationship between a link and an -interface, which is stronger than what specs say. +interface, which is stronger than what IPv6 specs say. +Other APIs like inet_pton(3) or getipnodebyname(3) are inherently unfriendly +with scoped addresses, since they are unable to annotate addresses with +scope identifier. + +1.3.3 Interaction with users (command line) + +Most of user applications now support an extended numeric IPv6 syntax, +as documented in draft-ietf-ipngwg-scopedaddr-format-xx.txt. In this +case, you can specify outgoing link, by using the name of the outgoing +interface like "fe80::1%ne0". This is the case for some management +tools such as route(8) or ndp(8). For example, to install the IPv6 +default route by hand, you can type like + # route add -inet6 default fe80::9876:5432:1234:abcd%ne0 +(Although we suggest you to run dynamic routing instead of static +routes, in order to avoid configuration mistakes.) + +Some applications have command line options for specifying an +appropriate zone of a scoped address (like "ping6 -I ne0 ff02::1" to +specify the outgoing interface). However, you can't always expect such +options. Thus, we recommend you to use the extended format described +above. + +In any case, when you specify a scoped address to the command line, +NEVER write the embedded form (such as ff02:1::1 or fe80:2::fedc), +which should only be used inside the kernel (see Section 1.3.1), and +is not supposed to work. 1.4 Plug and Play @@ -204,7 +315,7 @@ userland. 1.4.1 Assignment of link-local, and special addresses -IPv6 link-local address is generated from IEEE802 adddress (ethernet MAC +IPv6 link-local address is generated from IEEE802 address (ethernet MAC address). Each of interface is assigned an IPv6 link-local address automatically, when the interface becomes up (IFF_UP). Also, direct route for the link-local address is added to routing table. @@ -213,8 +324,8 @@ Here is an output of netstat command: Internet6: Destination Gateway Flags Netif Expire -fe80:1::%ed0/64 link#1 UC ed0 -fe80:2::%ep0/64 link#2 UC ep0 +fe80::%ed0/64 link#1 UC ed0 +fe80::%ep0/64 link#2 UC ep0 Interfaces that has no IEEE802 address (pseudo interfaces like tunnel interfaces, or ppp interfaces) will borrow IEEE802 address from other @@ -241,29 +352,39 @@ node-local multicast group ff01::1. In IPv6 specification, nodes are separated into two categories: routers and hosts. Routers forward packets addressed to others, hosts does not forward the packets. net.inet6.ip6.forwarding defines whether this -node is router or host (router if it is 1, host if it is 0). +node is a router or a host (router if it is 1, host if it is 0). + +It is NOT recommended to change net.inet6.ip6.forwarding while the node +is in operation. IPv6 specification defines behavior for "host" and "router" +quite differently, and switching from one to another can cause serious +troubles. It is recommended to configure the variable at bootstrap time only. + +The first step in stateless address configuration is Duplicated Address +Detection (DAD). See 1.2 for more detail on DAD. When a host hears Router Advertisement from the router, a host may autoconfigure itself by stateless address autoconfiguration. This behavior can be controlled by net.inet6.ip6.accept_rtadv (host autoconfigures itself if it is set to 1). By autoconfiguration, network address prefix for the receiving interface -(usually global address prefix) is added. Default route is also configured. -Routers periodically generate Router Advertisement packets. To request -an adjacent router to generate RA packet, a host can transmit Router -Solicitation. To generate a RS packet at any time, use the "rtsol" command. -"rtsold" daemon is also available. "rtsold" generates Router Solicitation -whenever necessary, and it works great for nomadic usage (notebooks/laptops). -If one wishes to ignore Router Advertisements, use sysctl to set -net.inet6.ip6.accept_rtadv to 0. +(usually global address prefix) is added. The default route is also +configured. + +Routers periodically generate Router Advertisement packets. To +request an adjacent router to generate RA packet, a host can transmit +Router Solicitation. To generate an RS packet at any time, use the +"rtsol" command. The "rtsold" daemon is also available. "rtsold" +generates Router Solicitation whenever necessary, and it works great +for nomadic usage (notebooks/laptops). If one wishes to ignore Router +Advertisements, use sysctl to set net.inet6.ip6.accept_rtadv to 0. To generate Router Advertisement from a router, use the "rtadvd" daemon. -Note that, IPv6 specification assumes the following items, and nonconforming -cases are left unspecified: +Note that the IPv6 specification assumes the following items and that +nonconforming cases are left unspecified: - Only hosts will listen to router advertisements - Hosts have single network interface (except loopback) -Therefore, this is unwise to enable net.inet6.ip6.accept_rtadv on routers, +This is therefore unwise to enable net.inet6.ip6.accept_rtadv on routers, or multi-interface host. A misconfigured node can behave strange (KAME code allows nonconforming configuration, for those who would like to do some experiments). @@ -275,13 +396,12 @@ To summarize the sysctl knob: 0 1 router 1 0 autoconfigured host (spec assumes that host has single - interface only, autoconfigured host - with multiple interface is - out-of-scope) + interface only, autoconfigred host with + multiple interface is out-of-scope) 1 1 invalid, or experimental (out-of-scope of spec) -RFC2462 has validation rule against incoming RA prefix information option, +RFC2462 has validation rules against incoming RA prefix information option, in 5.5.3 (e). This is to protect hosts from malicious (or misconfigured) routers that advertise very short prefix lifetime. There was an update from Jim Bound to ipngwg mailing list (look @@ -289,12 +409,13 @@ for "(ipng 6712)" in the archive) and KAME implements Jim's update. See 1.2 in the document for relationship between DAD and autoconfiguration. -1.4.3 DHCPv6 (not yet put into freebsd4.0) +1.4.3 DHCPv6 -We supply a tiny DHCPv6 server/client in kame/dhcp6. However, the -implementation is very premature (for example, this does NOT -implement address lease/release), and it is not in default compilation -tree. If you want to do some experiment, compile it on your own. +We supply a tiny DHCPv6 server/client in kame/dhcp6. However, the +implementation is premature (for example, this does NOT implement +address lease/release), and it is not in default compilation tree on +some platforms. If you want to do some experiment, compile it on your +own. DHCPv6 and autoconfiguration also needs more work. "Managed" and "Other" bits in RA have no special effect to stateful autoconfiguration procedure @@ -321,62 +442,107 @@ gif can be configured to be ECN-friendly. See 4.5 for ECN-friendliness of tunnels, and gif(4) manpage for how to configure. If you would like to configure an IPv4-in-IPv6 tunnel with gif interface, -read gif(4) carefully. You will need to remove IPv6 link-local address +read gif(4) carefully. You may need to remove IPv6 link-local address automatically assigned to the gif interface. 1.6 Source Address Selection -Source selection of KAME is scope oriented (there are some exceptions - -see below). For a given destination, a source IPv6 address is selected -by the following rule: - 1. If the source address is explicitly specified by the user - (e.g. via the advanced API), the specified address is used. - 2. If there is an address assigned to the outgoing interface - (which is usually determined by looking up the routing table) - that has the same scope as the destination address, the address - is used. - This is the most typical case. - 3. If there is no address that satisfies the above condition, - choose a global address assigned to one of the interfaces - on the sending node. - 4. If there is no address that satisfies the above condition, - and destination address is site local scope, - choose a site local address assigned to one of the interfaces - on the sending node. - 5. If there is no address that satisfies the above condition, - choose the address associated with the routing table - entry for the destination. - This is the last resort, which may cause scope violation. +KAME's source address selection takes care of the following +conditions: +- address scope +- prefix matching against the destination +- outgoing interface +- whether an address is deprecated -For instance, ::1 is selected for ff01::1, fe80:1::200:f8ff:fe01:6317 -for fe80:1::2a0:24ff:feab:839b (note that embedded interface index - -described in 1.3 - helps us choose the right source address. Those -embedded indices will not be on the wire). -If the outgoing interface has multiple address for the scope, -a source is selected longest match basis (rule 3). Suppose +Roughly speaking, the selection policy is as follows: +- always use an address that belongs to the same scope zone as the + destination. +- addresses that have equal or larger scope than the scope of the + destination are preferred. +- if multiple addresses have the equal scope, one which is longest + prefix matching against the destination is preferred. +- a deprecated address is not used in new communications if an + alternate (non-deprecated) address is available and has sufficient + scope. +- if none of above conditions tie-breaks, addresses assigned on the + outgoing interface are preferred. + +For instance, ::1 is selected for ff01::1, +fe80::200:f8ff:fe01:6317%ne0 for fe80::2a0:24ff:feab:839b%ne0. +To see how longest-matching works, suppose that 3ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317 -are given to the outgoing interface. 3ffe:501:808:1:200:f8ff:fe01:6317 -is chosen as the source for the destination 3ffe:501:800::1. +are given on the outgoing interface. Then the former is chosen as the +source for the destination 3ffe:501:800::1. Note that even if all +available addresses have smaller scope than the scope of the +destination, we choose one anyway. For example, if we have link-local +and site-local addresses only, we choose a site-local addresses for a +global destination. If the packet is going to break a site boundary, +the boundary router will return an ICMPv6 destination unreachable +error with code 2 - beyond scope of source address. + +The precise desripction of the algorithm is quite complicated. To +describe the algorithm, we introduce the following notation: + +For a given destination D, + samescope(D): A set of addresses that have the same scope as D. + largerscope(D): A set of addresses that have a larger scope than D. + smallerscope(D): A set of addresses that have a smaller scope than D. + +For a given set of addresses A, + DEP(A): a set of deprecated addresses in A. + nonDEP(A): A - DEP(A). + +Also, the algorithm assumes that the outgoing interface for the +destination D is determined. We call the interface "I". + +The algorithm is as follows. Selection proceeds step by step as +described; For example, if an address is selected by item 1, item 2 or +later are not considered at all. + + 0. If there is no address in the same scope zone as D, just give up; + the packet will not be sent. + 1. If nonDEP(samescope(D)) is not empty, + choose a longest matching address against D. If more than one + address is longest matching, choose arbitrary one provided that + an address on I is always preferred. + 2. If nonDEP(largerscope(D)) is not empty, + choose an address that has the smallest scope. If more than one + address has the smallest scope, choose arbitrary one provided + that an address on I is always preferred. + 3. If DEP(samescope(D)) is not empty, + choose a longest matching address against D. If more than one + address is longest matching, choose arbitrary one provided that + an address on I is always preferred. + 4. If DEP(largerscope(D)) is not empty, + choose an address that has the smallest scope. If more than one + address has the smallest scope, choose arbitrary one provided + that an address on I is always preferred. + 5. if nonDEP(smallerscope(D)) is not empty, + choose an address that has the largest scope. If more than one + address has the largest scope, choose arbitrary one provided + that an address on I is always preferred. + 6. if DEP(smallerscope(D)) is not empty, + choose an address that has the largest scope. If more than one + address has the largest scope, choose arbitrary one provided + that an address on I is always preferred. + +There exists a document about source address selection +(draft-ietf-ipngwg-default-addr-select-xx.txt). KAME's algorithm +described above takes a similar approach to the document, but there +are some differences. See the document for more details. -Note that the above rule is not documented in the IPv6 spec. It is -considered "up to implementation" item. There are some cases where we do not use the above rule. One -example is connected TCP session, and we use the address kept in tcb -as the source. +example is connected TCP session, and we use the address kept in TCP +protocol control block (tcb) as the source. Another example is source address for Neighbor Advertisement. Under the spec (RFC2461 7.2.2) NA's source should be the target address of the corresponding NS's target. In this case we follow the spec rather than the above longest-match rule. -For new connections (when rule 1 does not apply), deprecated addresses -(addresses with preferred lifetime = 0) will not be chosen as source address -if other choises are available. If no other choices are available, -deprecated address will be used as a last resort. If there are multiple -choice of deprecated addresses, the above scope rule will be used to choose -from those deprecated addreses. If you would like to prohibit the use -of deprecated address for some reason, configure net.inet6.ip6.use_deprecated -to 0. The issue related to deprecated address is described in RFC2462 5.5.4 -(NOTE: there is some debate underway in IETF ipngwg on how to use +If you would like to prohibit the use of deprecated address for some +reason, configure net.inet6.ip6.use_deprecated to 0. The issue +related to deprecated address is described in RFC2462 5.5.4 (NOTE: +there is some debate underway in IETF ipngwg on how to use "deprecated" address). 1.7 Jumbo Payload @@ -396,7 +562,7 @@ and recompile the new kernel. Then you can test jumbo payloads by the ping6 command with -b and -s options. The -b option must be specified to enlarge the size of the socket buffer and the -s option specifies the length of the packet, -which should be more than 65,535. For example, type as follows; +which should be more than 65,535. For example, type as follows; % ping6 -b 70000 -s 68000 ::1 The IPv6 specification requires that the Jumbo Payload option must not @@ -432,20 +598,20 @@ and this makes it real hard to authenticate inbound packet with jumbo payload option as well as AH). There are fundamental issues in *BSD support for jumbograms. We would like to -address those, but we need more time to finalize these. To name a few: -- mbuf pkthdr.len field is typed as "int" in 4.4BSD, so it will not hold +address those, but we need more time to finalize the task. To name a few: +- mbuf pkthdr.len field is typed as "int" in 4.4BSD, so it cannot hold jumbogram with len > 2G on 32bit architecture CPUs. If we would like to support jumbogram properly, the field must be expanded to hold 4G + IPv6 header + link-layer header. Therefore, it must be expanded to at least int64_t (u_int32_t is NOT enough). - We mistakingly use "int" to hold packet length in many places. We need - to convert them into larger integral type. It needs a great care, as we may + to convert them into larger numeric type. It needs a great care, as we may experience overflow during packet length computation. - We mistakingly check for ip6_plen field of IPv6 header for packet payload length in various places. We should be checking mbuf pkthdr.len instead. ip6_input() will perform sanity check on jumbo payload option on input, and we can safely use mbuf pkthdr.len afterwards. -- TCP code needs a careful update in bunch of places, of course. +- TCP code needs careful updates in bunch of places, of course. 1.8 Loop prevention in header processing @@ -456,14 +622,9 @@ overflow due to long function call chain. KAME sys/netinet6 code is carefully designed to avoid kernel stack overflow. Because of this, KAME sys/netinet6 code defines its own protocol switch structure, as "struct ip6protosw" (see netinet6/ip6protosw.h). -There is no such update to IPv4 part (sys/netinet) for -compatibility, but small change is added to its pr_input() -prototype. So "struct ipprotosw" is also defined. +IPv4 part (sys/netinet) remains untouched for compatibility. Because of this, if you receive IPsec-over-IPv4 packet with massive number of IPsec headers, kernel stack may blow up. IPsec-over-IPv6 is okay. -(Off-course, for those all IPsec headers to be processed, each -such IPsec header must pass each IPsec check. So an anonymous -attacker won't be able to do such an attack.) 1.9 ICMPv6 @@ -471,6 +632,22 @@ After RFC2463 was published, IETF ipngwg has decided to disallow ICMPv6 error packet against ICMPv6 redirect, to prevent ICMPv6 storm on a network medium. KAME already implements this into the kernel. +RFC2463 requires rate limitation for ICMPv6 error packets generated by a +node, to avoid possible DoS attacks. KAME kernel implements two rate- +limitation mechanisms, tunable via sysctl: +- Minimum time interval between ICMPv6 error packets + KAME kernel will generate no more than one ICMPv6 error packet, + during configured time interval. net.inet6.icmp6.errratelimit + controls the interval (default: disabled). +- Maximum ICMPv6 error packet-per-second + KAME kernel will generate no more than the configured number of + packets in one second. net.inet6.icmp6.errppslimit controls the + maximum packet-per-second value (default: 200pps) +Basically, we need to pick values that are suitable against the bandwidth +of link layer devices directly attached to the node. In some cases the +default values may not fit well. We are still unsure if the default value +is sane or not. Comments are welcome. + 1.10 Applications For userland programming, we support IPv6 socket API as specified in @@ -493,19 +670,19 @@ if_output() since routers must not divide IPv6 packets into fragments. ICMPv6 should contain the original packet as long as possible up to 1280. UDP6/IP6 port unreach, for instance, should contain all extension headers and the *unchanged* UDP6 and IP6 headers. -So, all IP6 functions except TCP never convert network byte +So, all IP6 functions except TCP6 never convert network byte order into host byte order, to save the original packet. -tcp_input(), udp6_input() and icmp6_input() can't assume that IP6 +tcp6_input(), udp6_input() and icmp6_input() can't assume that IP6 header is preceding the transport headers due to extension headers. So, in6_cksum() was implemented to handle packets whose IP6 -header and transport header is not continuous. TCP/IP6 nor UDP6/IP6 +header and transport header is not continuous. TCP/IP6 nor UDP/IP6 header structure don't exist for checksum calculation. To process IP6 header, extension headers and transport headers easily, KAME requires network drivers to store packets in one internal mbuf or one or more external mbufs. A typical old driver prepares two -internal mbufs for 96 - 204 bytes data, however, KAME's reference +internal mbufs for 100 - 208 bytes data, however, KAME's reference implementation stores it in one external mbuf. "netstat -s -p ip6" tells you whether or not your driver conforms @@ -527,7 +704,22 @@ M_LOOP flag, that is, the packet comes from the loopback interface. m_pullup() is never called for packets coming from physical network interfaces. -Both IP and IP6 reassemble functions never call m_pullup(). +TCP6 reassembly makes use of IP6 header to store reassemble +information. IP6 is not supposed to be just before TCP6, so +ip6tcpreass structure has a pointer to TCP6 header. Of course, it has +also a pointer back to mbuf to avoid m_pullup(). + +Like TCP6, both IP and IP6 reassemble functions never call m_pullup(). + +xxx_ctlinput() calls in_mrejoin() on PRC_IFNEWADDR. We think this is +one of 4.4BSD implementation flaws. Since 4.4BSD keeps ia_multiaddrs +in in_ifaddr{}, it can't use multicast feature if the interface has no +unicast address. So, if an application joins to an interface and then +all unicast addresses are removed from the interface, the application +can't send/receive any multicast packets. Moreover, if a new unicast +address is assigned to the interface, in_mrejoin() must be called. +KAME's interfaces, however, have ALWAYS one link-local unicast +address. These extensions have thus not been implemented in KAME. 1.12 IPv4 mapped address and IPv6 wildcard socket @@ -542,17 +734,26 @@ Here we call the former one "listening side" and the latter one "initiating side", for reference purposes. Almost all KAME implementations treat tcp/udp port number space separately -between IPv4 and IPv6. You can perform wildcard bind on both of the adderss +between IPv4 and IPv6. You can perform wildcard bind on both of the address families, on the same port. -The following table show the behavior of FreeBSD4x. +There are some OS-platform differences in KAME code, as we use tcp/udp +code from different origin. The following table summarizes the behavior. listening side initiating side - (AF_INET6 wildcard (connetion to ::ffff:10.1.1.1) + (AF_INET6 wildcard (connection to ::ffff:10.1.1.1) socket gets IPv4 conn.) --- --- -FreeBSD4x configurable supported +KAME/BSDI3 not supported not supported +KAME/FreeBSD228 not supported not supported +KAME/FreeBSD3x configurable supported default: enabled +KAME/FreeBSD4x configurable supported + default: enabled +KAME/NetBSD configurable supported + default: disabled +KAME/BSDI4 enabled supported +KAME/OpenBSD not supported not supported The following sections will give you more details, and how you can configure the behavior. @@ -560,8 +761,9 @@ configure the behavior. Comments on listening side: It looks that RFC2553 talks too little on wildcard bind issue, -especially on the port space issue, failure mode and relationship -between AF_INET/INET6 wildcard bind. There can be several separate +specifically on (1) port space issue, (2) failure mode, (3) relationship +between AF_INET/INET6 wildcard bind like ordering constraint, and (4) behavior +when conflicting socket is opened/closed. There can be several separate interpretation for this RFC which conform to it but behaves differently. So, to implement portable application you should assume nothing about the behavior in the kernel. Using getaddrinfo() is the safest way. @@ -569,37 +771,24 @@ Port number space and wildcard bind issues were discussed in detail on ipv6imp mailing list, in mid March 1999 and it looks that there's no concrete consensus (means, up to implementers). You may want to check the mailing list archives. +We supply a tool called "bindtest" that explores the behavior of +kernel bind(2). The tool will not be compiled by default. If a server application would like to accept IPv4 and IPv6 connections, -there will be two alternatives. - -One is using AF_INET and AF_INET6 socket (you'll need two sockets). +it should use AF_INET and AF_INET6 socket (you'll need two sockets). Use getaddrinfo() with AI_PASSIVE into ai_flags, and socket(2) and bind(2) to all the addresses returned. By opening multiple sockets, you can accept connections onto the socket with proper address family. IPv4 connections will be accepted by AF_INET socket, -and IPv6 connections will be accepted by AF_INET6 socket. +and IPv6 connections will be accepted by AF_INET6 socket (NOTE: KAME/BSDI4 +kernel sometimes violate this - we will fix it). -Another way is using one AF_INET6 wildcard bind socket. -Use getaddrinfo() with AI_PASSIVE into ai_flags and with -AF_INET6 into ai_family, and set the 1st argument hostname to -NULL. And socket(2) and bind(2) to the address returned. -(should be IPv6 unspecified addr) -You can accept either of IPv4 and IPv6 packet via this one socket. - -To support only IPv6 traffic on AF_INET6 wildcard binded socket portably, -always check the peer address when a connection is made toward +If you try to support IPv6 traffic only and would like to reject IPv4 +traffic, always check the peer address when a connection is made toward AF_INET6 listening socket. If the address is IPv4 mapped address, you may want to reject the connection. You can check the condition by using -IN6_IS_ADDR_V4MAPPED() macro. -To resolv this issue more easily, there is system dependent setsockopt() -option, IPV6_BINDV6ONLY, used like below. - int on; - - setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY, - (char *)&on, sizeof (on)) < 0)); -When this call succeed, then this socket only receive IPv6 packets. - +IN6_IS_ADDR_V4MAPPED() macro. This is one of the reasons the author of +the section (itojun) dislikes special behavior of AF_INET6 wildcard bind. Comments on initiating side: @@ -609,66 +798,193 @@ is the key to the success: - NEVER hardcode AF_INET nor AF_INET6. - Use getaddrinfo() and getnameinfo() throughout the system. Never use gethostby*(), getaddrby*(), inet_*() or getipnodeby*(). - (To update existing applications to be IPv6 aware easily, - sometime getipnodeby*() will be useful. But if possible, try to - rewrite the code to use getaddrinfo() and getnameinfo().) - If you would like to connect to destination, use getaddrinfo() and try all the destination returned, like telnet does. - Some of the IPv6 stack is shipped with buggy getaddrinfo(). Ship a minimal working version with your application and use that as last resort. If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing -connection, you will need to use getipnodebyname(). When you would like to -update your existing appication to be IPv6 aware with minimal effort, -this approach might be choosed. But please note that it is a temporal -solution, because getipnodebyname() itself is not recommended as it does -not handle scoped IPv6 addresses at all. For IPv6 name resolution, -getaddrinfo() is the preferred API. So you should rewrite your -application to use getaddrinfo(), when you get the time to do it. +connection, you will need tweaked implementation in DNS support libraries, +as documented in RFC2553 6.1. KAME libinet6 includes the tweak in +getipnodebyname(). Note that getipnodebyname() itself is not recommended as +it does not handle scoped IPv6 addresses at all. For IPv6 name resolution +getaddrinfo() is the preferred API. getaddrinfo() does not implement the +tweak. When writing applications that make outgoing connections, story goes much -simpler if you treat AF_INET and AF_INET6 as totally seaprate address family. +simpler if you treat AF_INET and AF_INET6 as totally separate address family. {set,get}sockopt issue goes simpler, DNS issue will be made simpler. We do not recommend you to rely upon IPv4 mapped address. -1.12.1 FreeBSD4x +1.12.1 KAME/BSDI3 and KAME/FreeBSD228 -FreeBSD4x uses shared tcp4/6 code (from sys/netinet/tcp*) and separete -udp4/6 code. It uses unified inpcb/in6pcb structure. +The platforms do not support IPv4 mapped address at all (both listening side +and initiating side). AF_INET6 and AF_INET sockets are totally separated. -The platform can be configured to support IPv4 mapped address. -Kernel configuration is summarized as follows: -- By default, AF_INET6 socket will grab IPv4 connections in certain condition, - and can initiate connection to IPv4 destination embedded in - IPv4 mapped IPv6 address. -- You can disable it on entire system with sysctl like below. - sysctl -w net.inet6.ip6.mapped_addr=0 +Port number space is totally separate between AF_INET and AF_INET6 sockets. -1.12.1.1 FreeBSD4x, listening side +1.12.2 KAME/FreeBSD[34]x -Each socket can be configured to support special AF_INET6 wildcard bind -(enabled by default). -You can disable it on each socket basis with setsockopt() like below. - int on; +KAME/FreeBSD3x and KAME/FreeBSD4x use shared tcp4/6 code (from +sys/netinet/tcp*) and shared udp4/6 code (from sys/netinet/udp*). +They use unified inpcb/in6pcb structure. - setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY, - (char *)&on, sizeof (on)) < 0)); +1.12.2.1 KAME/FreeBSD[34]x, listening side -Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following +The platform can be configured to support IPv4 mapped address/special +AF_INET6 wildcard bind (enabled by default). There is no kernel compilation +option to disable it. You can enable/disable the behavior with sysctl +(per-node), or setsockopt (per-socket). + +Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following conditions are satisfied: - there's no AF_INET socket that matches the IPv4 connection - the AF_INET6 socket is configured to accept IPv4 traffic, i.e. getsockopt(IPV6_BINDV6ONLY) returns 0. -There's no problem with open/close ordering. -1.12.1.2 FreeBSD4x, initiating side +(XXX need checking) -FreeBSD4x supports outgoing connetion to IPv4 mapped address -(::ffff:10.1.1.1), if the node is configured to support IPv4 mapped address. +1.12.2.2 KAME/FreeBSD[34]x, initiating side + +KAME/FreeBSD3x supports outgoing connection to IPv4 mapped address +(::ffff:10.1.1.1), if the node is configured to accept IPv4 connections +by AF_INET6 socket. + +(XXX need checking) + +1.12.3 KAME/NetBSD + +KAME/NetBSD uses shared tcp4/6 code (from sys/netinet/tcp*) and shared +udp4/6 code (from sys/netinet/udp*). The implementation is made differently +from KAME/FreeBSD[34]x. KAME/NetBSD uses separate inpcb/in6pcb structures, +while KAME/FreeBSD[34]x uses merged inpcb structure. + +1.12.3.1 KAME/NetBSD, listening side + +The platform can be configured to support IPv4 mapped address/special AF_INET6 +wildcard bind (disabled by default). Kernel behavior can be summarized as +follows: +- default: special support code will be compiled in, but is disabled by + default. It can be controlled by sysctl (net.inet6.ip6.bindv6only), + or setsockopt(IPV6_BINDV6ONLY). +- add "INET6_BINDV6ONLY": No special support code for AF_INET6 wildcard socket + will be compiled in. AF_INET6 sockets and AF_INET sockets are totally + separate. The behavior is similar to what described in 1.12.1. + +sysctl setting will affect per-socket configuration at in6pcb creation time +only. In other words, per-socket configuration will be copied from sysctl +configuration at in6pcb creation time. To change per-socket behavior, you +must perform setsockopt or reopen the socket. Change in sysctl configuration +will not change the behavior or sockets that are already opened. + +Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following +conditions are satisfied: +- there's no AF_INET socket that matches the IPv4 connection +- the AF_INET6 socket is configured to accept IPv4 traffic, i.e. + getsockopt(IPV6_BINDV6ONLY) returns 0. + +You cannot bind(2) with IPv4 mapped address. This is a workaround for port +number duplicate and other twists. + +1.12.3.2 KAME/NetBSD, initiating side + +When you initiate a connection, you can always connect to IPv4 destination +over AF_INET6 socket, usin IPv4 mapped address destination (::ffff:10.1.1.1). +This is enabled independently from the configuration for listening side, and +always enabled. + +1.12.4 KAME/BSDI4 + +KAME/BSDI4 uses NRL-based TCP/UDP stack and inpcb source code, +which was derived from NRL IPv6/IPsec stack. We guess it supports IPv4 mapped +address and speical AF_INET6 wildcard bind. The implementation is, again, +different from other KAME/*BSDs. + +1.12.4.1 KAME/BSDI4, listening side + +NRL inpcb layer supports special behavior of AF_INET6 wildcard socket. +There is no way to disable the behavior. + +Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following +condition is satisfied: +- there's no AF_INET socket that matches the IPv4 connection + +1.12.4.2 KAME/BSDI4, initiating side + +KAME/BSDi4 supports connection initiation to IPv4 mapped address +(like ::ffff:10.1.1.1). + +1.12.5 KAME/OpenBSD + +KAME/OpenBSD uses NRL-based TCP/UDP stack and inpcb source code, +which was derived from NRL IPv6/IPsec stack. + +1.12.5.1 KAME/OpenBSD, listening side + +KAME/OpenBSD disables special behavior on AF_INET6 wildcard bind for +security reasons (if IPv4 traffic toward AF_INET6 wildcard bind is allowed, +access control will become much harder). KAME/BSDI4 uses NRL-based TCP/UDP +stack as well, however, the behavior is different due to OpenBSD's security +policy. + +As a result the behavior of KAME/OpenBSD is similar to KAME/BSDI3 and +KAME/FreeBSD228 (see 1.12.1 for more detail). + +1.12.5.2 KAME/OpenBSD, initiating side + +KAME/OpenBSD does not support connection initiation to IPv4 mapped address +(like ::ffff:10.1.1.1). + +1.12.6 More issues + +IPv4 mapped address support adds a big requirement to EVERY userland codebase. +Every userland code should check if an AF_INET6 sockaddr contains IPv4 +mapped address or not. This adds many twists: + +- Access controls code becomes harder to write. + For example, if you would like to reject packets from 10.0.0.0/8, + you need to reject packets to AF_INET socket from 10.0.0.0/8, + and to AF_INET6 socket from ::ffff:10.0.0.0/104. +- If a protocol on top of IPv4 is defined differently with IPv6, we need to be + really careful when we determine which protocol to use. + For example, with FTP protocol, we can not simply use sa_family to determine + FTP command sets. The following example is incorrect: + if (sa_family == AF_INET) + use EPSV/EPRT or PASV/PORT; /*IPv4*/ + else if (sa_family == AF_INET6) + use EPSV/EPRT or LPSV/LPRT; /*IPv6*/ + else + error; + Under SIIT environment, the correct code would be: + if (sa_family == AF_INET) + use EPSV/EPRT or PASV/PORT; /*IPv4*/ + else if (sa_family == AF_INET6 && IPv4 mapped address) + use EPSV/EPRT or PASV/PORT; /*IPv4 command set on AF_INET6*/ + else if (sa_family == AF_INET6 && !IPv4 mapped address) + use EPSV/EPRT or LPSV/LPRT; /*IPv6*/ + else + error; + It is too much to ask for every body to be careful like this. + The problem is, we are not sure if the above code fragment is perfect for + all situations. +- By enabling kernel support for IPv4 mapped address (outgoing direction), + servers on the kernel can be hosed by IPv6 native packet that has IPv4 + mapped address in IPv6 header source, and can generate unwanted IPv4 packets. + http://playground.iijlab.net/i-d/draft-itojun-ipv6-transition-abuse-00.txt + talks more about this scenario. + +Due to the above twists, some of KAME userland programs has restrictions on +the use of IPv4 mapped addresses: +- rshd/rlogind do not accept connections from IPv4 mapped address. + This is to avoid malicious use of IPv4 mapped address in IPv6 native + packet, to bypass source-address based authentication. +- ftp/ftpd does not support SIIT environment. IPv4 mapped address will be + decoded in userland, and will be passed to AF_INET sockets + (SIIT client should pass IPv4 mapped address as is, to AF_INET6 sockets). 1.13 sockaddr_storage -When RFC2553 was about to be finalized, there was discusson on how struct +When RFC2553 was about to be finalized, there was discussion on how struct sockaddr_storage members are named. One proposal is to prepend "__" to the members (like "__ss_len") as they should not be touched. The other proposal was that don't prepend it (like "ss_len") as we need to touch those members @@ -692,7 +1008,7 @@ definition. KAME kit prior to December 1999 used RFC2553 definition. KAME kit after December 1999 (including December) will conform to XNET definition, -based on RFC2553bis discusson. +based on RFC2553bis discussion. If you look at multiple IPv6 implementations, you will be able to see both definitions. As an userland programmer, the most portable way of @@ -705,25 +1021,247 @@ dealing with it is to: struct sockaddr_storage ss; family = ((struct sockaddr *)&ss)->sa_family +1.14 Invalid addresses on the wire + +Some of IPv6 transition technologies embed IPv4 address into IPv6 address. +These specifications themselves are fine, however, there can be certain +set of attacks enabled by these specifications. Recent speicifcation +documents covers up those issues, however, there are already-published RFCs +that does not have protection against those (like using source address of +::ffff:127.0.0.1 to bypass "reject packet from remote" filter). + +To name a few, these address ranges can be used to hose an IPv6 implementation, +or bypass security controls: +- IPv4 mapped address that embeds unspecified/multicast/loopback/broadcast + IPv4 address (if they are in IPv6 native packet header, they are malicious) + ::ffff:0.0.0.0/104 ::ffff:127.0.0.0/104 + ::ffff:224.0.0.0/100 ::ffff:255.0.0.0/104 +- 6to4 prefix generated from unspecified/multicast/loopback/broadcast/private + IPv4 address + 2002:0000::/24 2002:7f00::/24 2002:e000::/24 + 2002:ff00::/24 2002:0a00::/24 2002:ac10::/28 + 2002:c0a8::/32 + +Also, since KAME does not support RFC1933 auto tunnels, seeing IPv4 compatible +is very rare. You should take caution if you see those on the wire. + +KAME code is carefully written to avoid such incidents. More specifically, +KAME kernel will reject packets with certain source/dstination address in IPv6 +base header, or IPv6 routing header. Also, KAME default configuration file +is written carefully, to avoid those attacks. + +http://playground.iijlab.net/i-d/draft-itojun-ipv6-transition-abuse-00.txt +talks about more about this. + +1.15 Node's required addresses + +RFC2373 section 2.8 talks about required addresses for an IPv6 +node. The section talks about how KAME stack manages those required +addresses. + +1.15.1 Host case + +The following items are automatically assigned to the node (or the node will +automatically joins the group), at bootstrap time: +- Loopback address +- All-nodes multicast addresses (ff01::1) + +The following items will be automatically handled when the interface becomes +IFF_UP: +- Its link-local address for each interface +- Solicited-node multicast address for link-local addresses +- Link-local allnodes multicast address (ff02::1) + +The following items need to be configured manually by ifconfig(8) or prefix(8). +Alternatively, these can be autoconfigured by using stateless address +autoconfiguration. +- Assigned unicast/anycast addresses +- Solicited-Node multicast address for assigned unicast address + +Users can join groups by using appropriate system calls like setsockopt(2). + +1.15.2 Router case + +In addition to the above, routers needs to handle the following items. + +The following items need to be configured manually by using ifconfig(8). +o The subnet-router anycast addresses for the interfaces it is configured + to act as a router on (prefix::/64) +o All other anycast addresses with which the router has been configured + +The router will join the following multicast group when rtadvd(8) is available +for the interface. +o All-Routers Multicast Addresses (ff02::2) + +Routing daemons will join appropriate multicast groups, as necessary, +like ff02::9 for RIPng. + +Users can join groups by using appropriate system calls like setsockopt(2). + 2. Network Drivers -KAME requires two items to be added into the standard drivers: +KAME requires three items to be added into the standard drivers: (1) mbuf clustering requirement. In this stable release, we changed MINCLSIZE into MHLEN+1 for all the operating systems in order to make - all the drivers behave as we expect. + all the drivers behave as we expect. (2) multicast. If "ifmcstat" yields no multicast group for a interface, that interface has to be patched. -If any of the driver don't support the requirements, then the driver -can't be used for IPv6 and/or IPsec communication. If you find any -problem with your card using IPv6/IPsec, then, please report it to -freebsd-bugs@freebsd.org. +To avoid troubles, we suggest you to comment out the device drivers +for unsupported/unnecessary cards, from the kernel configuration file. +If you accidentally enable unsupported drivers, some of the userland +tools may not work correctly (routing daemons are typical example). + +In the following sections, "official support" means that KAME developers +are using that ethernet card/driver frequently. (NOTE: In the past we required all pcmcia drivers to have a call to in6_ifattach(). We have no such requirement any more) +2.1 FreeBSD 2.2.x-RELEASE + +Here is a list of FreeBSD 2.2.x-RELEASE drivers and its conditions: + + driver mbuf(1) multicast(2) official support? + --- --- --- --- + (Ethernet) + ar looks ok - - + cnw ok ok yes (*) + ed ok ok yes + ep ok ok yes + fe ok ok yes + sn looks ok - - (*) + vx looks ok - - + wlp ok ok - (*) + xl ok ok yes + zp ok ok - + (FDDI) + fpa looks ok ? - + (ATM) + en ok ok yes + (Serial) + lp ? - not work + sl ? - not work + sr looks ok ok - (**) + +You may want to add an invocation of "rtsol" in "/etc/pccard_ether", +if you are using notebook computers and PCMCIA ethernet card. + +(*) These drivers are distributed with PAO (http://www.jp.freebsd.org/PAO/). + +(**) There was some report says that, if you make sr driver up and down and +then up, the kernel may hang up. We have disabled frame-relay support from +sr driver and after that this looks to be working fine. If you need +frame-relay support to come back, please contact KAME developers. + +2.2 BSD/OS 3.x + +The following lists BSD/OS 3.x device drivers and its conditions: + + driver mbuf(1) multicast(2) official support? + --- --- --- --- + (Ethernet) + cnw ok ok yes + de ok ok - + df ok ok - + eb ok ok - + ef ok ok yes + exp ok ok - + mz ok ok yes + ne ok ok yes + we ok ok - + (FDDI) + fpa ok ok - + (ATM) + en maybe ok - + (Serial) + ntwo ok ok yes + sl ? - not work + appp ? - not work + +You may want to use "@insert" directive in /etc/pccard.conf to invoke +"rtsol" command right after dynamic insertion of PCMCIA ethernet cards. + +2.3 NetBSD + +The following table lists the network drivers we have tried so far. + + driver mbuf(1) multicast(2) official support? + --- --- --- --- + (Ethernet) + awi pcmcia/i386 ok ok - + bah zbus/amiga NG(*) + cnw pcmcia/i386 ok ok yes + ep pcmcia/i386 ok ok - + le sbus/sparc ok ok yes + ne pci/i386 ok ok yes + ne pcmcia/i386 ok ok yes + wi pcmcia/i386 ok ok yes + (ATM) + en pci/i386 ok ok - + +(*) This may need some fix, but I'm not sure what arcnet interfaces assume... + +2.4 FreeBSD 3.x-RELEASE + +Here is a list of FreeBSD 3.x-RELEASE drivers and its conditions: + + driver mbuf(1) multicast(2) official support? + --- --- --- --- + (Ethernet) + cnw ok ok -(*) + ed ? ok - + ep ok ok - + fe ok ok yes + fxp ?(**) + lnc ? ok - + sn ? ? -(*) + wi ok ok yes + xl ? ok - + +(*) These drivers are distributed with PAO as PAO3 + (http://www.jp.freebsd.org/PAO/). +(**) there are trouble reports with multicast filter initialization. + +More drivers will just simply work on KAME FreeBSD 3.x-RELEASE but have not +been checked yet. + +2.5 OpenBSD 2.x + +Here is a list of OpenBSD 2.x drivers and its conditions: + + driver mbuf(1) multicast(2) official support? + --- --- --- --- + (Ethernet) + de pci/i386 ok ok yes + fxp pci/i386 ?(*) + le sbus/sparc ok ok yes + ne pci/i386 ok ok yes + ne pcmcia/i386 ok ok yes + wi pcmcia/i386 ok ok yes + +(*) There seem to be some problem in driver, with multicast filter +configuration. This happens with certain revision of chipset on the card. +Should be fixed by now by workaround in sys/net/if.c, but still not sure. + +2.6 BSD/OS 4.x + +The following lists BSD/OS 4.x device drivers and its conditions: + + driver mbuf(1) multicast(2) official support? + --- --- --- --- + (Ethernet) + de ok ok yes + exp (*) + +You may want to use "@insert" directive in /etc/pccard.conf to invoke +"rtsol" command right after dynamic insertion of PCMCIA ethernet cards. + +(*) exp driver has serious conflict with KAME initialization sequence. +A workaround is committed into sys/i386/pci/if_exp.c, and should be okay by now. + 3. Translator We categorize IPv4/IPv6 translator into 4 types. @@ -746,7 +1284,6 @@ to an IPv4 host in an IPv4 island. KAME provides an TCP relay translator for category A. This is called "FAITH". We also provide IP header translator for category A. -(The latter is not yet put into FreeBSD4.x yet.) 3.1 FAITH TCP relay translator @@ -768,19 +1305,24 @@ the connection will be relayed toward IPv4 destination 163.221.202.12. faithd must be invoked on FAITH-relay dual stack node. -For more details, consult src/usr.sbin/faithd/README. +For more details, consult kame/kame/faithd/README and +draft-ietf-ngtrans-tcpudp-relay-01.txt. 3.2 IPv6-to-IPv4 header translator -(to be written) +# removed since it is not imported to FreeBSD-current 4. IPsec -IPsec is mainly organized by three components. +IPsec is implemented as the following three components. (1) Policy Management (2) Key Management -(3) AH and ESP handling +(3) AH, ESP and IPComp handling in kernel + +Note that KAME/OpenBSD does NOT include support for KAME IPsec code, +as OpenBSD team has their home-brew IPsec stack and they have no plan +to replace it. IPv6 support for IPsec is, therefore, lacking on KAME/OpenBSD. 4.1 Policy Management @@ -790,20 +1332,29 @@ setsockopt(3). In this cases, policy configuration is described in ipsec_set_policy(3). The other is to configure kernel packet filter-based policy using PF_KEY interface, via setkey(8). -The policy entry is not re-ordered with its -indexes, so the order of entry when you add is very significant. +The policy entry will be matched in order. The order of entries makes +difference in behavior. 4.2 Key Management The key management code implemented in this kit (sys/netkey) is a home-brew PFKEY v2 implementation. This conforms to RFC2367. -The home-brew IKE daemon, "racoon" is included in the kit -(kame/kame/racoon). +The home-brew IKE daemon, "racoon" is included in the kit (kame/kame/racoon, +or usr.sbin/racoon). Basically you'll need to run racoon as daemon, then setup a policy to require keys (like ping -P 'out ipsec esp/transport//use'). The kernel will contact racoon daemon as necessary to exchange keys. +In IKE spec, there's ambiguity about interpretation of "tunnel" proposal. +For example, if we would like to propose the use of following packet: + IP AH ESP IP payload +some implementation proposes it as "AH transport and ESP tunnel", since +this is more logical from packet construction point of view. Some +implementation proposes it as "AH tunnel and ESP tunnel". +Racoon follows the former route. +This raises real interoperability issue. We hope this to be resolved quickly. + 4.3 AH and ESP handling IPsec module is implemented as "hooks" to the standard IPv4/IPv6 @@ -827,18 +1378,72 @@ transform are listed in {esp,ah}_core.c with wrapper functions. If you wish to add some algorithm, add wrapper function in {esp,ah}_core.c, and add your crypto algorithm code into sys/crypto. -Tunnel mode is partially supported in this release, with the following -restrictions: -- IPsec tunnel is not combined with GIF generic tunneling interface. - It needs a great care because we may create an infinite loop between - ip_output() and tunnelifp->if_output(). Opinion varies if it is better - to unify them, or not. -- MTU and Don't Fragment bit (IPv4) considerations need more checking, but - basically works fine. +Tunnel mode works basically fine, but comes with the following restrictions: +- You cannot run routing daemon across IPsec tunnel, since we do not model + IPsec tunnel as pseudo interfaces. - Authentication model for AH tunnel must be revisited. We'll need to improve the policy management engine, eventually. +- Tunnelling for IPv6 IPsec is still incomplete. This is disabled by default. + If you need to perform experiments, add "options IPSEC_IPV6FWD" into + the kernel configuration file. Note that path MTU discovery does not work + across IPv6 IPsec tunnel gateway due to insufficient code. -4.4 Conformance to RFCs and IDs +AH specificaton does not talk much about "multiple AH on a packet" case. +We incrementally compute AH checksum, from inside to outside. Also, we +treat inner AH to be immutable. +For example, if we are to create the following packet: + IP AH1 AH2 AH3 payload +we do it incrementally. As a result, we get crypto checksums like below: + AH3 has checksum against "IP AH3' payload". + where AH3' = AH3 with checksum field filled with 0. + AH2 has checksum against "IP AH2' AH3 payload". + AH1 has checksum against "IP AH1' AH2 AH3 payload", +Also note that AH3 has the smallest sequence number, and AH1 has the largest +sequence number. + +4.4 IPComp handling + +IPComp stands for IP payload compression protocol. This is aimed for +payload compression, not the header compression like PPP VJ compression. +This may be useful when you are using slow serial link (say, cell phone) +with powerful CPU (well, recent notebook PCs are really powerful...). +The protocol design of IPComp is very similar to IPsec, though it was +defined separately from IPsec itself. + +Here are some points to be noted: +- IPComp is treated as part of IPsec protocol suite, and SPI and + CPI space is unified. Spec says that there's no relationship + between two so they are assumed to be separate in specs. +- IPComp association (IPCA) is kept in SAD. +- It is possible to use well-known CPI (CPI=2 for DEFLATE for example), + for outbound/inbound packet, but for indexing purposes one element from + SPI/CPI space will be occupied anyway. +- pfkey is modified to support IPComp. However, there's no official + SA type number assignment yet. Portability with other IPComp + stack is questionable (anyway, who else implement IPComp on UN*X?). +- Spec says that IPComp output processing must be performed before AH/ESP + output processing, to achieve better compression ratio and "stir" data + stream before encryption. The most meaningful processing order is: + (1) compress payload by IPComp, (2) encrypt payload by ESP, then (3) attach + authentication data by AH. + However, with manual SPD setting, you are able to violate the ordering + (KAME code is too generic, maybe). Also, it is just okay to use IPComp + alone, without AH/ESP. +- Though the packet size can be significantly decreased by using IPComp, no + special consideration is made about path MTU (spec talks nothing about MTU + consideration). IPComp is designed for serial links, not ethernet-like + medium, it seems. +- You can change compression ratio on outbound packet, by changing + deflate_policy in sys/netinet6/ipcomp_core.c. You can also change outbound + history buffer size by changing deflate_window_out in the same source code. + (should it be sysctl accessible, or per-SAD configurable?) +- Tunnel mode IPComp is not working right. KAME box can generate tunnelled + IPComp packet, however, cannot accept tunneled IPComp packet. +- You can negotiate IPComp association with racoon IKE daemon. +- KAME code does not attach Adler32 checksum to compressed data. + see ipsec wg mailing list discussion in Jan 2000 for details. + +4.5 Conformance to RFCs and IDs The IPsec code in the kernel conforms (or, tries to conform) to the following standards: @@ -846,8 +1451,10 @@ following standards: "new IPsec" specification documented in rfc240[1-6].txt, rfc241[01].txt, rfc2451.txt and draft-mcdonald-simple-ipsec-api-01.txt (draft expired, but you can take from ftp://ftp.kame.net/pub/internet-drafts/). - (NOTE: IKE specifications, rfc241[7-9].txt are implemented in userland, + (NOTE: IKE specifications, rfc240[7-9].txt are implemented in userland, as "racoon" IKE daemon) + IPComp: + RFC2393: IP Payload Compression Protocol (IPComp) Currently supported algorithms are: old IPsec AH @@ -877,6 +1484,8 @@ Currently supported algorithms are: each of the above can be combined with: ESP authentication with HMAC-MD5(96bit) ESP authentication with HMAC-SHA1(96bit) + IPComp + RFC2394: IP Payload Compression Using DEFLATE The following algorithms are NOT supported: old IPsec AH @@ -884,16 +1493,14 @@ The following algorithms are NOT supported: (rfc2085.txt) keyed SHA1 with 160bit crypto checksum + 32bit padding (rfc1852.txt) -IPsec (in kernel) and IKE (in userland as "racoon") has been tested -at several interoperability test events, and it is known to interoperate -with many other implementations well. Also, KAME IPsec has quite wide -coverage for IPsec crypto algorithms documented in RFC (we cover -algorithms without intellectual property issues only). +The key/policy management API is based on the following document, with fair +amount of extensions: + RFC2367: PF_KEY key management API -4.5 ECN consideration on IPsec tunnels +4.6 ECN consideration on IPsec tunnels KAME IPsec implements ECN-friendly IPsec tunnel, described in -draft-ipsec-ecn-00.txt. +draft-ietf-ipsec-ecn-02.txt. Normal IPsec tunnel is described in RFC2401. On encapsulation, IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner IP header to outer IP header. On decapsulation outer IP header @@ -902,7 +1509,7 @@ with ECN, since ECN bit on the outer IP TOS/traffic class field will be lost. To make IPsec tunnel ECN-friendly, we should modify encapsulation and decapsulation procedure. This is described in -http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt, chapter 3. +draft-ietf-ipsec-ecn-02.txt, chapter 3.3. KAME IPsec tunnel implementation can give you three behaviors, by setting net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some value: @@ -910,7 +1517,8 @@ net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some value: - ECN forbidden (sysctl value 0) - ECN allowed (sysctl value 1) Note that the behavior is configurable in per-node manner, not per-SA manner -(draft-ipsec-ecn-00 wants per-SA configuration, but it looks too much for me). +(draft-ietf-ipsec-ecn-02 wants per-SA configuration, but it looks too much +for me). The behavior is summarized as follows (see source code for more detail): @@ -937,62 +1545,41 @@ General strategy for configuration is as follows: The default behavior is "ECN forbidden" (sysctl value 0). For more information, please refer to: - http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt + draft-ietf-ipsec-ecn-02.txt RFC2481 (Explicit Congestion Notification) KAME sys/netinet6/{ah,esp}_input.c (Thanks goes to Kenjiro Cho for detailed analysis) -4.6 Interoperability +4.7 Interoperability + +IPsec, IPComp (in kernel) and IKE (in userland as "racoon") has been tested +at several interoperability test events, and it is known to interoperate +with many other implementations well. Also, KAME IPsec has quite wide +coverage for IPsec crypto algorithms documented in RFC (we do not cover +algorithms with intellectual property issues, though). Here are (some of) platforms we have tested IPsec/IKE interoperability -in the past. Note that both ends (KAME and others) may have modified their -implementation, so use the following list just for reference purposes. - Altiga, Ashley-laurent (vpcom.com), Data Fellows (F-Secure), Ericsson - ACC, FreeS/WAN, HITACHI, IBM AIX, IIJ, Intel, Microsoft WinNT, NIST - (linux IPsec + plutoplus), Netscreen, OpenBSD, RedCreek, Routerware, - SSH, Secure Computing, Soliton, Toshiba, VPNet, Yamaha RT100i +in the past, in no particular order. Note that both ends (KAME and +others) may have modified their implementation, so use the following +list just for reference purposes. + Altiga, Ashley-laurent (vpcom.com), Data Fellows (F-Secure), + BlueSteel, CISCO, Ericsson, ACC, Fitel, FreeS/WAN, HITACHI, IBM + AIX, IIJ, Intel, Microsoft WinNT, NAI PGPnet, + NIST (linux IPsec + plutoplus), Netscreen, OpenBSD isakmpd, Radguard, + RedCreek, Routerware, SSH, Secure Computing, Soliton, Toshiba, + TIS/NAI Gauntret, VPNet, Yamaha RT100i -5. IPComp -(not yet put into FreeBSD4.x, due to inflate related changes in 4.x.) +Here are (some of) platforms we have tested IPComp/IKE interoperability +in the past, in no particular order. + IRE -IPComp stands for IP payload compression protocol. This is aimed for -payload compression, not the header compression like PPP VJ compression. -This may be useful when you are using slow serial link (say, cell phone) -with powerful CPU (well, recent notebook PCs are really powerful...). -The protocol design of IPComp is very similar to IPsec. +5. ALTQ -KAME implements the following specifications: -- RFC2393: IP Payload Compression Protocol (IPComp) -- RFC2394: IP Payload Compression Using DEFLATE +# removed since it is not imported to FreeBSD-current -Here are some points to be noted: -- IPComp is treated as part of IPsec protocol suite, and SPI and - CPI space is unified. Spec says that there's no relationship - between two so they are assumed to be separate. -- IPComp association (IPCA) is kept in SAD. -- It is possible to use well-known CPI (CPI=2 for DEFLATE for example), - for outbound/inbound packet, but for indexing purposes one element from - SPI/CPI space will be occupied anyway. -- pfkey is modified to support IPComp. However, there's no official - SA type number assignment yet. Portability with other IPComp - stack is questionable (anyway, who else implement IPComp on UN*X?). -- Spec says that IPComp output processing must be performed before IPsec - output processing, to achieve better compression ratio and "stir" data - stream before encryption. However, with manual SPD setting, you are able to - violate the ordering requirement (KAME code is too generic, maybe). -- Though MTU can be significantly decreased by using IPComp, no special - consideration is made about path MTU (spec talks nothing about MTU - consideration). IPComp is designed for serial links, not ethernet-like - medium, it seems. -- You can change compression ratio on outbound packet, by changing - deflate_policy in sys/netinet6/ipcomp_core.c. You can also change history - buffer size by changing deflate_window in the same source code. - (should it be sysctl accessible? or per-SAD configurable?) -- Tunnel mode IPComp is not working right. KAME box can generate tunnelled - IPComp packet, however, cannot accept tunneled IPComp packet. +6. mobile-ip6 -6. ALTQ - (not yet put into FreeBSD4.x) +# removed since it is not imported to FreeBSD-current