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