1# NOTE: this is from original KAME distribution.
2# Some portion of this document is not applicable to the code merged into
3# FreeBSD-current (for example, section 5).
4
| |
5 Implementation Note
6
7 KAME Project
8 http://www.kame.net/
9 $KAME: IMPLEMENTATION,v 1.216 2001/05/25 07:43:01 jinmei Exp $
| 1 Implementation Note
2
3 KAME Project
4 http://www.kame.net/
5 $KAME: IMPLEMENTATION,v 1.216 2001/05/25 07:43:01 jinmei Exp $
|
10 $FreeBSD: head/share/doc/IPv6/IMPLEMENTATION 121071 2003-10-13 14:57:41Z ume $
| 6 $FreeBSD: head/share/doc/IPv6/IMPLEMENTATION 122115 2003-11-05 12:00:32Z ume $
|
11
| 7
|
| 8NOTE: The document tries to describe behaviors/implementation choices
9of the latest KAME/*BSD stack (like KAME/NetBSD 1.5.1). The description
10here may not be applicable to KAME-integrated *BSD releases (like stock
11NetBSD 1.5.1), as we have certain amount of changes between them. Still,
12some of the content can be useful for KAME-integrated *BSD releases.
13
14Table of Contents
15
16 1. IPv6
17 1.1 Conformance
18 1.2 Neighbor Discovery
19 1.3 Scope Zone Index
20 1.3.1 Kernel internal
21 1.3.2 Interaction with API
22 1.3.3 Interaction with users (command line)
23 1.4 Plug and Play
24 1.4.1 Assignment of link-local, and special addresses
25 1.4.2 Stateless address autoconfiguration on hosts
26 1.4.3 DHCPv6
27 1.5 Generic tunnel interface
28 1.6 Address Selection
29 1.6.1 Source Address Selection
30 1.6.2 Destination Address Ordering
31 1.7 Jumbo Payload
32 1.8 Loop prevention in header processing
33 1.9 ICMPv6
34 1.10 Applications
35 1.11 Kernel Internals
36 1.12 IPv4 mapped address and IPv6 wildcard socket
37 1.12.1 KAME/BSDI3 and KAME/FreeBSD228
38 1.12.2 KAME/FreeBSD[34]x
39 1.12.2.1 KAME/FreeBSD[34]x, listening side
40 1.12.2.2 KAME/FreeBSD[34]x, initiating side
41 1.12.3 KAME/NetBSD
42 1.12.3.1 KAME/NetBSD, listening side
43 1.12.3.2 KAME/NetBSD, initiating side
44 1.12.4 KAME/BSDI4
45 1.12.4.1 KAME/BSDI4, listening side
46 1.12.4.2 KAME/BSDI4, initiating side
47 1.12.5 KAME/OpenBSD
48 1.12.5.1 KAME/OpenBSD, listening side
49 1.12.5.2 KAME/OpenBSD, initiating side
50 1.12.6 More issues
51 1.12.7 Interaction with SIIT translator
52 1.13 sockaddr_storage
53 1.14 Invalid addresses on the wire
54 1.15 Node's required addresses
55 1.15.1 Host case
56 1.15.2 Router case
57 1.16 Advanced API
58 1.17 DNS resolver
59 2. Network Drivers
60 2.1 FreeBSD 2.2.x-RELEASE
61 2.2 BSD/OS 3.x
62 2.3 NetBSD
63 2.4 FreeBSD 3.x-RELEASE
64 2.5 FreeBSD 4.x-RELEASE
65 2.6 OpenBSD 2.x
66 2.7 BSD/OS 4.x
67 3. Translator
68 3.1 FAITH TCP relay translator
69 3.2 IPv6-to-IPv4 header translator
70 4. IPsec
71 4.1 Policy Management
72 4.2 Key Management
73 4.3 AH and ESP handling
74 4.4 IPComp handling
75 4.5 Conformance to RFCs and IDs
76 4.6 ECN consideration on IPsec tunnels
77 4.7 Interoperability
78 4.8 Operations with IPsec tunnel mode
79 4.8.1 RFC2401 IPsec tunnel mode approach
80 4.8.2 draft-touch-ipsec-vpn approach
81 5. ALTQ
82 6. Mobile IPv6
83 6.1 KAME node as correspondent node
84 6.2 KAME node as home agent/mobile node
85 6.3 Old Mobile IPv6 code
86 7. Routing table extensions
87 7.1 ART routing table lookup algorithm
88 7.2 Multipath routing support
89 8. Coding style
90 9. Policy on technology with intellectual property right restriction
91
|
121. IPv6
13
141.1 Conformance
15
16The KAME kit conforms, or tries to conform, to the latest set of IPv6
17specifications. For future reference we list some of the relevant documents
18below (NOTE: this is not a complete list - this is too hard to maintain...).
19For details please refer to specific chapter in the document, RFCs, manpages
20come with KAME, or comments in the source code.
21
22Conformance tests have been performed on past and latest KAME STABLE kit,
23at TAHI project. Results can be viewed at http://www.tahi.org/report/KAME/.
24We also attended Univ. of New Hampshire IOL tests (http://www.iol.unh.edu/)
25in the past, with our past snapshots.
26
27RFC1639: FTP Operation Over Big Address Records (FOOBAR)
28 * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428,
29 then RFC1639 if failed.
30RFC1886: DNS Extensions to support IPv6
31RFC1933: (see RFC2893)
32RFC1981: Path MTU Discovery for IPv6
33RFC2080: RIPng for IPv6
34 * KAME-supplied route6d, bgpd and hroute6d support this.
35RFC2283: Multiprotocol Extensions for BGP-4
36 * so-called "BGP4+".
37 * KAME-supplied bgpd supports this.
38RFC2292: Advanced Sockets API for IPv6
| 921. IPv6
93
941.1 Conformance
95
96The KAME kit conforms, or tries to conform, to the latest set of IPv6
97specifications. For future reference we list some of the relevant documents
98below (NOTE: this is not a complete list - this is too hard to maintain...).
99For details please refer to specific chapter in the document, RFCs, manpages
100come with KAME, or comments in the source code.
101
102Conformance tests have been performed on past and latest KAME STABLE kit,
103at TAHI project. Results can be viewed at http://www.tahi.org/report/KAME/.
104We also attended Univ. of New Hampshire IOL tests (http://www.iol.unh.edu/)
105in the past, with our past snapshots.
106
107RFC1639: FTP Operation Over Big Address Records (FOOBAR)
108 * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428,
109 then RFC1639 if failed.
110RFC1886: DNS Extensions to support IPv6
111RFC1933: (see RFC2893)
112RFC1981: Path MTU Discovery for IPv6
113RFC2080: RIPng for IPv6
114 * KAME-supplied route6d, bgpd and hroute6d support this.
115RFC2283: Multiprotocol Extensions for BGP-4
116 * so-called "BGP4+".
117 * KAME-supplied bgpd supports this.
118RFC2292: Advanced Sockets API for IPv6
|
39 * For supported library functions/kernel APIs, see sys/netinet6/ADVAPI.
| 119 * see RFC3542
|
40RFC2362: Protocol Independent Multicast-Sparse Mode (PIM-SM)
41 * RFC2362 defines the packet formats and the protcol of PIM-SM.
42RFC2373: IPv6 Addressing Architecture
43 * KAME supports node required addresses, and conforms to the scope
44 requirement.
45RFC2374: An IPv6 Aggregatable Global Unicast Address Format
46 * KAME supports 64-bit length of Interface ID.
47RFC2375: IPv6 Multicast Address Assignments
48 * Userland applications use the well-known addresses assigned in the RFC.
49RFC2428: FTP Extensions for IPv6 and NATs
50 * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428,
51 then RFC1639 if failed.
52RFC2460: IPv6 specification
53RFC2461: Neighbor discovery for IPv6
54 * See 1.2 in this document for details.
55RFC2462: IPv6 Stateless Address Autoconfiguration
56 * See 1.4 in this document for details.
57RFC2463: ICMPv6 for IPv6 specification
| 120RFC2362: Protocol Independent Multicast-Sparse Mode (PIM-SM)
121 * RFC2362 defines the packet formats and the protcol of PIM-SM.
122RFC2373: IPv6 Addressing Architecture
123 * KAME supports node required addresses, and conforms to the scope
124 requirement.
125RFC2374: An IPv6 Aggregatable Global Unicast Address Format
126 * KAME supports 64-bit length of Interface ID.
127RFC2375: IPv6 Multicast Address Assignments
128 * Userland applications use the well-known addresses assigned in the RFC.
129RFC2428: FTP Extensions for IPv6 and NATs
130 * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428,
131 then RFC1639 if failed.
132RFC2460: IPv6 specification
133RFC2461: Neighbor discovery for IPv6
134 * See 1.2 in this document for details.
135RFC2462: IPv6 Stateless Address Autoconfiguration
136 * See 1.4 in this document for details.
137RFC2463: ICMPv6 for IPv6 specification
|
58 * See 1.8 in this document for details.
| 138 * See 1.9 in this document for details.
|
59RFC2464: Transmission of IPv6 Packets over Ethernet Networks
60RFC2465: MIB for IPv6: Textual Conventions and General Group
61 * Necessary statistics are gathered by the kernel. Actual IPv6 MIB
62 support is provided as patchkit for ucd-snmp.
63RFC2466: MIB for IPv6: ICMPv6 group
64 * Necessary statistics are gathered by the kernel. Actual IPv6 MIB
65 support is provided as patchkit for ucd-snmp.
66RFC2467: Transmission of IPv6 Packets over FDDI Networks
67RFC2472: IPv6 over PPP
68RFC2492: IPv6 over ATM Networks
69 * only PVC is supported.
70RFC2497: Transmission of IPv6 packet over ARCnet Networks
71RFC2545: Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing
| 139RFC2464: Transmission of IPv6 Packets over Ethernet Networks
140RFC2465: MIB for IPv6: Textual Conventions and General Group
141 * Necessary statistics are gathered by the kernel. Actual IPv6 MIB
142 support is provided as patchkit for ucd-snmp.
143RFC2466: MIB for IPv6: ICMPv6 group
144 * Necessary statistics are gathered by the kernel. Actual IPv6 MIB
145 support is provided as patchkit for ucd-snmp.
146RFC2467: Transmission of IPv6 Packets over FDDI Networks
147RFC2472: IPv6 over PPP
148RFC2492: IPv6 over ATM Networks
149 * only PVC is supported.
150RFC2497: Transmission of IPv6 packet over ARCnet Networks
151RFC2545: Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing
|
72RFC2553: Basic Socket Interface Extensions for IPv6
73 * IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind
74 socket (3.8) are,
75 - supported and turned on by default on KAME/FreeBSD[34]x
76 and KAME/BSDI4,
77 - supported but turned off by default on KAME/NetBSD,
78 - not supported on KAME/FreeBSD228, KAME/OpenBSD and KAME/BSDI3.
79 see 1.12 in this document for details.
| 152RFC2553: (see RFC3493)
|
80RFC2671: Extension Mechanisms for DNS (EDNS0)
81 * see USAGE for how to use it.
82 * not supported on kame/freebsd4 and kame/bsdi4.
83RFC2673: Binary Labels in the Domain Name System
84 * KAME/bsdi4 supports A6, DNAME and binary label to some extent.
85 * KAME apps/bind8 repository has resolver library with partial A6, DNAME
86 and binary label support.
87RFC2675: IPv6 Jumbograms
88 * See 1.7 in this document for details.
89RFC2710: Multicast Listener Discovery for IPv6
90RFC2711: IPv6 router alert option
91RFC2732: Format for Literal IPv6 Addresses in URL's
92 * The spec is implemented in programs that handle URLs
93 (like freebsd ftpio(3) and fetch(1), or netbsd ftp(1))
94RFC2766: Network Address Translation - Protocol Translation (NAT-PT)
95 * Section 4.2 is implemented by totd (see ports/totd, or pkgsrc/net/totd).
96RFC2874: DNS Extensions to Support IPv6 Address Aggregation and Renumbering
97 * KAME/bsdi4 supports A6, DNAME and binary label to some extent.
98 * KAME apps/bind8 repository has resolver library with partial A6, DNAME
99 and binary label support.
100RFC2893: Transition Mechanisms for IPv6 Hosts and Routers
101 * IPv4 compatible address is not supported.
102 * automatic tunneling (4.3) is not supported.
103 * "gif" interface implements IPv[46]-over-IPv[46] tunnel in a generic way,
104 and it covers "configured tunnel" described in the spec.
105 See 1.5 in this document for details.
106RFC2894: Router renumbering for IPv6
107RFC3041: Privacy Extensions for Stateless Address Autoconfiguration in IPv6
108RFC3056: Connection of IPv6 Domains via IPv4 Clouds
109 * So-called "6to4".
110 * "stf" interface implements it. Be sure to read
111 draft-itojun-ipv6-transition-abuse-01.txt
112 below before configuring it, there can be security issues.
| 153RFC2671: Extension Mechanisms for DNS (EDNS0)
154 * see USAGE for how to use it.
155 * not supported on kame/freebsd4 and kame/bsdi4.
156RFC2673: Binary Labels in the Domain Name System
157 * KAME/bsdi4 supports A6, DNAME and binary label to some extent.
158 * KAME apps/bind8 repository has resolver library with partial A6, DNAME
159 and binary label support.
160RFC2675: IPv6 Jumbograms
161 * See 1.7 in this document for details.
162RFC2710: Multicast Listener Discovery for IPv6
163RFC2711: IPv6 router alert option
164RFC2732: Format for Literal IPv6 Addresses in URL's
165 * The spec is implemented in programs that handle URLs
166 (like freebsd ftpio(3) and fetch(1), or netbsd ftp(1))
167RFC2766: Network Address Translation - Protocol Translation (NAT-PT)
168 * Section 4.2 is implemented by totd (see ports/totd, or pkgsrc/net/totd).
169RFC2874: DNS Extensions to Support IPv6 Address Aggregation and Renumbering
170 * KAME/bsdi4 supports A6, DNAME and binary label to some extent.
171 * KAME apps/bind8 repository has resolver library with partial A6, DNAME
172 and binary label support.
173RFC2893: Transition Mechanisms for IPv6 Hosts and Routers
174 * IPv4 compatible address is not supported.
175 * automatic tunneling (4.3) is not supported.
176 * "gif" interface implements IPv[46]-over-IPv[46] tunnel in a generic way,
177 and it covers "configured tunnel" described in the spec.
178 See 1.5 in this document for details.
179RFC2894: Router renumbering for IPv6
180RFC3041: Privacy Extensions for Stateless Address Autoconfiguration in IPv6
181RFC3056: Connection of IPv6 Domains via IPv4 Clouds
182 * So-called "6to4".
183 * "stf" interface implements it. Be sure to read
184 draft-itojun-ipv6-transition-abuse-01.txt
185 below before configuring it, there can be security issues.
|
113draft-ietf-ipngwg-icmp-name-lookups-07: IPv6 Name Lookups Through ICMP
114draft-ietf-dhc-dhcpv6-15.txt: DHCPv6
115draft-ietf-dhc-dhcpv6exts-12.txt: Extensions for DHCPv6
116 * kame/dhcp6 has test implementation, which will not be compiled in
117 default compilation.
118 * 15/12 drafts are not explicit about padding and string termination.
119 at IETF48, the author confirmed that there's no padding/termination
120 (and extensions can appear unaligned). our code follows the comment.
121draft-itojun-ipv6-tcp-to-anycast-00.txt:
122 Disconnecting TCP connection toward IPv6 anycast address
123draft-ietf-ipngwg-rfc2553bis-03.txt:
124 Basic Socket Interface Extensions for IPv6 (revised)
125draft-ietf-ipngwg-rfc2292bis-02.txt:
126 Advanced Sockets API for IPv6 (revised)
| 186RFC3152: Delegation of IP6.ARPA
187 * libinet6 resolvers contained in the KAME snaps support to use
188 the ip6.arpa domain (with the nibble format) for IPv6 reverse
189 lookups.
190RFC3484: Default Address Selection for IPv6
191 * the selection algorithm for both source and destination addresses
192 is implemented based on the RFC, though some rules are still omitted.
193RFC3493: Basic Socket Interface Extensions for IPv6
194 * IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind
195 socket (3.8) are,
196 - supported and turned on by default on KAME/FreeBSD[34]
197 and KAME/BSDI4,
198 - supported but turned off by default on KAME/NetBSD and KAME/FreeBSD5,
199 - not supported on KAME/FreeBSD228, KAME/OpenBSD and KAME/BSDI3.
200 see 1.12 in this document for details.
201RFC3542: Advanced Sockets API for IPv6 (revised)
202 * For supported library functions/kernel APIs, see sys/netinet6/ADVAPI.
|
127 * Some of the updates in the draft are not implemented yet. See
128 TODO.2292bis for more details.
| 203 * Some of the updates in the draft are not implemented yet. See
204 TODO.2292bis for more details.
|
129draft-ietf-mobileip-ipv6-13.txt: Mobility Support in IPv6
130 * See section 6.
| 205draft-ietf-ipngwg-icmp-name-lookups-09: IPv6 Name Lookups Through ICMP
|
131draft-ietf-ngtrans-tcpudp-relay-04.txt:
132 An IPv6-to-IPv4 transport relay translator
133 * FAITH tcp relay translator (faithd) implements this. See 3.1 for more
134 details.
135draft-ietf-ipngwg-router-selection-01.txt:
136 Default Router Preferences and More-Specific Routes
137 * router-side only.
138draft-ietf-ipngwg-scoping-arch-02.txt:
139 The architecture, text representation, and usage of IPv6
140 scoped addresses.
141 * some part of the documentation (especially about the routing
142 model) is not supported yet.
143draft-ietf-pim-sm-v2-new-02.txt
144 A revised version of RFC2362, which includes the IPv6 specific
145 packet format and protocol descriptions.
146draft-ietf-dnsext-mdns-00.txt: Multicast DNS
147 * kame/mdnsd has test implementation, which will not be built in
148 default compilation. The draft will experience a major change in the
149 near future, so don't rely upon it.
| 206draft-ietf-ngtrans-tcpudp-relay-04.txt:
207 An IPv6-to-IPv4 transport relay translator
208 * FAITH tcp relay translator (faithd) implements this. See 3.1 for more
209 details.
210draft-ietf-ipngwg-router-selection-01.txt:
211 Default Router Preferences and More-Specific Routes
212 * router-side only.
213draft-ietf-ipngwg-scoping-arch-02.txt:
214 The architecture, text representation, and usage of IPv6
215 scoped addresses.
216 * some part of the documentation (especially about the routing
217 model) is not supported yet.
218draft-ietf-pim-sm-v2-new-02.txt
219 A revised version of RFC2362, which includes the IPv6 specific
220 packet format and protocol descriptions.
221draft-ietf-dnsext-mdns-00.txt: Multicast DNS
222 * kame/mdnsd has test implementation, which will not be built in
223 default compilation. The draft will experience a major change in the
224 near future, so don't rely upon it.
|
150draft-itojun-ipv6-transition-abuse-02.txt:
| 225draft-itojun-ipv6-tcp-to-anycast-01.txt:
226 Disconnecting TCP connection toward IPv6 anycast address
227draft-itojun-ipv6-transition-abuse-01.txt:
|
151 Possible abuse against IPv6 transition technologies (expired)
152 * KAME does not implement RFC1933/2893 automatic tunnel.
153 * "stf" interface implements some address filters. Refer to stf(4)
154 for details. Since there's no way to make 6to4 interface 100% secure,
155 we do not include "stf" interface into GENERIC.v6 compilation.
156 * kame/openbsd completely disables IPv4 mapped address support.
157 * kame/netbsd makes IPv4 mapped address support off by default.
158 * See section 1.12.6 and 1.14 for more details.
| 228 Possible abuse against IPv6 transition technologies (expired)
229 * KAME does not implement RFC1933/2893 automatic tunnel.
230 * "stf" interface implements some address filters. Refer to stf(4)
231 for details. Since there's no way to make 6to4 interface 100% secure,
232 we do not include "stf" interface into GENERIC.v6 compilation.
233 * kame/openbsd completely disables IPv4 mapped address support.
234 * kame/netbsd makes IPv4 mapped address support off by default.
235 * See section 1.12.6 and 1.14 for more details.
|
159draft-itojun-ipv6-tclass-api-02.txt: Socket API for IPv6 traffic class field
| |
160draft-itojun-ipv6-flowlabel-api-01.txt: Socket API for IPv6 flow label field
161 * no consideration is made against the use of routing headers and such.
162
1631.2 Neighbor Discovery
164
165Neighbor Discovery is fairly stable. Currently Address Resolution,
166Duplicated Address Detection, and Neighbor Unreachability Detection
167are supported. In the near future we will be adding Unsolicited Neighbor
168Advertisement transmission command as admin tool.
169
170Duplicated Address Detection (DAD) will be performed when an IPv6 address
171is assigned to a network interface, or the network interface is enabled
172(ifconfig up). It is documented in RFC2462 5.4.
173If DAD fails, the address will be marked "duplicated" and message will be
174generated to syslog (and usually to console). The "duplicated" mark
175can be checked with ifconfig. It is administrators' responsibility to check
176for and recover from DAD failures. We may try to improve failure recovery
177in future KAME code.
178DAD procedure may not be effective on certain network interfaces/drivers.
179If a network driver needs long initialization time (with wireless network
180interfaces this situation is popular), and the driver mistakingly raises
181IFF_RUNNING before the driver becomes ready, DAD code will try to transmit
182DAD probes to not-really-ready network driver and the packet will not go out
183from the interface. In such cases, network drivers should be corrected.
184
185Some of network drivers loop multicast packets back to themselves,
186even if instructed not to do so (especially in promiscuous mode).
187In such cases DAD may fail, because DAD engine sees inbound NS packet
188(actually from the node itself) and considers it as a sign of duplicate.
189In this case, drivers should be corrected to honor IFF_SIMPLEX behavior.
190For example, you may need to check source MAC address on an inbound packet,
191and reject it if it is from the node itself.
192You may also want to look at #if condition marked "heuristics" in
193sys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note that the code
194fragment in "heuristics" section is not spec conformant).
195
196Neighbor Discovery specification (RFC2461) does not talk about neighbor
197cache handling in the following cases:
198(1) when there was no neighbor cache entry, node received unsolicited
199 RS/NS/NA/redirect packet without link-layer address
200(2) neighbor cache handling on medium without link-layer address
201 (we need a neighbor cache entry for IsRouter bit)
202For (1), we implemented workaround based on discussions on IETF ipngwg mailing
203list. For more details, see the comments in the source code and email
204thread started from (IPng 7155), dated Feb 6 1999.
205
206IPv6 on-link determination rule (RFC2461) is quite different from assumptions
207in BSD IPv4 network code. To implement behavior in RFC2461 section 5.2
208(when default router list is empty), the kernel needs to know the default
209outgoing interface. To configure the default outgoing interface, use
210commands like "ndp -I de0" as root. Note that the spec misuse the word
211"host" and "node" in several places in the section.
212
213To avoid possible DoS attacks and infinite loops, KAME stack will accept
214only 10 options on ND packet. Therefore, if you have 20 prefix options
215attached to RA, only the first 10 prefixes will be recognized.
216If this troubles you, please contact KAME team and/or modify
217nd6_maxndopt in sys/netinet6/nd6.c. If there are high demands we may
218provide sysctl knob for the variable.
219
220Proxy Neighbor Advertisement support is implemented in the kernel.
221For instance, you can configure it by using the following command:
222 # ndp -s fe80::1234%ne0 0:1:2:3:4:5 proxy
223where ne0 is the interface which attaches to the same link as the
224proxy target.
225There are certain limitations, though:
226- It does not send unsolicited multicast NA on configuration. This is MAY
227 behavior in RFC2461.
228- It does not add random delay before transmission of solicited NA. This is
229 SHOULD behavior in RFC2461.
230- We cannot configure proxy NDP for off-link address. The target address for
231 proxying must be link-local address, or must be in prefixes configured to
232 node which does proxy NDP.
233- RFC2461 is unclear about if it is legal for a host to perform proxy ND.
234 We do not prohibit hosts from doing proxy ND, but there will be very limited
235 use in it.
236
237Starting mid March 2000, we support Neighbor Unreachability Detection (NUD)
238on p2p interfaces, including tunnel interfaces (gif). NUD is turned on by
239default. Before March 2000 KAME stack did not perform NUD on p2p interfaces.
240If the change raises any interoperability issues, you can turn off/on NUD
241by per-interface basis. Use "ndp -i interface -nud" to turn it off.
242Consult ndp(8) for details.
243
244RFC2461 specifies upper-layer reachability confirmation hint. Whenever
245upper-layer reachability confirmation hint comes, ND process can use it
246to optimize neighbor discovery process - ND process can omit real ND exchange
247and keep the neighbor cache state in REACHABLE.
248We currently have two sources for hints: (1) setsockopt(IPV6_REACHCONF)
249defined by 2292bis API, and (2) hints from tcp_input.
250It is questionable if they are really trustworthy. For example, a rogue
251userland program can use IPV6_REACHCONF to confuse ND process. Neighbor
252cache is a system-wide information pool, and it is bad to allow single process
253to affect others. Also, tcp_input can be hosed by hijack attempts. It is
254wrong to allow hijack attempts to affect ND process.
255Starting June 2000, ND code has a protection mechanism against incorrect
256upper-layer reachability confirmation. ND code counts subsequent upper-layer
257hints. If the number of hints reaches maximum, ND code will ignore further
258upper-layer hints and run real ND process to confirm reachability to the peer.
259sysctl net.inet6.icmp6.nd6_maxnudhint defines maximum # of subsequent
260upper-layer hints to be accepted.
261(from April 2000 to June 2000, we rejected setsockopt(IPV6_REACHCONF) from
262non-root process - after local discussion, it looks that hints are not
263that trustworthy even if they are from privileged processes)
264
265If inbound ND packets carry invalid values, the KAME kernel will
266drop these packet and increment statistics variable. See
267"netstat -sn", icmp6 section. For detailed debugging session, you can
268turn on syslog output from the kernel on errors, by turning on sysctl MIB
269net.inet6.icmp6.nd6_debug. nd6_debug can be turned on at bootstrap
270time, by defining ND6_DEBUG kernel compilation option (so you can
271debug behavior during bootstrap). nd6_debug configuration should
272only be used for test/debug purposes - for production environment,
273nd6_debug must be set to 0. If you leave it to 1, malicious parties
274can inject broken packet and fill up /var/log partition.
275
2761.3 Scope Zone Index
277
278IPv6 uses scoped addresses. It is therefore very important to
279specify the scope zone index (link index for a link-local address, or
280site index for a site-local address) with an IPv6 address. Without a
281zone index, a scoped IPv6 address is ambiguous to the kernel, and
282the kernel would not be able to determine the outbound link for a
283packet to the scoped address. KAME code tries to address the issue in
284several ways.
285
286The entire architecture of scoped addresses is documented in
287draft-ietf-ipngwg-scoping-arch-xx.txt. One non-trivial point of the
288architecture is that the link scope is (theoretically) larger than the
289interface scope. That is, two different interfaces can belong to a
290same single link. However, in a normal operation, we can assume that
291there is 1-to-1 relationship between links and interfaces. In
292other words, we can usually put links and interfaces in the same scope
293type. The current KAME implementation assumes the 1-to-1
294relationship. In particular, we use interface names such as "ne1" as
295unique link identifiers. This would be much more human-readable and
296intuitive than numeric identifiers, but please keep your mind on the
297theoretical difference between links and interfaces.
298
299Site-local addresses are very vaguely defined in the specs, and both
300the specification and the KAME code need tons of improvements to
301enable its actual use. For example, it is still very unclear how we
302define a site, or how we resolve host names in a site. There is work
303underway to define behavior of routers at site border, but, we have
304almost no code for site boundary node support (both forwarding nor
305routing) and we bet almost noone has. We recommend, at this moment,
306you to use global addresses for experiments - there are way too many
307pitfalls if you use site-local addresses.
308
3091.3.1 Kernel internal
310
311In the kernel, the link index for a link-local scope address is
312embedded into the 2nd 16bit-word (the 3rd and 4th bytes) in the IPv6
313address.
314For example, you may see something like:
315 fe80:1::200:f8ff:fe01:6317
316in the routing table and the interface address structure (struct
317in6_ifaddr). The address above is a link-local unicast address which
318belongs to a network link whose link identifier is 1 (note that it
319eqauls to the interface index by the assumption of our
320implementation). The embedded index enables us to identify IPv6
321link-local addresses over multiple links effectively and with only a
322little code change.
323
3241.3.2 Interaction with API
325
326There are several candidates of API to deal with scoped addresses
327without ambiguity.
328
329The IPV6_PKTINFO ancillary data type or socket option defined in the
| 236draft-itojun-ipv6-flowlabel-api-01.txt: Socket API for IPv6 flow label field
237 * no consideration is made against the use of routing headers and such.
238
2391.2 Neighbor Discovery
240
241Neighbor Discovery is fairly stable. Currently Address Resolution,
242Duplicated Address Detection, and Neighbor Unreachability Detection
243are supported. In the near future we will be adding Unsolicited Neighbor
244Advertisement transmission command as admin tool.
245
246Duplicated Address Detection (DAD) will be performed when an IPv6 address
247is assigned to a network interface, or the network interface is enabled
248(ifconfig up). It is documented in RFC2462 5.4.
249If DAD fails, the address will be marked "duplicated" and message will be
250generated to syslog (and usually to console). The "duplicated" mark
251can be checked with ifconfig. It is administrators' responsibility to check
252for and recover from DAD failures. We may try to improve failure recovery
253in future KAME code.
254DAD procedure may not be effective on certain network interfaces/drivers.
255If a network driver needs long initialization time (with wireless network
256interfaces this situation is popular), and the driver mistakingly raises
257IFF_RUNNING before the driver becomes ready, DAD code will try to transmit
258DAD probes to not-really-ready network driver and the packet will not go out
259from the interface. In such cases, network drivers should be corrected.
260
261Some of network drivers loop multicast packets back to themselves,
262even if instructed not to do so (especially in promiscuous mode).
263In such cases DAD may fail, because DAD engine sees inbound NS packet
264(actually from the node itself) and considers it as a sign of duplicate.
265In this case, drivers should be corrected to honor IFF_SIMPLEX behavior.
266For example, you may need to check source MAC address on an inbound packet,
267and reject it if it is from the node itself.
268You may also want to look at #if condition marked "heuristics" in
269sys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note that the code
270fragment in "heuristics" section is not spec conformant).
271
272Neighbor Discovery specification (RFC2461) does not talk about neighbor
273cache handling in the following cases:
274(1) when there was no neighbor cache entry, node received unsolicited
275 RS/NS/NA/redirect packet without link-layer address
276(2) neighbor cache handling on medium without link-layer address
277 (we need a neighbor cache entry for IsRouter bit)
278For (1), we implemented workaround based on discussions on IETF ipngwg mailing
279list. For more details, see the comments in the source code and email
280thread started from (IPng 7155), dated Feb 6 1999.
281
282IPv6 on-link determination rule (RFC2461) is quite different from assumptions
283in BSD IPv4 network code. To implement behavior in RFC2461 section 5.2
284(when default router list is empty), the kernel needs to know the default
285outgoing interface. To configure the default outgoing interface, use
286commands like "ndp -I de0" as root. Note that the spec misuse the word
287"host" and "node" in several places in the section.
288
289To avoid possible DoS attacks and infinite loops, KAME stack will accept
290only 10 options on ND packet. Therefore, if you have 20 prefix options
291attached to RA, only the first 10 prefixes will be recognized.
292If this troubles you, please contact KAME team and/or modify
293nd6_maxndopt in sys/netinet6/nd6.c. If there are high demands we may
294provide sysctl knob for the variable.
295
296Proxy Neighbor Advertisement support is implemented in the kernel.
297For instance, you can configure it by using the following command:
298 # ndp -s fe80::1234%ne0 0:1:2:3:4:5 proxy
299where ne0 is the interface which attaches to the same link as the
300proxy target.
301There are certain limitations, though:
302- It does not send unsolicited multicast NA on configuration. This is MAY
303 behavior in RFC2461.
304- It does not add random delay before transmission of solicited NA. This is
305 SHOULD behavior in RFC2461.
306- We cannot configure proxy NDP for off-link address. The target address for
307 proxying must be link-local address, or must be in prefixes configured to
308 node which does proxy NDP.
309- RFC2461 is unclear about if it is legal for a host to perform proxy ND.
310 We do not prohibit hosts from doing proxy ND, but there will be very limited
311 use in it.
312
313Starting mid March 2000, we support Neighbor Unreachability Detection (NUD)
314on p2p interfaces, including tunnel interfaces (gif). NUD is turned on by
315default. Before March 2000 KAME stack did not perform NUD on p2p interfaces.
316If the change raises any interoperability issues, you can turn off/on NUD
317by per-interface basis. Use "ndp -i interface -nud" to turn it off.
318Consult ndp(8) for details.
319
320RFC2461 specifies upper-layer reachability confirmation hint. Whenever
321upper-layer reachability confirmation hint comes, ND process can use it
322to optimize neighbor discovery process - ND process can omit real ND exchange
323and keep the neighbor cache state in REACHABLE.
324We currently have two sources for hints: (1) setsockopt(IPV6_REACHCONF)
325defined by 2292bis API, and (2) hints from tcp_input.
326It is questionable if they are really trustworthy. For example, a rogue
327userland program can use IPV6_REACHCONF to confuse ND process. Neighbor
328cache is a system-wide information pool, and it is bad to allow single process
329to affect others. Also, tcp_input can be hosed by hijack attempts. It is
330wrong to allow hijack attempts to affect ND process.
331Starting June 2000, ND code has a protection mechanism against incorrect
332upper-layer reachability confirmation. ND code counts subsequent upper-layer
333hints. If the number of hints reaches maximum, ND code will ignore further
334upper-layer hints and run real ND process to confirm reachability to the peer.
335sysctl net.inet6.icmp6.nd6_maxnudhint defines maximum # of subsequent
336upper-layer hints to be accepted.
337(from April 2000 to June 2000, we rejected setsockopt(IPV6_REACHCONF) from
338non-root process - after local discussion, it looks that hints are not
339that trustworthy even if they are from privileged processes)
340
341If inbound ND packets carry invalid values, the KAME kernel will
342drop these packet and increment statistics variable. See
343"netstat -sn", icmp6 section. For detailed debugging session, you can
344turn on syslog output from the kernel on errors, by turning on sysctl MIB
345net.inet6.icmp6.nd6_debug. nd6_debug can be turned on at bootstrap
346time, by defining ND6_DEBUG kernel compilation option (so you can
347debug behavior during bootstrap). nd6_debug configuration should
348only be used for test/debug purposes - for production environment,
349nd6_debug must be set to 0. If you leave it to 1, malicious parties
350can inject broken packet and fill up /var/log partition.
351
3521.3 Scope Zone Index
353
354IPv6 uses scoped addresses. It is therefore very important to
355specify the scope zone index (link index for a link-local address, or
356site index for a site-local address) with an IPv6 address. Without a
357zone index, a scoped IPv6 address is ambiguous to the kernel, and
358the kernel would not be able to determine the outbound link for a
359packet to the scoped address. KAME code tries to address the issue in
360several ways.
361
362The entire architecture of scoped addresses is documented in
363draft-ietf-ipngwg-scoping-arch-xx.txt. One non-trivial point of the
364architecture is that the link scope is (theoretically) larger than the
365interface scope. That is, two different interfaces can belong to a
366same single link. However, in a normal operation, we can assume that
367there is 1-to-1 relationship between links and interfaces. In
368other words, we can usually put links and interfaces in the same scope
369type. The current KAME implementation assumes the 1-to-1
370relationship. In particular, we use interface names such as "ne1" as
371unique link identifiers. This would be much more human-readable and
372intuitive than numeric identifiers, but please keep your mind on the
373theoretical difference between links and interfaces.
374
375Site-local addresses are very vaguely defined in the specs, and both
376the specification and the KAME code need tons of improvements to
377enable its actual use. For example, it is still very unclear how we
378define a site, or how we resolve host names in a site. There is work
379underway to define behavior of routers at site border, but, we have
380almost no code for site boundary node support (both forwarding nor
381routing) and we bet almost noone has. We recommend, at this moment,
382you to use global addresses for experiments - there are way too many
383pitfalls if you use site-local addresses.
384
3851.3.1 Kernel internal
386
387In the kernel, the link index for a link-local scope address is
388embedded into the 2nd 16bit-word (the 3rd and 4th bytes) in the IPv6
389address.
390For example, you may see something like:
391 fe80:1::200:f8ff:fe01:6317
392in the routing table and the interface address structure (struct
393in6_ifaddr). The address above is a link-local unicast address which
394belongs to a network link whose link identifier is 1 (note that it
395eqauls to the interface index by the assumption of our
396implementation). The embedded index enables us to identify IPv6
397link-local addresses over multiple links effectively and with only a
398little code change.
399
4001.3.2 Interaction with API
401
402There are several candidates of API to deal with scoped addresses
403without ambiguity.
404
405The IPV6_PKTINFO ancillary data type or socket option defined in the
|
330advanced API (RFC2292 or draft-ietf-ipngwg-rfc2292bis-xx) can specify
| 406advanced API (RFC2292 or RFC3542) can specify
|
331the outgoing interface of a packet. Similarly, the IPV6_PKTINFO or
332IPV6_RECVPKTINFO socket options tell kernel to pass the incoming
333interface to user applications.
334
335These options are enough to disambiguate scoped addresses of an
336incoming packet, because we can uniquely identify the corresponding
337zone of the scoped address(es) by the incoming interface. However,
338they are too strong for outgoing packets. For example, consider a
339multi-sited node and suppose that more than one interface of the node
340belongs to a same site. When we want to send a packet to the site,
341we can only specify one of the interfaces for the outgoing packet with
342these options; we cannot just say "send the packet to (one of the
343interfaces of) the site."
344
345Another kind of candidates is to use the sin6_scope_id member in the
| 407the outgoing interface of a packet. Similarly, the IPV6_PKTINFO or
408IPV6_RECVPKTINFO socket options tell kernel to pass the incoming
409interface to user applications.
410
411These options are enough to disambiguate scoped addresses of an
412incoming packet, because we can uniquely identify the corresponding
413zone of the scoped address(es) by the incoming interface. However,
414they are too strong for outgoing packets. For example, consider a
415multi-sited node and suppose that more than one interface of the node
416belongs to a same site. When we want to send a packet to the site,
417we can only specify one of the interfaces for the outgoing packet with
418these options; we cannot just say "send the packet to (one of the
419interfaces of) the site."
420
421Another kind of candidates is to use the sin6_scope_id member in the
|
346sockaddr_in6 structure, defined in RFC2553 and
347draft-ietf-ipngwg-rfc2553bis-xx.txt. The KAME kernel interprets the
348sin6_scope_id field properly in order to disambiguate scoped
| 422sockaddr_in6 structure, defined in RFC2553. The KAME kernel
423interprets the sin6_scope_id field properly in order to disambiguate scoped
|
349addresses. For example, if an application passes a sockaddr_in6
350structure that has a non-zero sin6_scope_id value to the sendto(2)
351system call, the kernel should send the packet to the appropriate zone
352according to the sin6_scope_id field. Similarly, when the source or
353the destination address of an incoming packet is a scoped one, the
354kernel should detect the correct zone identifier based on the address
355and the receiving interface, fill the identifier in the sin6_scope_id
356field of a sockaddr_in6 structure, and then pass the packet to an
357application via the recvfrom(2) system call, etc.
358
359However, the semantics of the sin6_scope_id is still vague and on the
360way to standardization. Additionally, not so many operating systems
361support the behavior above at this moment.
362
363In summary,
364- If your target system is limited to KAME based ones (i.e. BSD
365 variants and KAME snaps), use the sin6_scope_id field assuming the
366 kernel behavior described above.
367- Otherwise, (i.e. if your program should be portable on other systems
368 than BSDs)
369 + Use the advanced API to disambiguate scoped addresses of incoming
370 packets.
371 + To disambiguate scoped addresses of outgoing packets,
372 * if it is okay to just specify the outgoing interface, use the
373 advanced API. This would be the case, for example, when you
374 should only consider link-local addresses and your system
375 assumes 1-to-1 relationship between links and interfaces.
376 * otherwise, sorry but you lose. Please rush the IETF IPv6
377 community into standardizing the semantics of the sin6_scope_id
378 field.
379
380Routing daemons and configuration programs, like route6d and ifconfig,
381will need to manipulate the "embedded" zone index. These programs use
382routing sockets and ioctls (like SIOCGIFADDR_IN6) and the kernel API
383will return IPv6 addresses with the 2nd 16bit-word filled in. The
384APIs are for manipulating kernel internal structure. Programs that
385use these APIs have to be prepared about differences in kernels
386anyway.
387
388getaddrinfo(3) and getnameinfo(3) support an extended numeric IPv6
| 424addresses. For example, if an application passes a sockaddr_in6
425structure that has a non-zero sin6_scope_id value to the sendto(2)
426system call, the kernel should send the packet to the appropriate zone
427according to the sin6_scope_id field. Similarly, when the source or
428the destination address of an incoming packet is a scoped one, the
429kernel should detect the correct zone identifier based on the address
430and the receiving interface, fill the identifier in the sin6_scope_id
431field of a sockaddr_in6 structure, and then pass the packet to an
432application via the recvfrom(2) system call, etc.
433
434However, the semantics of the sin6_scope_id is still vague and on the
435way to standardization. Additionally, not so many operating systems
436support the behavior above at this moment.
437
438In summary,
439- If your target system is limited to KAME based ones (i.e. BSD
440 variants and KAME snaps), use the sin6_scope_id field assuming the
441 kernel behavior described above.
442- Otherwise, (i.e. if your program should be portable on other systems
443 than BSDs)
444 + Use the advanced API to disambiguate scoped addresses of incoming
445 packets.
446 + To disambiguate scoped addresses of outgoing packets,
447 * if it is okay to just specify the outgoing interface, use the
448 advanced API. This would be the case, for example, when you
449 should only consider link-local addresses and your system
450 assumes 1-to-1 relationship between links and interfaces.
451 * otherwise, sorry but you lose. Please rush the IETF IPv6
452 community into standardizing the semantics of the sin6_scope_id
453 field.
454
455Routing daemons and configuration programs, like route6d and ifconfig,
456will need to manipulate the "embedded" zone index. These programs use
457routing sockets and ioctls (like SIOCGIFADDR_IN6) and the kernel API
458will return IPv6 addresses with the 2nd 16bit-word filled in. The
459APIs are for manipulating kernel internal structure. Programs that
460use these APIs have to be prepared about differences in kernels
461anyway.
462
463getaddrinfo(3) and getnameinfo(3) support an extended numeric IPv6
|
389syntax, as documented in draft-ietf-ipngwg-rfc2553bis-xx.txt. You can
| 464syntax, as documented in draft-ietf-ipv6-scoping-arch-xx.txt. You can
|
390specify the outgoing link, by using the name of the outgoing interface
391as the link, like "fe80::1%ne0" (again, note that we assume there is
3921-to-1 relationship between links and interfaces.) This way you will
393be able to specify a link-local scoped address without much trouble.
394
395Other APIs like inet_pton(3) and inet_ntop(3) are inherently
396unfriendly with scoped addresses, since they are unable to annotate
397addresses with zone identifier.
398
3991.3.3 Interaction with users (command line)
400
401Most of user applications now support the extended numeric IPv6
402syntax. In this case, you can specify outgoing link, by using the name
403of the outgoing interface like "fe80::1%ne0" (sorry for the duplicated
404notice, but please recall again that we assume 1-to-1 relationship
405between links and interfaces). This is even the case for some
406management tools such as route(8) or ndp(8). For example, to install
407the IPv6 default route by hand, you can type like
408 # route add -inet6 default fe80::9876:5432:1234:abcd%ne0
409(Although we suggest you to run dynamic routing instead of static
410routes, in order to avoid configuration mistakes.)
411
412Some applications have command line options for specifying an
413appropriate zone of a scoped address (like "ping6 -I ne0 ff02::1" to
414specify the outgoing interface). However, you can't always expect such
| 465specify the outgoing link, by using the name of the outgoing interface
466as the link, like "fe80::1%ne0" (again, note that we assume there is
4671-to-1 relationship between links and interfaces.) This way you will
468be able to specify a link-local scoped address without much trouble.
469
470Other APIs like inet_pton(3) and inet_ntop(3) are inherently
471unfriendly with scoped addresses, since they are unable to annotate
472addresses with zone identifier.
473
4741.3.3 Interaction with users (command line)
475
476Most of user applications now support the extended numeric IPv6
477syntax. In this case, you can specify outgoing link, by using the name
478of the outgoing interface like "fe80::1%ne0" (sorry for the duplicated
479notice, but please recall again that we assume 1-to-1 relationship
480between links and interfaces). This is even the case for some
481management tools such as route(8) or ndp(8). For example, to install
482the IPv6 default route by hand, you can type like
483 # route add -inet6 default fe80::9876:5432:1234:abcd%ne0
484(Although we suggest you to run dynamic routing instead of static
485routes, in order to avoid configuration mistakes.)
486
487Some applications have command line options for specifying an
488appropriate zone of a scoped address (like "ping6 -I ne0 ff02::1" to
489specify the outgoing interface). However, you can't always expect such
|
415options. Thus, we recommend you to use the extended format described
416above.
| 490options. Additionally, specifying the outgoing "interface" is in
491theory an overspecification as a way to specify the outgoing "link"
492(see above). Thus, we recommend you to use the extended format
493described above. This should apply to the case where the outgoing
494interface is specified.
|
417
418In any case, when you specify a scoped address to the command line,
419NEVER write the embedded form (such as ff02:1::1 or fe80:2::fedc),
420which should only be used inside the kernel (see Section 1.3.1), and
421is not supposed to work.
422
4231.4 Plug and Play
424
425The KAME kit implements most of the IPv6 stateless address
426autoconfiguration in the kernel.
427Neighbor Discovery functions are implemented in the kernel as a whole.
428Router Advertisement (RA) input for hosts is implemented in the
429kernel. Router Solicitation (RS) output for endhosts, RS input
430for routers, and RA output for routers are implemented in the
431userland.
432
4331.4.1 Assignment of link-local, and special addresses
434
435IPv6 link-local address is generated from IEEE802 address (ethernet MAC
436address). Each of interface is assigned an IPv6 link-local address
437automatically, when the interface becomes up (IFF_UP). Also, direct route
438for the link-local address is added to routing table.
439
440Here is an output of netstat command:
441
442Internet6:
443Destination Gateway Flags Netif Expire
444fe80::%ed0/64 link#1 UC ed0
445fe80::%ep0/64 link#2 UC ep0
446
447Interfaces that has no IEEE802 address (pseudo interfaces like tunnel
448interfaces, or ppp interfaces) will borrow IEEE802 address from other
449interfaces, such as ethernet interfaces, whenever possible.
450If there is no IEEE802 hardware attached, last-resort pseudorandom value,
451which is from MD5(hostname), will be used as source of link-local address.
452If it is not suitable for your usage, you will need to configure the
453link-local address manually.
454
455If an interface is not capable of handling IPv6 (such as lack of multicast
456support), link-local address will not be assigned to that interface.
457See section 2 for details.
458
459Each interface joins the solicited multicast address and the
460link-local all-nodes multicast addresses (e.g. fe80::1:ff01:6317
461and ff02::1, respectively, on the link the interface is attached).
462In addition to a link-local address, the loopback address (::1) will be
463assigned to the loopback interface. Also, ::1/128 and ff01::/32 are
464automatically added to routing table, and loopback interface joins
465node-local multicast group ff01::1.
466
4671.4.2 Stateless address autoconfiguration on hosts
468
469In IPv6 specification, nodes are separated into two categories:
470routers and hosts. Routers forward packets addressed to others, hosts does
471not forward the packets. net.inet6.ip6.forwarding defines whether this
472node is a router or a host (router if it is 1, host if it is 0).
473
474It is NOT recommended to change net.inet6.ip6.forwarding while the node
475is in operation. IPv6 specification defines behavior for "host" and "router"
476quite differently, and switching from one to another can cause serious
477troubles. It is recommended to configure the variable at bootstrap time only.
478
479The first step in stateless address configuration is Duplicated Address
480Detection (DAD). See 1.2 for more detail on DAD.
481
482When a host hears Router Advertisement from the router, a host may
483autoconfigure itself by stateless address autoconfiguration.
484This behavior can be controlled by net.inet6.ip6.accept_rtadv
485(host autoconfigures itself if it is set to 1).
486By autoconfiguration, network address prefix for the receiving interface
487(usually global address prefix) is added. The default route is also
488configured.
489
490Routers periodically generate Router Advertisement packets. To
491request an adjacent router to generate RA packet, a host can transmit
492Router Solicitation. To generate an RS packet at any time, use the
493"rtsol" command. The "rtsold" daemon is also available. "rtsold"
494generates Router Solicitation whenever necessary, and it works great
495for nomadic usage (notebooks/laptops). If one wishes to ignore Router
496Advertisements, use sysctl to set net.inet6.ip6.accept_rtadv to 0.
497
498To generate Router Advertisement from a router, use the "rtadvd" daemon.
499
500Note that the IPv6 specification assumes the following items and that
501nonconforming cases are left unspecified:
502- Only hosts will listen to router advertisements
503- Hosts have single network interface (except loopback)
504This is therefore unwise to enable net.inet6.ip6.accept_rtadv on routers,
505or multi-interface host. A misconfigured node can behave strange
506(KAME code allows nonconforming configuration, for those who would like
507to do some experiments).
508
509To summarize the sysctl knob:
510 accept_rtadv forwarding role of the node
511 --- --- ---
512 0 0 host (to be manually configured)
513 0 1 router
514 1 0 autoconfigured host
515 (spec assumes that host has single
516 interface only, autoconfigred host with
517 multiple interface is out-of-scope)
518 1 1 invalid, or experimental
519 (out-of-scope of spec)
520
521See 1.2 in the document for relationship between DAD and autoconfiguration.
522
5231.4.3 DHCPv6
524
525We supply a tiny DHCPv6 server/client in kame/dhcp6. However, the
526implementation is premature (for example, this does NOT implement
527address lease/release), and it is not in default compilation tree on
528some platforms. If you want to do some experiment, compile it on your
529own.
530
531DHCPv6 and autoconfiguration also needs more work. "Managed" and "Other"
532bits in RA have no special effect to stateful autoconfiguration procedure
533in DHCPv6 client program ("Managed" bit actually prevents stateless
534autoconfiguration, but no special action will be taken for DHCPv6 client).
535
5361.5 Generic tunnel interface
537
538GIF (Generic InterFace) is a pseudo interface for configured tunnel.
539Details are described in gif(4) manpage.
540Currently
541 v6 in v6
542 v6 in v4
543 v4 in v6
544 v4 in v4
545are available. Use "gifconfig" to assign physical (outer) source
546and destination address to gif interfaces.
547Configuration that uses same address family for inner and outer IP
548header (v4 in v4, or v6 in v6) is dangerous. It is very easy to
549configure interfaces and routing tables to perform infinite level
550of tunneling. Please be warned.
551
552gif can be configured to be ECN-friendly. See 4.5 for ECN-friendliness
553of tunnels, and gif(4) manpage for how to configure.
554
555If you would like to configure an IPv4-in-IPv6 tunnel with gif interface,
556read gif(4) carefully. You may need to remove IPv6 link-local address
557automatically assigned to the gif interface.
558
| 495
496In any case, when you specify a scoped address to the command line,
497NEVER write the embedded form (such as ff02:1::1 or fe80:2::fedc),
498which should only be used inside the kernel (see Section 1.3.1), and
499is not supposed to work.
500
5011.4 Plug and Play
502
503The KAME kit implements most of the IPv6 stateless address
504autoconfiguration in the kernel.
505Neighbor Discovery functions are implemented in the kernel as a whole.
506Router Advertisement (RA) input for hosts is implemented in the
507kernel. Router Solicitation (RS) output for endhosts, RS input
508for routers, and RA output for routers are implemented in the
509userland.
510
5111.4.1 Assignment of link-local, and special addresses
512
513IPv6 link-local address is generated from IEEE802 address (ethernet MAC
514address). Each of interface is assigned an IPv6 link-local address
515automatically, when the interface becomes up (IFF_UP). Also, direct route
516for the link-local address is added to routing table.
517
518Here is an output of netstat command:
519
520Internet6:
521Destination Gateway Flags Netif Expire
522fe80::%ed0/64 link#1 UC ed0
523fe80::%ep0/64 link#2 UC ep0
524
525Interfaces that has no IEEE802 address (pseudo interfaces like tunnel
526interfaces, or ppp interfaces) will borrow IEEE802 address from other
527interfaces, such as ethernet interfaces, whenever possible.
528If there is no IEEE802 hardware attached, last-resort pseudorandom value,
529which is from MD5(hostname), will be used as source of link-local address.
530If it is not suitable for your usage, you will need to configure the
531link-local address manually.
532
533If an interface is not capable of handling IPv6 (such as lack of multicast
534support), link-local address will not be assigned to that interface.
535See section 2 for details.
536
537Each interface joins the solicited multicast address and the
538link-local all-nodes multicast addresses (e.g. fe80::1:ff01:6317
539and ff02::1, respectively, on the link the interface is attached).
540In addition to a link-local address, the loopback address (::1) will be
541assigned to the loopback interface. Also, ::1/128 and ff01::/32 are
542automatically added to routing table, and loopback interface joins
543node-local multicast group ff01::1.
544
5451.4.2 Stateless address autoconfiguration on hosts
546
547In IPv6 specification, nodes are separated into two categories:
548routers and hosts. Routers forward packets addressed to others, hosts does
549not forward the packets. net.inet6.ip6.forwarding defines whether this
550node is a router or a host (router if it is 1, host if it is 0).
551
552It is NOT recommended to change net.inet6.ip6.forwarding while the node
553is in operation. IPv6 specification defines behavior for "host" and "router"
554quite differently, and switching from one to another can cause serious
555troubles. It is recommended to configure the variable at bootstrap time only.
556
557The first step in stateless address configuration is Duplicated Address
558Detection (DAD). See 1.2 for more detail on DAD.
559
560When a host hears Router Advertisement from the router, a host may
561autoconfigure itself by stateless address autoconfiguration.
562This behavior can be controlled by net.inet6.ip6.accept_rtadv
563(host autoconfigures itself if it is set to 1).
564By autoconfiguration, network address prefix for the receiving interface
565(usually global address prefix) is added. The default route is also
566configured.
567
568Routers periodically generate Router Advertisement packets. To
569request an adjacent router to generate RA packet, a host can transmit
570Router Solicitation. To generate an RS packet at any time, use the
571"rtsol" command. The "rtsold" daemon is also available. "rtsold"
572generates Router Solicitation whenever necessary, and it works great
573for nomadic usage (notebooks/laptops). If one wishes to ignore Router
574Advertisements, use sysctl to set net.inet6.ip6.accept_rtadv to 0.
575
576To generate Router Advertisement from a router, use the "rtadvd" daemon.
577
578Note that the IPv6 specification assumes the following items and that
579nonconforming cases are left unspecified:
580- Only hosts will listen to router advertisements
581- Hosts have single network interface (except loopback)
582This is therefore unwise to enable net.inet6.ip6.accept_rtadv on routers,
583or multi-interface host. A misconfigured node can behave strange
584(KAME code allows nonconforming configuration, for those who would like
585to do some experiments).
586
587To summarize the sysctl knob:
588 accept_rtadv forwarding role of the node
589 --- --- ---
590 0 0 host (to be manually configured)
591 0 1 router
592 1 0 autoconfigured host
593 (spec assumes that host has single
594 interface only, autoconfigred host with
595 multiple interface is out-of-scope)
596 1 1 invalid, or experimental
597 (out-of-scope of spec)
598
599See 1.2 in the document for relationship between DAD and autoconfiguration.
600
6011.4.3 DHCPv6
602
603We supply a tiny DHCPv6 server/client in kame/dhcp6. However, the
604implementation is premature (for example, this does NOT implement
605address lease/release), and it is not in default compilation tree on
606some platforms. If you want to do some experiment, compile it on your
607own.
608
609DHCPv6 and autoconfiguration also needs more work. "Managed" and "Other"
610bits in RA have no special effect to stateful autoconfiguration procedure
611in DHCPv6 client program ("Managed" bit actually prevents stateless
612autoconfiguration, but no special action will be taken for DHCPv6 client).
613
6141.5 Generic tunnel interface
615
616GIF (Generic InterFace) is a pseudo interface for configured tunnel.
617Details are described in gif(4) manpage.
618Currently
619 v6 in v6
620 v6 in v4
621 v4 in v6
622 v4 in v4
623are available. Use "gifconfig" to assign physical (outer) source
624and destination address to gif interfaces.
625Configuration that uses same address family for inner and outer IP
626header (v4 in v4, or v6 in v6) is dangerous. It is very easy to
627configure interfaces and routing tables to perform infinite level
628of tunneling. Please be warned.
629
630gif can be configured to be ECN-friendly. See 4.5 for ECN-friendliness
631of tunnels, and gif(4) manpage for how to configure.
632
633If you would like to configure an IPv4-in-IPv6 tunnel with gif interface,
634read gif(4) carefully. You may need to remove IPv6 link-local address
635automatically assigned to the gif interface.
636
|
5591.6 Source Address Selection
| 6371.6 Address Selection
|
560
| 638
|
561KAME's source address selection takes care of the following
562conditions:
563- address scope
564- outgoing interface
565- whether an address is deprecated
566- whether an address is temporary (in terms of RFC 3041)
567- prefix matching against the destination
| 6391.6.1 Source Address Selection
|
568
| 640
|
569Roughly speaking, the selection policy is as follows:
570- always use an address that belongs to the same scope zone as the
571 destination.
572- addresses that have equal or larger scope than the scope of the
573 destination are preferred.
574- a deprecated address is not used in new communications if an
575 alternate (non-deprecated) address is available and has sufficient
576 scope.
577- a temporary address (in terms of RFC 3041 privacy extension) are
578 preferred to a public address.
579- if none of above conditions tie-breaks, addresses assigned on the
580 outgoing interface are preferred.
581- if none of above conditions tie-breaks, one which is longest prefix
582 matching against the destination is preferred as the last resort.
| 641The KAME kernel chooses the source address for an outgoing packet
642sent from a user application as follows:
|
583
| 643
|
584For instance, ::1 is selected for ff01::1,
585fe80::200:f8ff:fe01:6317%ne0 for fe80::2a0:24ff:feab:839b%ne0.
586To see how longest-matching works, suppose that
5873ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317
588are given on the outgoing interface. Then the former is chosen as the
589source for the destination 3ffe:501:800::1. Note that even if all
590available addresses have smaller scope than the scope of the
591destination, we choose one anyway. For example, if we have link-local
592and site-local addresses only, we choose a site-local addresses for a
593global destination. If the packet is going to break a site boundary,
594the boundary router will return an ICMPv6 destination unreachable
595error with code 2 - beyond scope of source address.
| 6441. if the source address is explicitly specified via an IPV6_PKTINFO
645 ancillary data item or the socket option of that name, just use it.
646 Note that this item/option overrides the bound address of the
647 corresponding (datagram) socket.
|
596
| 648
|
597The precise desripction of the algorithm is quite complicated. To
598describe the algorithm, we introduce the following notation:
| 6492. if the corresponding socket is bound, use the bound address.
|
599
| 650
|
600For a given destination D,
601 samescope(D): The set of addresses that have the same scope as D.
602 largerscope(D): The set of addresses that have a larger scope than D.
603 smallerscope(D): The set of addresses that have a smaller scope than D.
| 6513. otherwise, the kernel first tries to find the outgoing interface of
652 the packet. If it fails, the source address selection also fails.
653 If the kernel can find an interface, choose the most appropriate
654 address based on the algorithm described in RFC3484.
|
604
| 655
|
605For a given set of addresses A,
606 DEP(A): the set of deprecated addresses in A.
607 nonDEP(A): A - DEP(A).
| 656 The policy table used in this algorithm is stored in the kernel.
657 To install or view the policy, use the ip6addrctl(8) command. The
658 kernel does not have pre-installed policy. It is expected that the
659 default policy described in the draft should be installed at the
660 bootstrap time using this command.
|
608
| 661
|
609For a given set of addresses A,
610 tmp(A): the set of preferred temporary-autoconfigured or
611 manually-configure addresses in A.
| 662 This draft allows an implementation to add implementation-specific
663 rules with higher precedence than the rule "Use longest matching
664 prefix." KAME's implementation has the following additional rules
665 (that apply in the appeared order):
|
612
| 666
|
613Also, the algorithm assumes that the outgoing interface for the
614destination D is determined. We call the interface "I".
| 667 - prefer addresses on alive interfaces, that is, interfaces with
668 the UP flag being on. This rule is particularly useful for
669 routers, since some routing daemons stop advertising prefixes
670 (addresses) on interfaces that have become down.
|
615
| 671
|
616The algorithm is as follows. Selection proceeds step by step as
617described; For example, if an address is selected by item 1, item 2 and
618later are not considered at all.
| 672 In any case, addresses that break the scope zone of the
673 destination, or addresses whose zone do not contain the outgoing
674 interface are never chosen.
|
619
| 675
|
620 0. If there is no address in the same scope zone as D, just give up;
621 the packet will not be sent.
622 1. If we do not prefer temporary addresses, go to 3.
623 Otherwise, and if tmp(samescope(D)) is not empty,
624 then choose an address that is on the interface I. If every
625 address is on I, or every address is on a different interface
626 from I, choose an arbitrary one provided that an address longest
627 matching against D is always preferred.
628 2. If tmp(largerscope(D)) is not empty,
629 then choose an address that has the smallest scope. If more than one
630 address has the smallest scope, choose an arbitrary one provided
631 that addresses on I are always preferred.
632 3. If nonDEP(samescope(D)) is not empty,
633 then apply the same logic as of 1.
634 4. If nonDEP(largerscope(D)) is not empty,
635 then apply the same logic as of 2.
636 5. If we do not prefer temporary addresses, go to 7.
637 Otherwise, and if tmp(DEP(samescope(D))) is not empty,
638 then choose an address that is on the interface I. If every
639 address is on I, or every address is on a different interface
640 from I, choose an arbitrary one provided that an address longest
641 matching against D is always preferred.
642 6. If tmp(DEP(largerscope(D))) is not empty,
643 then choose an address that has the smallest scope. If more than
644 one address has the smallest scope, choose an arbitrary one provided
645 that an address on I is always preferred.
646 7. If DEP(samescope(D)) is not empty,
647 then apply the same logic as of 5.
648 8. If DEP(largerscope(D)) is not empty,
649 then apply the same logic as of 6.
650 9. If we do not prefer temporary addresses, go to 11.
651 Otherwise, and if tmp(nonDEP(smallerscope(D))) is not empty,
652 then choose an address that has the largest scope. If more than
653 one address has the largest scope, choose an arbitrary one provided
654 that an address on I is always preferred.
655 10. If tmp(DEP(smallerscope(D))) is not empty,
656 then choose an address that has the largest scope. If more than
657 one address has the largest scope, choose an arbitrary one provided
658 that an address on I is always preferred.
659 11. If nonDEP(smallerscope(D)) is not empty,
660 then apply the same logic as of 9.
661 12. If DEP(smallerscope(D)) is not empty,
662 then apply the same logic as of 10.
| 676When the procedure above fails, the kernel usually returns
677EADDRNOTAVAIL to the application.
|
663
| 678
|
664There exists a document about source address selection
665(draft-ietf-ipngwg-default-addr-select-xx.txt). KAME's algorithm
666described above takes a similar approach to the document, but there
667are some differences. See the document for more details.
668
669There are some cases where we do not use the above rule. One
670example is connected TCP session, and we use the address kept in TCP
671protocol control block (tcb) as the source.
672Another example is source address for Neighbor Advertisement.
| 679In some cases, the specification explicitly requires the
680implementation to choose a particular source address. The source
681address for a Neighbor Advertisement (NA) message is an example.
|
673Under the spec (RFC2461 7.2.2) NA's source should be the target
| 682Under the spec (RFC2461 7.2.2) NA's source should be the target
|
674address of the corresponding NS's target. In this case we follow
675the spec rather than the above longest-match rule.
| 683address of the corresponding NS's target. In this case we follow the
684spec rather than the above rule.
|
676
677If you would like to prohibit the use of deprecated address for some
678reason, configure net.inet6.ip6.use_deprecated to 0. The issue
679related to deprecated address is described in RFC2462 5.5.4 (NOTE:
680there is some debate underway in IETF ipngwg on how to use
681"deprecated" address).
682
| 685
686If you would like to prohibit the use of deprecated address for some
687reason, configure net.inet6.ip6.use_deprecated to 0. The issue
688related to deprecated address is described in RFC2462 5.5.4 (NOTE:
689there is some debate underway in IETF ipngwg on how to use
690"deprecated" address).
691
|
| 692As documented in the source address selection document, temporary
693addresses for privacy extension are less preferred to public addresses
694by default. However, for administrators who are particularly aware of
695the privacy, there is a system-wide sysctl(3) variable
696"net.inet6.ip6.prefer_tempaddr". When the variable is set to
697non-zero, the kernel will rather prefer temporary addresses. The
698default value of this variable is 0.
699
7001.6.2 Destination Address Ordering
701
702KAME's getaddrinfo(3) supports the destination address ordering
703algorithm described in RFC3484. Getaddrinfo(3) needs to know the
704source address for each destination address and policy entries
705(described in the previous section) for the source and destination
706addresses. To get the source address, the library function opens a
707UDP socket and tries to connect(2) for the destination. To get the
708policy entry, the function issues sysctl(3).
709
|
6831.7 Jumbo Payload
684
685KAME supports the Jumbo Payload hop-by-hop option used to send IPv6
686packets with payloads longer than 65,535 octets. But since currently
687KAME does not support any physical interface whose MTU is more than
68865,535, such payloads can be seen only on the loopback interface(i.e.
689lo0).
690
691If you want to try jumbo payloads, you first have to reconfigure the
692kernel so that the MTU of the loopback interface is more than 65,535
693bytes; add the following to the kernel configuration file:
694 options "LARGE_LOMTU" #To test jumbo payload
695and recompile the new kernel.
696
697Then you can test jumbo payloads by the ping6 command with -b and -s
698options. The -b option must be specified to enlarge the size of the
699socket buffer and the -s option specifies the length of the packet,
700which should be more than 65,535. For example, type as follows;
701 % ping6 -b 70000 -s 68000 ::1
702
703The IPv6 specification requires that the Jumbo Payload option must not
704be used in a packet that carries a fragment header. If this condition
705is broken, an ICMPv6 Parameter Problem message must be sent to the
706sender. KAME kernel follows the specification, but you cannot usually
707see an ICMPv6 error caused by this requirement.
708
709If KAME kernel receives an IPv6 packet, it checks the frame length of
710the packet and compares it to the length specified in the payload
711length field of the IPv6 header or in the value of the Jumbo Payload
712option, if any. If the former is shorter than the latter, KAME kernel
713discards the packet and increments the statistics. You can see the
714statistics as output of netstat command with `-s -p ip6' option:
715 % netstat -s -p ip6
716 ip6:
717 (snip)
718 1 with data size < data length
719
720So, KAME kernel does not send an ICMPv6 error unless the erroneous
721packet is an actual Jumbo Payload, that is, its packet size is more
722than 65,535 bytes. As described above, KAME kernel currently does not
723support physical interface with such a huge MTU, so it rarely returns an
724ICMPv6 error.
725
726TCP/UDP over jumbogram is not supported at this moment. This is because
727we have no medium (other than loopback) to test this. Contact us if you
728need this.
729
730IPsec does not work on jumbograms. This is due to some specification twists
731in supporting AH with jumbograms (AH header size influences payload length,
732and this makes it real hard to authenticate inbound packet with jumbo payload
733option as well as AH).
734
735There are fundamental issues in *BSD support for jumbograms. We would like to
736address those, but we need more time to finalize the task. To name a few:
737- mbuf pkthdr.len field is typed as "int" in 4.4BSD, so it cannot hold
738 jumbogram with len > 2G on 32bit architecture CPUs. If we would like to
739 support jumbogram properly, the field must be expanded to hold 4G +
740 IPv6 header + link-layer header. Therefore, it must be expanded to at least
741 int64_t (u_int32_t is NOT enough).
742- We mistakingly use "int" to hold packet length in many places. We need
743 to convert them into larger numeric type. It needs a great care, as we may
744 experience overflow during packet length computation.
745- We mistakingly check for ip6_plen field of IPv6 header for packet payload
746 length in various places. We should be checking mbuf pkthdr.len instead.
747 ip6_input() will perform sanity check on jumbo payload option on input,
748 and we can safely use mbuf pkthdr.len afterwards.
749- TCP code needs careful updates in bunch of places, of course.
750
7511.8 Loop prevention in header processing
752
753IPv6 specification allows arbitrary number of extension headers to
754be placed onto packets. If we implement IPv6 packet processing
755code in the way BSD IPv4 code is implemented, kernel stack may
756overflow due to long function call chain. KAME sys/netinet6 code
757is carefully designed to avoid kernel stack overflow. Because of
758this, KAME sys/netinet6 code defines its own protocol switch
759structure, as "struct ip6protosw" (see netinet6/ip6protosw.h).
760
761In addition to this, we restrict the number of extension headers
762(including the IPv6 header) in each incoming packet, in order to
763prevent a DoS attack that tries to send packets with a massive number
764of extension headers. The upper limit can be configured by the sysctl
765value net.inet6.ip6.hdrnestlimit. In particular, if the value is 0,
766the node will allow an arbitrary number of headers. As of writing this
767document, the default value is 50.
768
769IPv4 part (sys/netinet) remains untouched for compatibility.
770Because of this, if you receive IPsec-over-IPv4 packet with massive
771number of IPsec headers, kernel stack may blow up. IPsec-over-IPv6 is okay.
772
7731.9 ICMPv6
774
775After RFC2463 was published, IETF ipngwg has decided to disallow ICMPv6 error
776packet against ICMPv6 redirect, to prevent ICMPv6 storm on a network medium.
777KAME already implements this into the kernel.
778
779RFC2463 requires rate limitation for ICMPv6 error packets generated by a
780node, to avoid possible DoS attacks. KAME kernel implements two rate-
781limitation mechanisms, tunable via sysctl:
782- Minimum time interval between ICMPv6 error packets
783 KAME kernel will generate no more than one ICMPv6 error packet,
784 during configured time interval. net.inet6.icmp6.errratelimit
785 controls the interval (default: disabled).
786- Maximum ICMPv6 error packet-per-second
787 KAME kernel will generate no more than the configured number of
788 packets in one second. net.inet6.icmp6.errppslimit controls the
789 maximum packet-per-second value (default: 200pps)
790Basically, we need to pick values that are suitable against the bandwidth
791of link layer devices directly attached to the node. In some cases the
792default values may not fit well. We are still unsure if the default value
793is sane or not. Comments are welcome.
794
7951.10 Applications
796
797For userland programming, we support IPv6 socket API as specified in
798RFC2553, RFC2292 and upcoming internet drafts.
799
800TCP/UDP over IPv6 is available and quite stable. You can enjoy "telnet",
801"ftp", "rlogin", "rsh", "ssh", etc. These applications are protocol
802independent. That is, they automatically chooses IPv4 or IPv6
803according to DNS.
804
8051.11 Kernel Internals
806
807 (*) TCP/UDP part is handled differently between operating system platforms.
808 See 1.12 for details.
809
810The current KAME has escaped from the IPv4 netinet logic. While
811ip_forward() calls ip_output(), ip6_forward() directly calls
812if_output() since routers must not divide IPv6 packets into fragments.
813
814ICMPv6 should contain the original packet as long as possible up to
8151280. UDP6/IP6 port unreach, for instance, should contain all
816extension headers and the *unchanged* UDP6 and IP6 headers.
817So, all IP6 functions except TCP6 never convert network byte
818order into host byte order, to save the original packet.
819
820tcp6_input(), udp6_input() and icmp6_input() can't assume that IP6
821header is preceding the transport headers due to extension
822headers. So, in6_cksum() was implemented to handle packets whose IP6
823header and transport header is not continuous. TCP/IP6 nor UDP/IP6
824header structure don't exist for checksum calculation.
825
826To process IP6 header, extension headers and transport headers easily,
827KAME requires network drivers to store packets in one internal mbuf or
828one or more external mbufs. A typical old driver prepares two
829internal mbufs for 100 - 208 bytes data, however, KAME's reference
830implementation stores it in one external mbuf.
831
832"netstat -s -p ip6" tells you whether or not your driver conforms
833KAME's requirement. In the following example, "cce0" violates the
834requirement. (For more information, refer to Section 2.)
835
836 Mbuf statistics:
837 317 one mbuf
838 two or more mbuf::
839 lo0 = 8
840 cce0 = 10
841 3282 one ext mbuf
842 0 two or more ext mbuf
843
844Each input function calls IP6_EXTHDR_CHECK in the beginning to check
845if the region between IP6 and its header is
846continuous. IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has
847M_LOOP flag, that is, the packet comes from the loopback
848interface. m_pullup() is never called for packets coming from physical
849network interfaces.
850
851TCP6 reassembly makes use of IP6 header to store reassemble
852information. IP6 is not supposed to be just before TCP6, so
853ip6tcpreass structure has a pointer to TCP6 header. Of course, it has
854also a pointer back to mbuf to avoid m_pullup().
855
856Like TCP6, both IP and IP6 reassemble functions never call m_pullup().
857
858xxx_ctlinput() calls in_mrejoin() on PRC_IFNEWADDR. We think this is
859one of 4.4BSD implementation flaws. Since 4.4BSD keeps ia_multiaddrs
860in in_ifaddr{}, it can't use multicast feature if the interface has no
861unicast address. So, if an application joins to an interface and then
862all unicast addresses are removed from the interface, the application
863can't send/receive any multicast packets. Moreover, if a new unicast
864address is assigned to the interface, in_mrejoin() must be called.
865KAME's interfaces, however, have ALWAYS one link-local unicast
866address. These extensions have thus not been implemented in KAME.
867
8681.12 IPv4 mapped address and IPv6 wildcard socket
869
| 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
718If you want to try jumbo payloads, you first have to reconfigure the
719kernel so that the MTU of the loopback interface is more than 65,535
720bytes; add the following to the kernel configuration file:
721 options "LARGE_LOMTU" #To test jumbo payload
722and recompile the new kernel.
723
724Then you can test jumbo payloads by the ping6 command with -b and -s
725options. The -b option must be specified to enlarge the size of the
726socket buffer and the -s option specifies the length of the packet,
727which should be more than 65,535. For example, type as follows;
728 % ping6 -b 70000 -s 68000 ::1
729
730The IPv6 specification requires that the Jumbo Payload option must not
731be used in a packet that carries a fragment header. If this condition
732is broken, an ICMPv6 Parameter Problem message must be sent to the
733sender. KAME kernel follows the specification, but you cannot usually
734see an ICMPv6 error caused by this requirement.
735
736If KAME kernel receives an IPv6 packet, it checks the frame length of
737the packet and compares it to the length specified in the payload
738length field of the IPv6 header or in the value of the Jumbo Payload
739option, if any. If the former is shorter than the latter, KAME kernel
740discards the packet and increments the statistics. You can see the
741statistics as output of netstat command with `-s -p ip6' option:
742 % netstat -s -p ip6
743 ip6:
744 (snip)
745 1 with data size < data length
746
747So, KAME kernel does not send an ICMPv6 error unless the erroneous
748packet is an actual Jumbo Payload, that is, its packet size is more
749than 65,535 bytes. As described above, KAME kernel currently does not
750support physical interface with such a huge MTU, so it rarely returns an
751ICMPv6 error.
752
753TCP/UDP over jumbogram is not supported at this moment. This is because
754we have no medium (other than loopback) to test this. Contact us if you
755need this.
756
757IPsec does not work on jumbograms. This is due to some specification twists
758in supporting AH with jumbograms (AH header size influences payload length,
759and this makes it real hard to authenticate inbound packet with jumbo payload
760option as well as AH).
761
762There are fundamental issues in *BSD support for jumbograms. We would like to
763address those, but we need more time to finalize the task. To name a few:
764- mbuf pkthdr.len field is typed as "int" in 4.4BSD, so it cannot hold
765 jumbogram with len > 2G on 32bit architecture CPUs. If we would like to
766 support jumbogram properly, the field must be expanded to hold 4G +
767 IPv6 header + link-layer header. Therefore, it must be expanded to at least
768 int64_t (u_int32_t is NOT enough).
769- We mistakingly use "int" to hold packet length in many places. We need
770 to convert them into larger numeric type. It needs a great care, as we may
771 experience overflow during packet length computation.
772- We mistakingly check for ip6_plen field of IPv6 header for packet payload
773 length in various places. We should be checking mbuf pkthdr.len instead.
774 ip6_input() will perform sanity check on jumbo payload option on input,
775 and we can safely use mbuf pkthdr.len afterwards.
776- TCP code needs careful updates in bunch of places, of course.
777
7781.8 Loop prevention in header processing
779
780IPv6 specification allows arbitrary number of extension headers to
781be placed onto packets. If we implement IPv6 packet processing
782code in the way BSD IPv4 code is implemented, kernel stack may
783overflow due to long function call chain. KAME sys/netinet6 code
784is carefully designed to avoid kernel stack overflow. Because of
785this, KAME sys/netinet6 code defines its own protocol switch
786structure, as "struct ip6protosw" (see netinet6/ip6protosw.h).
787
788In addition to this, we restrict the number of extension headers
789(including the IPv6 header) in each incoming packet, in order to
790prevent a DoS attack that tries to send packets with a massive number
791of extension headers. The upper limit can be configured by the sysctl
792value net.inet6.ip6.hdrnestlimit. In particular, if the value is 0,
793the node will allow an arbitrary number of headers. As of writing this
794document, the default value is 50.
795
796IPv4 part (sys/netinet) remains untouched for compatibility.
797Because of this, if you receive IPsec-over-IPv4 packet with massive
798number of IPsec headers, kernel stack may blow up. IPsec-over-IPv6 is okay.
799
8001.9 ICMPv6
801
802After RFC2463 was published, IETF ipngwg has decided to disallow ICMPv6 error
803packet against ICMPv6 redirect, to prevent ICMPv6 storm on a network medium.
804KAME already implements this into the kernel.
805
806RFC2463 requires rate limitation for ICMPv6 error packets generated by a
807node, to avoid possible DoS attacks. KAME kernel implements two rate-
808limitation mechanisms, tunable via sysctl:
809- Minimum time interval between ICMPv6 error packets
810 KAME kernel will generate no more than one ICMPv6 error packet,
811 during configured time interval. net.inet6.icmp6.errratelimit
812 controls the interval (default: disabled).
813- Maximum ICMPv6 error packet-per-second
814 KAME kernel will generate no more than the configured number of
815 packets in one second. net.inet6.icmp6.errppslimit controls the
816 maximum packet-per-second value (default: 200pps)
817Basically, we need to pick values that are suitable against the bandwidth
818of link layer devices directly attached to the node. In some cases the
819default values may not fit well. We are still unsure if the default value
820is sane or not. Comments are welcome.
821
8221.10 Applications
823
824For userland programming, we support IPv6 socket API as specified in
825RFC2553, RFC2292 and upcoming internet drafts.
826
827TCP/UDP over IPv6 is available and quite stable. You can enjoy "telnet",
828"ftp", "rlogin", "rsh", "ssh", etc. These applications are protocol
829independent. That is, they automatically chooses IPv4 or IPv6
830according to DNS.
831
8321.11 Kernel Internals
833
834 (*) TCP/UDP part is handled differently between operating system platforms.
835 See 1.12 for details.
836
837The current KAME has escaped from the IPv4 netinet logic. While
838ip_forward() calls ip_output(), ip6_forward() directly calls
839if_output() since routers must not divide IPv6 packets into fragments.
840
841ICMPv6 should contain the original packet as long as possible up to
8421280. UDP6/IP6 port unreach, for instance, should contain all
843extension headers and the *unchanged* UDP6 and IP6 headers.
844So, all IP6 functions except TCP6 never convert network byte
845order into host byte order, to save the original packet.
846
847tcp6_input(), udp6_input() and icmp6_input() can't assume that IP6
848header is preceding the transport headers due to extension
849headers. So, in6_cksum() was implemented to handle packets whose IP6
850header and transport header is not continuous. TCP/IP6 nor UDP/IP6
851header structure don't exist for checksum calculation.
852
853To process IP6 header, extension headers and transport headers easily,
854KAME requires network drivers to store packets in one internal mbuf or
855one or more external mbufs. A typical old driver prepares two
856internal mbufs for 100 - 208 bytes data, however, KAME's reference
857implementation stores it in one external mbuf.
858
859"netstat -s -p ip6" tells you whether or not your driver conforms
860KAME's requirement. In the following example, "cce0" violates the
861requirement. (For more information, refer to Section 2.)
862
863 Mbuf statistics:
864 317 one mbuf
865 two or more mbuf::
866 lo0 = 8
867 cce0 = 10
868 3282 one ext mbuf
869 0 two or more ext mbuf
870
871Each input function calls IP6_EXTHDR_CHECK in the beginning to check
872if the region between IP6 and its header is
873continuous. IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has
874M_LOOP flag, that is, the packet comes from the loopback
875interface. m_pullup() is never called for packets coming from physical
876network interfaces.
877
878TCP6 reassembly makes use of IP6 header to store reassemble
879information. IP6 is not supposed to be just before TCP6, so
880ip6tcpreass structure has a pointer to TCP6 header. Of course, it has
881also a pointer back to mbuf to avoid m_pullup().
882
883Like TCP6, both IP and IP6 reassemble functions never call m_pullup().
884
885xxx_ctlinput() calls in_mrejoin() on PRC_IFNEWADDR. We think this is
886one of 4.4BSD implementation flaws. Since 4.4BSD keeps ia_multiaddrs
887in in_ifaddr{}, it can't use multicast feature if the interface has no
888unicast address. So, if an application joins to an interface and then
889all unicast addresses are removed from the interface, the application
890can't send/receive any multicast packets. Moreover, if a new unicast
891address is assigned to the interface, in_mrejoin() must be called.
892KAME's interfaces, however, have ALWAYS one link-local unicast
893address. These extensions have thus not been implemented in KAME.
894
8951.12 IPv4 mapped address and IPv6 wildcard socket
896
|
870RFC2553 describes IPv4 mapped address (3.7) and special behavior
| 897RFC2553/3493 describes IPv4 mapped address (3.7) and special behavior
|
871of IPv6 wildcard bind socket (3.8). The spec allows you to:
872- Accept IPv4 connections by AF_INET6 wildcard bind socket.
873- Transmit IPv4 packet over AF_INET6 socket by using special form of
874 the address like ::ffff:10.1.1.1.
875but the spec itself is very complicated and does not specify how the
876socket layer should behave.
877Here we call the former one "listening side" and the latter one "initiating
878side", for reference purposes.
879
880Almost all KAME implementations treat tcp/udp port number space separately
881between IPv4 and IPv6. You can perform wildcard bind on both of the address
882families, on the same port.
883
884There are some OS-platform differences in KAME code, as we use tcp/udp
885code from different origin. The following table summarizes the behavior.
886
887 listening side initiating side
888 (AF_INET6 wildcard (connection to ::ffff:10.1.1.1)
889 socket gets IPv4 conn.)
890 --- ---
891KAME/BSDI3 not supported not supported
892KAME/FreeBSD228 not supported not supported
893KAME/FreeBSD3x configurable supported
894 default: enabled
895KAME/FreeBSD4x configurable supported
896 default: enabled
897KAME/NetBSD configurable supported
898 default: disabled
899KAME/BSDI4 enabled supported
900KAME/OpenBSD not supported not supported
901
902The following sections will give you more details, and how you can
903configure the behavior.
904
905Comments on listening side:
906
| 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.
906
907Almost all KAME implementations treat tcp/udp port number space separately
908between IPv4 and IPv6. You can perform wildcard bind on both of the address
909families, on the same port.
910
911There are some OS-platform differences in KAME code, as we use tcp/udp
912code from different origin. The following table summarizes the behavior.
913
914 listening side initiating side
915 (AF_INET6 wildcard (connection to ::ffff:10.1.1.1)
916 socket gets IPv4 conn.)
917 --- ---
918KAME/BSDI3 not supported not supported
919KAME/FreeBSD228 not supported not supported
920KAME/FreeBSD3x configurable supported
921 default: enabled
922KAME/FreeBSD4x configurable supported
923 default: enabled
924KAME/NetBSD configurable supported
925 default: disabled
926KAME/BSDI4 enabled supported
927KAME/OpenBSD not supported not supported
928
929The following sections will give you more details, and how you can
930configure the behavior.
931
932Comments on listening side:
933
|
907It looks that RFC2553 talks too little on wildcard bind issue,
| 934It looks that RFC2553/3493 talks too little on wildcard bind issue,
|
908specifically on (1) port space issue, (2) failure mode, (3) relationship
909between AF_INET/INET6 wildcard bind like ordering constraint, and (4) behavior
910when conflicting socket is opened/closed. There can be several separate
911interpretation for this RFC which conform to it but behaves differently.
912So, to implement portable application you should assume nothing
913about the behavior in the kernel. Using getaddrinfo() is the safest way.
914Port number space and wildcard bind issues were discussed in detail
915on ipv6imp mailing list, in mid March 1999 and it looks that there's
916no concrete consensus (means, up to implementers). You may want to
917check the mailing list archives.
918We supply a tool called "bindtest" that explores the behavior of
919kernel bind(2). The tool will not be compiled by default.
920
921If a server application would like to accept IPv4 and IPv6 connections,
922it should use AF_INET and AF_INET6 socket (you'll need two sockets).
923Use getaddrinfo() with AI_PASSIVE into ai_flags, and socket(2) and bind(2)
924to all the addresses returned.
925By opening multiple sockets, you can accept connections onto the socket with
926proper address family. IPv4 connections will be accepted by AF_INET socket,
927and IPv6 connections will be accepted by AF_INET6 socket (NOTE: KAME/BSDI4
928kernel sometimes violate this - we will fix it).
929
930If you try to support IPv6 traffic only and would like to reject IPv4
931traffic, always check the peer address when a connection is made toward
932AF_INET6 listening socket. If the address is IPv4 mapped address, you may
933want to reject the connection. You can check the condition by using
934IN6_IS_ADDR_V4MAPPED() macro. This is one of the reasons the author of
935the section (itojun) dislikes special behavior of AF_INET6 wildcard bind.
936
937Comments on initiating side:
938
939Advise to application implementers: to implement a portable IPv6 application
940(which works on multiple IPv6 kernels), we believe that the following
941is the key to the success:
942- NEVER hardcode AF_INET nor AF_INET6.
943- Use getaddrinfo() and getnameinfo() throughout the system.
944 Never use gethostby*(), getaddrby*(), inet_*() or getipnodeby*().
945- If you would like to connect to destination, use getaddrinfo() and try
946 all the destination returned, like telnet does.
947- Some of the IPv6 stack is shipped with buggy getaddrinfo(). Ship a minimal
948 working version with your application and use that as last resort.
949
950If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing
951connection, you will need tweaked implementation in DNS support libraries,
| 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
943no concrete consensus (means, up to implementers). You may want to
944check the mailing list archives.
945We supply a tool called "bindtest" that explores the behavior of
946kernel bind(2). The tool will not be compiled by default.
947
948If a server application would like to accept IPv4 and IPv6 connections,
949it should use AF_INET and AF_INET6 socket (you'll need two sockets).
950Use getaddrinfo() with AI_PASSIVE into ai_flags, and socket(2) and bind(2)
951to all the addresses returned.
952By opening multiple sockets, you can accept connections onto the socket with
953proper address family. IPv4 connections will be accepted by AF_INET socket,
954and IPv6 connections will be accepted by AF_INET6 socket (NOTE: KAME/BSDI4
955kernel sometimes violate this - we will fix it).
956
957If you try to support IPv6 traffic only and would like to reject IPv4
958traffic, always check the peer address when a connection is made toward
959AF_INET6 listening socket. If the address is IPv4 mapped address, you may
960want to reject the connection. You can check the condition by using
961IN6_IS_ADDR_V4MAPPED() macro. This is one of the reasons the author of
962the section (itojun) dislikes special behavior of AF_INET6 wildcard bind.
963
964Comments on initiating side:
965
966Advise to application implementers: to implement a portable IPv6 application
967(which works on multiple IPv6 kernels), we believe that the following
968is the key to the success:
969- NEVER hardcode AF_INET nor AF_INET6.
970- Use getaddrinfo() and getnameinfo() throughout the system.
971 Never use gethostby*(), getaddrby*(), inet_*() or getipnodeby*().
972- If you would like to connect to destination, use getaddrinfo() and try
973 all the destination returned, like telnet does.
974- Some of the IPv6 stack is shipped with buggy getaddrinfo(). Ship a minimal
975 working version with your application and use that as last resort.
976
977If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing
978connection, you will need tweaked implementation in DNS support libraries,
|
952as documented in RFC2553 6.1. KAME libinet6 includes the tweak in
| 979as documented in RFC2553/3493 6.1. KAME libinet6 includes the tweak in
|
953getipnodebyname(). Note that getipnodebyname() itself is not recommended as
954it does not handle scoped IPv6 addresses at all. For IPv6 name resolution
955getaddrinfo() is the preferred API. getaddrinfo() does not implement the
956tweak.
957
958When writing applications that make outgoing connections, story goes much
959simpler if you treat AF_INET and AF_INET6 as totally separate address family.
960{set,get}sockopt issue goes simpler, DNS issue will be made simpler. We do
961not recommend you to rely upon IPv4 mapped address.
962
9631.12.1 KAME/BSDI3 and KAME/FreeBSD228
964
965The platforms do not support IPv4 mapped address at all (both listening side
966and initiating side). AF_INET6 and AF_INET sockets are totally separated.
967
968Port number space is totally separate between AF_INET and AF_INET6 sockets.
969
970It should be noted that KAME/BSDI3 and KAME/FreeBSD228 are not conformant
| 980getipnodebyname(). Note that getipnodebyname() itself is not recommended as
981it does not handle scoped IPv6 addresses at all. For IPv6 name resolution
982getaddrinfo() is the preferred API. getaddrinfo() does not implement the
983tweak.
984
985When writing applications that make outgoing connections, story goes much
986simpler if you treat AF_INET and AF_INET6 as totally separate address family.
987{set,get}sockopt issue goes simpler, DNS issue will be made simpler. We do
988not recommend you to rely upon IPv4 mapped address.
989
9901.12.1 KAME/BSDI3 and KAME/FreeBSD228
991
992The platforms do not support IPv4 mapped address at all (both listening side
993and initiating side). AF_INET6 and AF_INET sockets are totally separated.
994
995Port number space is totally separate between AF_INET and AF_INET6 sockets.
996
997It should be noted that KAME/BSDI3 and KAME/FreeBSD228 are not conformant
|
971to RFC2553 section 3.7 and 3.8. It is due to code sharing reasons.
| 998to RFC2553/3493 section 3.7 and 3.8. It is due to code sharing reasons.
|
972
9731.12.2 KAME/FreeBSD[34]x
974
975KAME/FreeBSD3x and KAME/FreeBSD4x use shared tcp4/6 code (from
976sys/netinet/tcp*) and shared udp4/6 code (from sys/netinet/udp*).
977They use unified inpcb/in6pcb structure.
978
9791.12.2.1 KAME/FreeBSD[34]x, listening side
980
981The platform can be configured to support IPv4 mapped address/special
982AF_INET6 wildcard bind (enabled by default). There is no kernel compilation
983option to disable it. You can enable/disable the behavior with sysctl
984(per-node), or setsockopt (per-socket).
985
986Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
987conditions are satisfied:
988- there's no AF_INET socket that matches the IPv4 connection
989- the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
990 getsockopt(IPV6_V6ONLY) returns 0.
991
992(XXX need checking)
993
9941.12.2.2 KAME/FreeBSD[34]x, initiating side
995
996KAME/FreeBSD3x supports outgoing connection to IPv4 mapped address
997(::ffff:10.1.1.1), if the node is configured to accept IPv4 connections
998by AF_INET6 socket.
999
1000(XXX need checking)
1001
10021.12.3 KAME/NetBSD
1003
1004KAME/NetBSD uses shared tcp4/6 code (from sys/netinet/tcp*) and shared
1005udp4/6 code (from sys/netinet/udp*). The implementation is made differently
1006from KAME/FreeBSD[34]x. KAME/NetBSD uses separate inpcb/in6pcb structures,
1007while KAME/FreeBSD[34]x uses merged inpcb structure.
1008
1009It should be noted that the default configuration of KAME/NetBSD is not
| 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
1007
1008The platform can be configured to support IPv4 mapped address/special
1009AF_INET6 wildcard bind (enabled by default). There is no kernel compilation
1010option to disable it. You can enable/disable the behavior with sysctl
1011(per-node), or setsockopt (per-socket).
1012
1013Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
1014conditions are satisfied:
1015- there's no AF_INET socket that matches the IPv4 connection
1016- the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
1017 getsockopt(IPV6_V6ONLY) returns 0.
1018
1019(XXX need checking)
1020
10211.12.2.2 KAME/FreeBSD[34]x, initiating side
1022
1023KAME/FreeBSD3x supports outgoing connection to IPv4 mapped address
1024(::ffff:10.1.1.1), if the node is configured to accept IPv4 connections
1025by AF_INET6 socket.
1026
1027(XXX need checking)
1028
10291.12.3 KAME/NetBSD
1030
1031KAME/NetBSD uses shared tcp4/6 code (from sys/netinet/tcp*) and shared
1032udp4/6 code (from sys/netinet/udp*). The implementation is made differently
1033from KAME/FreeBSD[34]x. KAME/NetBSD uses separate inpcb/in6pcb structures,
1034while KAME/FreeBSD[34]x uses merged inpcb structure.
1035
1036It should be noted that the default configuration of KAME/NetBSD is not
|
1010conformant to RFC2553 section 3.8. It is intentionally turned off by default
1011for security reasons.
| 1037conformant to RFC2553/3493 section 3.8. It is intentionally turned off by
1038default for security reasons.
|
1012
| 1039
|
10131.12.3.1 KAME/NetBSD, listening side
1014
| |
1015The platform can be configured to support IPv4 mapped address/special AF_INET6
1016wildcard bind (disabled by default). Kernel behavior can be summarized as
1017follows:
1018- default: special support code will be compiled in, but is disabled by
1019 default. It can be controlled by sysctl (net.inet6.ip6.v6only),
1020 or setsockopt(IPV6_V6ONLY).
| 1040The platform can be configured to support IPv4 mapped address/special AF_INET6
1041wildcard bind (disabled by default). Kernel behavior can be summarized as
1042follows:
1043- default: special support code will be compiled in, but is disabled by
1044 default. It can be controlled by sysctl (net.inet6.ip6.v6only),
1045 or setsockopt(IPV6_V6ONLY).
|
1021- add "INET6_V6ONLY": No special support code for AF_INET6 wildcard socket
| 1046- add "INET6_BINDV6ONLY": No special support code for AF_INET6 wildcard socket
|
1022 will be compiled in. AF_INET6 sockets and AF_INET sockets are totally
1023 separate. The behavior is similar to what described in 1.12.1.
1024
1025sysctl setting will affect per-socket configuration at in6pcb creation time
1026only. In other words, per-socket configuration will be copied from sysctl
1027configuration at in6pcb creation time. To change per-socket behavior, you
1028must perform setsockopt or reopen the socket. Change in sysctl configuration
1029will not change the behavior or sockets that are already opened.
1030
| 1047 will be compiled in. AF_INET6 sockets and AF_INET sockets are totally
1048 separate. The behavior is similar to what described in 1.12.1.
1049
1050sysctl setting will affect per-socket configuration at in6pcb creation time
1051only. In other words, per-socket configuration will be copied from sysctl
1052configuration at in6pcb creation time. To change per-socket behavior, you
1053must perform setsockopt or reopen the socket. Change in sysctl configuration
1054will not change the behavior or sockets that are already opened.
1055
|
| 10561.12.3.1 KAME/NetBSD, listening side
1057
|
1031Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
1032conditions are satisfied:
1033- there's no AF_INET socket that matches the IPv4 connection
1034- the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
1035 getsockopt(IPV6_V6ONLY) returns 0.
1036
1037You cannot bind(2) with IPv4 mapped address. This is a workaround for port
1038number duplicate and other twists.
1039
10401.12.3.2 KAME/NetBSD, initiating side
1041
| 1058Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
1059conditions are satisfied:
1060- there's no AF_INET socket that matches the IPv4 connection
1061- the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
1062 getsockopt(IPV6_V6ONLY) returns 0.
1063
1064You cannot bind(2) with IPv4 mapped address. This is a workaround for port
1065number duplicate and other twists.
1066
10671.12.3.2 KAME/NetBSD, initiating side
1068
|
1042When you initiate a connection, you can always connect to IPv4 destination
1043over AF_INET6 socket, usin IPv4 mapped address destination (::ffff:10.1.1.1).
1044This is enabled independently from the configuration for listening side, and
1045always enabled.
| 1069When getsockopt(IPV6_V6ONLY) is 0 for a socket, you can make an outgoing
1070traffic to IPv4 destination over AF_INET6 socket, using IPv4 mapped
1071address destination (::ffff:10.1.1.1).
|
1046
| 1072
|
| 1073When getsockopt(IPV6_V6ONLY) is 1 for a socket, you cannot use IPv4 mapped
1074address for outgoing traffic.
1075
|
10471.12.4 KAME/BSDI4
1048
1049KAME/BSDI4 uses NRL-based TCP/UDP stack and inpcb source code,
1050which was derived from NRL IPv6/IPsec stack. We guess it supports IPv4 mapped
1051address and speical AF_INET6 wildcard bind. The implementation is, again,
1052different from other KAME/*BSDs.
1053
10541.12.4.1 KAME/BSDI4, listening side
1055
1056NRL inpcb layer supports special behavior of AF_INET6 wildcard socket.
1057There is no way to disable the behavior.
1058
1059Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
1060condition is satisfied:
1061- there's no AF_INET socket that matches the IPv4 connection
1062
10631.12.4.2 KAME/BSDI4, initiating side
1064
1065KAME/BSDi4 supports connection initiation to IPv4 mapped address
1066(like ::ffff:10.1.1.1).
1067
10681.12.5 KAME/OpenBSD
1069
1070KAME/OpenBSD uses NRL-based TCP/UDP stack and inpcb source code,
1071which was derived from NRL IPv6/IPsec stack.
1072
| 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
1084
1085NRL inpcb layer supports special behavior of AF_INET6 wildcard socket.
1086There is no way to disable the behavior.
1087
1088Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
1089condition is satisfied:
1090- there's no AF_INET socket that matches the IPv4 connection
1091
10921.12.4.2 KAME/BSDI4, initiating side
1093
1094KAME/BSDi4 supports connection initiation to IPv4 mapped address
1095(like ::ffff:10.1.1.1).
1096
10971.12.5 KAME/OpenBSD
1098
1099KAME/OpenBSD uses NRL-based TCP/UDP stack and inpcb source code,
1100which was derived from NRL IPv6/IPsec stack.
1101
|
1073It should be noted that KAME/OpenBSD is not conformant to RFC2553 section 3.7
1074and 3.8. It is intentionally omitted for security reasons.
| 1102It should be noted that KAME/OpenBSD is not conformant to RFC2553/3493 section
11033.7 and 3.8. It is intentionally omitted for security reasons.
|
1075
10761.12.5.1 KAME/OpenBSD, listening side
1077
1078KAME/OpenBSD disables special behavior on AF_INET6 wildcard bind for
1079security reasons (if IPv4 traffic toward AF_INET6 wildcard bind is allowed,
1080access control will become much harder). KAME/BSDI4 uses NRL-based TCP/UDP
1081stack as well, however, the behavior is different due to OpenBSD's security
1082policy.
1083
1084As a result the behavior of KAME/OpenBSD is similar to KAME/BSDI3 and
1085KAME/FreeBSD228 (see 1.12.1 for more detail).
1086
10871.12.5.2 KAME/OpenBSD, initiating side
1088
1089KAME/OpenBSD does not support connection initiation to IPv4 mapped address
1090(like ::ffff:10.1.1.1).
1091
10921.12.6 More issues
1093
1094IPv4 mapped address support adds a big requirement to EVERY userland codebase.
1095Every userland code should check if an AF_INET6 sockaddr contains IPv4
1096mapped address or not. This adds many twists:
1097
1098- Access controls code becomes harder to write.
1099 For example, if you would like to reject packets from 10.0.0.0/8,
1100 you need to reject packets to AF_INET socket from 10.0.0.0/8,
1101 and to AF_INET6 socket from ::ffff:10.0.0.0/104.
1102- If a protocol on top of IPv4 is defined differently with IPv6, we need to be
1103 really careful when we determine which protocol to use.
1104 For example, with FTP protocol, we can not simply use sa_family to determine
1105 FTP command sets. The following example is incorrect:
1106 if (sa_family == AF_INET)
1107 use EPSV/EPRT or PASV/PORT; /*IPv4*/
1108 else if (sa_family == AF_INET6)
1109 use EPSV/EPRT or LPSV/LPRT; /*IPv6*/
1110 else
1111 error;
1112 The correct code, with consideration to IPv4 mapped address, would be:
1113 if (sa_family == AF_INET)
1114 use EPSV/EPRT or PASV/PORT; /*IPv4*/
1115 else if (sa_family == AF_INET6 && IPv4 mapped address)
1116 use EPSV/EPRT or PASV/PORT; /*IPv4 command set on AF_INET6*/
1117 else if (sa_family == AF_INET6 && !IPv4 mapped address)
1118 use EPSV/EPRT or LPSV/LPRT; /*IPv6*/
1119 else
1120 error;
1121 It is too much to ask for every body to be careful like this.
1122 The problem is, we are not sure if the above code fragment is perfect for
1123 all situations.
1124- By enabling kernel support for IPv4 mapped address (outgoing direction),
1125 servers on the kernel can be hosed by IPv6 native packet that has IPv4
1126 mapped address in IPv6 header source, and can generate unwanted IPv4 packets.
| 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.
1112
1113As a result the behavior of KAME/OpenBSD is similar to KAME/BSDI3 and
1114KAME/FreeBSD228 (see 1.12.1 for more detail).
1115
11161.12.5.2 KAME/OpenBSD, initiating side
1117
1118KAME/OpenBSD does not support connection initiation to IPv4 mapped address
1119(like ::ffff:10.1.1.1).
1120
11211.12.6 More issues
1122
1123IPv4 mapped address support adds a big requirement to EVERY userland codebase.
1124Every userland code should check if an AF_INET6 sockaddr contains IPv4
1125mapped address or not. This adds many twists:
1126
1127- Access controls code becomes harder to write.
1128 For example, if you would like to reject packets from 10.0.0.0/8,
1129 you need to reject packets to AF_INET socket from 10.0.0.0/8,
1130 and to AF_INET6 socket from ::ffff:10.0.0.0/104.
1131- If a protocol on top of IPv4 is defined differently with IPv6, we need to be
1132 really careful when we determine which protocol to use.
1133 For example, with FTP protocol, we can not simply use sa_family to determine
1134 FTP command sets. The following example is incorrect:
1135 if (sa_family == AF_INET)
1136 use EPSV/EPRT or PASV/PORT; /*IPv4*/
1137 else if (sa_family == AF_INET6)
1138 use EPSV/EPRT or LPSV/LPRT; /*IPv6*/
1139 else
1140 error;
1141 The correct code, with consideration to IPv4 mapped address, would be:
1142 if (sa_family == AF_INET)
1143 use EPSV/EPRT or PASV/PORT; /*IPv4*/
1144 else if (sa_family == AF_INET6 && IPv4 mapped address)
1145 use EPSV/EPRT or PASV/PORT; /*IPv4 command set on AF_INET6*/
1146 else if (sa_family == AF_INET6 && !IPv4 mapped address)
1147 use EPSV/EPRT or LPSV/LPRT; /*IPv6*/
1148 else
1149 error;
1150 It is too much to ask for every body to be careful like this.
1151 The problem is, we are not sure if the above code fragment is perfect for
1152 all situations.
1153- By enabling kernel support for IPv4 mapped address (outgoing direction),
1154 servers on the kernel can be hosed by IPv6 native packet that has IPv4
1155 mapped address in IPv6 header source, and can generate unwanted IPv4 packets.
|
1127 draft-itojun-ipv6-transition-abuse-01.txt talks more about this scenario.
| 1156 draft-itojun-ipv6-transition-abuse-01.txt, draft-cmetz-v6ops-v4mapped-api-
1157 harmful-00.txt, and draft-itojun-v6ops-v4mapped-harmful-01.txt
1158 has more on this scenario.
|
1128
1129Due to the above twists, some of KAME userland programs has restrictions on
1130the use of IPv4 mapped addresses:
1131- rshd/rlogind do not accept connections from IPv4 mapped address.
1132 This is to avoid malicious use of IPv4 mapped address in IPv6 native
1133 packet, to bypass source-address based authentication.
1134- ftp/ftpd assume that you are on dual stack network. IPv4 mapped address
1135 will be decoded in userland, and will be passed to AF_INET sockets
1136 (in other words, ftp/ftpd do not support SIIT environment).
1137
11381.12.7 Interaction with SIIT translator
1139
1140SIIT translator is specified in RFC2765. KAME node cannot become a SIIT
1141translator box, nor SIIT end node (a node in SIIT cloud).
1142
1143To become a SIIT translator box, we need to put additional code for that.
1144We do not have the code in our tree at this moment.
1145
1146There are multiple reasons that we are unable to become SIIT end node.
1147(1) SIIT translators require end nodes in the SIIT cloud to be IPv6-only.
1148Since we are unable to compile INET-less kernel, we are unable to become
1149SIIT end node. (2) As presented in 1.12.6, some of our userland code assumes
1150dual stack network. (3) KAME stack filters out IPv6 packets with IPv4
1151mapped address in the header, to secure non-SIIT case (which is much more
1152common). Effectively KAME node will reject any packets via SIIT translator
1153box. See section 1.14 for more detail about the last item.
1154
1155There are documentation issues too - SIIT document requires very strange
1156things. For example, SIIT document asks IPv6-only (meaning no IPv4 code)
1157node to be able to construct IPv4 IPsec headers. If a node knows how to
1158construct IPv4 IPsec headers, that is not an IPv6-only node, it is a dual-stack
1159node. The requirements imposed in SIIT document contradict with the other
1160part of the document itself.
1161
11621.13 sockaddr_storage
1163
1164When RFC2553 was about to be finalized, there was discussion on how struct
1165sockaddr_storage members are named. One proposal is to prepend "__" to the
1166members (like "__ss_len") as they should not be touched. The other proposal
1167was that don't prepend it (like "ss_len") as we need to touch those members
1168directly. There was no clear consensus on it.
1169
1170As a result, RFC2553 defines struct sockaddr_storage as follows:
1171 struct sockaddr_storage {
1172 u_char __ss_len; /* address length */
1173 u_char __ss_family; /* address family */
1174 /* and bunch of padding */
1175 };
1176On the contrary, XNET draft defines as follows:
1177 struct sockaddr_storage {
1178 u_char ss_len; /* address length */
1179 u_char ss_family; /* address family */
1180 /* and bunch of padding */
1181 };
1182
| 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
1167 (in other words, ftp/ftpd do not support SIIT environment).
1168
11691.12.7 Interaction with SIIT translator
1170
1171SIIT translator is specified in RFC2765. KAME node cannot become a SIIT
1172translator box, nor SIIT end node (a node in SIIT cloud).
1173
1174To become a SIIT translator box, we need to put additional code for that.
1175We do not have the code in our tree at this moment.
1176
1177There are multiple reasons that we are unable to become SIIT end node.
1178(1) SIIT translators require end nodes in the SIIT cloud to be IPv6-only.
1179Since we are unable to compile INET-less kernel, we are unable to become
1180SIIT end node. (2) As presented in 1.12.6, some of our userland code assumes
1181dual stack network. (3) KAME stack filters out IPv6 packets with IPv4
1182mapped address in the header, to secure non-SIIT case (which is much more
1183common). Effectively KAME node will reject any packets via SIIT translator
1184box. See section 1.14 for more detail about the last item.
1185
1186There are documentation issues too - SIIT document requires very strange
1187things. For example, SIIT document asks IPv6-only (meaning no IPv4 code)
1188node to be able to construct IPv4 IPsec headers. If a node knows how to
1189construct IPv4 IPsec headers, that is not an IPv6-only node, it is a dual-stack
1190node. The requirements imposed in SIIT document contradict with the other
1191part of the document itself.
1192
11931.13 sockaddr_storage
1194
1195When RFC2553 was about to be finalized, there was discussion on how struct
1196sockaddr_storage members are named. One proposal is to prepend "__" to the
1197members (like "__ss_len") as they should not be touched. The other proposal
1198was that don't prepend it (like "ss_len") as we need to touch those members
1199directly. There was no clear consensus on it.
1200
1201As a result, RFC2553 defines struct sockaddr_storage as follows:
1202 struct sockaddr_storage {
1203 u_char __ss_len; /* address length */
1204 u_char __ss_family; /* address family */
1205 /* and bunch of padding */
1206 };
1207On the contrary, XNET draft defines as follows:
1208 struct sockaddr_storage {
1209 u_char ss_len; /* address length */
1210 u_char ss_family; /* address family */
1211 /* and bunch of padding */
1212 };
1213
|
1183In December 1999, it was agreed that RFC2553bis should pick the latter (XNET)
1184definition.
| 1214In December 1999, it was agreed that RFC2553bis (RFC3493) should pick the
1215latter (XNET) definition.
|
1185
1186KAME kit prior to December 1999 used RFC2553 definition. KAME kit after
1187December 1999 (including December) will conform to XNET definition,
| 1216
1217KAME kit prior to December 1999 used RFC2553 definition. KAME kit after
1218December 1999 (including December) will conform to XNET definition,
|
1188based on RFC2553bis discussion.
| 1219based on RFC3493 discussion.
|
1189
1190If you look at multiple IPv6 implementations, you will be able to see
1191both definitions. As an userland programmer, the most portable way of
1192dealing with it is to:
1193(1) ensure ss_family and/or ss_len are available on the platform, by using
1194 GNU autoconf,
1195(2) have -Dss_family=__ss_family to unify all occurences (including header
1196 file) into __ss_family, or
1197(3) never touch __ss_family. cast to sockaddr * and use sa_family like:
1198 struct sockaddr_storage ss;
1199 family = ((struct sockaddr *)&ss)->sa_family
1200
12011.14 Invalid addresses on the wire
1202
1203Some of IPv6 transition technologies embed IPv4 address into IPv6 address.
1204These specifications themselves are fine, however, there can be certain
1205set of attacks enabled by these specifications. Recent speicifcation
1206documents covers up those issues, however, there are already-published RFCs
1207that does not have protection against those (like using source address of
1208::ffff:127.0.0.1 to bypass "reject packet from remote" filter).
1209
1210To name a few, these address ranges can be used to hose an IPv6 implementation,
1211or bypass security controls:
1212- IPv4 mapped address that embeds unspecified/multicast/loopback/broadcast
1213 IPv4 address (if they are in IPv6 native packet header, they are malicious)
1214 ::ffff:0.0.0.0/104 ::ffff:127.0.0.0/104
1215 ::ffff:224.0.0.0/100 ::ffff:255.0.0.0/104
1216- 6to4 (RFC3056) prefix generated from unspecified/multicast/loopback/
1217 broadcast/private IPv4 address
1218 2002:0000::/24 2002:7f00::/24 2002:e000::/24
1219 2002:ff00::/24 2002:0a00::/24 2002:ac10::/28
1220 2002:c0a8::/32
1221- IPv4 compatible address that embeds unspecified/multicast/loopback/broadcast
1222 IPv4 address (if they are in IPv6 native packet header, they are malicious).
1223 Note that, since KAME doe snot support RFC1933/2893 auto tunnels, KAME nodes
1224 are not vulnerable to these packets.
1225 ::0.0.0.0/104 ::127.0.0.0/104 ::224.0.0.0/100 ::255.0.0.0/104
1226
1227Also, since KAME does not support RFC1933/2893 auto tunnels, seeing IPv4
1228compatible is very rare. You should take caution if you see those on the wire.
1229
1230If we see IPv6 packets with IPv4 mapped address (::ffff:0.0.0.0/96) in the
1231header in dual-stack environment (not in SIIT environment), they indicate
1232that someone is trying to inpersonate IPv4 peer. The packet should be dropped.
1233
1234IPv6 specifications do not talk very much about IPv6 unspecified address (::)
1235in the IPv6 source address field. Clarification is in progress.
1236Here are couple of comments:
1237- IPv6 unspecified address can be used in IPv6 source address field, if and
1238 only if we have no legal source address for the node. The legal situations
1239 include, but may not be limited to, (1) MLD while no IPv6 address is assigned
1240 to the node and (2) DAD.
1241- If IPv6 TCP packet has IPv6 unspecified address, it is an attack attempt.
1242 The form can be used as a trigger for TCP DoS attack. KAME code already
1243 filters them out.
1244- The following examples are seemingly illegal. It seems that there's general
1245 consensus among ipngwg for those. (1) mobile-ip6 home address option,
1246 (2) offlink packets (so routers should not forward them).
1247 KAME implmements (2) already.
1248
1249KAME code is carefully written to avoid such incidents. More specifically,
1250KAME kernel will reject packets with certain source/dstination address in IPv6
1251base header, or IPv6 routing header. Also, KAME default configuration file
1252is written carefully, to avoid those attacks.
1253
| 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
1228(3) never touch __ss_family. cast to sockaddr * and use sa_family like:
1229 struct sockaddr_storage ss;
1230 family = ((struct sockaddr *)&ss)->sa_family
1231
12321.14 Invalid addresses on the wire
1233
1234Some of IPv6 transition technologies embed IPv4 address into IPv6 address.
1235These specifications themselves are fine, however, there can be certain
1236set of attacks enabled by these specifications. Recent speicifcation
1237documents covers up those issues, however, there are already-published RFCs
1238that does not have protection against those (like using source address of
1239::ffff:127.0.0.1 to bypass "reject packet from remote" filter).
1240
1241To name a few, these address ranges can be used to hose an IPv6 implementation,
1242or bypass security controls:
1243- IPv4 mapped address that embeds unspecified/multicast/loopback/broadcast
1244 IPv4 address (if they are in IPv6 native packet header, they are malicious)
1245 ::ffff:0.0.0.0/104 ::ffff:127.0.0.0/104
1246 ::ffff:224.0.0.0/100 ::ffff:255.0.0.0/104
1247- 6to4 (RFC3056) prefix generated from unspecified/multicast/loopback/
1248 broadcast/private IPv4 address
1249 2002:0000::/24 2002:7f00::/24 2002:e000::/24
1250 2002:ff00::/24 2002:0a00::/24 2002:ac10::/28
1251 2002:c0a8::/32
1252- IPv4 compatible address that embeds unspecified/multicast/loopback/broadcast
1253 IPv4 address (if they are in IPv6 native packet header, they are malicious).
1254 Note that, since KAME doe snot support RFC1933/2893 auto tunnels, KAME nodes
1255 are not vulnerable to these packets.
1256 ::0.0.0.0/104 ::127.0.0.0/104 ::224.0.0.0/100 ::255.0.0.0/104
1257
1258Also, since KAME does not support RFC1933/2893 auto tunnels, seeing IPv4
1259compatible is very rare. You should take caution if you see those on the wire.
1260
1261If we see IPv6 packets with IPv4 mapped address (::ffff:0.0.0.0/96) in the
1262header in dual-stack environment (not in SIIT environment), they indicate
1263that someone is trying to inpersonate IPv4 peer. The packet should be dropped.
1264
1265IPv6 specifications do not talk very much about IPv6 unspecified address (::)
1266in the IPv6 source address field. Clarification is in progress.
1267Here are couple of comments:
1268- IPv6 unspecified address can be used in IPv6 source address field, if and
1269 only if we have no legal source address for the node. The legal situations
1270 include, but may not be limited to, (1) MLD while no IPv6 address is assigned
1271 to the node and (2) DAD.
1272- If IPv6 TCP packet has IPv6 unspecified address, it is an attack attempt.
1273 The form can be used as a trigger for TCP DoS attack. KAME code already
1274 filters them out.
1275- The following examples are seemingly illegal. It seems that there's general
1276 consensus among ipngwg for those. (1) mobile-ip6 home address option,
1277 (2) offlink packets (so routers should not forward them).
1278 KAME implmements (2) already.
1279
1280KAME code is carefully written to avoid such incidents. More specifically,
1281KAME kernel will reject packets with certain source/dstination address in IPv6
1282base header, or IPv6 routing header. Also, KAME default configuration file
1283is written carefully, to avoid those attacks.
1284
|
1254draft-itojun-ipv6-transition-abuse-01.txt talks about more about this.
| 1285draft-itojun-ipv6-transition-abuse-01.txt, draft-cmetz-v6ops-v4mapped-api-
1286harmful-00.txt and draft-itojun-v6ops-v4mapped-harmful-01.txt has more on
1287this issue.
|
1255
12561.15 Node's required addresses
1257
1258RFC2373 section 2.8 talks about required addresses for an IPv6
1259node. The section talks about how KAME stack manages those required
1260addresses.
1261
12621.15.1 Host case
1263
1264The following items are automatically assigned to the node (or the node will
1265automatically joins the group), at bootstrap time:
1266- Loopback address
1267- All-nodes multicast addresses (ff01::1)
1268
1269The following items will be automatically handled when the interface becomes
1270IFF_UP:
1271- Its link-local address for each interface
1272- Solicited-node multicast address for link-local addresses
1273- Link-local allnodes multicast address (ff02::1)
1274
1275The following items need to be configured manually by ifconfig(8) or prefix(8).
1276Alternatively, these can be autoconfigured by using stateless address
1277autoconfiguration.
1278- Assigned unicast/anycast addresses
1279- Solicited-Node multicast address for assigned unicast address
1280
1281Users can join groups by using appropriate system calls like setsockopt(2).
1282
12831.15.2 Router case
1284
1285In addition to the above, routers needs to handle the following items.
1286
1287The following items need to be configured manually by using ifconfig(8).
1288o The subnet-router anycast addresses for the interfaces it is configured
1289 to act as a router on (prefix::/64)
1290o All other anycast addresses with which the router has been configured
1291
1292The router will join the following multicast group when rtadvd(8) is available
1293for the interface.
1294o All-Routers Multicast Addresses (ff02::2)
1295
1296Routing daemons will join appropriate multicast groups, as necessary,
1297like ff02::9 for RIPng.
1298
1299Users can join groups by using appropriate system calls like setsockopt(2).
1300
13011.16 Advanced API
1302
| 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
1296
1297The following items are automatically assigned to the node (or the node will
1298automatically joins the group), at bootstrap time:
1299- Loopback address
1300- All-nodes multicast addresses (ff01::1)
1301
1302The following items will be automatically handled when the interface becomes
1303IFF_UP:
1304- Its link-local address for each interface
1305- Solicited-node multicast address for link-local addresses
1306- Link-local allnodes multicast address (ff02::1)
1307
1308The following items need to be configured manually by ifconfig(8) or prefix(8).
1309Alternatively, these can be autoconfigured by using stateless address
1310autoconfiguration.
1311- Assigned unicast/anycast addresses
1312- Solicited-Node multicast address for assigned unicast address
1313
1314Users can join groups by using appropriate system calls like setsockopt(2).
1315
13161.15.2 Router case
1317
1318In addition to the above, routers needs to handle the following items.
1319
1320The following items need to be configured manually by using ifconfig(8).
1321o The subnet-router anycast addresses for the interfaces it is configured
1322 to act as a router on (prefix::/64)
1323o All other anycast addresses with which the router has been configured
1324
1325The router will join the following multicast group when rtadvd(8) is available
1326for the interface.
1327o All-Routers Multicast Addresses (ff02::2)
1328
1329Routing daemons will join appropriate multicast groups, as necessary,
1330like ff02::9 for RIPng.
1331
1332Users can join groups by using appropriate system calls like setsockopt(2).
1333
13341.16 Advanced API
1335
|
1303Current KAME kernel implements 2292bis API, documented in
1304draft-ietf-ipngwg-rfc2292bis-xx.txt. It also implements RFC2292 API,
| 1336Current KAME kernel implements RFC3542 API. It also implements RFC2292 API,
|
1305for backward compatibility purposes with *BSD-integrated codebase.
| 1337for backward compatibility purposes with *BSD-integrated codebase.
|
1306KAME tree ships with 2292bis headers.
1307*BSD-integrated codebase implements either RFC2292, or 2292bis, API.
| 1338KAME tree ships with RFC3542 headers.
1339*BSD-integrated codebase implements either RFC2292, or RFC3542, API.
|
1308see "COVERAGE" document for detailed implementation status.
1309
1310Here are couple of issues to mention:
1311- *BSD-integrated binaries, compiled for RFC2292, will work on KAME kernel.
1312 For example, OpenBSD 2.7 /sbin/rtsol will work on KAME/openbsd kernel.
| 1340see "COVERAGE" document for detailed implementation status.
1341
1342Here are couple of issues to mention:
1343- *BSD-integrated binaries, compiled for RFC2292, will work on KAME kernel.
1344 For example, OpenBSD 2.7 /sbin/rtsol will work on KAME/openbsd kernel.
|
1313- KAME binaries, compiled using 2292bis, will not work on *BSD-integrated
| 1345- KAME binaries, compiled using RFC3542, will not work on *BSD-integrated
|
1314 kenrel. For example, KAME /usr/local/v6/sbin/rtsol will not work on
1315 OpenBSD 2.7 kernel.
| 1346 kenrel. For example, KAME /usr/local/v6/sbin/rtsol will not work on
1347 OpenBSD 2.7 kernel.
|
1316- 2292bis API is not compatible with RFC2292 API. 2292bis #define symbols
| 1348- RFC3542 API is not compatible with RFC2292 API. RFC3542 #define symbols
|
1317 conflict with RFC2292 symbols. Therefore, if you compile programs that
1318 assume RFC2292 API, the compilation itself goes fine, however, the compiled
1319 binary will not work correctly. The problem is not KAME issue, but API
| 1349 conflict with RFC2292 symbols. Therefore, if you compile programs that
1350 assume RFC2292 API, the compilation itself goes fine, however, the compiled
1351 binary will not work correctly. The problem is not KAME issue, but API
|
1320 issue. For example, Solaris 8 implements 2292bis API. If you compile
| 1352 issue. For example, Solaris 8 implements RFC3542 API. If you compile
|
1321 RFC2292-based code on Solaris 8, the binary can behave strange.
1322
1323There are few (or couple of) incompatible behavior in RFC2292 binary backward
1324compatibility support in KAME tree. To enumerate:
1325- Type 0 routing header lacks support for strict/loose bitmap.
1326 Even if we see packets with "strict" bit set, those bits will not be made
1327 visible to the userland.
1328 Background: RFC2292 document is based on RFC1883 IPv6, and it uses
| 1353 RFC2292-based code on Solaris 8, the binary can behave strange.
1354
1355There are few (or couple of) incompatible behavior in RFC2292 binary backward
1356compatibility support in KAME tree. To enumerate:
1357- Type 0 routing header lacks support for strict/loose bitmap.
1358 Even if we see packets with "strict" bit set, those bits will not be made
1359 visible to the userland.
1360 Background: RFC2292 document is based on RFC1883 IPv6, and it uses
|
1329 strict/loose bitmap. 2292bis document is based on RFC2460 IPv6, and it has
| 1361 strict/loose bitmap. RFC3542 document is based on RFC2460 IPv6, and it has
|
1330 no strict/loose bitmap (it was removed from RFC2460). KAME tree obeys
1331 RFC2460 IPv6, and lacks support for strict/loose bitmap.
1332
| 1362 no strict/loose bitmap (it was removed from RFC2460). KAME tree obeys
1363 RFC2460 IPv6, and lacks support for strict/loose bitmap.
1364
|
| 1365The RFC3542 documents leave some particular cases unspecified. The
1366KAME implementation treats them as follows:
1367- The IPV6_DONTFRAG and IPV6_RECVPATHMTU socket options for TCP
1368 sockets are ignored. That is, the setsocktopt() call will succeed
1369 but the specified value will have no effect.
1370
13711.17 DNS resolver
1372
1373KAME ships with modified DNS resolver, in libinet6.a.
1374libinet6.a has a comple of extensions against libc DNS resolver:
1375- Can take "options insecure1" and "options insecure2" in /etc/resolv.conf,
1376 which toggles RES_INSECURE[12] option flag bit.
1377- EDNS0 receive buffer size notification support. It can be enabled by
1378 "options edns0" in /etc/resolv.conf. See USAGE for details.
1379- IPv6 transport support (queries/responses over IPv6). Most of BSD official
1380 releases now has it already.
1381- Partial A6 chain chasing/DNAME/bit string label support (KAME/BSDI4).
1382
1383
|
13332. Network Drivers
1334
1335KAME requires three items to be added into the standard drivers:
1336
| 13842. Network Drivers
1385
1386KAME requires three items to be added into the standard drivers:
1387
|
1337(1) mbuf clustering requirement. In this stable release, we changed
1338 MINCLSIZE into MHLEN+1 for all the operating systems in order to make
1339 all the drivers behave as we expect.
| 1388(1) (freebsd[234] and bsdi[34] only) mbuf clustering requirement.
1389 In this stable release, we changed MINCLSIZE into MHLEN+1 for all the
1390 operating systems in order to make all the drivers behave as we expect.
|
1340
1341(2) multicast. If "ifmcstat" yields no multicast group for a
1342 interface, that interface has to be patched.
1343
1344To avoid troubles, we suggest you to comment out the device drivers
1345for unsupported/unnecessary cards, from the kernel configuration file.
1346If you accidentally enable unsupported drivers, some of the userland
1347tools may not work correctly (routing daemons are typical example).
1348
1349In the following sections, "official support" means that KAME developers
1350are using that ethernet card/driver frequently.
1351
1352(NOTE: In the past we required all pcmcia drivers to have a call to
1353in6_ifattach(). We have no such requirement any more)
1354
13552.1 FreeBSD 2.2.x-RELEASE
1356
1357Here is a list of FreeBSD 2.2.x-RELEASE drivers and its conditions:
1358
1359 driver mbuf(1) multicast(2) official support?
1360 --- --- --- ---
1361 (Ethernet)
1362 ar looks ok - -
1363 cnw ok ok yes (*)
1364 ed ok ok yes
1365 ep ok ok yes
1366 fe ok ok yes
1367 sn looks ok - - (*)
1368 vx looks ok - -
1369 wlp ok ok - (*)
1370 xl ok ok yes
1371 zp ok ok -
1372 (FDDI)
1373 fpa looks ok ? -
1374 (ATM)
1375 en ok ok yes
1376 (Serial)
1377 lp ? - not work
1378 sl ? - not work
1379 sr looks ok ok - (**)
1380
1381You may want to add an invocation of "rtsol" in "/etc/pccard_ether",
1382if you are using notebook computers and PCMCIA ethernet card.
1383
1384(*) These drivers are distributed with PAO (http://www.jp.freebsd.org/PAO/).
1385
1386(**) There was some report says that, if you make sr driver up and down and
1387then up, the kernel may hang up. We have disabled frame-relay support from
1388sr driver and after that this looks to be working fine. If you need
1389frame-relay support to come back, please contact KAME developers.
1390
13912.2 BSD/OS 3.x
1392
1393The following lists BSD/OS 3.x device drivers and its conditions:
1394
1395 driver mbuf(1) multicast(2) official support?
1396 --- --- --- ---
1397 (Ethernet)
1398 cnw ok ok yes
1399 de ok ok -
1400 df ok ok -
1401 eb ok ok -
1402 ef ok ok yes
1403 exp ok ok -
1404 mz ok ok yes
1405 ne ok ok yes
1406 we ok ok -
1407 (FDDI)
1408 fpa ok ok -
1409 (ATM)
1410 en maybe ok -
1411 (Serial)
1412 ntwo ok ok yes
1413 sl ? - not work
1414 appp ? - not work
1415
1416You may want to use "@insert" directive in /etc/pccard.conf to invoke
1417"rtsol" command right after dynamic insertion of PCMCIA ethernet cards.
1418
14192.3 NetBSD
1420
1421The following table lists the network drivers we have tried so far.
1422
1423 driver mbuf(1) multicast(2) official support?
1424 --- --- --- ---
1425 (Ethernet)
1426 awi pcmcia/i386 ok ok -
1427 bah zbus/amiga NG(*)
1428 cnw pcmcia/i386 ok ok yes
1429 ep pcmcia/i386 ok ok -
1430 le sbus/sparc ok ok yes
1431 ne pci/i386 ok ok yes
1432 ne pcmcia/i386 ok ok yes
1433 wi pcmcia/i386 ok ok yes
1434 (ATM)
1435 en pci/i386 ok ok -
1436
1437(*) This may need some fix, but I'm not sure what arcnet interfaces assume...
1438
14392.4 FreeBSD 3.x-RELEASE
1440
1441Here is a list of FreeBSD 3.x-RELEASE drivers and its conditions:
1442
1443 driver mbuf(1) multicast(2) official support?
1444 --- --- --- ---
1445 (Ethernet)
1446 cnw ok ok -(*)
1447 ed ? ok -
1448 ep ok ok -
1449 fe ok ok yes
1450 fxp ?(**)
1451 lnc ? ok -
1452 sn ? ? -(*)
1453 wi ok ok yes
1454 xl ? ok -
1455
1456(*) These drivers are distributed with PAO as PAO3
1457 (http://www.jp.freebsd.org/PAO/).
1458(**) there are trouble reports with multicast filter initialization.
1459
1460More drivers will just simply work on KAME FreeBSD 3.x-RELEASE but have not
1461been checked yet.
1462
14632.5 FreeBSD 4.x-RELEASE
1464
1465Here is a list of FreeBSD 4.x-RELEASE drivers and its conditions:
1466
1467 driver multicast
1468 --- ---
1469 (Ethernet)
1470 lnc/vmware ok
1471
14722.6 OpenBSD 2.x
1473
1474Here is a list of OpenBSD 2.x drivers and its conditions:
1475
1476 driver mbuf(1) multicast(2) official support?
1477 --- --- --- ---
1478 (Ethernet)
1479 de pci/i386 ok ok yes
1480 fxp pci/i386 ?(*)
1481 le sbus/sparc ok ok yes
1482 ne pci/i386 ok ok yes
1483 ne pcmcia/i386 ok ok yes
1484 wi pcmcia/i386 ok ok yes
1485
1486(*) There seem to be some problem in driver, with multicast filter
1487configuration. This happens with certain revision of chipset on the card.
1488Should be fixed by now by workaround in sys/net/if.c, but still not sure.
1489
14902.7 BSD/OS 4.x
1491
1492The following lists BSD/OS 4.x device drivers and its conditions:
1493
1494 driver mbuf(1) multicast(2) official support?
1495 --- --- --- ---
1496 (Ethernet)
1497 de ok ok yes
1498 exp (*)
1499
1500You may want to use "@insert" directive in /etc/pccard.conf to invoke
1501"rtsol" command right after dynamic insertion of PCMCIA ethernet cards.
1502
1503(*) exp driver has serious conflict with KAME initialization sequence.
1504A workaround is committed into sys/i386/pci/if_exp.c, and should be okay by now.
1505
15063. Translator
1507
1508We categorize IPv4/IPv6 translator into 4 types.
1509
1510Translator A --- It is used in the early stage of transition to make
1511it possible to establish a connection from an IPv6 host in an IPv6
1512island to an IPv4 host in the IPv4 ocean.
1513
1514Translator B --- It is used in the early stage of transition to make
1515it possible to establish a connection from an IPv4 host in the IPv4
1516ocean to an IPv6 host in an IPv6 island.
1517
1518Translator C --- It is used in the late stage of transition to make it
1519possible to establish a connection from an IPv4 host in an IPv4 island
1520to an IPv6 host in the IPv6 ocean.
1521
1522Translator D --- It is used in the late stage of transition to make it
1523possible to establish a connection from an IPv6 host in the IPv6 ocean
1524to an IPv4 host in an IPv4 island.
1525
1526KAME provides an TCP relay translator for category A. This is called
1527"FAITH". We also provide IP header translator for category A.
1528
15293.1 FAITH TCP relay translator
1530
1531FAITH system uses TCP relay daemon called "faithd" helped by the KAME kernel.
1532FAITH will reserve an IPv6 address prefix, and relay TCP connection
1533toward that prefix to IPv4 destination.
1534
1535For example, if the reserved IPv6 prefix is 3ffe:0501:0200:ffff::, and
1536the IPv6 destination for TCP connection is 3ffe:0501:0200:ffff::163.221.202.12,
1537the connection will be relayed toward IPv4 destination 163.221.202.12.
1538
1539 destination IPv4 node (163.221.202.12)
1540 ^
1541 | IPv4 tcp toward 163.221.202.12
1542 FAITH-relay dual stack node
1543 ^
1544 | IPv6 TCP toward 3ffe:0501:0200:ffff::163.221.202.12
1545 source IPv6 node
1546
1547faithd must be invoked on FAITH-relay dual stack node.
1548
1549For more details, consult kame/kame/faithd/README and
1550draft-ietf-ngtrans-tcpudp-relay-04.txt.
1551
15523.2 IPv6-to-IPv4 header translator
1553
1554(to be written)
1555
15564. IPsec
1557
1558IPsec is implemented as the following three components.
1559
1560(1) Policy Management
1561(2) Key Management
1562(3) AH, ESP and IPComp handling in kernel
1563
1564Note that KAME/OpenBSD does NOT include support for KAME IPsec code,
1565as OpenBSD team has their home-brew IPsec stack and they have no plan
1566to replace it. IPv6 support for IPsec is, therefore, lacking on KAME/OpenBSD.
1567
1568http://www.netbsd.org/Documentation/network/ipsec/ has more information
1569including usage examples.
1570
15714.1 Policy Management
1572
| 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).
1399
1400In the following sections, "official support" means that KAME developers
1401are using that ethernet card/driver frequently.
1402
1403(NOTE: In the past we required all pcmcia drivers to have a call to
1404in6_ifattach(). We have no such requirement any more)
1405
14062.1 FreeBSD 2.2.x-RELEASE
1407
1408Here is a list of FreeBSD 2.2.x-RELEASE drivers and its conditions:
1409
1410 driver mbuf(1) multicast(2) official support?
1411 --- --- --- ---
1412 (Ethernet)
1413 ar looks ok - -
1414 cnw ok ok yes (*)
1415 ed ok ok yes
1416 ep ok ok yes
1417 fe ok ok yes
1418 sn looks ok - - (*)
1419 vx looks ok - -
1420 wlp ok ok - (*)
1421 xl ok ok yes
1422 zp ok ok -
1423 (FDDI)
1424 fpa looks ok ? -
1425 (ATM)
1426 en ok ok yes
1427 (Serial)
1428 lp ? - not work
1429 sl ? - not work
1430 sr looks ok ok - (**)
1431
1432You may want to add an invocation of "rtsol" in "/etc/pccard_ether",
1433if you are using notebook computers and PCMCIA ethernet card.
1434
1435(*) These drivers are distributed with PAO (http://www.jp.freebsd.org/PAO/).
1436
1437(**) There was some report says that, if you make sr driver up and down and
1438then up, the kernel may hang up. We have disabled frame-relay support from
1439sr driver and after that this looks to be working fine. If you need
1440frame-relay support to come back, please contact KAME developers.
1441
14422.2 BSD/OS 3.x
1443
1444The following lists BSD/OS 3.x device drivers and its conditions:
1445
1446 driver mbuf(1) multicast(2) official support?
1447 --- --- --- ---
1448 (Ethernet)
1449 cnw ok ok yes
1450 de ok ok -
1451 df ok ok -
1452 eb ok ok -
1453 ef ok ok yes
1454 exp ok ok -
1455 mz ok ok yes
1456 ne ok ok yes
1457 we ok ok -
1458 (FDDI)
1459 fpa ok ok -
1460 (ATM)
1461 en maybe ok -
1462 (Serial)
1463 ntwo ok ok yes
1464 sl ? - not work
1465 appp ? - not work
1466
1467You may want to use "@insert" directive in /etc/pccard.conf to invoke
1468"rtsol" command right after dynamic insertion of PCMCIA ethernet cards.
1469
14702.3 NetBSD
1471
1472The following table lists the network drivers we have tried so far.
1473
1474 driver mbuf(1) multicast(2) official support?
1475 --- --- --- ---
1476 (Ethernet)
1477 awi pcmcia/i386 ok ok -
1478 bah zbus/amiga NG(*)
1479 cnw pcmcia/i386 ok ok yes
1480 ep pcmcia/i386 ok ok -
1481 le sbus/sparc ok ok yes
1482 ne pci/i386 ok ok yes
1483 ne pcmcia/i386 ok ok yes
1484 wi pcmcia/i386 ok ok yes
1485 (ATM)
1486 en pci/i386 ok ok -
1487
1488(*) This may need some fix, but I'm not sure what arcnet interfaces assume...
1489
14902.4 FreeBSD 3.x-RELEASE
1491
1492Here is a list of FreeBSD 3.x-RELEASE drivers and its conditions:
1493
1494 driver mbuf(1) multicast(2) official support?
1495 --- --- --- ---
1496 (Ethernet)
1497 cnw ok ok -(*)
1498 ed ? ok -
1499 ep ok ok -
1500 fe ok ok yes
1501 fxp ?(**)
1502 lnc ? ok -
1503 sn ? ? -(*)
1504 wi ok ok yes
1505 xl ? ok -
1506
1507(*) These drivers are distributed with PAO as PAO3
1508 (http://www.jp.freebsd.org/PAO/).
1509(**) there are trouble reports with multicast filter initialization.
1510
1511More drivers will just simply work on KAME FreeBSD 3.x-RELEASE but have not
1512been checked yet.
1513
15142.5 FreeBSD 4.x-RELEASE
1515
1516Here is a list of FreeBSD 4.x-RELEASE drivers and its conditions:
1517
1518 driver multicast
1519 --- ---
1520 (Ethernet)
1521 lnc/vmware ok
1522
15232.6 OpenBSD 2.x
1524
1525Here is a list of OpenBSD 2.x drivers and its conditions:
1526
1527 driver mbuf(1) multicast(2) official support?
1528 --- --- --- ---
1529 (Ethernet)
1530 de pci/i386 ok ok yes
1531 fxp pci/i386 ?(*)
1532 le sbus/sparc ok ok yes
1533 ne pci/i386 ok ok yes
1534 ne pcmcia/i386 ok ok yes
1535 wi pcmcia/i386 ok ok yes
1536
1537(*) There seem to be some problem in driver, with multicast filter
1538configuration. This happens with certain revision of chipset on the card.
1539Should be fixed by now by workaround in sys/net/if.c, but still not sure.
1540
15412.7 BSD/OS 4.x
1542
1543The following lists BSD/OS 4.x device drivers and its conditions:
1544
1545 driver mbuf(1) multicast(2) official support?
1546 --- --- --- ---
1547 (Ethernet)
1548 de ok ok yes
1549 exp (*)
1550
1551You may want to use "@insert" directive in /etc/pccard.conf to invoke
1552"rtsol" command right after dynamic insertion of PCMCIA ethernet cards.
1553
1554(*) exp driver has serious conflict with KAME initialization sequence.
1555A workaround is committed into sys/i386/pci/if_exp.c, and should be okay by now.
1556
15573. Translator
1558
1559We categorize IPv4/IPv6 translator into 4 types.
1560
1561Translator A --- It is used in the early stage of transition to make
1562it possible to establish a connection from an IPv6 host in an IPv6
1563island to an IPv4 host in the IPv4 ocean.
1564
1565Translator B --- It is used in the early stage of transition to make
1566it possible to establish a connection from an IPv4 host in the IPv4
1567ocean to an IPv6 host in an IPv6 island.
1568
1569Translator C --- It is used in the late stage of transition to make it
1570possible to establish a connection from an IPv4 host in an IPv4 island
1571to an IPv6 host in the IPv6 ocean.
1572
1573Translator D --- It is used in the late stage of transition to make it
1574possible to establish a connection from an IPv6 host in the IPv6 ocean
1575to an IPv4 host in an IPv4 island.
1576
1577KAME provides an TCP relay translator for category A. This is called
1578"FAITH". We also provide IP header translator for category A.
1579
15803.1 FAITH TCP relay translator
1581
1582FAITH system uses TCP relay daemon called "faithd" helped by the KAME kernel.
1583FAITH will reserve an IPv6 address prefix, and relay TCP connection
1584toward that prefix to IPv4 destination.
1585
1586For example, if the reserved IPv6 prefix is 3ffe:0501:0200:ffff::, and
1587the IPv6 destination for TCP connection is 3ffe:0501:0200:ffff::163.221.202.12,
1588the connection will be relayed toward IPv4 destination 163.221.202.12.
1589
1590 destination IPv4 node (163.221.202.12)
1591 ^
1592 | IPv4 tcp toward 163.221.202.12
1593 FAITH-relay dual stack node
1594 ^
1595 | IPv6 TCP toward 3ffe:0501:0200:ffff::163.221.202.12
1596 source IPv6 node
1597
1598faithd must be invoked on FAITH-relay dual stack node.
1599
1600For more details, consult kame/kame/faithd/README and
1601draft-ietf-ngtrans-tcpudp-relay-04.txt.
1602
16033.2 IPv6-to-IPv4 header translator
1604
1605(to be written)
1606
16074. IPsec
1608
1609IPsec is implemented as the following three components.
1610
1611(1) Policy Management
1612(2) Key Management
1613(3) AH, ESP and IPComp handling in kernel
1614
1615Note that KAME/OpenBSD does NOT include support for KAME IPsec code,
1616as OpenBSD team has their home-brew IPsec stack and they have no plan
1617to replace it. IPv6 support for IPsec is, therefore, lacking on KAME/OpenBSD.
1618
1619http://www.netbsd.org/Documentation/network/ipsec/ has more information
1620including usage examples.
1621
16224.1 Policy Management
1623
|
1573The kernel implements experimental policy management code. There are two way
| 1624The kernel implements experimental policy management code. There are two ways
|
1574to manage security policy. One is to configure per-socket policy using
1575setsockopt(3). In this cases, policy configuration is described in
1576ipsec_set_policy(3). The other is to configure kernel packet filter-based
1577policy using PF_KEY interface, via setkey(8).
1578
1579The policy entry will be matched in order. The order of entries makes
1580difference in behavior.
1581
15824.2 Key Management
1583
1584The key management code implemented in this kit (sys/netkey) is a
1585home-brew PFKEY v2 implementation. This conforms to RFC2367.
1586
1587The home-brew IKE daemon, "racoon" is included in the kit (kame/kame/racoon,
1588or usr.sbin/racoon).
1589Basically you'll need to run racoon as daemon, then setup a policy
1590to require keys (like ping -P 'out ipsec esp/transport//use').
1591The kernel will contact racoon daemon as necessary to exchange keys.
1592
1593In IKE spec, there's ambiguity about interpretation of "tunnel" proposal.
1594For example, if we would like to propose the use of following packet:
1595 IP AH ESP IP payload
1596some implementation proposes it as "AH transport and ESP tunnel", since
1597this is more logical from packet construction point of view. Some
1598implementation proposes it as "AH tunnel and ESP tunnel".
| 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
16334.2 Key Management
1634
1635The key management code implemented in this kit (sys/netkey) is a
1636home-brew PFKEY v2 implementation. This conforms to RFC2367.
1637
1638The home-brew IKE daemon, "racoon" is included in the kit (kame/kame/racoon,
1639or usr.sbin/racoon).
1640Basically you'll need to run racoon as daemon, then setup a policy
1641to require keys (like ping -P 'out ipsec esp/transport//use').
1642The kernel will contact racoon daemon as necessary to exchange keys.
1643
1644In IKE spec, there's ambiguity about interpretation of "tunnel" proposal.
1645For example, if we would like to propose the use of following packet:
1646 IP AH ESP IP payload
1647some implementation proposes it as "AH transport and ESP tunnel", since
1648this is more logical from packet construction point of view. Some
1649implementation proposes it as "AH tunnel and ESP tunnel".
|
1599Racoon follows the former route.
| 1650Racoon follows the latter route (previously it followed the former, and
1651the latter interpretation seems to be popular/consensus).
|
1600This raises real interoperability issue. We hope this to be resolved quickly.
1601
| 1652This raises real interoperability issue. We hope this to be resolved quickly.
1653
|
| 1654racoon does not implement byte lifetime for both phase 1 and phase 2
1655(RFC2409 page 35, Life Type = kilobytes).
1656
|
16024.3 AH and ESP handling
1603
1604IPsec module is implemented as "hooks" to the standard IPv4/IPv6
1605processing. When sending a packet, ip{,6}_output() checks if ESP/AH
1606processing is required by checking if a matching SPD (Security
1607Policy Database) is found. If ESP/AH is needed,
1608{esp,ah}{4,6}_output() will be called and mbuf will be updated
1609accordingly. When a packet is received, {esp,ah}4_input() will be
1610called based on protocol number, i.e. (*inetsw[proto])().
1611{esp,ah}4_input() will decrypt/check authenticity of the packet,
1612and strips off daisy-chained header and padding for ESP/AH. It is
1613safe to strip off the ESP/AH header on packet reception, since we
1614will never use the received packet in "as is" form.
1615
1616By using ESP/AH, TCP4/6 effective data segment size will be affected by
1617extra daisy-chained headers inserted by ESP/AH. Our code takes care of
1618the case.
1619
1620Basic crypto functions can be found in directory "sys/crypto". ESP/AH
1621transform are listed in {esp,ah}_core.c with wrapper functions. If you
1622wish to add some algorithm, add wrapper function in {esp,ah}_core.c, and
1623add your crypto algorithm code into sys/crypto.
1624
1625Tunnel mode works basically fine, but comes with the following restrictions:
1626- You cannot run routing daemon across IPsec tunnel, since we do not model
1627 IPsec tunnel as pseudo interfaces.
1628- Authentication model for AH tunnel must be revisited. We'll need to
1629 improve the policy management engine, eventually.
1630- Path MTU discovery does not work across IPv6 IPsec tunnel gateway due to
1631 insufficient code.
1632
1633AH specificaton does not talk much about "multiple AH on a packet" case.
1634We incrementally compute AH checksum, from inside to outside. Also, we
1635treat inner AH to be immutable.
1636For example, if we are to create the following packet:
1637 IP AH1 AH2 AH3 payload
1638we do it incrementally. As a result, we get crypto checksums like below:
1639 AH3 has checksum against "IP AH3' payload".
1640 where AH3' = AH3 with checksum field filled with 0.
1641 AH2 has checksum against "IP AH2' AH3 payload".
1642 AH1 has checksum against "IP AH1' AH2 AH3 payload",
1643Also note that AH3 has the smallest sequence number, and AH1 has the largest
1644sequence number.
1645
1646To avoid traffic analysis on shorter packets, ESP output logic supports
1647random length padding. By setting net.inet.ipsec.esp_randpad (or
1648net.inet6.ipsec6.esp_randpad) to positive value N, you can ask the kernel
1649to randomly pad packets shorter than N bytes, to random length smaller than
1650or equal to N. Note that N does not include ESP authentication data length.
1651Also note that the random padding is not included in TCP segment
1652size computation. Negative value will turn off the functionality.
1653Recommeded value for N is like 128, or 256. If you use a too big number
1654as N, you may experience inefficiency due to fragmented packtes.
1655
16564.4 IPComp handling
1657
1658IPComp stands for IP payload compression protocol. This is aimed for
1659payload compression, not the header compression like PPP VJ compression.
1660This may be useful when you are using slow serial link (say, cell phone)
1661with powerful CPU (well, recent notebook PCs are really powerful...).
1662The protocol design of IPComp is very similar to IPsec, though it was
1663defined separately from IPsec itself.
1664
1665Here are some points to be noted:
1666- IPComp is treated as part of IPsec protocol suite, and SPI and
1667 CPI space is unified. Spec says that there's no relationship
1668 between two so they are assumed to be separate in specs.
1669- IPComp association (IPCA) is kept in SAD.
1670- It is possible to use well-known CPI (CPI=2 for DEFLATE for example),
1671 for outbound/inbound packet, but for indexing purposes one element from
1672 SPI/CPI space will be occupied anyway.
1673- pfkey is modified to support IPComp. However, there's no official
1674 SA type number assignment yet. Portability with other IPComp
1675 stack is questionable (anyway, who else implement IPComp on UN*X?).
1676- Spec says that IPComp output processing must be performed before AH/ESP
1677 output processing, to achieve better compression ratio and "stir" data
1678 stream before encryption. The most meaningful processing order is:
1679 (1) compress payload by IPComp, (2) encrypt payload by ESP, then (3) attach
1680 authentication data by AH.
1681 However, with manual SPD setting, you are able to violate the ordering
1682 (KAME code is too generic, maybe). Also, it is just okay to use IPComp
1683 alone, without AH/ESP.
1684- Though the packet size can be significantly decreased by using IPComp, no
1685 special consideration is made about path MTU (spec talks nothing about MTU
1686 consideration). IPComp is designed for serial links, not ethernet-like
1687 medium, it seems.
1688- You can change compression ratio on outbound packet, by changing
1689 deflate_policy in sys/netinet6/ipcomp_core.c. You can also change outbound
1690 history buffer size by changing deflate_window_out in the same source code.
1691 (should it be sysctl accessible, or per-SAD configurable?)
1692- Tunnel mode IPComp is not working right. KAME box can generate tunnelled
1693 IPComp packet, however, cannot accept tunneled IPComp packet.
1694- You can negotiate IPComp association with racoon IKE daemon.
1695- KAME code does not attach Adler32 checksum to compressed data.
1696 see ipsec wg mailing list discussion in Jan 2000 for details.
1697
16984.5 Conformance to RFCs and IDs
1699
1700The IPsec code in the kernel conforms (or, tries to conform) to the
1701following standards:
1702 "old IPsec" specification documented in rfc182[5-9].txt
1703 "new IPsec" specification documented in:
| 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
1665called based on protocol number, i.e. (*inetsw[proto])().
1666{esp,ah}4_input() will decrypt/check authenticity of the packet,
1667and strips off daisy-chained header and padding for ESP/AH. It is
1668safe to strip off the ESP/AH header on packet reception, since we
1669will never use the received packet in "as is" form.
1670
1671By using ESP/AH, TCP4/6 effective data segment size will be affected by
1672extra daisy-chained headers inserted by ESP/AH. Our code takes care of
1673the case.
1674
1675Basic crypto functions can be found in directory "sys/crypto". ESP/AH
1676transform are listed in {esp,ah}_core.c with wrapper functions. If you
1677wish to add some algorithm, add wrapper function in {esp,ah}_core.c, and
1678add your crypto algorithm code into sys/crypto.
1679
1680Tunnel mode works basically fine, but comes with the following restrictions:
1681- You cannot run routing daemon across IPsec tunnel, since we do not model
1682 IPsec tunnel as pseudo interfaces.
1683- Authentication model for AH tunnel must be revisited. We'll need to
1684 improve the policy management engine, eventually.
1685- Path MTU discovery does not work across IPv6 IPsec tunnel gateway due to
1686 insufficient code.
1687
1688AH specificaton does not talk much about "multiple AH on a packet" case.
1689We incrementally compute AH checksum, from inside to outside. Also, we
1690treat inner AH to be immutable.
1691For example, if we are to create the following packet:
1692 IP AH1 AH2 AH3 payload
1693we do it incrementally. As a result, we get crypto checksums like below:
1694 AH3 has checksum against "IP AH3' payload".
1695 where AH3' = AH3 with checksum field filled with 0.
1696 AH2 has checksum against "IP AH2' AH3 payload".
1697 AH1 has checksum against "IP AH1' AH2 AH3 payload",
1698Also note that AH3 has the smallest sequence number, and AH1 has the largest
1699sequence number.
1700
1701To avoid traffic analysis on shorter packets, ESP output logic supports
1702random length padding. By setting net.inet.ipsec.esp_randpad (or
1703net.inet6.ipsec6.esp_randpad) to positive value N, you can ask the kernel
1704to randomly pad packets shorter than N bytes, to random length smaller than
1705or equal to N. Note that N does not include ESP authentication data length.
1706Also note that the random padding is not included in TCP segment
1707size computation. Negative value will turn off the functionality.
1708Recommeded value for N is like 128, or 256. If you use a too big number
1709as N, you may experience inefficiency due to fragmented packtes.
1710
17114.4 IPComp handling
1712
1713IPComp stands for IP payload compression protocol. This is aimed for
1714payload compression, not the header compression like PPP VJ compression.
1715This may be useful when you are using slow serial link (say, cell phone)
1716with powerful CPU (well, recent notebook PCs are really powerful...).
1717The protocol design of IPComp is very similar to IPsec, though it was
1718defined separately from IPsec itself.
1719
1720Here are some points to be noted:
1721- IPComp is treated as part of IPsec protocol suite, and SPI and
1722 CPI space is unified. Spec says that there's no relationship
1723 between two so they are assumed to be separate in specs.
1724- IPComp association (IPCA) is kept in SAD.
1725- It is possible to use well-known CPI (CPI=2 for DEFLATE for example),
1726 for outbound/inbound packet, but for indexing purposes one element from
1727 SPI/CPI space will be occupied anyway.
1728- pfkey is modified to support IPComp. However, there's no official
1729 SA type number assignment yet. Portability with other IPComp
1730 stack is questionable (anyway, who else implement IPComp on UN*X?).
1731- Spec says that IPComp output processing must be performed before AH/ESP
1732 output processing, to achieve better compression ratio and "stir" data
1733 stream before encryption. The most meaningful processing order is:
1734 (1) compress payload by IPComp, (2) encrypt payload by ESP, then (3) attach
1735 authentication data by AH.
1736 However, with manual SPD setting, you are able to violate the ordering
1737 (KAME code is too generic, maybe). Also, it is just okay to use IPComp
1738 alone, without AH/ESP.
1739- Though the packet size can be significantly decreased by using IPComp, no
1740 special consideration is made about path MTU (spec talks nothing about MTU
1741 consideration). IPComp is designed for serial links, not ethernet-like
1742 medium, it seems.
1743- You can change compression ratio on outbound packet, by changing
1744 deflate_policy in sys/netinet6/ipcomp_core.c. You can also change outbound
1745 history buffer size by changing deflate_window_out in the same source code.
1746 (should it be sysctl accessible, or per-SAD configurable?)
1747- Tunnel mode IPComp is not working right. KAME box can generate tunnelled
1748 IPComp packet, however, cannot accept tunneled IPComp packet.
1749- You can negotiate IPComp association with racoon IKE daemon.
1750- KAME code does not attach Adler32 checksum to compressed data.
1751 see ipsec wg mailing list discussion in Jan 2000 for details.
1752
17534.5 Conformance to RFCs and IDs
1754
1755The IPsec code in the kernel conforms (or, tries to conform) to the
1756following standards:
1757 "old IPsec" specification documented in rfc182[5-9].txt
1758 "new IPsec" specification documented in:
|
1704 rfc240[1-6].txt rfc241[01].txt rfc2451.txt
1705 draft-mcdonald-simple-ipsec-api-01.txt
1706 (expired, available in ftp://ftp.kame.net/pub/internet-drafts/)
1707 draft-ietf-ipsec-ciph-aes-cbc-00.txt
| 1759 rfc240[1-6].txt rfc241[01].txt rfc2451.txt rfc3602.txt
|
1708 IPComp:
1709 RFC2393: IP Payload Compression Protocol (IPComp)
1710IKE specifications (rfc240[7-9].txt) are implemented in userland
1711as "racoon" IKE daemon.
1712
1713Currently supported algorithms are:
1714 old IPsec AH
1715 null crypto checksum (no document, just for debugging)
1716 keyed MD5 with 128bit crypto checksum (rfc1828.txt)
1717 keyed SHA1 with 128bit crypto checksum (no document)
1718 HMAC MD5 with 128bit crypto checksum (rfc2085.txt)
1719 HMAC SHA1 with 128bit crypto checksum (no document)
1720 HMAC RIPEMD160 with 128bit crypto checksum (no document)
1721 old IPsec ESP
1722 null encryption (no document, similar to rfc2410.txt)
1723 DES-CBC mode (rfc1829.txt)
1724 new IPsec AH
1725 null crypto checksum (no document, just for debugging)
1726 keyed MD5 with 96bit crypto checksum (no document)
1727 keyed SHA1 with 96bit crypto checksum (no document)
1728 HMAC MD5 with 96bit crypto checksum (rfc2403.txt
1729 HMAC SHA1 with 96bit crypto checksum (rfc2404.txt)
1730 HMAC SHA2-256 with 96bit crypto checksum (no document)
1731 HMAC SHA2-384 with 96bit crypto checksum (no document)
1732 HMAC SHA2-512 with 96bit crypto checksum (no document)
1733 HMAC RIPEMD160 with 96bit crypto checksum (RFC2857)
1734 AES XCBC MAC with 96bit crypto checksum (RFC3566)
1735 new IPsec ESP
1736 null encryption (rfc2410.txt)
1737 DES-CBC with derived IV
1738 (draft-ietf-ipsec-ciph-des-derived-01.txt, draft expired)
1739 DES-CBC with explicit IV (rfc2405.txt)
1740 3DES-CBC with explicit IV (rfc2451.txt)
1741 BLOWFISH CBC (rfc2451.txt)
1742 CAST128 CBC (rfc2451.txt)
1743 RIJNDAEL/AES CBC (rfc3602.txt)
1744 AES counter mode (draft-ietf-ipsec-ciph-aes-ctr-03.txt)
1745
1746 each of the above can be combined with:
1747 ESP authentication with HMAC-MD5(96bit)
1748 ESP authentication with HMAC-SHA1(96bit)
1749 IPComp
1750 RFC2394: IP Payload Compression Using DEFLATE
1751
1752The following algorithms are NOT supported:
1753 old IPsec AH
1754 HMAC MD5 with 128bit crypto checksum + 64bit replay prevention
1755 (rfc2085.txt)
1756 keyed SHA1 with 160bit crypto checksum + 32bit padding (rfc1852.txt)
1757
1758The key/policy management API is based on the following document, with fair
1759amount of extensions:
1760 RFC2367: PF_KEY key management API
1761
17624.6 ECN consideration on IPsec tunnels
1763
1764KAME IPsec implements ECN-friendly IPsec tunnel, described in
1765draft-ietf-ipsec-ecn-02.txt.
1766Normal IPsec tunnel is described in RFC2401. On encapsulation,
1767IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner
1768IP header to outer IP header. On decapsulation outer IP header
1769will be simply dropped. The decapsulation rule is not compatible
1770with ECN, since ECN bit on the outer IP TOS/traffic class field will be
1771lost.
1772To make IPsec tunnel ECN-friendly, we should modify encapsulation
1773and decapsulation procedure. This is described in
1774draft-ietf-ipsec-ecn-02.txt, chapter 3.3.
1775
1776KAME IPsec tunnel implementation can give you three behaviors, by setting
1777net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some value:
1778- RFC2401: no consideration for ECN (sysctl value -1)
1779- ECN forbidden (sysctl value 0)
1780- ECN allowed (sysctl value 1)
1781Note that the behavior is configurable in per-node manner, not per-SA manner
1782(draft-ietf-ipsec-ecn-02 wants per-SA configuration, but it looks too much
1783for me).
1784
1785The behavior is summarized as follows (see source code for more detail):
1786
1787 encapsulate decapsulate
1788 --- ---
1789RFC2401 copy all TOS bits drop TOS bits on outer
1790 from inner to outer. (use inner TOS bits as is)
1791
1792ECN forbidden copy TOS bits except for ECN drop TOS bits on outer
1793 (masked with 0xfc) from inner (use inner TOS bits as is)
1794 to outer. set ECN bits to 0.
1795
1796ECN allowed copy TOS bits except for ECN use inner TOS bits with some
1797 CE (masked with 0xfe) from change. if outer ECN CE bit
1798 inner to outer. is 1, enable ECN CE bit on
1799 set ECN CE bit to 0. the inner.
1800
1801General strategy for configuration is as follows:
1802- if both IPsec tunnel endpoint are capable of ECN-friendly behavior,
1803 you'd better configure both end to "ECN allowed" (sysctl value 1).
1804- if the other end is very strict about TOS bit, use "RFC2401"
1805 (sysctl value -1).
1806- in other cases, use "ECN forbidden" (sysctl value 0).
1807The default behavior is "ECN forbidden" (sysctl value 0).
1808
1809For more information, please refer to:
1810 draft-ietf-ipsec-ecn-02.txt
1811 RFC2481 (Explicit Congestion Notification)
1812 KAME sys/netinet6/{ah,esp}_input.c
1813
1814(Thanks goes to Kenjiro Cho <kjc@csl.sony.co.jp> for detailed analysis)
1815
18164.7 Interoperability
1817
1818IPsec, IPComp (in kernel) and IKE (in userland as "racoon") has been tested
1819at several interoperability test events, and it is known to interoperate
1820with many other implementations well. Also, KAME IPsec has quite wide
1821coverage for IPsec crypto algorithms documented in RFC (we do not cover
1822algorithms with intellectual property issues, though).
1823
1824Here are (some of) platforms we have tested IPsec/IKE interoperability
1825in the past, no particular order. Note that both ends (KAME and
1826others) may have modified their implementation, so use the following
1827list just for reference purposes.
1828 ACC, allied-telesis, Altiga, Ashley-laurent (vpcom.com), BlueSteel,
1829 CISCO IOS, Cryptek, Checkpoint FW-1, Data Fellows (F-Secure),
1830 Ericsson, Fitel, FreeS/WAN, HiFn, HITACHI, IBM AIX, IIJ, Intel Canada,
1831 Intel Packet Protect, MEW NetCocoon, MGCS, Microsoft WinNT/2000,
1832 NAI PGPnet, NetLock, NIST (linux IPsec + plutoplus), NEC IX5000,
1833 Netscreen, NxNetworks, OpenBSD isakmpd, Pivotal, Radguard, RapidStream,
1834 RedCreek, Routerware, RSA, SSH (both IPv4/IPv6), Secure Computing,
1835 Soliton, Sun Solaris8, TIS/NAI Gauntret, Toshiba, VPNet,
1836 Yamaha RT series
1837
1838Here are (some of) platforms we have tested IPComp/IKE interoperability
1839in the past, in no particular order.
1840 IRE, SSH (both IPv4/IPv6), NetLock
1841
1842VPNC (vpnc.org) provides IPsec conformance tests, using KAME and OpenBSD
1843IPsec/IKE implementations. Their test results are available at
1844http://www.vpnc.org/conformance.html, and it may give you more idea
1845about which implementation interoperates with KAME IPsec/IKE implementation.
1846
| 1760 IPComp:
1761 RFC2393: IP Payload Compression Protocol (IPComp)
1762IKE specifications (rfc240[7-9].txt) are implemented in userland
1763as "racoon" IKE daemon.
1764
1765Currently supported algorithms are:
1766 old IPsec AH
1767 null crypto checksum (no document, just for debugging)
1768 keyed MD5 with 128bit crypto checksum (rfc1828.txt)
1769 keyed SHA1 with 128bit crypto checksum (no document)
1770 HMAC MD5 with 128bit crypto checksum (rfc2085.txt)
1771 HMAC SHA1 with 128bit crypto checksum (no document)
1772 HMAC RIPEMD160 with 128bit crypto checksum (no document)
1773 old IPsec ESP
1774 null encryption (no document, similar to rfc2410.txt)
1775 DES-CBC mode (rfc1829.txt)
1776 new IPsec AH
1777 null crypto checksum (no document, just for debugging)
1778 keyed MD5 with 96bit crypto checksum (no document)
1779 keyed SHA1 with 96bit crypto checksum (no document)
1780 HMAC MD5 with 96bit crypto checksum (rfc2403.txt
1781 HMAC SHA1 with 96bit crypto checksum (rfc2404.txt)
1782 HMAC SHA2-256 with 96bit crypto checksum (no document)
1783 HMAC SHA2-384 with 96bit crypto checksum (no document)
1784 HMAC SHA2-512 with 96bit crypto checksum (no document)
1785 HMAC RIPEMD160 with 96bit crypto checksum (RFC2857)
1786 AES XCBC MAC with 96bit crypto checksum (RFC3566)
1787 new IPsec ESP
1788 null encryption (rfc2410.txt)
1789 DES-CBC with derived IV
1790 (draft-ietf-ipsec-ciph-des-derived-01.txt, draft expired)
1791 DES-CBC with explicit IV (rfc2405.txt)
1792 3DES-CBC with explicit IV (rfc2451.txt)
1793 BLOWFISH CBC (rfc2451.txt)
1794 CAST128 CBC (rfc2451.txt)
1795 RIJNDAEL/AES CBC (rfc3602.txt)
1796 AES counter mode (draft-ietf-ipsec-ciph-aes-ctr-03.txt)
1797
1798 each of the above can be combined with:
1799 ESP authentication with HMAC-MD5(96bit)
1800 ESP authentication with HMAC-SHA1(96bit)
1801 IPComp
1802 RFC2394: IP Payload Compression Using DEFLATE
1803
1804The following algorithms are NOT supported:
1805 old IPsec AH
1806 HMAC MD5 with 128bit crypto checksum + 64bit replay prevention
1807 (rfc2085.txt)
1808 keyed SHA1 with 160bit crypto checksum + 32bit padding (rfc1852.txt)
1809
1810The key/policy management API is based on the following document, with fair
1811amount of extensions:
1812 RFC2367: PF_KEY key management API
1813
18144.6 ECN consideration on IPsec tunnels
1815
1816KAME IPsec implements ECN-friendly IPsec tunnel, described in
1817draft-ietf-ipsec-ecn-02.txt.
1818Normal IPsec tunnel is described in RFC2401. On encapsulation,
1819IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner
1820IP header to outer IP header. On decapsulation outer IP header
1821will be simply dropped. The decapsulation rule is not compatible
1822with ECN, since ECN bit on the outer IP TOS/traffic class field will be
1823lost.
1824To make IPsec tunnel ECN-friendly, we should modify encapsulation
1825and decapsulation procedure. This is described in
1826draft-ietf-ipsec-ecn-02.txt, chapter 3.3.
1827
1828KAME IPsec tunnel implementation can give you three behaviors, by setting
1829net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some value:
1830- RFC2401: no consideration for ECN (sysctl value -1)
1831- ECN forbidden (sysctl value 0)
1832- ECN allowed (sysctl value 1)
1833Note that the behavior is configurable in per-node manner, not per-SA manner
1834(draft-ietf-ipsec-ecn-02 wants per-SA configuration, but it looks too much
1835for me).
1836
1837The behavior is summarized as follows (see source code for more detail):
1838
1839 encapsulate decapsulate
1840 --- ---
1841RFC2401 copy all TOS bits drop TOS bits on outer
1842 from inner to outer. (use inner TOS bits as is)
1843
1844ECN forbidden copy TOS bits except for ECN drop TOS bits on outer
1845 (masked with 0xfc) from inner (use inner TOS bits as is)
1846 to outer. set ECN bits to 0.
1847
1848ECN allowed copy TOS bits except for ECN use inner TOS bits with some
1849 CE (masked with 0xfe) from change. if outer ECN CE bit
1850 inner to outer. is 1, enable ECN CE bit on
1851 set ECN CE bit to 0. the inner.
1852
1853General strategy for configuration is as follows:
1854- if both IPsec tunnel endpoint are capable of ECN-friendly behavior,
1855 you'd better configure both end to "ECN allowed" (sysctl value 1).
1856- if the other end is very strict about TOS bit, use "RFC2401"
1857 (sysctl value -1).
1858- in other cases, use "ECN forbidden" (sysctl value 0).
1859The default behavior is "ECN forbidden" (sysctl value 0).
1860
1861For more information, please refer to:
1862 draft-ietf-ipsec-ecn-02.txt
1863 RFC2481 (Explicit Congestion Notification)
1864 KAME sys/netinet6/{ah,esp}_input.c
1865
1866(Thanks goes to Kenjiro Cho <kjc@csl.sony.co.jp> for detailed analysis)
1867
18684.7 Interoperability
1869
1870IPsec, IPComp (in kernel) and IKE (in userland as "racoon") has been tested
1871at several interoperability test events, and it is known to interoperate
1872with many other implementations well. Also, KAME IPsec has quite wide
1873coverage for IPsec crypto algorithms documented in RFC (we do not cover
1874algorithms with intellectual property issues, though).
1875
1876Here are (some of) platforms we have tested IPsec/IKE interoperability
1877in the past, no particular order. Note that both ends (KAME and
1878others) may have modified their implementation, so use the following
1879list just for reference purposes.
1880 ACC, allied-telesis, Altiga, Ashley-laurent (vpcom.com), BlueSteel,
1881 CISCO IOS, Cryptek, Checkpoint FW-1, Data Fellows (F-Secure),
1882 Ericsson, Fitel, FreeS/WAN, HiFn, HITACHI, IBM AIX, IIJ, Intel Canada,
1883 Intel Packet Protect, MEW NetCocoon, MGCS, Microsoft WinNT/2000,
1884 NAI PGPnet, NetLock, NIST (linux IPsec + plutoplus), NEC IX5000,
1885 Netscreen, NxNetworks, OpenBSD isakmpd, Pivotal, Radguard, RapidStream,
1886 RedCreek, Routerware, RSA, SSH (both IPv4/IPv6), Secure Computing,
1887 Soliton, Sun Solaris8, TIS/NAI Gauntret, Toshiba, VPNet,
1888 Yamaha RT series
1889
1890Here are (some of) platforms we have tested IPComp/IKE interoperability
1891in the past, in no particular order.
1892 IRE, SSH (both IPv4/IPv6), NetLock
1893
1894VPNC (vpnc.org) provides IPsec conformance tests, using KAME and OpenBSD
1895IPsec/IKE implementations. Their test results are available at
1896http://www.vpnc.org/conformance.html, and it may give you more idea
1897about which implementation interoperates with KAME IPsec/IKE implementation.
1898
|
| 18994.8 Operations with IPsec tunnel mode
1900
1901First of all, IPsec tunnel is a very hairy thing. It seems to do a neat thing
1902like VPN configuration or secure remote accesses, however, it comes with lots
1903of architectural twists.
1904
1905RFC2401 defines IPsec tunnel mode, within the context of IPsec. RFC2401
1906defines tunnel mode packet encapsulation/decapsulation on its own, and
1907does not refer other tunnelling specifications. Since RFC2401 advocates
1908filter-based SPD database matches, it would be natural for us to implement
1909IPsec IPsec tunnel mode as filters - not as pseudo interfaces.
1910
1911There are some people who are trying to separate IPsec "tunnel mode" from
1912the IPsec itself. They would like to implement IPsec transport mode only,
1913and combine it with tunneling pseudo devices. The prime example is found
1914in draft-touch-ipsec-vpn-01.txt. However, if you really define pseudo
1915interfaces separately from IPsec, IKE daemons would need to negotiate
1916transport mode SAs, instead of tunnel mode SAs. Therefore, we cannot
1917really mix RFC2401-based interpretation and draft-touch-ipsec-vpn-01.txt
1918interpretation.
1919
1920The KAME stack implements can be configured in two ways. You may need
1921to recompile your kernel to switch the behavior.
1922- RFC2401 IPsec tunnel mode appraoch (4.8.1)
1923- draft-touch-ipsec-vpn approach (4.8.2)
1924 Works in all kernel configuration, but racoon(8) may not interoperate.
1925
1926There are pros and cons on these approaches:
1927
1928RFC2401 IPsec tunnel mode (filter-like) approach
1929 PRO: SPD lookup fits nicely with packet filters (if you integrate them)
1930 CON: cannot run routing daemons across IPsec tunnels
1931 CON: it is very hard to control source address selection on originating
1932 cases
1933 ???: IPv6 scope zone is kept the same
1934draft-touch-ipsec-vpn (transportmode + Pseudo-interface) approach
1935 PRO: run routing daemons across IPsec tunnels
1936 PRO: source address selection can be done normally, by looking at
1937 IPsec tunnel pseudo devices
1938 CON: on outbound, possibility of infinite loops if routing setup
1939 is wrong
1940 CON: due to differences in encap/decap logic from RFC2401, it may not
1941 interoperate with very picky RFC2401 implementations
1942 (those who check TOS bits, for example)
1943 CON: cannot negotiate IKE with other IPsec tunnel-mode devices
1944 (the other end has to implement
1945 ???: IPv6 scope zone is likely to be different from the real ethernet
1946 interface
1947
1948The recommendation is different depending on the situation you have:
1949- use draft-touch-ipsec-vpn if you have the control over the other end.
1950 this one is the best in terms of simplicity.
1951- if the other end is normal IPsec device with RFC2401 implementation,
1952 you need to use RFC2401, otherwise you won't be able to run IKE.
1953- use RFC2401 approach if you just want to forward packets back and forth
1954 and there's no plan to use IPsec gateway itself as an originating device.
1955
19564.8.1 RFC2401 IPsec tunnel mode approach
1957
1958To configure your device as RFC2401 IPsec tunnel mode endpoint, you will
1959use "tunnel" keyword in setkey(8) "spdadd" directives. Let us assume the
1960following topology (A and B could be a network, like prefix/length):
1961
1962 ((((((((((((The internet))))))))))))
1963 | |
1964 |C (global) |D
1965 your device peer's device
1966 |A (private) |B
1967 ==+===== VPN net ==+===== VPN net
1968
1969The policy configuration directive is like this. You will need manual
1970SAs, or IKE daemon, for actual encryption:
1971
1972 # setkey -c <<EOF
1973 spdadd A B any -P out ipsec esp/tunnel/C-D/use;
1974 spdadd B A any -P in ipsec esp/tunnel/D-C/use;
1975 ^D
1976
1977The inbound/outbound traffic is monitored/captured by SPD engine, which works
1978just like packet filters.
1979
1980With this, forwarding case should work flawlessly. However, troubles arise
1981when you have one of the following requirements:
1982- When you originate traffic from your VPN gateway device to VPN net on the
1983 other end (like B), you want your source address to be A (private side)
1984 so that the traffic would be protected by the policy.
1985 With this approach, however, the source address selection logic follows
1986 normal routing table, and C (global side) will be picked for any outgoing
1987 traffic, even if the destination is B. The resulting packet will be like
1988 this:
1989 IP[C -> B] payload
1990 and will not match the policy (= sent in clear).
1991- When you want to run routing protocols on top of the IPsec tunnel, it is
1992 not possible. As there is no pseudo device that identifies the IPsec tunnel,
1993 you cannot identify where the routing information came from. As a result,
1994 you can't run routing daemons.
1995
19964.8.2 draft-touch-ipsec-vpn approach
1997
1998With this approach, you will configure gif(4) tunnel interfaces, as well as
1999IPsec transport mode SAs.
2000
2001 # gifconfig gif0 C D
2002 # ifconfig gif0 A B
2003 # setkey -c <<EOF
2004 spdadd C D any -P out ipsec esp/transport//use;
2005 spdadd D C any -P in ipsec esp/transport//use;
2006 ^D
2007
2008Since we have a pseudo-interface "gif0", and it affects the routes and
2009the source address selection logic, we can have source address A, for
2010packets originated by the VPN gateway to B (and the VPN cloud).
2011We can also exchange routing information over the tunnel (gif0), as the tunnel
2012is represented as a pseudo interface (dynamic routes points to the
2013pseudo interface).
2014
2015There is a big drawbacks, however; with this, you can use IKE if and only if
2016the other end is using draft-touch-ipsec-vpn approach too. Since racoon(8)
2017grabs phase 2 IKE proposals from the kernel SPD database, you will be
2018negotiating IPsec transport-mode SAs with the other end, not tunnel-mode SAs.
2019Also, since the encapsulation mechanism is different from RFC2401, you may not
2020be able to interoperate with a picky RFC2401 implementations - if the other
2021end checks certain outer IP header fields (like TOS), you will not be able to
2022interoperate.
2023
2024
|
18475. ALTQ
1848
1849KAME kit includes ALTQ 2.1 code, which supports FreeBSD2, FreeBSD3,
1850NetBSD and OpenBSD. For BSD/OS, ALTQ does not work.
1851ALTQ in KAME supports (or tries to support) IPv6.
1852(actually, ALTQ is developed on KAME repository since ALTQ 2.1 - Jan 2000)
1853
1854ALTQ occupies single character device number. For FreeBSD, it is officially
1855allocated. For OpenBSD and NetBSD, we use the number which is not
1856currently allocated (will eventually get an official number).
1857The character device is enabled for i386 architecture only. To enable and
1858compile ALTQ-ready kernel for other archititectures, take the following steps:
1859- assume that your architecture is FOOBAA.
1860- modify sys/arch/FOOBAA/FOOBAA/conf.c (or somewhere that defines cdevsw),
1861 to include a line for ALTQ. look at sys/arch/i386/i386/conf.c for
1862 example. The major number must be same as i386 case.
1863- copy kernel configuration file (like ALTQ.v6 or GENERIC.v6) from i386,
1864 and modify accordingly.
1865- build a kernel.
1866- before building userland, change netbsd/{lib,usr.sbin,usr.bin}/Makefile
1867 (or openbsd/foobaa) so that it will visit altq-related sub directories.
1868
18696. mobile-ip6
1870
18716.1 KAME node as correspondent node
1872
1873Default installation recognizes home address option (in destination
1874options header). No sub-options are supported. interaction with
1875IPsec, and/or 2292bis API, needs further study.
1876
18776.2 KAME node as home agent/mobile node
1878
1879KAME kit includes Ericsson mobile-ip6 code. The integration is just started
1880(in Feb 2000), and we will need some more time to integrate it better.
1881
1882See kame/mip6config/{QUICKSTART,README_MIP6.txt} for more details.
1883
1884The Ericsson code implements revision 09 of the mobile-ip6 draft. There
1885are other implementations available:
1886 NEC: http://www.6bone.nec.co.jp/mipv6/internal-dist/ (-13 draft)
1887 SFC: http://neo.sfc.wide.ad.jp/~mip6/ (-13 draft)
1888
18897. Coding style
1890
1891The KAME developers basically do not make a bother about coding
1892style. However, there is still some agreement on the style, in order
1893to make the distributed develoment smooth.
1894
| 20255. ALTQ
2026
2027KAME kit includes ALTQ 2.1 code, which supports FreeBSD2, FreeBSD3,
2028NetBSD and OpenBSD. For BSD/OS, ALTQ does not work.
2029ALTQ in KAME supports (or tries to support) IPv6.
2030(actually, ALTQ is developed on KAME repository since ALTQ 2.1 - Jan 2000)
2031
2032ALTQ occupies single character device number. For FreeBSD, it is officially
2033allocated. For OpenBSD and NetBSD, we use the number which is not
2034currently allocated (will eventually get an official number).
2035The character device is enabled for i386 architecture only. To enable and
2036compile ALTQ-ready kernel for other archititectures, take the following steps:
2037- assume that your architecture is FOOBAA.
2038- modify sys/arch/FOOBAA/FOOBAA/conf.c (or somewhere that defines cdevsw),
2039 to include a line for ALTQ. look at sys/arch/i386/i386/conf.c for
2040 example. The major number must be same as i386 case.
2041- copy kernel configuration file (like ALTQ.v6 or GENERIC.v6) from i386,
2042 and modify accordingly.
2043- build a kernel.
2044- before building userland, change netbsd/{lib,usr.sbin,usr.bin}/Makefile
2045 (or openbsd/foobaa) so that it will visit altq-related sub directories.
2046
20476. mobile-ip6
2048
20496.1 KAME node as correspondent node
2050
2051Default installation recognizes home address option (in destination
2052options header). No sub-options are supported. interaction with
2053IPsec, and/or 2292bis API, needs further study.
2054
20556.2 KAME node as home agent/mobile node
2056
2057KAME kit includes Ericsson mobile-ip6 code. The integration is just started
2058(in Feb 2000), and we will need some more time to integrate it better.
2059
2060See kame/mip6config/{QUICKSTART,README_MIP6.txt} for more details.
2061
2062The Ericsson code implements revision 09 of the mobile-ip6 draft. There
2063are other implementations available:
2064 NEC: http://www.6bone.nec.co.jp/mipv6/internal-dist/ (-13 draft)
2065 SFC: http://neo.sfc.wide.ad.jp/~mip6/ (-13 draft)
2066
20677. Coding style
2068
2069The KAME developers basically do not make a bother about coding
2070style. However, there is still some agreement on the style, in order
2071to make the distributed develoment smooth.
2072
|
| 2073- follow *BSD KNF where possible. note: there are multiple KNF standards.
|
1895- the tab character should be 8 columns wide (tabstops are at 8, 16, 24, ...
1896 column). With vi, use ":set ts=8 sw=8".
| 2074- the tab character should be 8 columns wide (tabstops are at 8, 16, 24, ...
2075 column). With vi, use ":set ts=8 sw=8".
|
| 2076 With GNU Emacs 20 and later, the easiest way is to use the "bsd" style of
2077 cc-mode with the variable "c-basic-offset" being 8;
2078 (add-hook 'c-mode-common-hook
2079 (function
2080 (lambda ()
2081 (c-set-style "bsd")
2082 (setq c-basic-offset 8) ; XXX for Emacs 20 only
2083 )))
2084 The "bsd" style in GNU Emacs 21 sets the variable to 8 by default,
2085 so the line marked by "XXX" is not necessary if you only use GNU
2086 Emacs 21.
|
1897- each line should be within 80 characters.
1898- keep a single open/close bracket in a comment such as in the following
1899 line:
1900 putchar('('); /* ) */
1901 without this, some vi users would have a hard time to match a pair of
1902 brackets. Although this type of bracket seems clumsy and is even
1903 harmful for some other type of vi users and Emacs users, the
1904 agreement in the KAME developers is to allow it.
1905- add the following line to the head of every KAME-derived file:
1906 /* (dollar)KAME(dollar) */
1907 where "(dollar)" is the dollar character ($), and around "$" are tabs.
| 2087- each line should be within 80 characters.
2088- keep a single open/close bracket in a comment such as in the following
2089 line:
2090 putchar('('); /* ) */
2091 without this, some vi users would have a hard time to match a pair of
2092 brackets. Although this type of bracket seems clumsy and is even
2093 harmful for some other type of vi users and Emacs users, the
2094 agreement in the KAME developers is to allow it.
2095- add the following line to the head of every KAME-derived file:
2096 /* (dollar)KAME(dollar) */
2097 where "(dollar)" is the dollar character ($), and around "$" are tabs.
|
1908 (this is for C. For other language, you should use its own comment
| 2098 (this is for C. For other language, you should use its own comment
|
1909 line.)
1910 Once commited to the CVS repository, this line will contain its
1911 version number (see, for example, at the top of this file). This
1912 would make it easy to report a bug.
1913- when creating a new file with the WIDE copyright, tap "make copyright.c" at
1914 the top-level, and use copyright.c as a template. KAME RCS tag will be
1915 included automatically.
1916- when editting a third-party package, keep its own coding style as
1917 much as possible, even if the style does not follow the items above.
| 2099 line.)
2100 Once commited to the CVS repository, this line will contain its
2101 version number (see, for example, at the top of this file). This
2102 would make it easy to report a bug.
2103- when creating a new file with the WIDE copyright, tap "make copyright.c" at
2104 the top-level, and use copyright.c as a template. KAME RCS tag will be
2105 included automatically.
2106- when editting a third-party package, keep its own coding style as
2107 much as possible, even if the style does not follow the items above.
|
| 2108- it is recommended to always wrap an expression containing
2109 bitwise operators by parentheses, especially when the expression is
2110 combined with relational operators, in order to avoid unintentional
2111 mismatch of operators. Thus, we should write
2112 if ((a & b) == 0) /* (A) */
2113 or
2114 if (a & (b == 0)) /* (B) */
2115 instead of
2116 if (a & b == 0) /* (C) */
2117 even if the programmer's intention was (C), which is equivalent to
2118 (B) according to the grammar of the language C.
2119 Thus, we should write a code to test if a bit-flag is set for a
2120 given variable as follows:
2121 if ((flag & FLAG_A) == 0) /* (D) the FLAG_A is NOT set */
2122 if ((flag & FLAG_A) != 0) /* (E) the FLAG_A is set */
2123 Some developers in the KAME project rather prefer the following style:
2124 if (!(flag & FLAG_A)) /* (F) the FLAG_A is NOT set */
2125 if ((flag & FLAG_A)) /* (G) the FLAG_A is set */
2126 because it would be more intuitive in terms of the relationship
2127 between the negation operator (!) and the semantics of the
2128 condition. The KAME developers have discussed the style, and have
2129 agreed that all the styles from (D) to (G) are valid. So, when you
2130 see styles like (D) and (E) in the KAME code and feel a bit strange,
2131 please just keep them. They are intentional.
2132- When inserting a separate block just to define some intra-block
2133 variables, add the level of indentation as if the block was in a
2134 control statement such as if-else, for, or while. For example,
2135 foo ()
2136 {
2137 int a;
|
1918
| 2138
|
| 2139 {
2140 int internal_a;
2141 ...
2142 }
2143 }
2144 should be used, instead of
2145 foo ()
2146 {
2147 int a;
2148
2149 {
2150 int internal_a;
2151 ...
2152 }
2153 }
2154- Do not use printf() or log() in the packet input path of the kernel code.
2155 They can make the system vulnerable to packet flooding attacks (results in
2156 /var overflow).
2157- (not a style issue)
2158 To disable a module that is mistakenly imported (by CVS), just
2159 remove the source tree in the repository. Note, however, that the
2160 removal might annoy other developers who have already checked the
2161 module out, so you should announce the removal as soon as possible.
2162 Also, be 100% sure not to remove other modules.
2163
|
1919When you want to contribute something to the KAME project, and if *you
1920do not mind* the agreement, it would be helpful for the project to
1921keep these rules. Note, however, that we would never intend to force
1922you to adopt our rules. We would rather regard your own style,
1923especially when you have a policy about the style.
1924
| 2164When you want to contribute something to the KAME project, and if *you
2165do not mind* the agreement, it would be helpful for the project to
2166keep these rules. Note, however, that we would never intend to force
2167you to adopt our rules. We would rather regard your own style,
2168especially when you have a policy about the style.
2169
|
| 2170
21719. Policy on technology with intellectual property right restriction
2172
2173There are quite a few IETF documents/whatever which has intellectual property
2174right (IPR) restriction. KAME's stance is stated below.
2175
2176 The goal of KAME is to provide freely redistributable, BSD-licensed,
2177 implementation of Internet protocol technologies.
2178 For this purpose, we implement protocols that (1) do not need license
2179 contract with IPR holder, and (2) are royalty-free.
2180 The reason for (1) is, even if KAME contracts with the IPR holder in
2181 question, the users of KAME stack (usually implementers of some other
2182 codebase) would need to make a license contract with the IPR holder.
2183 It would damage the "freely redistributable" status of KAME codebase.
2184
2185 By doing so KAME is (implicitly) trying to advocate no-license-contract,
2186 royalty-free, release of IPRs.
2187
2188Note however, as documented in README, we do not guarantee that KAME code
2189is free of IPR infringement, you MUST check it if you are to integrate
2190KAME into your product (or whatever):
2191 READ CAREFULLY: Several countries have legal enforcement for
2192 export/import/use of cryptographic software. Check it before playing
2193 with the kit. We do not intend to be your legalease clearing house
2194 (NO WARRANTY). If you intend to include KAME stack into your product,
2195 you'll need to check if the licenses on each file fit your situations,
2196 and/or possible intellectual property right issues.
2197
|
1925 <end of IMPLEMENTATION>
| 2198 <end of IMPLEMENTATION>
|