5 $KAME: IMPLEMENTATION,v 1.216 2001/05/25 07:43:01 jinmei Exp $
8 NOTE: The document tries to describe behaviors/implementation choices
9 of the latest KAME/*BSD stack. The description here may not be
10 applicable to KAME-integrated *BSD releases, as we have certain amount
11 of changes between them. Still, some of the content can be useful for
12 KAME-integrated *BSD releases.
18 1.2 Neighbor Discovery
21 1.3.2 Interaction with API
22 1.3.3 Interaction with users (command line)
24 1.4.1 Assignment of link-local, and special addresses
25 1.4.2 Stateless address autoconfiguration on hosts
27 1.5 Generic tunnel interface
29 1.6.1 Source Address Selection
30 1.6.2 Destination Address Ordering
32 1.8 Loop prevention in header processing
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
42 1.12.3.1 KAME/NetBSD, listening side
43 1.12.3.2 KAME/NetBSD, initiating side
45 1.12.4.1 KAME/BSDI4, listening side
46 1.12.4.2 KAME/BSDI4, initiating side
48 1.12.5.1 KAME/OpenBSD, listening side
49 1.12.5.2 KAME/OpenBSD, initiating side
51 1.12.7 Interaction with SIIT translator
53 1.14 Invalid addresses on the wire
54 1.15 Node's required addresses
60 2.1 FreeBSD 2.2.x-RELEASE
63 2.4 FreeBSD 3.x-RELEASE
64 2.5 FreeBSD 4.x-RELEASE
68 3.1 FAITH TCP relay translator
69 3.2 IPv6-to-IPv4 header translator
73 4.3 AH and ESP handling
75 4.5 Conformance to RFCs and IDs
76 4.6 ECN consideration on IPsec tunnels
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
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
87 8. Policy on technology with intellectual property right restriction
93 The KAME kit conforms, or tries to conform, to the latest set of IPv6
94 specifications. For future reference we list some of the relevant documents
95 below (NOTE: this is not a complete list - this is too hard to maintain...).
96 For details please refer to specific chapter in the document, RFCs, manpages
97 come with KAME, or comments in the source code.
99 Conformance tests have been performed on past and latest KAME STABLE kit,
100 at TAHI project. Results can be viewed at http://www.tahi.org/report/KAME/.
101 We also attended Univ. of New Hampshire IOL tests (http://www.iol.unh.edu/)
102 in the past, with our past snapshots.
104 RFC1639: FTP Operation Over Big Address Records (FOOBAR)
105 * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428,
106 then RFC1639 if failed.
107 RFC1886: DNS Extensions to support IPv6
108 RFC1933: (see RFC2893)
109 RFC1981: Path MTU Discovery for IPv6
110 RFC2080: RIPng for IPv6
111 * KAME-supplied route6d, bgpd and hroute6d support this.
112 RFC2283: Multiprotocol Extensions for BGP-4
114 * KAME-supplied bgpd supports this.
115 RFC2292: Advanced Sockets API for IPv6
117 RFC2362: Protocol Independent Multicast-Sparse Mode (PIM-SM)
118 * RFC2362 defines the packet formats and the protcol of PIM-SM.
119 RFC2373: IPv6 Addressing Architecture
120 * KAME supports node required addresses, and conforms to the scope
122 RFC2374: An IPv6 Aggregatable Global Unicast Address Format
123 * KAME supports 64-bit length of Interface ID.
124 RFC2375: IPv6 Multicast Address Assignments
125 * Userland applications use the well-known addresses assigned in the RFC.
126 RFC2428: FTP Extensions for IPv6 and NATs
127 * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428,
128 then RFC1639 if failed.
129 RFC2460: IPv6 specification
130 RFC2461: Neighbor discovery for IPv6
131 * See 1.2 in this document for details.
132 RFC2462: IPv6 Stateless Address Autoconfiguration
133 * See 1.4 in this document for details.
134 RFC2463: ICMPv6 for IPv6 specification
135 * See 1.9 in this document for details.
136 RFC2464: Transmission of IPv6 Packets over Ethernet Networks
137 RFC2465: MIB for IPv6: Textual Conventions and General Group
138 * Necessary statistics are gathered by the kernel. Actual IPv6 MIB
139 support is provided as patchkit for ucd-snmp.
140 RFC2466: MIB for IPv6: ICMPv6 group
141 * Necessary statistics are gathered by the kernel. Actual IPv6 MIB
142 support is provided as patchkit for ucd-snmp.
143 RFC2467: Transmission of IPv6 Packets over FDDI Networks
144 RFC2472: IPv6 over PPP
145 RFC2492: IPv6 over ATM Networks
146 * only PVC is supported.
147 RFC2497: Transmission of IPv6 packet over ARCnet Networks
148 RFC2545: Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing
149 RFC2553: (see RFC3493)
150 RFC2671: Extension Mechanisms for DNS (EDNS0)
151 * see USAGE for how to use it.
152 * not supported on kame/freebsd4 and kame/bsdi4.
153 RFC2673: Binary Labels in the Domain Name System
154 * KAME/bsdi4 supports A6, DNAME and binary label to some extent.
155 * KAME apps/bind8 repository has resolver library with partial A6, DNAME
156 and binary label support.
157 RFC2675: IPv6 Jumbograms
158 * See 1.7 in this document for details.
159 RFC2710: Multicast Listener Discovery for IPv6
160 RFC2711: IPv6 router alert option
161 RFC2732: Format for Literal IPv6 Addresses in URL's
162 * The spec is implemented in programs that handle URLs
163 (like freebsd ftpio(3) and fetch(1), or netbsd ftp(1))
164 RFC2874: DNS Extensions to Support IPv6 Address Aggregation and Renumbering
165 * KAME/bsdi4 supports A6, DNAME and binary label to some extent.
166 * KAME apps/bind8 repository has resolver library with partial A6, DNAME
167 and binary label support.
168 RFC2893: Transition Mechanisms for IPv6 Hosts and Routers
169 * IPv4 compatible address is not supported.
170 * automatic tunneling (4.3) is not supported.
171 * "gif" interface implements IPv[46]-over-IPv[46] tunnel in a generic way,
172 and it covers "configured tunnel" described in the spec.
173 See 1.5 in this document for details.
174 RFC2894: Router renumbering for IPv6
175 RFC3041: Privacy Extensions for Stateless Address Autoconfiguration in IPv6
176 RFC3056: Connection of IPv6 Domains via IPv4 Clouds
178 * "stf" interface implements it. Be sure to read
179 draft-itojun-ipv6-transition-abuse-01.txt
180 below before configuring it, there can be security issues.
181 RFC3142: An IPv6-to-IPv4 transport relay translator
182 * FAITH tcp relay translator (faithd) implements this. See 3.1 for more
184 RFC3152: Delegation of IP6.ARPA
185 * libinet6 resolvers contained in the KAME snaps support to use
186 the ip6.arpa domain (with the nibble format) for IPv6 reverse
188 RFC3484: Default Address Selection for IPv6
189 * the selection algorithm for both source and destination addresses
190 is implemented based on the RFC, though some rules are still omitted.
191 RFC3493: Basic Socket Interface Extensions for IPv6
192 * IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind
194 - supported and turned on by default on KAME/FreeBSD[34]
196 - supported but turned off by default on KAME/NetBSD and KAME/FreeBSD5,
197 - not supported on KAME/FreeBSD228, KAME/OpenBSD and KAME/BSDI3.
198 see 1.12 in this document for details.
199 * The AI_ALL and AI_V4MAPPED flags are not supported.
200 RFC3542: Advanced Sockets API for IPv6 (revised)
201 * For supported library functions/kernel APIs, see sys/netinet6/ADVAPI.
202 * Some of the updates in the draft are not implemented yet. See
203 TODO.2292bis for more details.
204 RFC4007: IPv6 Scoped Address Architecture
205 * some part of the documentation (especially about the routing
206 model) is not supported yet.
207 * zone indices that contain scope types have not been supported yet.
209 draft-ietf-ipngwg-icmp-name-lookups-09: IPv6 Name Lookups Through ICMP
210 draft-ietf-ipv6-router-selection-07.txt:
211 Default Router Preferences and More-Specific Routes
212 * router-side: both router preference and specific routes are supported.
213 * host-side: only router preference is supported.
214 draft-ietf-pim-sm-v2-new-02.txt
215 A revised version of RFC2362, which includes the IPv6 specific
216 packet format and protocol descriptions.
217 draft-ietf-dnsext-mdns-00.txt: Multicast DNS
218 * kame/mdnsd has test implementation, which will not be built in
219 default compilation. The draft will experience a major change in the
220 near future, so don't rely upon it.
221 draft-ietf-ipngwg-icmp-v3-02.txt: ICMPv6 for IPv6 specification (revised)
222 * See 1.9 in this document for details.
223 draft-itojun-ipv6-tcp-to-anycast-01.txt:
224 Disconnecting TCP connection toward IPv6 anycast address
225 draft-ietf-ipv6-rfc2462bis-06.txt: IPv6 Stateless Address
226 Autoconfiguration (revised)
227 draft-itojun-ipv6-transition-abuse-01.txt:
228 Possible abuse against IPv6 transition technologies (expired)
229 * KAME does not implement RFC1933/2893 automatic tunnel.
230 * "stf" interface implements some address filters. Refer to stf(4)
231 for details. Since there's no way to make 6to4 interface 100% secure,
232 we do not include "stf" interface into GENERIC.v6 compilation.
233 * kame/openbsd completely disables IPv4 mapped address support.
234 * kame/netbsd makes IPv4 mapped address support off by default.
235 * See section 1.12.6 and 1.14 for more details.
236 draft-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.
239 1.2 Neighbor Discovery
241 Our implementation of Neighbor Discovery is fairly stable. Currently
242 Address Resolution, Duplicated Address Detection, and Neighbor
243 Unreachability Detection are supported. In the near future we will be
244 adding an Unsolicited Neighbor Advertisement transmission command as
245 an administration tool.
247 Duplicated Address Detection (DAD) will be performed when an IPv6 address
248 is assigned to a network interface, or the network interface is enabled
249 (ifconfig up). It is documented in RFC2462 5.4.
250 If DAD fails, the address will be marked "duplicated" and message will be
251 generated to syslog (and usually to console). The "duplicated" mark
252 can be checked with ifconfig. It is administrators' responsibility to check
253 for and recover from DAD failures. We may try to improve failure recovery
256 A successor version of RFC2462 (called rfc2462bis) clarifies the
257 behavior when DAD fails (i.e., duplicate is detected): if the
258 duplicate address is a link-local address formed from an interface
259 identifier based on the hardware address which is supposed to be
260 uniquely assigned (e.g., EUI-64 for an Ethernet interface), IPv6
261 operation on the interface should be disabled. The KAME
262 implementation supports this as follows: if this type of duplicate is
263 detected, the kernel marks "disabled" in the ND specific data
264 structure for the interface. Every IPv6 I/O operation in the kernel
265 checks this mark, and the kernel will drop packets received on or
266 being sent to the "disabled" interface. Whether the IPv6 operation is
267 disabled or not can be confirmed by the ndp(8) command. See the man
268 page for more details.
270 DAD procedure may not be effective on certain network interfaces/drivers.
271 If a network driver needs long initialization time (with wireless network
272 interfaces this situation is popular), and the driver mistakingly raises
273 IFF_RUNNING before the driver becomes ready, DAD code will try to transmit
274 DAD probes to not-really-ready network driver and the packet will not go out
275 from the interface. In such cases, network drivers should be corrected.
277 Some of network drivers loop multicast packets back to themselves,
278 even if instructed not to do so (especially in promiscuous mode). In
279 such cases DAD may fail, because the DAD engine sees inbound NS packet
280 (actually from the node itself) and considers it as a sign of
281 duplicate. In this case, drivers should be corrected to honor
282 IFF_SIMPLEX behavior. For example, you may need to check source MAC
283 address on an inbound packet, and reject it if it is from the node
286 Neighbor Discovery specification (RFC2461) does not talk about neighbor
287 cache handling in the following cases:
288 (1) when there was no neighbor cache entry, node received unsolicited
289 RS/NS/NA/redirect packet without link-layer address
290 (2) neighbor cache handling on medium without link-layer address
291 (we need a neighbor cache entry for IsRouter bit)
292 For (1), we implemented workaround based on discussions on IETF ipngwg mailing
293 list. For more details, see the comments in the source code and email
294 thread started from (IPng 7155), dated Feb 6 1999.
296 IPv6 on-link determination rule (RFC2461) is quite different from
297 assumptions in BSD IPv4 network code. To implement the behavior in
298 RFC2461 section 6.3.6 (3), the kernel needs to know the default
299 outgoing interface. To configure the default outgoing interface, use
300 commands like "ndp -I de0" as root. Then the kernel will have a
301 "default" route to the interface with the cloning "C" bit being on.
302 This default route will cause to make a neighbor cache entry for every
303 destination that does not match an explicit route entry.
305 Note that we intentionally disable configuring the default interface
306 by default. This is because we found it sometimes caused inconvenient
307 situation while it was rarely useful in practical usage. For example,
308 consider a destination that has both IPv4 and IPv6 addresses but is
309 only reachable via IPv4. Since our getaddrinfo(3) prefers IPv6 by
310 default, an (TCP) application using the library with PF_UNSPEC first
311 tries to connect to the IPv6 address. If we turn on RFC 2461 6.3.6
312 (3), we have to wait for quite a long period before the first attempt
313 to make a connection fails. If we turn it off, the first attempt will
314 immediately fail with EHOSTUNREACH, and then the application can try
315 the next, reachable address.
317 The notion of the default interface is also disabled when the node is
318 acting as a router. The reason is that routers tend to control all
319 routes stored in the kernel and the default route automatically
320 installed would rather confuse the routers. Note that the spec misuse
321 the word "host" and "node" in several places in Section 5.2 of RFC
322 2461. We basically read the word "node" in this section as "host,"
323 and thus believe the implementation policy does not break the
326 To avoid possible DoS attacks and infinite loops, KAME stack will accept
327 only 10 options on ND packet. Therefore, if you have 20 prefix options
328 attached to RA, only the first 10 prefixes will be recognized.
329 If this troubles you, please contact the KAME team and/or modify
330 nd6_maxndopt in sys/netinet6/nd6.c. If there are high demands we may
331 provide a sysctl knob for the variable.
333 Proxy Neighbor Advertisement support is implemented in the kernel.
334 For instance, you can configure it by using the following command:
335 # ndp -s fe80::1234%ne0 0:1:2:3:4:5 proxy
336 where ne0 is the interface which attaches to the same link as the
338 There are certain limitations, though:
339 - It does not send unsolicited multicast NA on configuration. This is MAY
341 - It does not add random delay before transmission of solicited NA. This is
342 SHOULD behavior in RFC2461.
343 - We cannot configure proxy NDP for off-link address. The target address for
344 proxying must be link-local address, or must be in prefixes configured to
345 node which does proxy NDP.
346 - RFC2461 is unclear about if it is legal for a host to perform proxy ND.
347 We do not prohibit hosts from doing proxy ND, but there will be very limited
350 Starting mid March 2000, we support Neighbor Unreachability Detection
351 (NUD) on p2p interfaces, including tunnel interfaces (gif). NUD is
352 turned on by default. Before March 2000 the KAME stack did not
353 perform NUD on p2p interfaces. If the change raises any
354 interoperability issues, you can turn off/on NUD by per-interface
355 basis. Use "ndp -i interface -nud" to turn it off. Consult ndp(8)
358 RFC2461 specifies upper-layer reachability confirmation hint. Whenever
359 upper-layer reachability confirmation hint comes, ND process can use it
360 to optimize neighbor discovery process - ND process can omit real ND exchange
361 and keep the neighbor cache state in REACHABLE.
362 We currently have two sources for hints: (1) setsockopt(IPV6_REACHCONF)
363 defined by the RFC3542 API, and (2) hints from tcp(6)_input.
365 It is questionable if they are really trustworthy. For example, a
366 rogue userland program can use IPV6_REACHCONF to confuse the ND
367 process. Neighbor cache is a system-wide information pool, and it is
368 bad to allow a single process to affect others. Also, tcp(6)_input
369 can be hosed by hijack attempts. It is wrong to allow hijack attempts
370 to affect the ND process.
372 Starting June 2000, the ND code has a protection mechanism against
373 incorrect upper-layer reachability confirmation. The ND code counts
374 subsequent upper-layer hints. If the number of hints reaches the
375 maximum, the ND code will ignore further upper-layer hints and run
376 real ND process to confirm reachability to the peer. sysctl
377 net.inet6.icmp6.nd6_maxnudhint defines the maximum # of subsequent
378 upper-layer hints to be accepted.
379 (from April 2000 to June 2000, we rejected setsockopt(IPV6_REACHCONF) from
380 non-root process - after a local discussion, it looks that hints are not
381 that trustworthy even if they are from privileged processes)
383 If inbound ND packets carry invalid values, the KAME kernel will
384 drop these packet and increment statistics variable. See
385 "netstat -sn", icmp6 section. For detailed debugging session, you can
386 turn on syslog output from the kernel on errors, by turning on sysctl MIB
387 net.inet6.icmp6.nd6_debug. nd6_debug can be turned on at bootstrap
388 time, by defining ND6_DEBUG kernel compilation option (so you can
389 debug behavior during bootstrap). nd6_debug configuration should
390 only be used for test/debug purposes - for a production environment,
391 nd6_debug must be set to 0. If you leave it to 1, malicious parties
392 can inject broken packet and fill up /var/log partition.
396 IPv6 uses scoped addresses. It is therefore very important to
397 specify the scope zone index (link index for a link-local address, or
398 site index for a site-local address) with an IPv6 address. Without a
399 zone index, a scoped IPv6 address is ambiguous to the kernel, and
400 the kernel would not be able to determine the outbound zone for a
401 packet to the scoped address. KAME code tries to address the issue in
404 The entire architecture of scoped addresses is documented in RFC4007.
405 One non-trivial point of the architecture is that the link scope is
406 (theoretically) larger than the interface scope. That is, two
407 different interfaces can belong to a same single link. However, in a
408 normal operation, we can assume that there is 1-to-1 relationship
409 between links and interfaces. In other words, we can usually put
410 links and interfaces in the same scope type. The current KAME
411 implementation assumes the 1-to-1 relationship. In particular, we use
412 interface names such as "ne1" as unique link identifiers. This would
413 be much more human-readable and intuitive than numeric identifiers,
414 but please keep your mind on the theoretical difference between links
417 Site-local addresses are very vaguely defined in the specs, and both
418 the specification and the KAME code need tons of improvements to
419 enable its actual use. For example, it is still very unclear how we
420 define a site, or how we resolve host names in a site. There is work
421 underway to define behavior of routers at site border, but, we have
422 almost no code for site boundary node support (neither forwarding nor
423 routing) and we bet almost noone has. We recommend, at this moment,
424 you to use global addresses for experiments - there are way too many
425 pitfalls if you use site-local addresses.
427 1.3.1 Kernel internal
429 In the kernel, the link index for a link-local scope address is
430 embedded into the 2nd 16bit-word (the 3rd and 4th bytes) in the IPv6
432 For example, you may see something like:
433 fe80:1::200:f8ff:fe01:6317
434 in the routing table and the interface address structure (struct
435 in6_ifaddr). The address above is a link-local unicast address which
436 belongs to a network link whose link identifier is 1 (note that it
437 eqauls to the interface index by the assumption of our
438 implementation). The embedded index enables us to identify IPv6
439 link-local addresses over multiple links effectively and with only a
442 The use of the internal format must be limited inside the kernel. In
443 particular, addresses sent by an application should not contain the
444 embedded index (except via some very special APIs such as routing
445 sockets). Instead, the index should be specified in the sin6_scope_id
446 field of a sockaddr_in6 structure. Obviously, packets sent to or
447 received from must not contain the embedded index either, since the
448 index is meaningful only within the sending/receiving node.
450 In order to deal with the differences, several kernel routines are
451 provided. These are available by including <netinet6/scope_var.h>.
452 Typically, the following functions will be most generally used:
454 - int sa6_embedscope(struct sockaddr_in6 *sa6, int defaultok);
455 Embed sa6->sin6_scope_id into sa6->sin6_addr. If sin6_scope_id is
456 0, defaultok is non-0, and the default zone ID (see RFC4007) is
457 configured, the default ID will be used instead of the value of the
458 sin6_scope_id field. On success, sa6->sin6_scope_id will be reset
461 This function returns 0 on success, or a non-0 error code otherwise.
463 - int sa6_recoverscope(struct sockaddr_in6 *sa6);
464 Extract embedded zone ID in sa6->sin6_addr and set
465 sa6->sin6_scope_id to that ID. The embedded ID will be cleared with
468 This function returns 0 on success, or a non-0 error code otherwise.
470 - int in6_clearscope(struct in6_addr *in6);
471 Reset the embedded zone ID in 'in6' to 0. This function never fails, and
472 returns 0 if the original address is intact or non 0 if the address is
473 modified. The return value doesn't matter in most cases; currently, the
474 only point where we care about the return value is ip6_input() for checking
475 whether the source or destination addresses of the incoming packet is in
478 - int in6_setscope(struct in6_addr *in6, struct ifnet *ifp,
480 Embed zone ID determined by the address scope type for 'in6' and the
481 interface 'ifp' into 'in6'. If zoneidp is non NULL, *zoneidp will
482 also have the zone ID.
484 This function returns 0 on success, or a non-0 error code otherwise.
486 The typical usage of these functions is as follows:
488 sa6_embedscope() will be used at the socket or transport layer to
489 convert a sockaddr_in6 structure passed by an application into the
490 kernel-internal form. In this usage, the second argument is often the
491 'ip6_use_defzone' global variable.
493 sa6_recoverscope() will also be used at the socket or transport layer
494 to convert an in6_addr structure with the embedded zone ID into a
495 sockaddr_in6 structure with the corresponding ID in the sin6_scope_id
496 field (and without the embedded ID in sin6_addr).
498 in6_clearscope() will be used just before sending a packet to the wire
499 to remove the embedded ID. In general, this must be done at the last
500 stage of an output path, since otherwise the address would lose the ID
501 and could be ambiguous with regard to scope.
503 in6_setscope() will be used when the kernel receives a packet from the
504 wire to construct the kernel internal form for each address field in
505 the packet (typical examples are the source and destination addresses
506 of the packet). In the typical usage, the third argument 'zoneidp'
507 will be NULL. A non-NULL value will be used when the validity of the
508 zone ID must be checked, e.g., when forwarding a packet to another
509 link (see ip6_forward() for this usage).
511 An application, when sending a packet, is basically assumed to specify
512 the appropriate scope zone of the destination address by the
513 sin6_scope_id field (this might be done transparently from the
514 application with getaddrinfo() and the extended textual format - see
515 below), or at least the default scope zone(s) must be configured as a
516 last resort. In some cases, however, an application could specify an
517 ambiguous address with regard to scope, expecting it is disambiguated
518 in the kernel by some other means. A typical usage is to specify the
519 outgoing interface through another API, which can disambiguate the
520 unspecified scope zone. Such a usage is not recommended, but the
521 kernel implements some trick to deal with even this case.
523 A rough sketch of the trick can be summarized as the following
526 sa6_embedscope(dst, ip6_use_defzone);
527 in6_selectsrc(dst, ..., &ifp, ...);
528 in6_setscope(&dst->sin6_addr, ifp, NULL);
530 sa6_embedscope() first tries to convert sin6_scope_id (or the default
531 zone ID) into the kernel-internal form. This can fail with an
532 ambiguous destination, but it still tries to get the outgoing
533 interface (ifp) in the attempt of determining the source address of
534 the outgoing packet using in6_selectsrc(). If the interface is
535 detected, and the scope zone was originally ambiguous, in6_setscope()
536 can finally determine the appropriate ID with the address itself and
537 the interface, and construct the kernel-internal form. See, for
538 example, comments in udp6_output() for more concrete example.
540 In any case, kernel routines except ones in netinet6/scope6.c MUST NOT
541 directly refer to the embedded form. They MUST use the above
542 interface functions. In particular, kernel routines MUST NOT have the
543 following code fragment:
545 /* This is a bad practice. Don't do this */
546 if (IN6_IS_ADDR_LINKLOCAL(&sin6->sin6_addr))
547 sin6->sin6_addr.s6_addr16[1] = htons(ifp->if_index);
549 This is bad for several reasons. First, address ambiguity is not
550 specific to link-local addresses (any non-global multicast addresses
551 are inherently ambiguous, and this is particularly true for
552 interface-local addresses). Secondly, this is vulnerable to future
553 changes of the embedded form (the embedded position may change, or the
554 zone ID may not actually be the interface index). Only scope6.c
555 routines should know the details.
557 The above code fragment should thus actually be as follows:
559 /* This is correct. */
560 in6_setscope(&sin6->sin6_addr, ifp, NULL);
561 (and catch errors if possible and necessary)
563 1.3.2 Interaction with API
565 There are several candidates of API to deal with scoped addresses
568 The IPV6_PKTINFO ancillary data type or socket option defined in the
569 advanced API (RFC2292 or RFC3542) can specify
570 the outgoing interface of a packet. Similarly, the IPV6_PKTINFO or
571 IPV6_RECVPKTINFO socket options tell kernel to pass the incoming
572 interface to user applications.
574 These options are enough to disambiguate scoped addresses of an
575 incoming packet, because we can uniquely identify the corresponding
576 zone of the scoped address(es) by the incoming interface. However,
577 they are too strong for outgoing packets. For example, consider a
578 multi-sited node and suppose that more than one interface of the node
579 belongs to a same site. When we want to send a packet to the site,
580 we can only specify one of the interfaces for the outgoing packet with
581 these options; we cannot just say "send the packet to (one of the
582 interfaces of) the site."
584 Another kind of candidates is to use the sin6_scope_id member in the
585 sockaddr_in6 structure, defined in RFC2553. The KAME kernel
586 interprets the sin6_scope_id field properly in order to disambiguate scoped
587 addresses. For example, if an application passes a sockaddr_in6
588 structure that has a non-zero sin6_scope_id value to the sendto(2)
589 system call, the kernel should send the packet to the appropriate zone
590 according to the sin6_scope_id field. Similarly, when the source or
591 the destination address of an incoming packet is a scoped one, the
592 kernel should detect the correct zone identifier based on the address
593 and the receiving interface, fill the identifier in the sin6_scope_id
594 field of a sockaddr_in6 structure, and then pass the packet to an
595 application via the recvfrom(2) system call, etc.
597 However, the semantics of the sin6_scope_id is still vague and on the
598 way to standardization. Additionally, not so many operating systems
599 support the behavior above at this moment.
602 - If your target system is limited to KAME based ones (i.e. BSD
603 variants and KAME snaps), use the sin6_scope_id field assuming the
604 kernel behavior described above.
605 - Otherwise, (i.e. if your program should be portable on other systems
607 + Use the advanced API to disambiguate scoped addresses of incoming
609 + To disambiguate scoped addresses of outgoing packets,
610 * if it is okay to just specify the outgoing interface, use the
611 advanced API. This would be the case, for example, when you
612 should only consider link-local addresses and your system
613 assumes 1-to-1 relationship between links and interfaces.
614 * otherwise, sorry but you lose. Please rush the IETF IPv6
615 community into standardizing the semantics of the sin6_scope_id
618 Routing daemons and configuration programs, like route6d and ifconfig,
619 will need to manipulate the "embedded" zone index. These programs use
620 routing sockets and ioctls (like SIOCGIFADDR_IN6) and the kernel API
621 will return IPv6 addresses with the 2nd 16bit-word filled in. The
622 APIs are for manipulating kernel internal structure. Programs that
623 use these APIs have to be prepared about differences in kernels
626 getaddrinfo(3) and getnameinfo(3) support an extended numeric IPv6
627 syntax, as documented in RFC4007. You can specify the outgoing link,
628 by using the name of the outgoing interface as the link, like
629 "fe80::1%ne0" (again, note that we assume there is 1-to-1 relationship
630 between links and interfaces.) This way you will be able to specify a
631 link-local scoped address without much trouble.
633 Other APIs like inet_pton(3) and inet_ntop(3) are inherently
634 unfriendly with scoped addresses, since they are unable to annotate
635 addresses with zone identifier.
637 1.3.3 Interaction with users (command line)
639 Most of user applications now support the extended numeric IPv6
640 syntax. In this case, you can specify outgoing link, by using the name
641 of the outgoing interface like "fe80::1%ne0" (sorry for the duplicated
642 notice, but please recall again that we assume 1-to-1 relationship
643 between links and interfaces). This is even the case for some
644 management tools such as route(8) or ndp(8). For example, to install
645 the IPv6 default route by hand, you can type like
646 # route add -inet6 default fe80::9876:5432:1234:abcd%ne0
647 (Although we suggest you to run dynamic routing instead of static
648 routes, in order to avoid configuration mistakes.)
650 Some applications have command line options for specifying an
651 appropriate zone of a scoped address (like "ping6 -I ne0 ff02::1" to
652 specify the outgoing interface). However, you can't always expect such
653 options. Additionally, specifying the outgoing "interface" is in
654 theory an overspecification as a way to specify the outgoing "link"
655 (see above). Thus, we recommend you to use the extended format
656 described above. This should apply to the case where the outgoing
657 interface is specified.
659 In any case, when you specify a scoped address to the command line,
660 NEVER write the embedded form (such as ff02:1::1 or fe80:2::fedc),
661 which should only be used inside the kernel (see Section 1.3.1), and
662 is not supposed to work.
666 The KAME kit implements most of the IPv6 stateless address
667 autoconfiguration in the kernel.
668 Neighbor Discovery functions are implemented in the kernel as a whole.
669 Router Advertisement (RA) input for hosts is implemented in the
670 kernel. Router Solicitation (RS) output for endhosts, RS input
671 for routers, and RA output for routers are implemented in the
674 1.4.1 Assignment of link-local, and special addresses
676 IPv6 link-local address is generated from IEEE802 address (ethernet MAC
677 address). Each of interface is assigned an IPv6 link-local address
678 automatically, when the interface becomes up (IFF_UP). Also, direct route
679 for the link-local address is added to routing table.
681 Here is an output of netstat command:
684 Destination Gateway Flags Netif Expire
685 fe80::%ed0/64 link#1 UC ed0
686 fe80::%ep0/64 link#2 UC ep0
688 Interfaces that has no IEEE802 address (pseudo interfaces like tunnel
689 interfaces, or ppp interfaces) will borrow IEEE802 address from other
690 interfaces, such as ethernet interfaces, whenever possible.
691 If there is no IEEE802 hardware attached, last-resort pseudorandom value,
692 which is from MD5(hostname), will be used as source of link-local address.
693 If it is not suitable for your usage, you will need to configure the
694 link-local address manually.
696 If an interface is not capable of handling IPv6 (such as lack of multicast
697 support), link-local address will not be assigned to that interface.
698 See section 2 for details.
700 Each interface joins the solicited multicast address and the
701 link-local all-nodes multicast addresses (e.g. fe80::1:ff01:6317
702 and ff02::1, respectively, on the link the interface is attached).
703 In addition to a link-local address, the loopback address (::1) will be
704 assigned to the loopback interface. Also, ::1/128 and ff01::/32 are
705 automatically added to routing table, and loopback interface joins
706 node-local multicast group ff01::1.
708 1.4.2 Stateless address autoconfiguration on hosts
710 In IPv6 specification, nodes are separated into two categories:
711 routers and hosts. Routers forward packets addressed to others, hosts does
712 not forward the packets. net.inet6.ip6.forwarding defines whether this
713 node is a router or a host (router if it is 1, host if it is 0).
715 It is NOT recommended to change net.inet6.ip6.forwarding while the node
716 is in operation. IPv6 specification defines behavior for "host" and "router"
717 quite differently, and switching from one to another can cause serious
718 troubles. It is recommended to configure the variable at bootstrap time only.
720 The first step in stateless address configuration is Duplicated Address
721 Detection (DAD). See 1.2 for more detail on DAD.
723 When a host hears Router Advertisement from the router, a host may
724 autoconfigure itself by stateless address autoconfiguration. This
725 behavior can be controlled by the net.inet6.ip6.accept_rtadv sysctl
726 variable and a per-interface flag managed in the kernel. The latter,
727 which we call "if_accept_rtadv" here, can be changed by the ndp(8)
728 command (see the manpage for more details). When the sysctl variable
729 is set to 1, and the flag is set, the host autoconfigures itself. By
730 autoconfiguration, network address prefixes for the receiving
731 interface (usually global address prefix) are added. The default
732 route is also configured.
734 Routers periodically generate Router Advertisement packets. To
735 request an adjacent router to generate RA packet, a host can transmit
736 Router Solicitation. To generate an RS packet at any time, use the
737 "rtsol" command. The "rtsold" daemon is also available. "rtsold"
738 generates Router Solicitation whenever necessary, and it works greatly
739 for nomadic usage (notebooks/laptops). If one wishes to ignore Router
740 Advertisements, use sysctl to set net.inet6.ip6.accept_rtadv to 0.
741 Additionally, ndp(8) command can be used to control the behavior
744 To generate Router Advertisement from a router, use the "rtadvd" daemon.
746 Note that the IPv6 specification assumes the following items and that
747 nonconforming cases are left unspecified:
748 - Only hosts will listen to router advertisements
749 - Hosts have a single network interface (except loopback)
750 This is therefore unwise to enable net.inet6.ip6.accept_rtadv on routers,
751 or multi-interface hosts. A misconfigured node can behave strange
752 (KAME code allows nonconforming configuration, for those who would like
753 to do some experiments).
755 To summarize the sysctl knob:
756 accept_rtadv forwarding role of the node
758 0 0 host (to be manually configured)
760 1 0 autoconfigured host
761 (spec assumes that hosts have a single
762 interface only, autoconfigred hosts
763 with multiple interfaces are
765 1 1 invalid, or experimental
766 (out-of-scope of spec)
768 The if_accept_rtadv flag is referred only when accept_rtadv is 1 (the
769 latter two cases). The flag does not have any effects when the sysctl
772 See 1.2 in the document for relationship between DAD and autoconfiguration.
776 We supply a tiny DHCPv6 server/client in kame/dhcp6. However, the
777 implementation is premature (for example, this does NOT implement
778 address lease/release), and it is not in default compilation tree on
779 some platforms. If you want to do some experiment, compile it on your
782 DHCPv6 and autoconfiguration also needs more work. "Managed" and "Other"
783 bits in RA have no special effect to stateful autoconfiguration procedure
784 in DHCPv6 client program ("Managed" bit actually prevents stateless
785 autoconfiguration, but no special action will be taken for DHCPv6 client).
787 1.5 Generic tunnel interface
789 GIF (Generic InterFace) is a pseudo interface for configured tunnel.
790 Details are described in gif(4) manpage.
796 are available. Use "gifconfig" to assign physical (outer) source
797 and destination address to gif interfaces.
798 Configuration that uses same address family for inner and outer IP
799 header (v4 in v4, or v6 in v6) is dangerous. It is very easy to
800 configure interfaces and routing tables to perform infinite level
801 of tunneling. Please be warned.
803 gif can be configured to be ECN-friendly. See 4.5 for ECN-friendliness
804 of tunnels, and gif(4) manpage for how to configure.
806 If you would like to configure an IPv4-in-IPv6 tunnel with gif interface,
807 read gif(4) carefully. You may need to remove IPv6 link-local address
808 automatically assigned to the gif interface.
810 1.6 Address Selection
812 1.6.1 Source Address Selection
814 The KAME kernel chooses the source address for an outgoing packet
815 sent from a user application as follows:
817 1. if the source address is explicitly specified via an IPV6_PKTINFO
818 ancillary data item or the socket option of that name, just use it.
819 Note that this item/option overrides the bound address of the
820 corresponding (datagram) socket.
822 2. if the corresponding socket is bound, use the bound address.
824 3. otherwise, the kernel first tries to find the outgoing interface of
825 the packet. If it fails, the source address selection also fails.
826 If the kernel can find an interface, choose the most appropriate
827 address based on the algorithm described in RFC3484.
829 The policy table used in this algorithm is stored in the kernel.
830 To install or view the policy, use the ip6addrctl(8) command. The
831 kernel does not have pre-installed policy. It is expected that the
832 default policy described in the draft should be installed at the
833 bootstrap time using this command.
835 This draft allows an implementation to add implementation-specific
836 rules with higher precedence than the rule "Use longest matching
837 prefix." KAME's implementation has the following additional rules
838 (that apply in the appeared order):
840 - prefer addresses on alive interfaces, that is, interfaces with
841 the UP flag being on. This rule is particularly useful for
842 routers, since some routing daemons stop advertising prefixes
843 (addresses) on interfaces that have become down.
845 - prefer addresses on "preferred" interfaces. "Preferred"
846 interfaces can be specified by the ndp(8) command. By default,
847 no interface is preferred, that is, this rule does not apply.
848 Again, this rule is particularly useful for routers, since there
849 is a convention, among router administrators, of assigning
850 "stable" addresses on a particular interface (typically a
853 In any case, addresses that break the scope zone of the
854 destination, or addresses whose zone do not contain the outgoing
855 interface are never chosen.
857 When the procedure above fails, the kernel usually returns
858 EADDRNOTAVAIL to the application.
860 In some cases, the specification explicitly requires the
861 implementation to choose a particular source address. The source
862 address for a Neighbor Advertisement (NA) message is an example.
863 Under the spec (RFC2461 7.2.2) NA's source should be the target
864 address of the corresponding NS's target. In this case we follow the
865 spec rather than the above rule.
867 If you would like to prohibit the use of deprecated address for some
868 reason, configure net.inet6.ip6.use_deprecated to 0. The issue
869 related to deprecated address is described in RFC2462 5.5.4 (NOTE:
870 there is some debate underway in IETF ipngwg on how to use
871 "deprecated" address).
873 As documented in the source address selection document, temporary
874 addresses for privacy extension are less preferred to public addresses
875 by default. However, for administrators who are particularly aware of
876 the privacy, there is a system-wide sysctl(3) variable
877 "net.inet6.ip6.prefer_tempaddr". When the variable is set to
878 non-zero, the kernel will rather prefer temporary addresses. The
879 default value of this variable is 0.
881 1.6.2 Destination Address Ordering
883 KAME's getaddrinfo(3) supports the destination address ordering
884 algorithm described in RFC3484. Getaddrinfo(3) needs to know the
885 source address for each destination address and policy entries
886 (described in the previous section) for the source and destination
887 addresses. To get the source address, the library function opens a
888 UDP socket and tries to connect(2) for the destination. To get the
889 policy entry, the function issues sysctl(3).
893 KAME supports the Jumbo Payload hop-by-hop option used to send IPv6
894 packets with payloads longer than 65,535 octets. But since currently
895 KAME does not support any physical interface whose MTU is more than
896 65,535, such payloads can be seen only on the loopback interface(i.e.
899 If you want to try jumbo payloads, you first have to reconfigure the
900 kernel so that the MTU of the loopback interface is more than 65,535
901 bytes; add the following to the kernel configuration file:
902 options "LARGE_LOMTU" #To test jumbo payload
903 and recompile the new kernel.
905 Then you can test jumbo payloads by the ping6 command with -b and -s
906 options. The -b option must be specified to enlarge the size of the
907 socket buffer and the -s option specifies the length of the packet,
908 which should be more than 65,535. For example, type as follows;
909 % ping6 -b 70000 -s 68000 ::1
911 The IPv6 specification requires that the Jumbo Payload option must not
912 be used in a packet that carries a fragment header. If this condition
913 is broken, an ICMPv6 Parameter Problem message must be sent to the
914 sender. KAME kernel follows the specification, but you cannot usually
915 see an ICMPv6 error caused by this requirement.
917 If KAME kernel receives an IPv6 packet, it checks the frame length of
918 the packet and compares it to the length specified in the payload
919 length field of the IPv6 header or in the value of the Jumbo Payload
920 option, if any. If the former is shorter than the latter, KAME kernel
921 discards the packet and increments the statistics. You can see the
922 statistics as output of netstat command with `-s -p ip6' option:
926 1 with data size < data length
928 So, KAME kernel does not send an ICMPv6 error unless the erroneous
929 packet is an actual Jumbo Payload, that is, its packet size is more
930 than 65,535 bytes. As described above, KAME kernel currently does not
931 support physical interface with such a huge MTU, so it rarely returns an
934 TCP/UDP over jumbogram is not supported at this moment. This is because
935 we have no medium (other than loopback) to test this. Contact us if you
938 IPsec does not work on jumbograms. This is due to some specification twists
939 in supporting AH with jumbograms (AH header size influences payload length,
940 and this makes it real hard to authenticate inbound packet with jumbo payload
941 option as well as AH).
943 There are fundamental issues in *BSD support for jumbograms. We would like to
944 address those, but we need more time to finalize the task. To name a few:
945 - mbuf pkthdr.len field is typed as "int" in 4.4BSD, so it cannot hold
946 jumbogram with len > 2G on 32bit architecture CPUs. If we would like to
947 support jumbogram properly, the field must be expanded to hold 4G +
948 IPv6 header + link-layer header. Therefore, it must be expanded to at least
949 int64_t (u_int32_t is NOT enough).
950 - We mistakingly use "int" to hold packet length in many places. We need
951 to convert them into larger numeric type. It needs a great care, as we may
952 experience overflow during packet length computation.
953 - We mistakingly check for ip6_plen field of IPv6 header for packet payload
954 length in various places. We should be checking mbuf pkthdr.len instead.
955 ip6_input() will perform sanity check on jumbo payload option on input,
956 and we can safely use mbuf pkthdr.len afterwards.
957 - TCP code needs careful updates in bunch of places, of course.
959 1.8 Loop prevention in header processing
961 IPv6 specification allows arbitrary number of extension headers to
962 be placed onto packets. If we implement IPv6 packet processing
963 code in the way BSD IPv4 code is implemented, kernel stack may
964 overflow due to long function call chain. KAME sys/netinet6 code
965 is carefully designed to avoid kernel stack overflow. Because of
966 this, KAME sys/netinet6 code defines its own protocol switch
967 structure, as "struct ip6protosw" (see netinet6/ip6protosw.h).
969 In addition to this, we restrict the number of extension headers
970 (including the IPv6 header) in each incoming packet, in order to
971 prevent a DoS attack that tries to send packets with a massive number
972 of extension headers. The upper limit can be configured by the sysctl
973 value net.inet6.ip6.hdrnestlimit. In particular, if the value is 0,
974 the node will allow an arbitrary number of headers. As of writing this
975 document, the default value is 50.
977 IPv4 part (sys/netinet) remains untouched for compatibility.
978 Because of this, if you receive IPsec-over-IPv4 packet with massive
979 number of IPsec headers, kernel stack may blow up. IPsec-over-IPv6 is okay.
983 After RFC2463 was published, IETF ipngwg has decided to disallow ICMPv6 error
984 packet against ICMPv6 redirect, to prevent ICMPv6 storm on a network medium.
985 KAME already implements this into the kernel.
987 RFC2463 requires rate limitation for ICMPv6 error packets generated by a
988 node, to avoid possible DoS attacks. KAME kernel implements two rate-
989 limitation mechanisms, tunable via sysctl:
990 - Minimum time interval between ICMPv6 error packets
991 KAME kernel will generate no more than one ICMPv6 error packet,
992 during configured time interval. net.inet6.icmp6.errratelimit
993 controls the interval (default: disabled).
994 - Maximum ICMPv6 error packet-per-second
995 KAME kernel will generate no more than the configured number of
996 packets in one second. net.inet6.icmp6.errppslimit controls the
997 maximum packet-per-second value (default: 200pps)
998 Basically, we need to pick values that are suitable against the bandwidth
999 of link layer devices directly attached to the node. In some cases the
1000 default values may not fit well. We are still unsure if the default value
1001 is sane or not. Comments are welcome.
1005 For userland programming, we support IPv6 socket API as specified in
1006 RFC2553/3493, RFC3542 and upcoming internet drafts.
1008 TCP/UDP over IPv6 is available and quite stable. You can enjoy "telnet",
1009 "ftp", "rlogin", "rsh", "ssh", etc. These applications are protocol
1010 independent. That is, they automatically chooses IPv4 or IPv6
1013 1.11 Kernel Internals
1015 (*) TCP/UDP part is handled differently between operating system platforms.
1016 See 1.12 for details.
1018 The current KAME has escaped from the IPv4 netinet logic. While
1019 ip_forward() calls ip_output(), ip6_forward() directly calls
1020 if_output() since routers must not divide IPv6 packets into fragments.
1022 ICMPv6 should contain the original packet as long as possible up to
1023 1280. UDP6/IP6 port unreach, for instance, should contain all
1024 extension headers and the *unchanged* UDP6 and IP6 headers.
1025 So, all IP6 functions except TCP6 never convert network byte
1026 order into host byte order, to save the original packet.
1028 tcp6_input(), udp6_input() and icmp6_input() can't assume that IP6
1029 header is preceding the transport headers due to extension
1030 headers. So, in6_cksum() was implemented to handle packets whose IP6
1031 header and transport header is not continuous. TCP/IP6 nor UDP/IP6
1032 header structure don't exist for checksum calculation.
1034 To process IP6 header, extension headers and transport headers easily,
1035 KAME requires network drivers to store packets in one internal mbuf or
1036 one or more external mbufs. A typical old driver prepares two
1037 internal mbufs for 100 - 208 bytes data, however, KAME's reference
1038 implementation stores it in one external mbuf.
1040 "netstat -s -p ip6" tells you whether or not your driver conforms
1041 KAME's requirement. In the following example, "cce0" violates the
1042 requirement. (For more information, refer to Section 2.)
1050 0 two or more ext mbuf
1052 Each input function calls IP6_EXTHDR_CHECK in the beginning to check
1053 if the region between IP6 and its header is
1054 continuous. IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has
1055 M_LOOP flag, that is, the packet comes from the loopback
1056 interface. m_pullup() is never called for packets coming from physical
1059 TCP6 reassembly makes use of IP6 header to store reassemble
1060 information. IP6 is not supposed to be just before TCP6, so
1061 ip6tcpreass structure has a pointer to TCP6 header. Of course, it has
1062 also a pointer back to mbuf to avoid m_pullup().
1064 Like TCP6, both IP and IP6 reassemble functions never call m_pullup().
1066 xxx_ctlinput() calls in_mrejoin() on PRC_IFNEWADDR. We think this is
1067 one of 4.4BSD implementation flaws. Since 4.4BSD keeps ia_multiaddrs
1068 in in_ifaddr{}, it can't use multicast feature if the interface has no
1069 unicast address. So, if an application joins to an interface and then
1070 all unicast addresses are removed from the interface, the application
1071 can't send/receive any multicast packets. Moreover, if a new unicast
1072 address is assigned to the interface, in_mrejoin() must be called.
1073 KAME's interfaces, however, have ALWAYS one link-local unicast
1074 address. These extensions have thus not been implemented in KAME.
1076 1.12 IPv4 mapped address and IPv6 wildcard socket
1078 RFC2553/3493 describes IPv4 mapped address (3.7) and special behavior
1079 of IPv6 wildcard bind socket (3.8). The spec allows you to:
1080 - Accept IPv4 connections by AF_INET6 wildcard bind socket.
1081 - Transmit IPv4 packet over AF_INET6 socket by using special form of
1082 the address like ::ffff:10.1.1.1.
1083 but the spec itself is very complicated and does not specify how the
1084 socket layer should behave.
1085 Here we call the former one "listening side" and the latter one "initiating
1086 side", for reference purposes.
1088 Almost all KAME implementations treat tcp/udp port number space separately
1089 between IPv4 and IPv6. You can perform wildcard bind on both of the address
1090 families, on the same port.
1092 There are some OS-platform differences in KAME code, as we use tcp/udp
1093 code from different origin. The following table summarizes the behavior.
1095 listening side initiating side
1096 (AF_INET6 wildcard (connection to ::ffff:10.1.1.1)
1097 socket gets IPv4 conn.)
1099 KAME/BSDI3 not supported not supported
1100 KAME/FreeBSD228 not supported not supported
1101 KAME/FreeBSD3x configurable supported
1103 KAME/FreeBSD4x configurable supported
1105 KAME/NetBSD configurable supported
1107 KAME/BSDI4 enabled supported
1108 KAME/OpenBSD not supported not supported
1110 The following sections will give you more details, and how you can
1111 configure the behavior.
1113 Comments on listening side:
1115 It looks that RFC2553/3493 talks too little on wildcard bind issue,
1116 specifically on (1) port space issue, (2) failure mode, (3) relationship
1117 between AF_INET/INET6 wildcard bind like ordering constraint, and (4) behavior
1118 when conflicting socket is opened/closed. There can be several separate
1119 interpretation for this RFC which conform to it but behaves differently.
1120 So, to implement portable application you should assume nothing
1121 about the behavior in the kernel. Using getaddrinfo() is the safest way.
1122 Port number space and wildcard bind issues were discussed in detail
1123 on ipv6imp mailing list, in mid March 1999 and it looks that there's
1124 no concrete consensus (means, up to implementers). You may want to
1125 check the mailing list archives.
1126 We supply a tool called "bindtest" that explores the behavior of
1127 kernel bind(2). The tool will not be compiled by default.
1129 If a server application would like to accept IPv4 and IPv6 connections,
1130 it should use AF_INET and AF_INET6 socket (you'll need two sockets).
1131 Use getaddrinfo() with AI_PASSIVE into ai_flags, and socket(2) and bind(2)
1132 to all the addresses returned.
1133 By opening multiple sockets, you can accept connections onto the socket with
1134 proper address family. IPv4 connections will be accepted by AF_INET socket,
1135 and IPv6 connections will be accepted by AF_INET6 socket (NOTE: KAME/BSDI4
1136 kernel sometimes violate this - we will fix it).
1138 If you try to support IPv6 traffic only and would like to reject IPv4
1139 traffic, always check the peer address when a connection is made toward
1140 AF_INET6 listening socket. If the address is IPv4 mapped address, you may
1141 want to reject the connection. You can check the condition by using
1142 IN6_IS_ADDR_V4MAPPED() macro. This is one of the reasons the author of
1143 the section (itojun) dislikes special behavior of AF_INET6 wildcard bind.
1145 Comments on initiating side:
1147 Advise to application implementers: to implement a portable IPv6 application
1148 (which works on multiple IPv6 kernels), we believe that the following
1149 is the key to the success:
1150 - NEVER hardcode AF_INET nor AF_INET6.
1151 - Use getaddrinfo() and getnameinfo() throughout the system.
1152 Never use gethostby*(), getaddrby*(), inet_*() or getipnodeby*().
1153 - If you would like to connect to destination, use getaddrinfo() and try
1154 all the destination returned, like telnet does.
1155 - Some of the IPv6 stack is shipped with buggy getaddrinfo(). Ship a minimal
1156 working version with your application and use that as last resort.
1158 If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing
1159 connection, you will need tweaked implementation in DNS support libraries,
1160 as documented in RFC2553/3493 6.1. KAME libinet6 includes the tweak in
1161 getipnodebyname(). Note that getipnodebyname() itself is not recommended as
1162 it does not handle scoped IPv6 addresses at all. For IPv6 name resolution
1163 getaddrinfo() is the preferred API. getaddrinfo() does not implement the
1166 When writing applications that make outgoing connections, story goes much
1167 simpler if you treat AF_INET and AF_INET6 as totally separate address family.
1168 {set,get}sockopt issue goes simpler, DNS issue will be made simpler. We do
1169 not recommend you to rely upon IPv4 mapped address.
1171 1.12.1 KAME/BSDI3 and KAME/FreeBSD228
1173 The platforms do not support IPv4 mapped address at all (both listening side
1174 and initiating side). AF_INET6 and AF_INET sockets are totally separated.
1176 Port number space is totally separate between AF_INET and AF_INET6 sockets.
1178 It should be noted that KAME/BSDI3 and KAME/FreeBSD228 are not conformant
1179 to RFC2553/3493 section 3.7 and 3.8. It is due to code sharing reasons.
1181 1.12.2 KAME/FreeBSD[34]x
1183 KAME/FreeBSD3x and KAME/FreeBSD4x use shared tcp4/6 code (from
1184 sys/netinet/tcp*) and shared udp4/6 code (from sys/netinet/udp*).
1185 They use unified inpcb/in6pcb structure.
1187 1.12.2.1 KAME/FreeBSD[34]x, listening side
1189 The platform can be configured to support IPv4 mapped address/special
1190 AF_INET6 wildcard bind (enabled by default). There is no kernel compilation
1191 option to disable it. You can enable/disable the behavior with sysctl
1192 (per-node), or setsockopt (per-socket).
1194 Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
1195 conditions are satisfied:
1196 - there's no AF_INET socket that matches the IPv4 connection
1197 - the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
1198 getsockopt(IPV6_V6ONLY) returns 0.
1202 1.12.2.2 KAME/FreeBSD[34]x, initiating side
1204 KAME/FreeBSD3x supports outgoing connection to IPv4 mapped address
1205 (::ffff:10.1.1.1), if the node is configured to accept IPv4 connections
1212 KAME/NetBSD uses shared tcp4/6 code (from sys/netinet/tcp*) and shared
1213 udp4/6 code (from sys/netinet/udp*). The implementation is made differently
1214 from KAME/FreeBSD[34]x. KAME/NetBSD uses separate inpcb/in6pcb structures,
1215 while KAME/FreeBSD[34]x uses merged inpcb structure.
1217 It should be noted that the default configuration of KAME/NetBSD is not
1218 conformant to RFC2553/3493 section 3.8. It is intentionally turned off by
1219 default for security reasons.
1221 The platform can be configured to support IPv4 mapped address/special AF_INET6
1222 wildcard bind (disabled by default). Kernel behavior can be summarized as
1224 - default: special support code will be compiled in, but is disabled by
1225 default. It can be controlled by sysctl (net.inet6.ip6.v6only),
1226 or setsockopt(IPV6_V6ONLY).
1227 - add "INET6_BINDV6ONLY": No special support code for AF_INET6 wildcard socket
1228 will be compiled in. AF_INET6 sockets and AF_INET sockets are totally
1229 separate. The behavior is similar to what described in 1.12.1.
1231 sysctl setting will affect per-socket configuration at in6pcb creation time
1232 only. In other words, per-socket configuration will be copied from sysctl
1233 configuration at in6pcb creation time. To change per-socket behavior, you
1234 must perform setsockopt or reopen the socket. Change in sysctl configuration
1235 will not change the behavior or sockets that are already opened.
1237 1.12.3.1 KAME/NetBSD, listening side
1239 Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
1240 conditions are satisfied:
1241 - there's no AF_INET socket that matches the IPv4 connection
1242 - the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
1243 getsockopt(IPV6_V6ONLY) returns 0.
1245 You cannot bind(2) with IPv4 mapped address. This is a workaround for port
1246 number duplicate and other twists.
1248 1.12.3.2 KAME/NetBSD, initiating side
1250 When getsockopt(IPV6_V6ONLY) is 0 for a socket, you can make an outgoing
1251 traffic to IPv4 destination over AF_INET6 socket, using IPv4 mapped
1252 address destination (::ffff:10.1.1.1).
1254 When getsockopt(IPV6_V6ONLY) is 1 for a socket, you cannot use IPv4 mapped
1255 address for outgoing traffic.
1259 KAME/BSDI4 uses NRL-based TCP/UDP stack and inpcb source code,
1260 which was derived from NRL IPv6/IPsec stack. We guess it supports IPv4 mapped
1261 address and speical AF_INET6 wildcard bind. The implementation is, again,
1262 different from other KAME/*BSDs.
1264 1.12.4.1 KAME/BSDI4, listening side
1266 NRL inpcb layer supports special behavior of AF_INET6 wildcard socket.
1267 There is no way to disable the behavior.
1269 Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
1270 condition is satisfied:
1271 - there's no AF_INET socket that matches the IPv4 connection
1273 1.12.4.2 KAME/BSDI4, initiating side
1275 KAME/BSDi4 supports connection initiation to IPv4 mapped address
1276 (like ::ffff:10.1.1.1).
1280 KAME/OpenBSD uses NRL-based TCP/UDP stack and inpcb source code,
1281 which was derived from NRL IPv6/IPsec stack.
1283 It should be noted that KAME/OpenBSD is not conformant to RFC2553/3493 section
1284 3.7 and 3.8. It is intentionally omitted for security reasons.
1286 1.12.5.1 KAME/OpenBSD, listening side
1288 KAME/OpenBSD disables special behavior on AF_INET6 wildcard bind for
1289 security reasons (if IPv4 traffic toward AF_INET6 wildcard bind is allowed,
1290 access control will become much harder). KAME/BSDI4 uses NRL-based TCP/UDP
1291 stack as well, however, the behavior is different due to OpenBSD's security
1294 As a result the behavior of KAME/OpenBSD is similar to KAME/BSDI3 and
1295 KAME/FreeBSD228 (see 1.12.1 for more detail).
1297 1.12.5.2 KAME/OpenBSD, initiating side
1299 KAME/OpenBSD does not support connection initiation to IPv4 mapped address
1300 (like ::ffff:10.1.1.1).
1304 IPv4 mapped address support adds a big requirement to EVERY userland codebase.
1305 Every userland code should check if an AF_INET6 sockaddr contains IPv4
1306 mapped address or not. This adds many twists:
1308 - Access controls code becomes harder to write.
1309 For example, if you would like to reject packets from 10.0.0.0/8,
1310 you need to reject packets to AF_INET socket from 10.0.0.0/8,
1311 and to AF_INET6 socket from ::ffff:10.0.0.0/104.
1312 - If a protocol on top of IPv4 is defined differently with IPv6, we need to be
1313 really careful when we determine which protocol to use.
1314 For example, with FTP protocol, we can not simply use sa_family to determine
1315 FTP command sets. The following example is incorrect:
1316 if (sa_family == AF_INET)
1317 use EPSV/EPRT or PASV/PORT; /*IPv4*/
1318 else if (sa_family == AF_INET6)
1319 use EPSV/EPRT or LPSV/LPRT; /*IPv6*/
1322 The correct code, with consideration to IPv4 mapped address, would be:
1323 if (sa_family == AF_INET)
1324 use EPSV/EPRT or PASV/PORT; /*IPv4*/
1325 else if (sa_family == AF_INET6 && IPv4 mapped address)
1326 use EPSV/EPRT or PASV/PORT; /*IPv4 command set on AF_INET6*/
1327 else if (sa_family == AF_INET6 && !IPv4 mapped address)
1328 use EPSV/EPRT or LPSV/LPRT; /*IPv6*/
1331 It is too much to ask for every body to be careful like this.
1332 The problem is, we are not sure if the above code fragment is perfect for
1334 - By enabling kernel support for IPv4 mapped address (outgoing direction),
1335 servers on the kernel can be hosed by IPv6 native packet that has IPv4
1336 mapped address in IPv6 header source, and can generate unwanted IPv4 packets.
1337 draft-itojun-ipv6-transition-abuse-01.txt, draft-cmetz-v6ops-v4mapped-api-
1338 harmful-00.txt, and draft-itojun-v6ops-v4mapped-harmful-01.txt
1339 has more on this scenario.
1341 Due to the above twists, some of KAME userland programs has restrictions on
1342 the use of IPv4 mapped addresses:
1343 - rshd/rlogind do not accept connections from IPv4 mapped address.
1344 This is to avoid malicious use of IPv4 mapped address in IPv6 native
1345 packet, to bypass source-address based authentication.
1346 - ftp/ftpd assume that you are on dual stack network. IPv4 mapped address
1347 will be decoded in userland, and will be passed to AF_INET sockets
1348 (in other words, ftp/ftpd do not support SIIT environment).
1350 1.12.7 Interaction with SIIT translator
1352 SIIT translator is specified in RFC2765. KAME node cannot become a SIIT
1353 translator box, nor SIIT end node (a node in SIIT cloud).
1355 To become a SIIT translator box, we need to put additional code for that.
1356 We do not have the code in our tree at this moment.
1358 There are multiple reasons that we are unable to become SIIT end node.
1359 (1) SIIT translators require end nodes in the SIIT cloud to be IPv6-only.
1360 Since we are unable to compile INET-less kernel, we are unable to become
1361 SIIT end node. (2) As presented in 1.12.6, some of our userland code assumes
1362 dual stack network. (3) KAME stack filters out IPv6 packets with IPv4
1363 mapped address in the header, to secure non-SIIT case (which is much more
1364 common). Effectively KAME node will reject any packets via SIIT translator
1365 box. See section 1.14 for more detail about the last item.
1367 There are documentation issues too - SIIT document requires very strange
1368 things. For example, SIIT document asks IPv6-only (meaning no IPv4 code)
1369 node to be able to construct IPv4 IPsec headers. If a node knows how to
1370 construct IPv4 IPsec headers, that is not an IPv6-only node, it is a dual-stack
1371 node. The requirements imposed in SIIT document contradict with the other
1372 part of the document itself.
1374 1.13 sockaddr_storage
1376 When RFC2553 was about to be finalized, there was discussion on how struct
1377 sockaddr_storage members are named. One proposal is to prepend "__" to the
1378 members (like "__ss_len") as they should not be touched. The other proposal
1379 was that don't prepend it (like "ss_len") as we need to touch those members
1380 directly. There was no clear consensus on it.
1382 As a result, RFC2553 defines struct sockaddr_storage as follows:
1383 struct sockaddr_storage {
1384 u_char __ss_len; /* address length */
1385 u_char __ss_family; /* address family */
1386 /* and bunch of padding */
1388 On the contrary, XNET draft defines as follows:
1389 struct sockaddr_storage {
1390 u_char ss_len; /* address length */
1391 u_char ss_family; /* address family */
1392 /* and bunch of padding */
1395 In December 1999, it was agreed that RFC2553bis (RFC3493) should pick the
1396 latter (XNET) definition.
1398 KAME kit prior to December 1999 used RFC2553 definition. KAME kit after
1399 December 1999 (including December) will conform to XNET definition,
1400 based on RFC3493 discussion.
1402 If you look at multiple IPv6 implementations, you will be able to see
1403 both definitions. As an userland programmer, the most portable way of
1404 dealing with it is to:
1405 (1) ensure ss_family and/or ss_len are available on the platform, by using
1407 (2) have -Dss_family=__ss_family to unify all occurrences (including header
1408 file) into __ss_family, or
1409 (3) never touch __ss_family. cast to sockaddr * and use sa_family like:
1410 struct sockaddr_storage ss;
1411 family = ((struct sockaddr *)&ss)->sa_family
1413 1.14 Invalid addresses on the wire
1415 Some of IPv6 transition technologies embed IPv4 address into IPv6 address.
1416 These specifications themselves are fine, however, there can be certain
1417 set of attacks enabled by these specifications. Recent specification
1418 documents covers up those issues, however, there are already-published RFCs
1419 that does not have protection against those (like using source address of
1420 ::ffff:127.0.0.1 to bypass "reject packet from remote" filter).
1422 To name a few, these address ranges can be used to hose an IPv6 implementation,
1423 or bypass security controls:
1424 - IPv4 mapped address that embeds unspecified/multicast/loopback/broadcast
1425 IPv4 address (if they are in IPv6 native packet header, they are malicious)
1426 ::ffff:0.0.0.0/104 ::ffff:127.0.0.0/104
1427 ::ffff:224.0.0.0/100 ::ffff:255.0.0.0/104
1428 - 6to4 (RFC3056) prefix generated from unspecified/multicast/loopback/
1429 broadcast/private IPv4 address
1430 2002:0000::/24 2002:7f00::/24 2002:e000::/24
1431 2002:ff00::/24 2002:0a00::/24 2002:ac10::/28
1433 - IPv4 compatible address that embeds unspecified/multicast/loopback/broadcast
1434 IPv4 address (if they are in IPv6 native packet header, they are malicious).
1435 Note that, since KAME doe snot support RFC1933/2893 auto tunnels, KAME nodes
1436 are not vulnerable to these packets.
1437 ::0.0.0.0/104 ::127.0.0.0/104 ::224.0.0.0/100 ::255.0.0.0/104
1439 Also, since KAME does not support RFC1933/2893 auto tunnels, seeing IPv4
1440 compatible is very rare. You should take caution if you see those on the wire.
1442 If we see IPv6 packets with IPv4 mapped address (::ffff:0.0.0.0/96) in the
1443 header in dual-stack environment (not in SIIT environment), they indicate
1444 that someone is trying to impersonate IPv4 peer. The packet should be dropped.
1446 IPv6 specifications do not talk very much about IPv6 unspecified address (::)
1447 in the IPv6 source address field. Clarification is in progress.
1448 Here are couple of comments:
1449 - IPv6 unspecified address can be used in IPv6 source address field, if and
1450 only if we have no legal source address for the node. The legal situations
1451 include, but may not be limited to, (1) MLD while no IPv6 address is assigned
1452 to the node and (2) DAD.
1453 - If IPv6 TCP packet has IPv6 unspecified address, it is an attack attempt.
1454 The form can be used as a trigger for TCP DoS attack. KAME code already
1456 - The following examples are seemingly illegal. It seems that there's general
1457 consensus among ipngwg for those. (1) Mobile IPv6 home address option,
1458 (2) offlink packets (so routers should not forward them).
1459 KAME implements (2) already.
1461 KAME code is carefully written to avoid such incidents. More specifically,
1462 KAME kernel will reject packets with certain source/destination address in IPv6
1463 base header, or IPv6 routing header. Also, KAME default configuration file
1464 is written carefully, to avoid those attacks.
1466 draft-itojun-ipv6-transition-abuse-01.txt, draft-cmetz-v6ops-v4mapped-api-
1467 harmful-00.txt and draft-itojun-v6ops-v4mapped-harmful-01.txt has more on
1470 1.15 Node's required addresses
1472 RFC2373 section 2.8 talks about required addresses for an IPv6
1473 node. The section talks about how KAME stack manages those required
1478 The following items are automatically assigned to the node (or the node will
1479 automatically joins the group), at bootstrap time:
1481 - All-nodes multicast addresses (ff01::1)
1483 The following items will be automatically handled when the interface becomes
1485 - Its link-local address for each interface
1486 - Solicited-node multicast address for link-local addresses
1487 - Link-local allnodes multicast address (ff02::1)
1489 The following items need to be configured manually by ifconfig(8) or prefix(8).
1490 Alternatively, these can be autoconfigured by using stateless address
1492 - Assigned unicast/anycast addresses
1493 - Solicited-Node multicast address for assigned unicast address
1495 Users can join groups by using appropriate system calls like setsockopt(2).
1499 In addition to the above, routers needs to handle the following items.
1501 The following items need to be configured manually by using ifconfig(8).
1502 o The subnet-router anycast addresses for the interfaces it is configured
1503 to act as a router on (prefix::/64)
1504 o All other anycast addresses with which the router has been configured
1506 The router will join the following multicast group when rtadvd(8) is available
1508 o All-Routers Multicast Addresses (ff02::2)
1510 Routing daemons will join appropriate multicast groups, as necessary,
1511 like ff02::9 for RIPng.
1513 Users can join groups by using appropriate system calls like setsockopt(2).
1517 Current KAME kernel implements RFC3542 API. It also implements RFC2292 API,
1518 for backward compatibility purposes with *BSD-integrated codebase.
1519 KAME tree ships with RFC3542 headers.
1520 *BSD-integrated codebase implements either RFC2292, or RFC3542, API.
1521 see "COVERAGE" document for detailed implementation status.
1523 Here are couple of issues to mention:
1524 - *BSD-integrated binaries, compiled for RFC2292, will work on KAME kernel.
1525 For example, OpenBSD 2.7 /sbin/rtsol will work on KAME/openbsd kernel.
1526 - KAME binaries, compiled using RFC3542, will not work on *BSD-integrated
1527 kenrel. For example, KAME /usr/local/v6/sbin/rtsol will not work on
1529 - RFC3542 API is not compatible with RFC2292 API. RFC3542 #define symbols
1530 conflict with RFC2292 symbols. Therefore, if you compile programs that
1531 assume RFC2292 API, the compilation itself goes fine, however, the compiled
1532 binary will not work correctly. The problem is not KAME issue, but API
1533 issue. For example, Solaris 8 implements RFC3542 API. If you compile
1534 RFC2292-based code on Solaris 8, the binary can behave strange.
1536 There are few (or couple of) incompatible behavior in RFC2292 binary backward
1537 compatibility support in KAME tree. To enumerate:
1538 - Type 0 routing header lacks support for strict/loose bitmap.
1539 Even if we see packets with "strict" bit set, those bits will not be made
1540 visible to the userland.
1541 Background: RFC2292 document is based on RFC1883 IPv6, and it uses
1542 strict/loose bitmap. RFC3542 document is based on RFC2460 IPv6, and it has
1543 no strict/loose bitmap (it was removed from RFC2460). KAME tree obeys
1544 RFC2460 IPv6, and lacks support for strict/loose bitmap.
1546 The RFC3542 documents leave some particular cases unspecified. The
1547 KAME implementation treats them as follows:
1548 - The IPV6_DONTFRAG and IPV6_RECVPATHMTU socket options for TCP
1549 sockets are ignored. That is, the setsocktopt() call will succeed
1550 but the specified value will have no effect.
1554 KAME ships with modified DNS resolver, in libinet6.a.
1555 libinet6.a has a couple of extensions against libc DNS resolver:
1556 - Can take "options insecure1" and "options insecure2" in /etc/resolv.conf,
1557 which toggles RES_INSECURE[12] option flag bit.
1558 - EDNS0 receive buffer size notification support. It can be enabled by
1559 "options edns0" in /etc/resolv.conf. See USAGE for details.
1560 - IPv6 transport support (queries/responses over IPv6). Most of BSD official
1561 releases now has it already.
1562 - Partial A6 chain chasing/DNAME/bit string label support (KAME/BSDI4).
1567 KAME requires three items to be added into the standard drivers:
1569 (1) (freebsd[234] and bsdi[34] only) mbuf clustering requirement.
1570 In this stable release, we changed MINCLSIZE into MHLEN+1 for all the
1571 operating systems in order to make all the drivers behave as we expect.
1573 (2) multicast. If "ifmcstat" yields no multicast group for a
1574 interface, that interface has to be patched.
1576 To avoid troubles, we suggest you to comment out the device drivers
1577 for unsupported/unnecessary cards, from the kernel configuration file.
1578 If you accidentally enable unsupported drivers, some of the userland
1579 tools may not work correctly (routing daemons are typical example).
1581 In the following sections, "official support" means that KAME developers
1582 are using that ethernet card/driver frequently.
1584 (NOTE: In the past we required all pcmcia drivers to have a call to
1585 in6_ifattach(). We have no such requirement any more)
1587 2.1 FreeBSD 2.2.x-RELEASE
1589 Here is a list of FreeBSD 2.2.x-RELEASE drivers and its conditions:
1591 driver mbuf(1) multicast(2) official support?
1611 sr looks ok ok - (**)
1613 You may want to add an invocation of "rtsol" in "/etc/pccard_ether",
1614 if you are using notebook computers and PCMCIA ethernet card.
1616 (*) These drivers are distributed with PAO (http://www.jp.freebsd.org/PAO/).
1618 (**) There was some report says that, if you make sr driver up and down and
1619 then up, the kernel may hang up. We have disabled frame-relay support from
1620 sr driver and after that this looks to be working fine. If you need
1621 frame-relay support to come back, please contact KAME developers.
1625 The following lists BSD/OS 3.x device drivers and its conditions:
1627 driver mbuf(1) multicast(2) official support?
1648 You may want to use "@insert" directive in /etc/pccard.conf to invoke
1649 "rtsol" command right after dynamic insertion of PCMCIA ethernet cards.
1653 The following table lists the network drivers we have tried so far.
1655 driver mbuf(1) multicast(2) official support?
1658 awi pcmcia/i386 ok ok -
1659 bah zbus/amiga NG(*)
1660 cnw pcmcia/i386 ok ok yes
1661 ep pcmcia/i386 ok ok -
1662 fxp pci/i386 ok(*2) ok -
1663 tlp pci/i386 ok ok -
1664 le sbus/sparc ok ok yes
1665 ne pci/i386 ok ok yes
1666 ne pcmcia/i386 ok ok yes
1667 rtk pci/i386 ok ok -
1668 wi pcmcia/i386 ok ok yes
1672 (*) This may need some fix, but I'm not sure what arcnet interfaces assume...
1674 2.4 FreeBSD 3.x-RELEASE
1676 Here is a list of FreeBSD 3.x-RELEASE drivers and its conditions:
1678 driver mbuf(1) multicast(2) official support?
1691 (*) These drivers are distributed with PAO as PAO3
1692 (http://www.jp.freebsd.org/PAO/).
1693 (**) there were trouble reports with multicast filter initialization.
1695 More drivers will just simply work on KAME FreeBSD 3.x-RELEASE but have not
1698 2.5 FreeBSD 4.x-RELEASE
1700 Here is a list of FreeBSD 4.x-RELEASE drivers and its conditions:
1709 Here is a list of OpenBSD 2.x drivers and its conditions:
1711 driver mbuf(1) multicast(2) official support?
1714 de pci/i386 ok ok yes
1716 le sbus/sparc ok ok yes
1717 ne pci/i386 ok ok yes
1718 ne pcmcia/i386 ok ok yes
1719 wi pcmcia/i386 ok ok yes
1721 (*) There seem to be some problem in driver, with multicast filter
1722 configuration. This happens with certain revision of chipset on the card.
1723 Should be fixed by now by workaround in sys/net/if.c, but still not sure.
1727 The following lists BSD/OS 4.x device drivers and its conditions:
1729 driver mbuf(1) multicast(2) official support?
1735 You may want to use "@insert" directive in /etc/pccard.conf to invoke
1736 "rtsol" command right after dynamic insertion of PCMCIA ethernet cards.
1738 (*) exp driver has serious conflict with KAME initialization sequence.
1739 A workaround is committed into sys/i386/pci/if_exp.c, and should be okay by now.
1744 We categorize IPv4/IPv6 translator into 4 types.
1746 Translator A --- It is used in the early stage of transition to make
1747 it possible to establish a connection from an IPv6 host in an IPv6
1748 island to an IPv4 host in the IPv4 ocean.
1750 Translator B --- It is used in the early stage of transition to make
1751 it possible to establish a connection from an IPv4 host in the IPv4
1752 ocean to an IPv6 host in an IPv6 island.
1754 Translator C --- It is used in the late stage of transition to make it
1755 possible to establish a connection from an IPv4 host in an IPv4 island
1756 to an IPv6 host in the IPv6 ocean.
1758 Translator D --- It is used in the late stage of transition to make it
1759 possible to establish a connection from an IPv6 host in the IPv6 ocean
1760 to an IPv4 host in an IPv4 island.
1762 KAME provides an TCP relay translator for category A. This is called
1763 "FAITH". We also provide IP header translator for category A.
1765 3.1 FAITH TCP relay translator
1767 FAITH system uses TCP relay daemon called "faithd" helped by the KAME kernel.
1768 FAITH will reserve an IPv6 address prefix, and relay TCP connection
1769 toward that prefix to IPv4 destination.
1771 For example, if the reserved IPv6 prefix is 3ffe:0501:0200:ffff::, and
1772 the IPv6 destination for TCP connection is 3ffe:0501:0200:ffff::163.221.202.12,
1773 the connection will be relayed toward IPv4 destination 163.221.202.12.
1775 destination IPv4 node (163.221.202.12)
1777 | IPv4 tcp toward 163.221.202.12
1778 FAITH-relay dual stack node
1780 | IPv6 TCP toward 3ffe:0501:0200:ffff::163.221.202.12
1783 faithd must be invoked on FAITH-relay dual stack node.
1785 For more details, consult kame/kame/faithd/README and RFC3142.
1787 3.2 IPv6-to-IPv4 header translator
1794 IPsec is implemented as the following three components.
1796 (1) Policy Management
1798 (3) AH, ESP and IPComp handling in kernel
1800 Note that KAME/OpenBSD does NOT include support for KAME IPsec code,
1801 as OpenBSD team has their home-brew IPsec stack and they have no plan
1802 to replace it. IPv6 support for IPsec is, therefore, lacking on KAME/OpenBSD.
1804 http://www.netbsd.org/Documentation/network/ipsec/ has more information
1805 including usage examples.
1807 4.1 Policy Management
1809 The kernel implements experimental policy management code. There are two ways
1810 to manage security policy. One is to configure per-socket policy using
1811 setsockopt(3). In this cases, policy configuration is described in
1812 ipsec_set_policy(3). The other is to configure kernel packet filter-based
1813 policy using PF_KEY interface, via setkey(8).
1815 The policy entry will be matched in order. The order of entries makes
1816 difference in behavior.
1820 The key management code implemented in this kit (sys/netkey) is a
1821 home-brew PFKEY v2 implementation. This conforms to RFC2367.
1823 The home-brew IKE daemon, "racoon" is included in the kit (kame/kame/racoon,
1824 or usr.sbin/racoon).
1825 Basically you'll need to run racoon as daemon, then setup a policy
1826 to require keys (like ping -P 'out ipsec esp/transport//use').
1827 The kernel will contact racoon daemon as necessary to exchange keys.
1829 In IKE spec, there's ambiguity about interpretation of "tunnel" proposal.
1830 For example, if we would like to propose the use of following packet:
1831 IP AH ESP IP payload
1832 some implementation proposes it as "AH transport and ESP tunnel", since
1833 this is more logical from packet construction point of view. Some
1834 implementation proposes it as "AH tunnel and ESP tunnel".
1835 Racoon follows the latter route (previously it followed the former, and
1836 the latter interpretation seems to be popular/consensus).
1837 This raises real interoperability issue. We hope this to be resolved quickly.
1839 racoon does not implement byte lifetime for both phase 1 and phase 2
1840 (RFC2409 page 35, Life Type = kilobytes).
1842 4.3 AH and ESP handling
1844 IPsec module is implemented as "hooks" to the standard IPv4/IPv6
1845 processing. When sending a packet, ip{,6}_output() checks if ESP/AH
1846 processing is required by checking if a matching SPD (Security
1847 Policy Database) is found. If ESP/AH is needed,
1848 {esp,ah}{4,6}_output() will be called and mbuf will be updated
1849 accordingly. When a packet is received, {esp,ah}4_input() will be
1850 called based on protocol number, i.e. (*inetsw[proto])().
1851 {esp,ah}4_input() will decrypt/check authenticity of the packet,
1852 and strips off daisy-chained header and padding for ESP/AH. It is
1853 safe to strip off the ESP/AH header on packet reception, since we
1854 will never use the received packet in "as is" form.
1856 By using ESP/AH, TCP4/6 effective data segment size will be affected by
1857 extra daisy-chained headers inserted by ESP/AH. Our code takes care of
1860 Basic crypto functions can be found in directory "sys/crypto". ESP/AH
1861 transform are listed in {esp,ah}_core.c with wrapper functions. If you
1862 wish to add some algorithm, add wrapper function in {esp,ah}_core.c, and
1863 add your crypto algorithm code into sys/crypto.
1865 Tunnel mode works basically fine, but comes with the following restrictions:
1866 - You cannot run routing daemon across IPsec tunnel, since we do not model
1867 IPsec tunnel as pseudo interfaces.
1868 - Authentication model for AH tunnel must be revisited. We'll need to
1869 improve the policy management engine, eventually.
1870 - Path MTU discovery does not work across IPv6 IPsec tunnel gateway due to
1873 AH specification does not talk much about "multiple AH on a packet" case.
1874 We incrementally compute AH checksum, from inside to outside. Also, we
1875 treat inner AH to be immutable.
1876 For example, if we are to create the following packet:
1877 IP AH1 AH2 AH3 payload
1878 we do it incrementally. As a result, we get crypto checksums like below:
1879 AH3 has checksum against "IP AH3' payload".
1880 where AH3' = AH3 with checksum field filled with 0.
1881 AH2 has checksum against "IP AH2' AH3 payload".
1882 AH1 has checksum against "IP AH1' AH2 AH3 payload",
1883 Also note that AH3 has the smallest sequence number, and AH1 has the largest
1886 To avoid traffic analysis on shorter packets, ESP output logic supports
1887 random length padding. By setting net.inet.ipsec.esp_randpad (or
1888 net.inet6.ipsec6.esp_randpad) to positive value N, you can ask the kernel
1889 to randomly pad packets shorter than N bytes, to random length smaller than
1890 or equal to N. Note that N does not include ESP authentication data length.
1891 Also note that the random padding is not included in TCP segment
1892 size computation. Negative value will turn off the functionality.
1893 Recommended value for N is like 128, or 256. If you use a too big number
1894 as N, you may experience inefficiency due to fragmented packets.
1898 IPComp stands for IP payload compression protocol. This is aimed for
1899 payload compression, not the header compression like PPP VJ compression.
1900 This may be useful when you are using slow serial link (say, cell phone)
1901 with powerful CPU (well, recent notebook PCs are really powerful...).
1902 The protocol design of IPComp is very similar to IPsec, though it was
1903 defined separately from IPsec itself.
1905 Here are some points to be noted:
1906 - IPComp is treated as part of IPsec protocol suite, and SPI and
1907 CPI space is unified. Spec says that there's no relationship
1908 between two so they are assumed to be separate in specs.
1909 - IPComp association (IPCA) is kept in SAD.
1910 - It is possible to use well-known CPI (CPI=2 for DEFLATE for example),
1911 for outbound/inbound packet, but for indexing purposes one element from
1912 SPI/CPI space will be occupied anyway.
1913 - pfkey is modified to support IPComp. However, there's no official
1914 SA type number assignment yet. Portability with other IPComp
1915 stack is questionable (anyway, who else implement IPComp on UN*X?).
1916 - Spec says that IPComp output processing must be performed before AH/ESP
1917 output processing, to achieve better compression ratio and "stir" data
1918 stream before encryption. The most meaningful processing order is:
1919 (1) compress payload by IPComp, (2) encrypt payload by ESP, then (3) attach
1920 authentication data by AH.
1921 However, with manual SPD setting, you are able to violate the ordering
1922 (KAME code is too generic, maybe). Also, it is just okay to use IPComp
1923 alone, without AH/ESP.
1924 - Though the packet size can be significantly decreased by using IPComp, no
1925 special consideration is made about path MTU (spec talks nothing about MTU
1926 consideration). IPComp is designed for serial links, not ethernet-like
1928 - You can change compression ratio on outbound packet, by changing
1929 deflate_policy in sys/netinet6/ipcomp_core.c. You can also change outbound
1930 history buffer size by changing deflate_window_out in the same source code.
1931 (should it be sysctl accessible, or per-SAD configurable?)
1932 - Tunnel mode IPComp is not working right. KAME box can generate tunnelled
1933 IPComp packet, however, cannot accept tunneled IPComp packet.
1934 - You can negotiate IPComp association with racoon IKE daemon.
1935 - KAME code does not attach Adler32 checksum to compressed data.
1936 see ipsec wg mailing list discussion in Jan 2000 for details.
1938 4.5 Conformance to RFCs and IDs
1940 The IPsec code in the kernel conforms (or, tries to conform) to the
1941 following standards:
1942 "old IPsec" specification documented in rfc182[5-9].txt
1943 "new IPsec" specification documented in:
1944 rfc240[1-6].txt rfc241[01].txt rfc2451.txt rfc3602.txt
1946 RFC2393: IP Payload Compression Protocol (IPComp)
1947 IKE specifications (rfc240[7-9].txt) are implemented in userland
1948 as "racoon" IKE daemon.
1950 Currently supported algorithms are:
1952 null crypto checksum (no document, just for debugging)
1953 keyed MD5 with 128bit crypto checksum (rfc1828.txt)
1954 keyed SHA1 with 128bit crypto checksum (no document)
1955 HMAC MD5 with 128bit crypto checksum (rfc2085.txt)
1956 HMAC SHA1 with 128bit crypto checksum (no document)
1957 HMAC RIPEMD160 with 128bit crypto checksum (no document)
1959 null encryption (no document, similar to rfc2410.txt)
1960 DES-CBC mode (rfc1829.txt)
1962 null crypto checksum (no document, just for debugging)
1963 keyed MD5 with 96bit crypto checksum (no document)
1964 keyed SHA1 with 96bit crypto checksum (no document)
1965 HMAC MD5 with 96bit crypto checksum (rfc2403.txt
1966 HMAC SHA1 with 96bit crypto checksum (rfc2404.txt)
1967 HMAC SHA2-256 with 96bit crypto checksum (draft-ietf-ipsec-ciph-sha-256-00.txt)
1968 HMAC SHA2-384 with 96bit crypto checksum (no document)
1969 HMAC SHA2-512 with 96bit crypto checksum (no document)
1970 HMAC RIPEMD160 with 96bit crypto checksum (RFC2857)
1971 AES XCBC MAC with 96bit crypto checksum (RFC3566)
1973 null encryption (rfc2410.txt)
1974 DES-CBC with derived IV
1975 (draft-ietf-ipsec-ciph-des-derived-01.txt, draft expired)
1976 DES-CBC with explicit IV (rfc2405.txt)
1977 3DES-CBC with explicit IV (rfc2451.txt)
1978 BLOWFISH CBC (rfc2451.txt)
1979 CAST128 CBC (rfc2451.txt)
1980 RIJNDAEL/AES CBC (rfc3602.txt)
1981 AES counter mode (rfc3686.txt)
1983 each of the above can be combined with new IPsec AH schemes for
1986 RFC2394: IP Payload Compression Using DEFLATE
1988 The following algorithms are NOT supported:
1990 HMAC MD5 with 128bit crypto checksum + 64bit replay prevention
1992 keyed SHA1 with 160bit crypto checksum + 32bit padding (rfc1852.txt)
1994 The key/policy management API is based on the following document, with fair
1995 amount of extensions:
1996 RFC2367: PF_KEY key management API
1998 4.6 ECN consideration on IPsec tunnels
2000 KAME IPsec implements ECN-friendly IPsec tunnel, described in
2001 draft-ietf-ipsec-ecn-02.txt.
2002 Normal IPsec tunnel is described in RFC2401. On encapsulation,
2003 IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner
2004 IP header to outer IP header. On decapsulation outer IP header
2005 will be simply dropped. The decapsulation rule is not compatible
2006 with ECN, since ECN bit on the outer IP TOS/traffic class field will be
2008 To make IPsec tunnel ECN-friendly, we should modify encapsulation
2009 and decapsulation procedure. This is described in
2010 draft-ietf-ipsec-ecn-02.txt, chapter 3.3.
2012 KAME IPsec tunnel implementation can give you three behaviors, by setting
2013 net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some value:
2014 - RFC2401: no consideration for ECN (sysctl value -1)
2015 - ECN forbidden (sysctl value 0)
2016 - ECN allowed (sysctl value 1)
2017 Note that the behavior is configurable in per-node manner, not per-SA manner
2018 (draft-ietf-ipsec-ecn-02 wants per-SA configuration, but it looks too much
2021 The behavior is summarized as follows (see source code for more detail):
2023 encapsulate decapsulate
2025 RFC2401 copy all TOS bits drop TOS bits on outer
2026 from inner to outer. (use inner TOS bits as is)
2028 ECN forbidden copy TOS bits except for ECN drop TOS bits on outer
2029 (masked with 0xfc) from inner (use inner TOS bits as is)
2030 to outer. set ECN bits to 0.
2032 ECN allowed copy TOS bits except for ECN use inner TOS bits with some
2033 CE (masked with 0xfe) from change. if outer ECN CE bit
2034 inner to outer. is 1, enable ECN CE bit on
2035 set ECN CE bit to 0. the inner.
2037 General strategy for configuration is as follows:
2038 - if both IPsec tunnel endpoint are capable of ECN-friendly behavior,
2039 you'd better configure both end to "ECN allowed" (sysctl value 1).
2040 - if the other end is very strict about TOS bit, use "RFC2401"
2042 - in other cases, use "ECN forbidden" (sysctl value 0).
2043 The default behavior is "ECN forbidden" (sysctl value 0).
2045 For more information, please refer to:
2046 draft-ietf-ipsec-ecn-02.txt
2047 RFC2481 (Explicit Congestion Notification)
2048 KAME sys/netinet6/{ah,esp}_input.c
2050 (Thanks goes to Kenjiro Cho <kjc@csl.sony.co.jp> for detailed analysis)
2052 4.7 Interoperability
2054 IPsec, IPComp (in kernel) and IKE (in userland as "racoon") has been tested
2055 at several interoperability test events, and it is known to interoperate
2056 with many other implementations well. Also, KAME IPsec has quite wide
2057 coverage for IPsec crypto algorithms documented in RFC (we do not cover
2058 algorithms with intellectual property issues, though).
2060 Here are (some of) platforms we have tested IPsec/IKE interoperability
2061 in the past, no particular order. Note that both ends (KAME and
2062 others) may have modified their implementation, so use the following
2063 list just for reference purposes.
2064 6WIND, ACC, Allied-telesis, Altiga, Ashley-laurent (vpcom.com),
2065 BlueSteel, CISCO IOS, Checkpoint FW-1, Compaq Tru54 UNIX
2066 X5.1B-BL4, Cryptek, Data Fellows (F-Secure), Ericsson,
2067 F-Secure VPN+ 5.40, Fitec, Fitel, FreeS/WAN, HITACHI, HiFn,
2068 IBM AIX 5.1, III, IIJ (fujie stack), Intel Canada, Intel
2069 Packet Protect, MEW NetCocoon, MGCS, Microsoft WinNT/2000/XP,
2070 NAI PGPnet, NEC IX5000, NIST (linux IPsec + plutoplus),
2071 NetLock, Netoctave, Netopia, Netscreen, Nokia EPOC, Nortel
2072 GatewayController/CallServer 2000 (not released yet),
2073 NxNetworks, OpenBSD isakmpd on OpenBSD, Oullim information
2074 technologies SECUREWORKS VPN gateway 3.0, Pivotal, RSA,
2075 Radguard, RapidStream, RedCreek, Routerware, SSH, SecGo
2076 CryptoIP v3, Secure Computing, Soliton, Sun Solaris 8,
2077 TIS/NAI Gauntret, Toshiba, Trilogy AdmitOne 2.6, Trustworks
2078 TrustedClient v3.2, USAGI linux, VPNet, Yamaha RT series,
2081 Here are (some of) platforms we have tested IPComp/IKE interoperability
2082 in the past, in no particular order.
2083 Compaq, IRE, SSH, NetLock, FreeS/WAN, F-Secure VPN+ 5.40
2085 VPNC (vpnc.org) provides IPsec conformance tests, using KAME and OpenBSD
2086 IPsec/IKE implementations. Their test results are available at
2087 http://www.vpnc.org/conformance.html, and it may give you more idea
2088 about which implementation interoperates with KAME IPsec/IKE implementation.
2090 4.8 Operations with IPsec tunnel mode
2092 First of all, IPsec tunnel is a very hairy thing. It seems to do a neat thing
2093 like VPN configuration or secure remote accesses, however, it comes with lots
2094 of architectural twists.
2096 RFC2401 defines IPsec tunnel mode, within the context of IPsec. RFC2401
2097 defines tunnel mode packet encapsulation/decapsulation on its own, and
2098 does not refer other tunnelling specifications. Since RFC2401 advocates
2099 filter-based SPD database matches, it would be natural for us to implement
2100 IPsec tunnel mode as filters - not as pseudo interfaces.
2102 There are some people who are trying to separate IPsec "tunnel mode" from
2103 the IPsec itself. They would like to implement IPsec transport mode only,
2104 and combine it with tunneling pseudo devices. The prime example is found
2105 in draft-touch-ipsec-vpn-01.txt. However, if you really define pseudo
2106 interfaces separately from IPsec, IKE daemons would need to negotiate
2107 transport mode SAs, instead of tunnel mode SAs. Therefore, we cannot
2108 really mix RFC2401-based interpretation and draft-touch-ipsec-vpn-01.txt
2111 The KAME stack implements can be configured in two ways. You may need
2112 to recompile your kernel to switch the behavior.
2113 - RFC2401 IPsec tunnel mode approach (4.8.1)
2114 - draft-touch-ipsec-vpn approach (4.8.2)
2115 Works in all kernel configuration, but racoon(8) may not interoperate.
2117 There are pros and cons on these approaches:
2119 RFC2401 IPsec tunnel mode (filter-like) approach
2120 PRO: SPD lookup fits nicely with packet filters (if you integrate them)
2121 CON: cannot run routing daemons across IPsec tunnels
2122 CON: it is very hard to control source address selection on originating
2124 ???: IPv6 scope zone is kept the same
2125 draft-touch-ipsec-vpn (transportmode + Pseudo-interface) approach
2126 PRO: run routing daemons across IPsec tunnels
2127 PRO: source address selection can be done normally, by looking at
2128 IPsec tunnel pseudo devices
2129 CON: on outbound, possibility of infinite loops if routing setup
2131 CON: due to differences in encap/decap logic from RFC2401, it may not
2132 interoperate with very picky RFC2401 implementations
2133 (those who check TOS bits, for example)
2134 CON: cannot negotiate IKE with other IPsec tunnel-mode devices
2135 (the other end has to implement
2136 ???: IPv6 scope zone is likely to be different from the real ethernet
2139 The recommendation is different depending on the situation you have:
2140 - use draft-touch-ipsec-vpn if you have the control over the other end.
2141 this one is the best in terms of simplicity.
2142 - if the other end is normal IPsec device with RFC2401 implementation,
2143 you need to use RFC2401, otherwise you won't be able to run IKE.
2144 - use RFC2401 approach if you just want to forward packets back and forth
2145 and there's no plan to use IPsec gateway itself as an originating device.
2147 4.8.1 RFC2401 IPsec tunnel mode approach
2149 To configure your device as RFC2401 IPsec tunnel mode endpoint, you will
2150 use "tunnel" keyword in setkey(8) "spdadd" directives. Let us assume the
2151 following topology (A and B could be a network, like prefix/length):
2153 ((((((((((((The internet))))))))))))
2156 your device peer's device
2158 ==+===== VPN net ==+===== VPN net
2160 The policy configuration directive is like this. You will need manual
2161 SAs, or IKE daemon, for actual encryption:
2164 spdadd A B any -P out ipsec esp/tunnel/C-D/use;
2165 spdadd B A any -P in ipsec esp/tunnel/D-C/use;
2168 The inbound/outbound traffic is monitored/captured by SPD engine, which works
2169 just like packet filters.
2171 With this, forwarding case should work flawlessly. However, troubles arise
2172 when you have one of the following requirements:
2173 - When you originate traffic from your VPN gateway device to VPN net on the
2174 other end (like B), you want your source address to be A (private side)
2175 so that the traffic would be protected by the policy.
2176 With this approach, however, the source address selection logic follows
2177 normal routing table, and C (global side) will be picked for any outgoing
2178 traffic, even if the destination is B. The resulting packet will be like
2181 and will not match the policy (= sent in clear).
2182 - When you want to run routing protocols on top of the IPsec tunnel, it is
2183 not possible. As there is no pseudo device that identifies the IPsec tunnel,
2184 you cannot identify where the routing information came from. As a result,
2185 you can't run routing daemons.
2187 4.8.2 draft-touch-ipsec-vpn approach
2189 With this approach, you will configure gif(4) tunnel interfaces, as well as
2190 IPsec transport mode SAs.
2192 # gifconfig gif0 C D
2195 spdadd C D any -P out ipsec esp/transport//use;
2196 spdadd D C any -P in ipsec esp/transport//use;
2199 Since we have a pseudo-interface "gif0", and it affects the routes and
2200 the source address selection logic, we can have source address A, for
2201 packets originated by the VPN gateway to B (and the VPN cloud).
2202 We can also exchange routing information over the tunnel (gif0), as the tunnel
2203 is represented as a pseudo interface (dynamic routes points to the
2206 There is a big drawbacks, however; with this, you can use IKE if and only if
2207 the other end is using draft-touch-ipsec-vpn approach too. Since racoon(8)
2208 grabs phase 2 IKE proposals from the kernel SPD database, you will be
2209 negotiating IPsec transport-mode SAs with the other end, not tunnel-mode SAs.
2210 Also, since the encapsulation mechanism is different from RFC2401, you may not
2211 be able to interoperate with a picky RFC2401 implementations - if the other
2212 end checks certain outer IP header fields (like TOS), you will not be able to
2218 KAME kit includes ALTQ, which supports FreeBSD3, FreeBSD4, FreeBSD5
2219 NetBSD. OpenBSD has ALTQ merged into pf and its ALTQ code is not
2220 compatible with other platforms so that KAME's ALTQ is not used for
2221 OpenBSD. For BSD/OS, ALTQ does not work.
2222 ALTQ in KAME supports IPv6.
2223 (actually, ALTQ is developed on KAME repository since ALTQ 2.1 - Jan 2000)
2225 ALTQ occupies single character device number. For FreeBSD, it is officially
2226 allocated. For OpenBSD and NetBSD, we use the number which is not
2227 currently allocated (will eventually get an official number).
2228 The character device is enabled for i386 architecture only. To enable and
2229 compile ALTQ-ready kernel for other architectures, take the following steps:
2230 - assume that your architecture is FOOBAA.
2231 - modify sys/arch/FOOBAA/FOOBAA/conf.c (or somewhere that defines cdevsw),
2232 to include a line for ALTQ. look at sys/arch/i386/i386/conf.c for
2233 example. The major number must be same as i386 case.
2234 - copy kernel configuration file (like ALTQ.v6 or GENERIC.v6) from i386,
2235 and modify accordingly.
2237 - before building userland, change netbsd/{lib,usr.sbin,usr.bin}/Makefile
2238 (or openbsd/foobaa) so that it will visit altq-related sub directories.
2243 6.1 KAME node as correspondent node
2245 Default installation recognizes home address option (in destination
2246 options header). No sub-options are supported. Interaction with
2247 IPsec, and/or 2292bis API, needs further study.
2249 6.2 KAME node as home agent/mobile node
2251 KAME kit includes Ericsson mobile-ip6 code. The integration is just started
2252 (in Feb 2000), and we will need some more time to integrate it better.
2254 See kame/mip6config/{QUICKSTART,README_MIP6.txt} for more details.
2256 The Ericsson code implements revision 09 of the mobile-ip6 draft. There
2257 are other implementations available:
2258 NEC: http://www.6bone.nec.co.jp/mipv6/internal-dist/ (-13 draft)
2259 SFC: http://neo.sfc.wide.ad.jp/~mip6/ (-13 draft)
2263 The KAME developers basically do not make a bother about coding
2264 style. However, there is still some agreement on the style, in order
2265 to make the distributed development smooth.
2267 - follow *BSD KNF where possible. note: there are multiple KNF standards.
2268 - the tab character should be 8 columns wide (tabstops are at 8, 16, 24, ...
2269 column). With vi, use ":set ts=8 sw=8".
2270 With GNU Emacs 20 and later, the easiest way is to use the "bsd" style of
2271 cc-mode with the variable "c-basic-offset" being 8;
2272 (add-hook 'c-mode-common-hook
2276 (setq c-basic-offset 8) ; XXX for Emacs 20 only
2278 The "bsd" style in GNU Emacs 21 sets the variable to 8 by default,
2279 so the line marked by "XXX" is not necessary if you only use GNU
2281 - each line should be within 80 characters.
2282 - keep a single open/close bracket in a comment such as in the following
2284 putchar('('); /* ) */
2285 without this, some vi users would have a hard time to match a pair of
2286 brackets. Although this type of bracket seems clumsy and is even
2287 harmful for some other type of vi users and Emacs users, the
2288 agreement in the KAME developers is to allow it.
2289 - add the following line to the head of every KAME-derived file:
2290 /* (dollar)KAME(dollar) */
2291 where "(dollar)" is the dollar character ($), and around "$" are tabs.
2292 (this is for C. For other language, you should use its own comment
2294 Once committed to the CVS repository, this line will contain its
2295 version number (see, for example, at the top of this file). This
2296 would make it easy to report a bug.
2297 - when creating a new file with the WIDE copyright, tap "make copyright.c" at
2298 the top-level, and use copyright.c as a template. KAME RCS tag will be
2299 included automatically.
2300 - when editing a third-party package, keep its own coding style as
2301 much as possible, even if the style does not follow the items above.
2302 - it is recommended to always wrap an expression containing
2303 bitwise operators by parentheses, especially when the expression is
2304 combined with relational operators, in order to avoid unintentional
2305 mismatch of operators. Thus, we should write
2306 if ((a & b) == 0) /* (A) */
2308 if (a & (b == 0)) /* (B) */
2310 if (a & b == 0) /* (C) */
2311 even if the programmer's intention was (C), which is equivalent to
2312 (B) according to the grammar of the language C.
2313 Thus, we should write a code to test if a bit-flag is set for a
2314 given variable as follows:
2315 if ((flag & FLAG_A) == 0) /* (D) the FLAG_A is NOT set */
2316 if ((flag & FLAG_A) != 0) /* (E) the FLAG_A is set */
2317 Some developers in the KAME project rather prefer the following style:
2318 if (!(flag & FLAG_A)) /* (F) the FLAG_A is NOT set */
2319 if ((flag & FLAG_A)) /* (G) the FLAG_A is set */
2320 because it would be more intuitive in terms of the relationship
2321 between the negation operator (!) and the semantics of the
2322 condition. The KAME developers have discussed the style, and have
2323 agreed that all the styles from (D) to (G) are valid. So, when you
2324 see styles like (D) and (E) in the KAME code and feel a bit strange,
2325 please just keep them. They are intentional.
2326 - When inserting a separate block just to define some intra-block
2327 variables, add the level of indentation as if the block was in a
2328 control statement such as if-else, for, or while. For example,
2338 should be used, instead of
2348 - Do not use printf() or log() in the packet input path of the kernel code.
2349 They can make the system vulnerable to packet flooding attacks (results in
2351 - (not a style issue)
2352 To disable a module that is mistakenly imported (by CVS), just
2353 remove the source tree in the repository. Note, however, that the
2354 removal might annoy other developers who have already checked the
2355 module out, so you should announce the removal as soon as possible.
2356 Also, be 100% sure not to remove other modules.
2358 When you want to contribute something to the KAME project, and if *you
2359 do not mind* the agreement, it would be helpful for the project to
2360 keep these rules. Note, however, that we would never intend to force
2361 you to adopt our rules. We would rather regard your own style,
2362 especially when you have a policy about the style.
2365 8. Policy on technology with intellectual property right restriction
2367 There are quite a few IETF documents/whatever which has intellectual property
2368 right (IPR) restriction. KAME's stance is stated below.
2370 The goal of KAME is to provide freely redistributable, BSD-licensed,
2371 implementation of Internet protocol technologies.
2372 For this purpose, we implement protocols that (1) do not need license
2373 contract with IPR holder, and (2) are royalty-free.
2374 The reason for (1) is, even if KAME contracts with the IPR holder in
2375 question, the users of KAME stack (usually implementers of some other
2376 codebase) would need to make a license contract with the IPR holder.
2377 It would damage the "freely redistributable" status of KAME codebase.
2379 By doing so KAME is (implicitly) trying to advocate no-license-contract,
2380 royalty-free, release of IPRs.
2382 Note however, as documented in README, we do not guarantee that KAME code
2383 is free of IPR infringement, you MUST check it if you are to integrate
2384 KAME into your product (or whatever):
2385 READ CAREFULLY: Several countries have legal enforcement for
2386 export/import/use of cryptographic software. Check it before playing
2387 with the kit. We do not intend to be your legalese clearing house
2388 (NO WARRANTY). If you intend to include KAME stack into your product,
2389 you'll need to check if the licenses on each file fit your situations,
2390 and/or possible intellectual property right issues.
2392 <end of IMPLEMENTATION>