1 Implementation Note
2
3 KAME Project
4 http://www.kame.net/
5 $FreeBSD: head/share/doc/IPv6/IMPLEMENTATION 57522 2000-02-26 19:44:12Z shin $
6
71. IPv6
8
91.1 Conformance
10
11The KAME kit conforms, or tries to conform, to the latest set of IPv6
12specifications. For future reference we list some of the relevant documents
13below (NOTE: this is not a complete list - this is too hard to maintain...).
14For details please refer to specific chapter in the document, RFCs, manpages
15come with KAME, or comments in the source code.
16
17Conformance tests have been performed on the KAME STABLE kit
18at TAHI project. Results can be viewed at http://www.tahi.org/report/KAME/.
19We also attended Univ. of New Hampshire IOL tests (http://www.iol.unh.edu/)
20in the past, with our past snapshots.
21
22RFC1639: FTP Operation Over Big Address Records (FOOBAR)
23 * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428,
24 then RFC1639 if failed.
25RFC1886: DNS Extensions to support IPv6
--- 41 unchanged lines hidden (view full) ---
67RFC2467: Transmission of IPv6 Packets over FDDI Networks
68RFC2472: IPv6 over PPP
69RFC2492: IPv6 over ATM Networks
70 * only PVC is supported.
71RFC2497: Transmission of IPv6 packet over ARCnet Networks
72RFC2545: Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing
73RFC2553: Basic Socket Interface Extensions for IPv6
74 * IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind
75 socket (3.8) are supported.
76 see 1.12 in this document for details.
77RFC2675: IPv6 Jumbograms
78 * See 1.7 in this document for details.
79RFC2710: Multicast Listener Discovery for IPv6
80RFC2711: IPv6 router alert option
81draft-ietf-ipngwg-router-renum-08: Router renumbering for IPv6
82draft-ietf-ipngwg-icmp-namelookups-02: IPv6 Name Lookups Through ICMP
83draft-ietf-ipngwg-icmp-name-lookups-03: IPv6 Name Lookups Through ICMP
84draft-ietf-pim-ipv6-01.txt: PIM for IPv6
85 * pim6dd implements dense mode. pim6sd implements sparse mode.
86draft-ietf-dhc-dhcpv6-14.txt: DHCPv6
87draft-ietf-dhc-v6exts-11.txt: Extensions for DHCPv6
88 * kame/dhcp6 has test implementation, which will not be compiled in
89 default compilation.
90draft-itojun-ipv6-tcp-to-anycast-00:
91 Disconnecting TCP connection toward IPv6 anycast address
92draft-yamamoto-wideipv6-comm-model-00
93 * See 1.6 in this document for details.
94draft-ietf-ipngwg-scopedaddr-format-00.txt:
95 An Extension of Format for IPv6 Scoped Addresses
96
971.2 Neighbor Discovery
98
99Neighbor Discovery is fairly stable. Currently Address Resolution,
100Duplicated Address Detection, and Neighbor Unreachability Detection
101are supported. In the near future we will be adding Proxy Neighbor
102Advertisement support in the kernel and Unsolicited Neighbor Advertisement
103transmission command as admin tool.
104
105If DAD fails, the address will be marked "duplicated" and message will be
106generated to syslog (and usually to console). The "duplicated" mark
107can be checked with ifconfig. It is administrators' responsibility to check
108for and recover from DAD failures.
109The behavior should be improved in the near future.
110
111Some of the network driver loops multicast packets back to itself,
112even if instructed not to do so (especially in promiscuous mode).
113In such cases DAD may fail, because DAD engine sees inbound NS packet
114(actually from the node itself) and considers it as a sign of duplicate.
115You may want to look at #if condition marked "heuristics" in
116sys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note that the code
117fragment in "heuristics" section is not spec conformant).
118
119Neighbor Discovery specification (RFC2461) does not talk about neighbor
120cache handling in the following cases:
121(1) when there was no neighbor cache entry, node received unsolicited
122 RS/NS/NA/redirect packet without link-layer address
123(2) neighbor cache handling on medium without link-layer address
124 (we need a neighbor cache entry for IsRouter bit)
125For (1), we implemented workaround based on discussions on IETF ipngwg mailing
126list. For more details, see the comments in the source code and email
127thread started from (IPng 7155), dated Feb 6 1999.
128
129IPv6 on-link determination rule (RFC2461) is quite different from assumptions
130in BSD network code. At this moment, KAME does not implement on-link
131determination rule when default router list is empty (RFC2461, section 5.2,
132last sentence in 2nd paragraph - note that the spec misuse the word "host"
133and "node" in several places in the section).
134
135To avoid possible DoS attacks and infinite loops, KAME stack will accept
136only 10 options on ND packet. Therefore, if you have 20 prefix options
137attached to RA, only the first 10 prefixes will be recognized.
138If this troubles you, please contact KAME team and/or modify
139nd6_maxndopt in sys/netinet6/nd6.c. If there are high demands we may
140provide sysctl knob for the variable.
141
1421.3 Scope Index
143
144IPv6 uses scoped addresses. Therefore, it is very important to
145specify scope index (interface index for link-local address, or
146site index for site-local address) with an IPv6 address. Without
147scope index, scoped IPv6 address is ambiguous to the kernel, and
148kernel will not be able to determine the outbound interface for a
149packet.
150
151Ordinary userland applications should use advanced API (RFC2292) to
152specify scope index, or interface index. For similar purpose,
153sin6_scope_id member in sockaddr_in6 structure is defined in RFC2553.
154However, the semantics for sin6_scope_id is rather vague. If you
155care about portability of your application, we suggest you to use
156advanced API rather than sin6_scope_id.
157
158In the kernel, an interface index for link-local scoped address is
159embedded into 2nd 16bit-word (3rd and 4th byte) in IPv6 address.
160For example, you may see something like:
161 fe80:1::200:f8ff:fe01:6317
162in the routing table and interface address structure (struct
163in6_ifaddr). The address above is a link-local unicast address
164which belongs to a network interface whose interface identifier is 1.
165The embedded index enables us to identify IPv6 link local
166addresses over multiple interfaces effectively and with only a
167little code change.
168Routing daemons and configuration programs, like route6d and
169ifconfig, will need to manipulate the "embedded" scope index.
170These programs use routing sockets and ioctls (like SIOCGIFADDR_IN6)
171and the kernel API will return IPv6 addresses with 2nd 16bit-word
172filled in. The APIs are for manipulating kernel internal structure.
173Programs that use these APIs have to be prepared about differences
174in kernels anyway.
175
176When you specify scoped address to the command line, NEVER write the
177embedded form (such as ff02:1::1 or fe80:2::fedc). This is not supposed
178to work. Always use standard form, like ff02::1 or fe80::fedc, with
179command line option for specifying interface (like "ping6 -I ne0 ff02::1).
180In general, if a command does not have command line option to specify
181outgoing interface, that command is not ready to accept scoped address.
182This may seem to be opposite from IPv6's premise to support "dentist office"
183situation. We believe that specifications need some improvements for this.
184
185Some of the userland tools support extended numeric IPv6 syntax, as
186documented in draft-ietf-ipngwg-scopedaddr-format-00.txt. You can specify
187outgoing link, by using name of the outgoing interface like "fe80::1%ne0".
188This way you will be able to specify link-local scoped address without much
189trouble.
190To use this extension in your program, you'll need to use getaddrinfo(3),
191and getnameinfo(3) with NI_WITHSCOPEID.
192The implementation currently assumes 1-to-1 relationship between a link and an
193interface, which is stronger than what specs say.
194
1951.4 Plug and Play
196
197The KAME kit implements most of the IPv6 stateless address
198autoconfiguration in the kernel.
199Neighbor Discovery functions are implemented in the kernel as a whole.
200Router Advertisement (RA) input for hosts is implemented in the
201kernel. Router Solicitation (RS) output for endhosts, RS input
202for routers, and RA output for routers are implemented in the
203userland.
204
2051.4.1 Assignment of link-local, and special addresses
206
207IPv6 link-local address is generated from IEEE802 adddress (ethernet MAC
208address). Each of interface is assigned an IPv6 link-local address
209automatically, when the interface becomes up (IFF_UP). Also, direct route
210for the link-local address is added to routing table.
211
212Here is an output of netstat command:
213
214Internet6:
215Destination Gateway Flags Netif Expire
216fe80:1::%ed0/64 link#1 UC ed0
217fe80:2::%ep0/64 link#2 UC ep0
218
219Interfaces that has no IEEE802 address (pseudo interfaces like tunnel
220interfaces, or ppp interfaces) will borrow IEEE802 address from other
221interfaces, such as ethernet interfaces, whenever possible.
222If there is no IEEE802 hardware attached, last-resort pseudorandom value,
223which is from MD5(hostname), will be used as source of link-local address.
224If it is not suitable for your usage, you will need to configure the
225link-local address manually.
--- 10 unchanged lines hidden (view full) ---
236automatically added to routing table, and loopback interface joins
237node-local multicast group ff01::1.
238
2391.4.2 Stateless address autoconfiguration on hosts
240
241In IPv6 specification, nodes are separated into two categories:
242routers and hosts. Routers forward packets addressed to others, hosts does
243not forward the packets. net.inet6.ip6.forwarding defines whether this
244node is router or host (router if it is 1, host if it is 0).
245
246When a host hears Router Advertisement from the router, a host may
247autoconfigure itself by stateless address autoconfiguration.
248This behavior can be controlled by net.inet6.ip6.accept_rtadv
249(host autoconfigures itself if it is set to 1).
250By autoconfiguration, network address prefix for the receiving interface
251(usually global address prefix) is added. Default route is also configured.
252Routers periodically generate Router Advertisement packets. To request
253an adjacent router to generate RA packet, a host can transmit Router
254Solicitation. To generate a RS packet at any time, use the "rtsol" command.
255"rtsold" daemon is also available. "rtsold" generates Router Solicitation
256whenever necessary, and it works great for nomadic usage (notebooks/laptops).
257If one wishes to ignore Router Advertisements, use sysctl to set
258net.inet6.ip6.accept_rtadv to 0.
259
260To generate Router Advertisement from a router, use the "rtadvd" daemon.
261
262Note that, IPv6 specification assumes the following items, and nonconforming
263cases are left unspecified:
264- Only hosts will listen to router advertisements
265- Hosts have single network interface (except loopback)
266Therefore, this is unwise to enable net.inet6.ip6.accept_rtadv on routers,
267or multi-interface host. A misconfigured node can behave strange
268(KAME code allows nonconforming configuration, for those who would like
269to do some experiments).
270
271To summarize the sysctl knob:
272 accept_rtadv forwarding role of the node
273 --- --- ---
274 0 0 host (to be manually configured)
275 0 1 router
276 1 0 autoconfigured host
277 (spec assumes that host has single
278 interface only, autoconfigured host
279 with multiple interface is
280 out-of-scope)
281 1 1 invalid, or experimental
282 (out-of-scope of spec)
283
284RFC2462 has validation rule against incoming RA prefix information option,
285in 5.5.3 (e). This is to protect hosts from malicious (or misconfigured)
286routers that advertise very short prefix lifetime.
287There was an update from Jim Bound to ipngwg mailing list (look
288for "(ipng 6712)" in the archive) and KAME implements Jim's update.
289
290See 1.2 in the document for relationship between DAD and autoconfiguration.
291
2921.4.3 DHCPv6 (not yet put into freebsd4.0)
293
294We supply a tiny DHCPv6 server/client in kame/dhcp6. However, the
295implementation is very premature (for example, this does NOT
296implement address lease/release), and it is not in default compilation
297tree. If you want to do some experiment, compile it on your own.
298
299DHCPv6 and autoconfiguration also needs more work. "Managed" and "Other"
300bits in RA have no special effect to stateful autoconfiguration procedure
301in DHCPv6 client program ("Managed" bit actually prevents stateless
302autoconfiguration, but no special action will be taken for DHCPv6 client).
303
3041.5 Generic tunnel interface
305
--- 10 unchanged lines hidden (view full) ---
316header (v4 in v4, or v6 in v6) is dangerous. It is very easy to
317configure interfaces and routing tables to perform infinite level
318of tunneling. Please be warned.
319
320gif can be configured to be ECN-friendly. See 4.5 for ECN-friendliness
321of tunnels, and gif(4) manpage for how to configure.
322
323If you would like to configure an IPv4-in-IPv6 tunnel with gif interface,
324read gif(4) carefully. You will need to remove IPv6 link-local address
325automatically assigned to the gif interface.
326
3271.6 Source Address Selection
328
329Source selection of KAME is scope oriented (there are some exceptions -
330see below). For a given destination, a source IPv6 address is selected
331by the following rule:
332 1. If the source address is explicitly specified by the user
333 (e.g. via the advanced API), the specified address is used.
334 2. If there is an address assigned to the outgoing interface
335 (which is usually determined by looking up the routing table)
336 that has the same scope as the destination address, the address
337 is used.
338 This is the most typical case.
339 3. If there is no address that satisfies the above condition,
340 choose a global address assigned to one of the interfaces
341 on the sending node.
342 4. If there is no address that satisfies the above condition,
343 and destination address is site local scope,
344 choose a site local address assigned to one of the interfaces
345 on the sending node.
346 5. If there is no address that satisfies the above condition,
347 choose the address associated with the routing table
348 entry for the destination.
349 This is the last resort, which may cause scope violation.
350
351For instance, ::1 is selected for ff01::1, fe80:1::200:f8ff:fe01:6317
352for fe80:1::2a0:24ff:feab:839b (note that embedded interface index -
353described in 1.3 - helps us choose the right source address. Those
354embedded indices will not be on the wire).
355If the outgoing interface has multiple address for the scope,
356a source is selected longest match basis (rule 3). Suppose
3573ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317
358are given to the outgoing interface. 3ffe:501:808:1:200:f8ff:fe01:6317
359is chosen as the source for the destination 3ffe:501:800::1.
360
361Note that the above rule is not documented in the IPv6 spec. It is
362considered "up to implementation" item.
363There are some cases where we do not use the above rule. One
364example is connected TCP session, and we use the address kept in tcb
365as the source.
366Another example is source address for Neighbor Advertisement.
367Under the spec (RFC2461 7.2.2) NA's source should be the target
368address of the corresponding NS's target. In this case we follow
369the spec rather than the above longest-match rule.
370
371For new connections (when rule 1 does not apply), deprecated addresses
372(addresses with preferred lifetime = 0) will not be chosen as source address
373if other choises are available. If no other choices are available,
374deprecated address will be used as a last resort. If there are multiple
375choice of deprecated addresses, the above scope rule will be used to choose
376from those deprecated addreses. If you would like to prohibit the use
377of deprecated address for some reason, configure net.inet6.ip6.use_deprecated
378to 0. The issue related to deprecated address is described in RFC2462 5.5.4
379(NOTE: there is some debate underway in IETF ipngwg on how to use
380"deprecated" address).
381
3821.7 Jumbo Payload
383
384KAME supports the Jumbo Payload hop-by-hop option used to send IPv6
385packets with payloads longer than 65,535 octets. But since currently
386KAME does not support any physical interface whose MTU is more than
38765,535, such payloads can be seen only on the loopback interface(i.e.
388lo0).
389
390If you want to try jumbo payloads, you first have to reconfigure the
391kernel so that the MTU of the loopback interface is more than 65,535
392bytes; add the following to the kernel configuration file:
393 options "LARGE_LOMTU" #To test jumbo payload
394and recompile the new kernel.
395
396Then you can test jumbo payloads by the ping6 command with -b and -s
397options. The -b option must be specified to enlarge the size of the
398socket buffer and the -s option specifies the length of the packet,
399which should be more than 65,535. For example, type as follows;
400 % ping6 -b 70000 -s 68000 ::1
401
402The IPv6 specification requires that the Jumbo Payload option must not
403be used in a packet that carries a fragment header. If this condition
404is broken, an ICMPv6 Parameter Problem message must be sent to the
405sender. KAME kernel follows the specification, but you cannot usually
406see an ICMPv6 error caused by this requirement.
407
--- 19 unchanged lines hidden (view full) ---
427need this.
428
429IPsec does not work on jumbograms. This is due to some specification twists
430in supporting AH with jumbograms (AH header size influences payload length,
431and this makes it real hard to authenticate inbound packet with jumbo payload
432option as well as AH).
433
434There are fundamental issues in *BSD support for jumbograms. We would like to
435address those, but we need more time to finalize these. To name a few:
436- mbuf pkthdr.len field is typed as "int" in 4.4BSD, so it will not hold
437 jumbogram with len > 2G on 32bit architecture CPUs. If we would like to
438 support jumbogram properly, the field must be expanded to hold 4G +
439 IPv6 header + link-layer header. Therefore, it must be expanded to at least
440 int64_t (u_int32_t is NOT enough).
441- We mistakingly use "int" to hold packet length in many places. We need
442 to convert them into larger integral type. It needs a great care, as we may
443 experience overflow during packet length computation.
444- We mistakingly check for ip6_plen field of IPv6 header for packet payload
445 length in various places. We should be checking mbuf pkthdr.len instead.
446 ip6_input() will perform sanity check on jumbo payload option on input,
447 and we can safely use mbuf pkthdr.len afterwards.
448- TCP code needs a careful update in bunch of places, of course.
449
4501.8 Loop prevention in header processing
451
452IPv6 specification allows arbitrary number of extension headers to
453be placed onto packets. If we implement IPv6 packet processing
454code in the way BSD IPv4 code is implemented, kernel stack may
455overflow due to long function call chain. KAME sys/netinet6 code
456is carefully designed to avoid kernel stack overflow. Because of
457this, KAME sys/netinet6 code defines its own protocol switch
458structure, as "struct ip6protosw" (see netinet6/ip6protosw.h).
459There is no such update to IPv4 part (sys/netinet) for
460compatibility, but small change is added to its pr_input()
461prototype. So "struct ipprotosw" is also defined.
462Because of this, if you receive IPsec-over-IPv4 packet with massive
463number of IPsec headers, kernel stack may blow up. IPsec-over-IPv6 is okay.
464(Off-course, for those all IPsec headers to be processed, each
465such IPsec header must pass each IPsec check. So an anonymous
466attacker won't be able to do such an attack.)
467
4681.9 ICMPv6
469
470After RFC2463 was published, IETF ipngwg has decided to disallow ICMPv6 error
471packet against ICMPv6 redirect, to prevent ICMPv6 storm on a network medium.
472KAME already implements this into the kernel.
473
4741.10 Applications
475
476For userland programming, we support IPv6 socket API as specified in
477RFC2553, RFC2292 and upcoming internet drafts.
478
479TCP/UDP over IPv6 is available and quite stable. You can enjoy "telnet",
480"ftp", "rlogin", "rsh", "ssh", etc. These applications are protocol
481independent. That is, they automatically chooses IPv4 or IPv6
--- 6 unchanged lines hidden (view full) ---
488
489The current KAME has escaped from the IPv4 netinet logic. While
490ip_forward() calls ip_output(), ip6_forward() directly calls
491if_output() since routers must not divide IPv6 packets into fragments.
492
493ICMPv6 should contain the original packet as long as possible up to
4941280. UDP6/IP6 port unreach, for instance, should contain all
495extension headers and the *unchanged* UDP6 and IP6 headers.
496So, all IP6 functions except TCP never convert network byte
497order into host byte order, to save the original packet.
498
499tcp_input(), udp6_input() and icmp6_input() can't assume that IP6
500header is preceding the transport headers due to extension
501headers. So, in6_cksum() was implemented to handle packets whose IP6
502header and transport header is not continuous. TCP/IP6 nor UDP6/IP6
503header structure don't exist for checksum calculation.
504
505To process IP6 header, extension headers and transport headers easily,
506KAME requires network drivers to store packets in one internal mbuf or
507one or more external mbufs. A typical old driver prepares two
508internal mbufs for 96 - 204 bytes data, however, KAME's reference
509implementation stores it in one external mbuf.
510
511"netstat -s -p ip6" tells you whether or not your driver conforms
512KAME's requirement. In the following example, "cce0" violates the
513requirement. (For more information, refer to Section 2.)
514
515 Mbuf statistics:
516 317 one mbuf
--- 5 unchanged lines hidden (view full) ---
522
523Each input function calls IP6_EXTHDR_CHECK in the beginning to check
524if the region between IP6 and its header is
525continuous. IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has
526M_LOOP flag, that is, the packet comes from the loopback
527interface. m_pullup() is never called for packets coming from physical
528network interfaces.
529
530Both IP and IP6 reassemble functions never call m_pullup().
531
5321.12 IPv4 mapped address and IPv6 wildcard socket
533
534RFC2553 describes IPv4 mapped address (3.7) and special behavior
535of IPv6 wildcard bind socket (3.8). The spec allows you to:
536- Accept IPv4 connections by AF_INET6 wildcard bind socket.
537- Transmit IPv4 packet over AF_INET6 socket by using special form of
538 the address like ::ffff:10.1.1.1.
539but the spec itself is very complicated and does not specify how the
540socket layer should behave.
541Here we call the former one "listening side" and the latter one "initiating
542side", for reference purposes.
543
544Almost all KAME implementations treat tcp/udp port number space separately
545between IPv4 and IPv6. You can perform wildcard bind on both of the adderss
546families, on the same port.
547
548The following table show the behavior of FreeBSD4x.
549
550 listening side initiating side
551 (AF_INET6 wildcard (connetion to ::ffff:10.1.1.1)
552 socket gets IPv4 conn.)
553 --- ---
554FreeBSD4x configurable supported
555 default: enabled
556
557The following sections will give you more details, and how you can
558configure the behavior.
559
560Comments on listening side:
561
562It looks that RFC2553 talks too little on wildcard bind issue,
563especially on the port space issue, failure mode and relationship
564between AF_INET/INET6 wildcard bind. There can be several separate
565interpretation for this RFC which conform to it but behaves differently.
566So, to implement portable application you should assume nothing
567about the behavior in the kernel. Using getaddrinfo() is the safest way.
568Port number space and wildcard bind issues were discussed in detail
569on ipv6imp mailing list, in mid March 1999 and it looks that there's
570no concrete consensus (means, up to implementers). You may want to
571check the mailing list archives.
572
573If a server application would like to accept IPv4 and IPv6 connections,
574there will be two alternatives.
575
576One is using AF_INET and AF_INET6 socket (you'll need two sockets).
577Use getaddrinfo() with AI_PASSIVE into ai_flags, and socket(2) and bind(2)
578to all the addresses returned.
579By opening multiple sockets, you can accept connections onto the socket with
580proper address family. IPv4 connections will be accepted by AF_INET socket,
581and IPv6 connections will be accepted by AF_INET6 socket.
582
583Another way is using one AF_INET6 wildcard bind socket.
584Use getaddrinfo() with AI_PASSIVE into ai_flags and with
585AF_INET6 into ai_family, and set the 1st argument hostname to
586NULL. And socket(2) and bind(2) to the address returned.
587(should be IPv6 unspecified addr)
588You can accept either of IPv4 and IPv6 packet via this one socket.
589
590To support only IPv6 traffic on AF_INET6 wildcard binded socket portably,
591always check the peer address when a connection is made toward
592AF_INET6 listening socket. If the address is IPv4 mapped address, you may
593want to reject the connection. You can check the condition by using
594IN6_IS_ADDR_V4MAPPED() macro.
595To resolv this issue more easily, there is system dependent setsockopt()
596option, IPV6_BINDV6ONLY, used like below.
597 int on;
598
599 setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY,
600 (char *)&on, sizeof (on)) < 0));
601When this call succeed, then this socket only receive IPv6 packets.
602
603
604Comments on initiating side:
605
606Advise to application implementers: to implement a portable IPv6 application
607(which works on multiple IPv6 kernels), we believe that the following
608is the key to the success:
609- NEVER hardcode AF_INET nor AF_INET6.
610- Use getaddrinfo() and getnameinfo() throughout the system.
611 Never use gethostby*(), getaddrby*(), inet_*() or getipnodeby*().
612 (To update existing applications to be IPv6 aware easily,
613 sometime getipnodeby*() will be useful. But if possible, try to
614 rewrite the code to use getaddrinfo() and getnameinfo().)
615- If you would like to connect to destination, use getaddrinfo() and try
616 all the destination returned, like telnet does.
617- Some of the IPv6 stack is shipped with buggy getaddrinfo(). Ship a minimal
618 working version with your application and use that as last resort.
619
620If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing
621connection, you will need to use getipnodebyname(). When you would like to
622update your existing appication to be IPv6 aware with minimal effort,
623this approach might be choosed. But please note that it is a temporal
624solution, because getipnodebyname() itself is not recommended as it does
625not handle scoped IPv6 addresses at all. For IPv6 name resolution,
626getaddrinfo() is the preferred API. So you should rewrite your
627application to use getaddrinfo(), when you get the time to do it.
628
629When writing applications that make outgoing connections, story goes much
630simpler if you treat AF_INET and AF_INET6 as totally seaprate address family.
631{set,get}sockopt issue goes simpler, DNS issue will be made simpler. We do
632not recommend you to rely upon IPv4 mapped address.
633
6341.12.1 FreeBSD4x
635
636FreeBSD4x uses shared tcp4/6 code (from sys/netinet/tcp*) and separete
637udp4/6 code. It uses unified inpcb/in6pcb structure.
638
639The platform can be configured to support IPv4 mapped address.
640Kernel configuration is summarized as follows:
641- By default, AF_INET6 socket will grab IPv4 connections in certain condition,
642 and can initiate connection to IPv4 destination embedded in
643 IPv4 mapped IPv6 address.
644- You can disable it on entire system with sysctl like below.
645 sysctl -w net.inet6.ip6.mapped_addr=0
646
6471.12.1.1 FreeBSD4x, listening side
648
649Each socket can be configured to support special AF_INET6 wildcard bind
650(enabled by default).
651You can disable it on each socket basis with setsockopt() like below.
652 int on;
653
654 setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY,
655 (char *)&on, sizeof (on)) < 0));
656
657Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
658conditions are satisfied:
659- there's no AF_INET socket that matches the IPv4 connection
660- the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
661 getsockopt(IPV6_BINDV6ONLY) returns 0.
662There's no problem with open/close ordering.
663
6641.12.1.2 FreeBSD4x, initiating side
665
666FreeBSD4x supports outgoing connetion to IPv4 mapped address
667(::ffff:10.1.1.1), if the node is configured to support IPv4 mapped address.
668
6691.13 sockaddr_storage
670
671When RFC2553 was about to be finalized, there was discusson on how struct
672sockaddr_storage members are named. One proposal is to prepend "__" to the
673members (like "__ss_len") as they should not be touched. The other proposal
674was that don't prepend it (like "ss_len") as we need to touch those members
675directly. There was no clear consensus on it.
676
677As a result, RFC2553 defines struct sockaddr_storage as follows:
678 struct sockaddr_storage {
679 u_char __ss_len; /* address length */
--- 7 unchanged lines hidden (view full) ---
687 /* and bunch of padding */
688 };
689
690In December 1999, it was agreed that RFC2553bis should pick the latter (XNET)
691definition.
692
693KAME kit prior to December 1999 used RFC2553 definition. KAME kit after
694December 1999 (including December) will conform to XNET definition,
695based on RFC2553bis discusson.
696
697If you look at multiple IPv6 implementations, you will be able to see
698both definitions. As an userland programmer, the most portable way of
699dealing with it is to:
700(1) ensure ss_family and/or ss_len are available on the platform, by using
701 GNU autoconf,
702(2) have -Dss_family=__ss_family to unify all occurences (including header
703 file) into __ss_family, or
704(3) never touch __ss_family. cast to sockaddr * and use sa_family like:
705 struct sockaddr_storage ss;
706 family = ((struct sockaddr *)&ss)->sa_family
707
7082. Network Drivers
709
710KAME requires two items to be added into the standard drivers:
711
712(1) mbuf clustering requirement. In this stable release, we changed
713 MINCLSIZE into MHLEN+1 for all the operating systems in order to make
714 all the drivers behave as we expect.
715
716(2) multicast. If "ifmcstat" yields no multicast group for a
717 interface, that interface has to be patched.
718
719If any of the driver don't support the requirements, then the driver
720can't be used for IPv6 and/or IPsec communication. If you find any
721problem with your card using IPv6/IPsec, then, please report it to
722freebsd-bugs@freebsd.org.
723
724(NOTE: In the past we required all pcmcia drivers to have a call to
725in6_ifattach(). We have no such requirement any more)
726
7273. Translator
728
729We categorize IPv4/IPv6 translator into 4 types.
730
731Translator A --- It is used in the early stage of transition to make
732it possible to establish a connection from an IPv6 host in an IPv6
733island to an IPv4 host in the IPv4 ocean.
734
--- 6 unchanged lines hidden (view full) ---
741to an IPv6 host in the IPv6 ocean.
742
743Translator D --- It is used in the late stage of transition to make it
744possible to establish a connection from an IPv6 host in the IPv6 ocean
745to an IPv4 host in an IPv4 island.
746
747KAME provides an TCP relay translator for category A. This is called
748"FAITH". We also provide IP header translator for category A.
749(The latter is not yet put into FreeBSD4.x yet.)
750
7513.1 FAITH TCP relay translator
752
753FAITH system uses TCP relay daemon called "faithd" helped by the KAME kernel.
754FAITH will reserve an IPv6 address prefix, and relay TCP connection
755toward that prefix to IPv4 destination.
756
757For example, if the reserved IPv6 prefix is 3ffe:0501:0200:ffff::, and
--- 5 unchanged lines hidden (view full) ---
763 | IPv4 tcp toward 163.221.202.12
764 FAITH-relay dual stack node
765 ^
766 | IPv6 TCP toward 3ffe:0501:0200:ffff::163.221.202.12
767 source IPv6 node
768
769faithd must be invoked on FAITH-relay dual stack node.
770
771For more details, consult src/usr.sbin/faithd/README.
772
7733.2 IPv6-to-IPv4 header translator
774
775(to be written)
776
7774. IPsec
778
779IPsec is mainly organized by three components.
780
781(1) Policy Management
782(2) Key Management
783(3) AH and ESP handling
784
7854.1 Policy Management
786
787The kernel implements experimental policy management code. There are two way
788to manage security policy. One is to configure per-socket policy using
789setsockopt(3). In this cases, policy configuration is described in
790ipsec_set_policy(3). The other is to configure kernel packet filter-based
791policy using PF_KEY interface, via setkey(8).
792
793The policy entry is not re-ordered with its
794indexes, so the order of entry when you add is very significant.
795
7964.2 Key Management
797
798The key management code implemented in this kit (sys/netkey) is a
799home-brew PFKEY v2 implementation. This conforms to RFC2367.
800
801The home-brew IKE daemon, "racoon" is included in the kit
802(kame/kame/racoon).
803Basically you'll need to run racoon as daemon, then setup a policy
804to require keys (like ping -P 'out ipsec esp/transport//use').
805The kernel will contact racoon daemon as necessary to exchange keys.
806
8074.3 AH and ESP handling
808
809IPsec module is implemented as "hooks" to the standard IPv4/IPv6
810processing. When sending a packet, ip{,6}_output() checks if ESP/AH
811processing is required by checking if a matching SPD (Security
812Policy Database) is found. If ESP/AH is needed,
813{esp,ah}{4,6}_output() will be called and mbuf will be updated
814accordingly. When a packet is received, {esp,ah}4_input() will be
--- 7 unchanged lines hidden (view full) ---
822extra daisy-chained headers inserted by ESP/AH. Our code takes care of
823the case.
824
825Basic crypto functions can be found in directory "sys/crypto". ESP/AH
826transform are listed in {esp,ah}_core.c with wrapper functions. If you
827wish to add some algorithm, add wrapper function in {esp,ah}_core.c, and
828add your crypto algorithm code into sys/crypto.
829
830Tunnel mode is partially supported in this release, with the following
831restrictions:
832- IPsec tunnel is not combined with GIF generic tunneling interface.
833 It needs a great care because we may create an infinite loop between
834 ip_output() and tunnelifp->if_output(). Opinion varies if it is better
835 to unify them, or not.
836- MTU and Don't Fragment bit (IPv4) considerations need more checking, but
837 basically works fine.
838- Authentication model for AH tunnel must be revisited. We'll need to
839 improve the policy management engine, eventually.
840
8414.4 Conformance to RFCs and IDs
842
843The IPsec code in the kernel conforms (or, tries to conform) to the
844following standards:
845 "old IPsec" specification documented in rfc182[5-9].txt
846 "new IPsec" specification documented in rfc240[1-6].txt, rfc241[01].txt,
847 rfc2451.txt and draft-mcdonald-simple-ipsec-api-01.txt (draft expired,
848 but you can take from ftp://ftp.kame.net/pub/internet-drafts/).
849 (NOTE: IKE specifications, rfc241[7-9].txt are implemented in userland,
850 as "racoon" IKE daemon)
851
852Currently supported algorithms are:
853 old IPsec AH
854 null crypto checksum (no document, just for debugging)
855 keyed MD5 with 128bit crypto checksum (rfc1828.txt)
856 keyed SHA1 with 128bit crypto checksum (no document)
857 HMAC MD5 with 128bit crypto checksum (rfc2085.txt)
858 HMAC SHA1 with 128bit crypto checksum (no document)
--- 13 unchanged lines hidden (view full) ---
872 DES-CBC with explicit IV (rfc2405.txt)
873 3DES-CBC with explicit IV (rfc2451.txt)
874 BLOWFISH CBC (rfc2451.txt)
875 CAST128 CBC (rfc2451.txt)
876 RC5 CBC (rfc2451.txt)
877 each of the above can be combined with:
878 ESP authentication with HMAC-MD5(96bit)
879 ESP authentication with HMAC-SHA1(96bit)
880
881The following algorithms are NOT supported:
882 old IPsec AH
883 HMAC MD5 with 128bit crypto checksum + 64bit replay prevention
884 (rfc2085.txt)
885 keyed SHA1 with 160bit crypto checksum + 32bit padding (rfc1852.txt)
886
887IPsec (in kernel) and IKE (in userland as "racoon") has been tested
888at several interoperability test events, and it is known to interoperate
889with many other implementations well. Also, KAME IPsec has quite wide
890coverage for IPsec crypto algorithms documented in RFC (we cover
891algorithms without intellectual property issues only).
892
8934.5 ECN consideration on IPsec tunnels
894
895KAME IPsec implements ECN-friendly IPsec tunnel, described in
896draft-ipsec-ecn-00.txt.
897Normal IPsec tunnel is described in RFC2401. On encapsulation,
898IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner
899IP header to outer IP header. On decapsulation outer IP header
900will be simply dropped. The decapsulation rule is not compatible
901with ECN, since ECN bit on the outer IP TOS/traffic class field will be
902lost.
903To make IPsec tunnel ECN-friendly, we should modify encapsulation
904and decapsulation procedure. This is described in
905http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt, chapter 3.
906
907KAME IPsec tunnel implementation can give you three behaviors, by setting
908net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some value:
909- RFC2401: no consideration for ECN (sysctl value -1)
910- ECN forbidden (sysctl value 0)
911- ECN allowed (sysctl value 1)
912Note that the behavior is configurable in per-node manner, not per-SA manner
913(draft-ipsec-ecn-00 wants per-SA configuration, but it looks too much for me).
914
915The behavior is summarized as follows (see source code for more detail):
916
917 encapsulate decapsulate
918 --- ---
919RFC2401 copy all TOS bits drop TOS bits on outer
920 from inner to outer. (use inner TOS bits as is)
921
--- 10 unchanged lines hidden (view full) ---
932- if both IPsec tunnel endpoint are capable of ECN-friendly behavior,
933 you'd better configure both end to "ECN allowed" (sysctl value 1).
934- if the other end is very strict about TOS bit, use "RFC2401"
935 (sysctl value -1).
936- in other cases, use "ECN forbidden" (sysctl value 0).
937The default behavior is "ECN forbidden" (sysctl value 0).
938
939For more information, please refer to:
940 http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt
941 RFC2481 (Explicit Congestion Notification)
942 KAME sys/netinet6/{ah,esp}_input.c
943
944(Thanks goes to Kenjiro Cho <kjc@csl.sony.co.jp> for detailed analysis)
945
9464.6 Interoperability
947
948Here are (some of) platforms we have tested IPsec/IKE interoperability
949in the past. Note that both ends (KAME and others) may have modified their
950implementation, so use the following list just for reference purposes.
951 Altiga, Ashley-laurent (vpcom.com), Data Fellows (F-Secure), Ericsson
952 ACC, FreeS/WAN, HITACHI, IBM AIX, IIJ, Intel, Microsoft WinNT, NIST
953 (linux IPsec + plutoplus), Netscreen, OpenBSD, RedCreek, Routerware,
954 SSH, Secure Computing, Soliton, Toshiba, VPNet, Yamaha RT100i
955
9565. IPComp
957(not yet put into FreeBSD4.x, due to inflate related changes in 4.x.)
958
959IPComp stands for IP payload compression protocol. This is aimed for
960payload compression, not the header compression like PPP VJ compression.
961This may be useful when you are using slow serial link (say, cell phone)
962with powerful CPU (well, recent notebook PCs are really powerful...).
963The protocol design of IPComp is very similar to IPsec.
964
965KAME implements the following specifications:
966- RFC2393: IP Payload Compression Protocol (IPComp)
967- RFC2394: IP Payload Compression Using DEFLATE
968
969Here are some points to be noted:
970- IPComp is treated as part of IPsec protocol suite, and SPI and
971 CPI space is unified. Spec says that there's no relationship
972 between two so they are assumed to be separate.
973- IPComp association (IPCA) is kept in SAD.
974- It is possible to use well-known CPI (CPI=2 for DEFLATE for example),
975 for outbound/inbound packet, but for indexing purposes one element from
976 SPI/CPI space will be occupied anyway.
977- pfkey is modified to support IPComp. However, there's no official
978 SA type number assignment yet. Portability with other IPComp
979 stack is questionable (anyway, who else implement IPComp on UN*X?).
980- Spec says that IPComp output processing must be performed before IPsec
981 output processing, to achieve better compression ratio and "stir" data
982 stream before encryption. However, with manual SPD setting, you are able to
983 violate the ordering requirement (KAME code is too generic, maybe).
984- Though MTU can be significantly decreased by using IPComp, no special
985 consideration is made about path MTU (spec talks nothing about MTU
986 consideration). IPComp is designed for serial links, not ethernet-like
987 medium, it seems.
988- You can change compression ratio on outbound packet, by changing
989 deflate_policy in sys/netinet6/ipcomp_core.c. You can also change history
990 buffer size by changing deflate_window in the same source code.
991 (should it be sysctl accessible? or per-SAD configurable?)
992- Tunnel mode IPComp is not working right. KAME box can generate tunnelled
993 IPComp packet, however, cannot accept tunneled IPComp packet.
994
9956. ALTQ
996 (not yet put into FreeBSD4.x)
997
998 <end of IMPLEMENTATION>
2
3 KAME Project
4 http://www.kame.net/
5 $FreeBSD: head/share/doc/IPv6/IMPLEMENTATION 57522 2000-02-26 19:44:12Z shin $
6
71. IPv6
8
91.1 Conformance
10
11The KAME kit conforms, or tries to conform, to the latest set of IPv6
12specifications. For future reference we list some of the relevant documents
13below (NOTE: this is not a complete list - this is too hard to maintain...).
14For details please refer to specific chapter in the document, RFCs, manpages
15come with KAME, or comments in the source code.
16
17Conformance tests have been performed on the KAME STABLE kit
18at TAHI project. Results can be viewed at http://www.tahi.org/report/KAME/.
19We also attended Univ. of New Hampshire IOL tests (http://www.iol.unh.edu/)
20in the past, with our past snapshots.
21
22RFC1639: FTP Operation Over Big Address Records (FOOBAR)
23 * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428,
24 then RFC1639 if failed.
25RFC1886: DNS Extensions to support IPv6
--- 41 unchanged lines hidden (view full) ---
67RFC2467: Transmission of IPv6 Packets over FDDI Networks
68RFC2472: IPv6 over PPP
69RFC2492: IPv6 over ATM Networks
70 * only PVC is supported.
71RFC2497: Transmission of IPv6 packet over ARCnet Networks
72RFC2545: Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing
73RFC2553: Basic Socket Interface Extensions for IPv6
74 * IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind
75 socket (3.8) are supported.
76 see 1.12 in this document for details.
77RFC2675: IPv6 Jumbograms
78 * See 1.7 in this document for details.
79RFC2710: Multicast Listener Discovery for IPv6
80RFC2711: IPv6 router alert option
81draft-ietf-ipngwg-router-renum-08: Router renumbering for IPv6
82draft-ietf-ipngwg-icmp-namelookups-02: IPv6 Name Lookups Through ICMP
83draft-ietf-ipngwg-icmp-name-lookups-03: IPv6 Name Lookups Through ICMP
84draft-ietf-pim-ipv6-01.txt: PIM for IPv6
85 * pim6dd implements dense mode. pim6sd implements sparse mode.
86draft-ietf-dhc-dhcpv6-14.txt: DHCPv6
87draft-ietf-dhc-v6exts-11.txt: Extensions for DHCPv6
88 * kame/dhcp6 has test implementation, which will not be compiled in
89 default compilation.
90draft-itojun-ipv6-tcp-to-anycast-00:
91 Disconnecting TCP connection toward IPv6 anycast address
92draft-yamamoto-wideipv6-comm-model-00
93 * See 1.6 in this document for details.
94draft-ietf-ipngwg-scopedaddr-format-00.txt:
95 An Extension of Format for IPv6 Scoped Addresses
96
971.2 Neighbor Discovery
98
99Neighbor Discovery is fairly stable. Currently Address Resolution,
100Duplicated Address Detection, and Neighbor Unreachability Detection
101are supported. In the near future we will be adding Proxy Neighbor
102Advertisement support in the kernel and Unsolicited Neighbor Advertisement
103transmission command as admin tool.
104
105If DAD fails, the address will be marked "duplicated" and message will be
106generated to syslog (and usually to console). The "duplicated" mark
107can be checked with ifconfig. It is administrators' responsibility to check
108for and recover from DAD failures.
109The behavior should be improved in the near future.
110
111Some of the network driver loops multicast packets back to itself,
112even if instructed not to do so (especially in promiscuous mode).
113In such cases DAD may fail, because DAD engine sees inbound NS packet
114(actually from the node itself) and considers it as a sign of duplicate.
115You may want to look at #if condition marked "heuristics" in
116sys/netinet6/nd6_nbr.c:nd6_dad_timer() as workaround (note that the code
117fragment in "heuristics" section is not spec conformant).
118
119Neighbor Discovery specification (RFC2461) does not talk about neighbor
120cache handling in the following cases:
121(1) when there was no neighbor cache entry, node received unsolicited
122 RS/NS/NA/redirect packet without link-layer address
123(2) neighbor cache handling on medium without link-layer address
124 (we need a neighbor cache entry for IsRouter bit)
125For (1), we implemented workaround based on discussions on IETF ipngwg mailing
126list. For more details, see the comments in the source code and email
127thread started from (IPng 7155), dated Feb 6 1999.
128
129IPv6 on-link determination rule (RFC2461) is quite different from assumptions
130in BSD network code. At this moment, KAME does not implement on-link
131determination rule when default router list is empty (RFC2461, section 5.2,
132last sentence in 2nd paragraph - note that the spec misuse the word "host"
133and "node" in several places in the section).
134
135To avoid possible DoS attacks and infinite loops, KAME stack will accept
136only 10 options on ND packet. Therefore, if you have 20 prefix options
137attached to RA, only the first 10 prefixes will be recognized.
138If this troubles you, please contact KAME team and/or modify
139nd6_maxndopt in sys/netinet6/nd6.c. If there are high demands we may
140provide sysctl knob for the variable.
141
1421.3 Scope Index
143
144IPv6 uses scoped addresses. Therefore, it is very important to
145specify scope index (interface index for link-local address, or
146site index for site-local address) with an IPv6 address. Without
147scope index, scoped IPv6 address is ambiguous to the kernel, and
148kernel will not be able to determine the outbound interface for a
149packet.
150
151Ordinary userland applications should use advanced API (RFC2292) to
152specify scope index, or interface index. For similar purpose,
153sin6_scope_id member in sockaddr_in6 structure is defined in RFC2553.
154However, the semantics for sin6_scope_id is rather vague. If you
155care about portability of your application, we suggest you to use
156advanced API rather than sin6_scope_id.
157
158In the kernel, an interface index for link-local scoped address is
159embedded into 2nd 16bit-word (3rd and 4th byte) in IPv6 address.
160For example, you may see something like:
161 fe80:1::200:f8ff:fe01:6317
162in the routing table and interface address structure (struct
163in6_ifaddr). The address above is a link-local unicast address
164which belongs to a network interface whose interface identifier is 1.
165The embedded index enables us to identify IPv6 link local
166addresses over multiple interfaces effectively and with only a
167little code change.
168Routing daemons and configuration programs, like route6d and
169ifconfig, will need to manipulate the "embedded" scope index.
170These programs use routing sockets and ioctls (like SIOCGIFADDR_IN6)
171and the kernel API will return IPv6 addresses with 2nd 16bit-word
172filled in. The APIs are for manipulating kernel internal structure.
173Programs that use these APIs have to be prepared about differences
174in kernels anyway.
175
176When you specify scoped address to the command line, NEVER write the
177embedded form (such as ff02:1::1 or fe80:2::fedc). This is not supposed
178to work. Always use standard form, like ff02::1 or fe80::fedc, with
179command line option for specifying interface (like "ping6 -I ne0 ff02::1).
180In general, if a command does not have command line option to specify
181outgoing interface, that command is not ready to accept scoped address.
182This may seem to be opposite from IPv6's premise to support "dentist office"
183situation. We believe that specifications need some improvements for this.
184
185Some of the userland tools support extended numeric IPv6 syntax, as
186documented in draft-ietf-ipngwg-scopedaddr-format-00.txt. You can specify
187outgoing link, by using name of the outgoing interface like "fe80::1%ne0".
188This way you will be able to specify link-local scoped address without much
189trouble.
190To use this extension in your program, you'll need to use getaddrinfo(3),
191and getnameinfo(3) with NI_WITHSCOPEID.
192The implementation currently assumes 1-to-1 relationship between a link and an
193interface, which is stronger than what specs say.
194
1951.4 Plug and Play
196
197The KAME kit implements most of the IPv6 stateless address
198autoconfiguration in the kernel.
199Neighbor Discovery functions are implemented in the kernel as a whole.
200Router Advertisement (RA) input for hosts is implemented in the
201kernel. Router Solicitation (RS) output for endhosts, RS input
202for routers, and RA output for routers are implemented in the
203userland.
204
2051.4.1 Assignment of link-local, and special addresses
206
207IPv6 link-local address is generated from IEEE802 adddress (ethernet MAC
208address). Each of interface is assigned an IPv6 link-local address
209automatically, when the interface becomes up (IFF_UP). Also, direct route
210for the link-local address is added to routing table.
211
212Here is an output of netstat command:
213
214Internet6:
215Destination Gateway Flags Netif Expire
216fe80:1::%ed0/64 link#1 UC ed0
217fe80:2::%ep0/64 link#2 UC ep0
218
219Interfaces that has no IEEE802 address (pseudo interfaces like tunnel
220interfaces, or ppp interfaces) will borrow IEEE802 address from other
221interfaces, such as ethernet interfaces, whenever possible.
222If there is no IEEE802 hardware attached, last-resort pseudorandom value,
223which is from MD5(hostname), will be used as source of link-local address.
224If it is not suitable for your usage, you will need to configure the
225link-local address manually.
--- 10 unchanged lines hidden (view full) ---
236automatically added to routing table, and loopback interface joins
237node-local multicast group ff01::1.
238
2391.4.2 Stateless address autoconfiguration on hosts
240
241In IPv6 specification, nodes are separated into two categories:
242routers and hosts. Routers forward packets addressed to others, hosts does
243not forward the packets. net.inet6.ip6.forwarding defines whether this
244node is router or host (router if it is 1, host if it is 0).
245
246When a host hears Router Advertisement from the router, a host may
247autoconfigure itself by stateless address autoconfiguration.
248This behavior can be controlled by net.inet6.ip6.accept_rtadv
249(host autoconfigures itself if it is set to 1).
250By autoconfiguration, network address prefix for the receiving interface
251(usually global address prefix) is added. Default route is also configured.
252Routers periodically generate Router Advertisement packets. To request
253an adjacent router to generate RA packet, a host can transmit Router
254Solicitation. To generate a RS packet at any time, use the "rtsol" command.
255"rtsold" daemon is also available. "rtsold" generates Router Solicitation
256whenever necessary, and it works great for nomadic usage (notebooks/laptops).
257If one wishes to ignore Router Advertisements, use sysctl to set
258net.inet6.ip6.accept_rtadv to 0.
259
260To generate Router Advertisement from a router, use the "rtadvd" daemon.
261
262Note that, IPv6 specification assumes the following items, and nonconforming
263cases are left unspecified:
264- Only hosts will listen to router advertisements
265- Hosts have single network interface (except loopback)
266Therefore, this is unwise to enable net.inet6.ip6.accept_rtadv on routers,
267or multi-interface host. A misconfigured node can behave strange
268(KAME code allows nonconforming configuration, for those who would like
269to do some experiments).
270
271To summarize the sysctl knob:
272 accept_rtadv forwarding role of the node
273 --- --- ---
274 0 0 host (to be manually configured)
275 0 1 router
276 1 0 autoconfigured host
277 (spec assumes that host has single
278 interface only, autoconfigured host
279 with multiple interface is
280 out-of-scope)
281 1 1 invalid, or experimental
282 (out-of-scope of spec)
283
284RFC2462 has validation rule against incoming RA prefix information option,
285in 5.5.3 (e). This is to protect hosts from malicious (or misconfigured)
286routers that advertise very short prefix lifetime.
287There was an update from Jim Bound to ipngwg mailing list (look
288for "(ipng 6712)" in the archive) and KAME implements Jim's update.
289
290See 1.2 in the document for relationship between DAD and autoconfiguration.
291
2921.4.3 DHCPv6 (not yet put into freebsd4.0)
293
294We supply a tiny DHCPv6 server/client in kame/dhcp6. However, the
295implementation is very premature (for example, this does NOT
296implement address lease/release), and it is not in default compilation
297tree. If you want to do some experiment, compile it on your own.
298
299DHCPv6 and autoconfiguration also needs more work. "Managed" and "Other"
300bits in RA have no special effect to stateful autoconfiguration procedure
301in DHCPv6 client program ("Managed" bit actually prevents stateless
302autoconfiguration, but no special action will be taken for DHCPv6 client).
303
3041.5 Generic tunnel interface
305
--- 10 unchanged lines hidden (view full) ---
316header (v4 in v4, or v6 in v6) is dangerous. It is very easy to
317configure interfaces and routing tables to perform infinite level
318of tunneling. Please be warned.
319
320gif can be configured to be ECN-friendly. See 4.5 for ECN-friendliness
321of tunnels, and gif(4) manpage for how to configure.
322
323If you would like to configure an IPv4-in-IPv6 tunnel with gif interface,
324read gif(4) carefully. You will need to remove IPv6 link-local address
325automatically assigned to the gif interface.
326
3271.6 Source Address Selection
328
329Source selection of KAME is scope oriented (there are some exceptions -
330see below). For a given destination, a source IPv6 address is selected
331by the following rule:
332 1. If the source address is explicitly specified by the user
333 (e.g. via the advanced API), the specified address is used.
334 2. If there is an address assigned to the outgoing interface
335 (which is usually determined by looking up the routing table)
336 that has the same scope as the destination address, the address
337 is used.
338 This is the most typical case.
339 3. If there is no address that satisfies the above condition,
340 choose a global address assigned to one of the interfaces
341 on the sending node.
342 4. If there is no address that satisfies the above condition,
343 and destination address is site local scope,
344 choose a site local address assigned to one of the interfaces
345 on the sending node.
346 5. If there is no address that satisfies the above condition,
347 choose the address associated with the routing table
348 entry for the destination.
349 This is the last resort, which may cause scope violation.
350
351For instance, ::1 is selected for ff01::1, fe80:1::200:f8ff:fe01:6317
352for fe80:1::2a0:24ff:feab:839b (note that embedded interface index -
353described in 1.3 - helps us choose the right source address. Those
354embedded indices will not be on the wire).
355If the outgoing interface has multiple address for the scope,
356a source is selected longest match basis (rule 3). Suppose
3573ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317
358are given to the outgoing interface. 3ffe:501:808:1:200:f8ff:fe01:6317
359is chosen as the source for the destination 3ffe:501:800::1.
360
361Note that the above rule is not documented in the IPv6 spec. It is
362considered "up to implementation" item.
363There are some cases where we do not use the above rule. One
364example is connected TCP session, and we use the address kept in tcb
365as the source.
366Another example is source address for Neighbor Advertisement.
367Under the spec (RFC2461 7.2.2) NA's source should be the target
368address of the corresponding NS's target. In this case we follow
369the spec rather than the above longest-match rule.
370
371For new connections (when rule 1 does not apply), deprecated addresses
372(addresses with preferred lifetime = 0) will not be chosen as source address
373if other choises are available. If no other choices are available,
374deprecated address will be used as a last resort. If there are multiple
375choice of deprecated addresses, the above scope rule will be used to choose
376from those deprecated addreses. If you would like to prohibit the use
377of deprecated address for some reason, configure net.inet6.ip6.use_deprecated
378to 0. The issue related to deprecated address is described in RFC2462 5.5.4
379(NOTE: there is some debate underway in IETF ipngwg on how to use
380"deprecated" address).
381
3821.7 Jumbo Payload
383
384KAME supports the Jumbo Payload hop-by-hop option used to send IPv6
385packets with payloads longer than 65,535 octets. But since currently
386KAME does not support any physical interface whose MTU is more than
38765,535, such payloads can be seen only on the loopback interface(i.e.
388lo0).
389
390If you want to try jumbo payloads, you first have to reconfigure the
391kernel so that the MTU of the loopback interface is more than 65,535
392bytes; add the following to the kernel configuration file:
393 options "LARGE_LOMTU" #To test jumbo payload
394and recompile the new kernel.
395
396Then you can test jumbo payloads by the ping6 command with -b and -s
397options. The -b option must be specified to enlarge the size of the
398socket buffer and the -s option specifies the length of the packet,
399which should be more than 65,535. For example, type as follows;
400 % ping6 -b 70000 -s 68000 ::1
401
402The IPv6 specification requires that the Jumbo Payload option must not
403be used in a packet that carries a fragment header. If this condition
404is broken, an ICMPv6 Parameter Problem message must be sent to the
405sender. KAME kernel follows the specification, but you cannot usually
406see an ICMPv6 error caused by this requirement.
407
--- 19 unchanged lines hidden (view full) ---
427need this.
428
429IPsec does not work on jumbograms. This is due to some specification twists
430in supporting AH with jumbograms (AH header size influences payload length,
431and this makes it real hard to authenticate inbound packet with jumbo payload
432option as well as AH).
433
434There are fundamental issues in *BSD support for jumbograms. We would like to
435address those, but we need more time to finalize these. To name a few:
436- mbuf pkthdr.len field is typed as "int" in 4.4BSD, so it will not hold
437 jumbogram with len > 2G on 32bit architecture CPUs. If we would like to
438 support jumbogram properly, the field must be expanded to hold 4G +
439 IPv6 header + link-layer header. Therefore, it must be expanded to at least
440 int64_t (u_int32_t is NOT enough).
441- We mistakingly use "int" to hold packet length in many places. We need
442 to convert them into larger integral type. It needs a great care, as we may
443 experience overflow during packet length computation.
444- We mistakingly check for ip6_plen field of IPv6 header for packet payload
445 length in various places. We should be checking mbuf pkthdr.len instead.
446 ip6_input() will perform sanity check on jumbo payload option on input,
447 and we can safely use mbuf pkthdr.len afterwards.
448- TCP code needs a careful update in bunch of places, of course.
449
4501.8 Loop prevention in header processing
451
452IPv6 specification allows arbitrary number of extension headers to
453be placed onto packets. If we implement IPv6 packet processing
454code in the way BSD IPv4 code is implemented, kernel stack may
455overflow due to long function call chain. KAME sys/netinet6 code
456is carefully designed to avoid kernel stack overflow. Because of
457this, KAME sys/netinet6 code defines its own protocol switch
458structure, as "struct ip6protosw" (see netinet6/ip6protosw.h).
459There is no such update to IPv4 part (sys/netinet) for
460compatibility, but small change is added to its pr_input()
461prototype. So "struct ipprotosw" is also defined.
462Because of this, if you receive IPsec-over-IPv4 packet with massive
463number of IPsec headers, kernel stack may blow up. IPsec-over-IPv6 is okay.
464(Off-course, for those all IPsec headers to be processed, each
465such IPsec header must pass each IPsec check. So an anonymous
466attacker won't be able to do such an attack.)
467
4681.9 ICMPv6
469
470After RFC2463 was published, IETF ipngwg has decided to disallow ICMPv6 error
471packet against ICMPv6 redirect, to prevent ICMPv6 storm on a network medium.
472KAME already implements this into the kernel.
473
4741.10 Applications
475
476For userland programming, we support IPv6 socket API as specified in
477RFC2553, RFC2292 and upcoming internet drafts.
478
479TCP/UDP over IPv6 is available and quite stable. You can enjoy "telnet",
480"ftp", "rlogin", "rsh", "ssh", etc. These applications are protocol
481independent. That is, they automatically chooses IPv4 or IPv6
--- 6 unchanged lines hidden (view full) ---
488
489The current KAME has escaped from the IPv4 netinet logic. While
490ip_forward() calls ip_output(), ip6_forward() directly calls
491if_output() since routers must not divide IPv6 packets into fragments.
492
493ICMPv6 should contain the original packet as long as possible up to
4941280. UDP6/IP6 port unreach, for instance, should contain all
495extension headers and the *unchanged* UDP6 and IP6 headers.
496So, all IP6 functions except TCP never convert network byte
497order into host byte order, to save the original packet.
498
499tcp_input(), udp6_input() and icmp6_input() can't assume that IP6
500header is preceding the transport headers due to extension
501headers. So, in6_cksum() was implemented to handle packets whose IP6
502header and transport header is not continuous. TCP/IP6 nor UDP6/IP6
503header structure don't exist for checksum calculation.
504
505To process IP6 header, extension headers and transport headers easily,
506KAME requires network drivers to store packets in one internal mbuf or
507one or more external mbufs. A typical old driver prepares two
508internal mbufs for 96 - 204 bytes data, however, KAME's reference
509implementation stores it in one external mbuf.
510
511"netstat -s -p ip6" tells you whether or not your driver conforms
512KAME's requirement. In the following example, "cce0" violates the
513requirement. (For more information, refer to Section 2.)
514
515 Mbuf statistics:
516 317 one mbuf
--- 5 unchanged lines hidden (view full) ---
522
523Each input function calls IP6_EXTHDR_CHECK in the beginning to check
524if the region between IP6 and its header is
525continuous. IP6_EXTHDR_CHECK calls m_pullup() only if the mbuf has
526M_LOOP flag, that is, the packet comes from the loopback
527interface. m_pullup() is never called for packets coming from physical
528network interfaces.
529
530Both IP and IP6 reassemble functions never call m_pullup().
531
5321.12 IPv4 mapped address and IPv6 wildcard socket
533
534RFC2553 describes IPv4 mapped address (3.7) and special behavior
535of IPv6 wildcard bind socket (3.8). The spec allows you to:
536- Accept IPv4 connections by AF_INET6 wildcard bind socket.
537- Transmit IPv4 packet over AF_INET6 socket by using special form of
538 the address like ::ffff:10.1.1.1.
539but the spec itself is very complicated and does not specify how the
540socket layer should behave.
541Here we call the former one "listening side" and the latter one "initiating
542side", for reference purposes.
543
544Almost all KAME implementations treat tcp/udp port number space separately
545between IPv4 and IPv6. You can perform wildcard bind on both of the adderss
546families, on the same port.
547
548The following table show the behavior of FreeBSD4x.
549
550 listening side initiating side
551 (AF_INET6 wildcard (connetion to ::ffff:10.1.1.1)
552 socket gets IPv4 conn.)
553 --- ---
554FreeBSD4x configurable supported
555 default: enabled
556
557The following sections will give you more details, and how you can
558configure the behavior.
559
560Comments on listening side:
561
562It looks that RFC2553 talks too little on wildcard bind issue,
563especially on the port space issue, failure mode and relationship
564between AF_INET/INET6 wildcard bind. There can be several separate
565interpretation for this RFC which conform to it but behaves differently.
566So, to implement portable application you should assume nothing
567about the behavior in the kernel. Using getaddrinfo() is the safest way.
568Port number space and wildcard bind issues were discussed in detail
569on ipv6imp mailing list, in mid March 1999 and it looks that there's
570no concrete consensus (means, up to implementers). You may want to
571check the mailing list archives.
572
573If a server application would like to accept IPv4 and IPv6 connections,
574there will be two alternatives.
575
576One is using AF_INET and AF_INET6 socket (you'll need two sockets).
577Use getaddrinfo() with AI_PASSIVE into ai_flags, and socket(2) and bind(2)
578to all the addresses returned.
579By opening multiple sockets, you can accept connections onto the socket with
580proper address family. IPv4 connections will be accepted by AF_INET socket,
581and IPv6 connections will be accepted by AF_INET6 socket.
582
583Another way is using one AF_INET6 wildcard bind socket.
584Use getaddrinfo() with AI_PASSIVE into ai_flags and with
585AF_INET6 into ai_family, and set the 1st argument hostname to
586NULL. And socket(2) and bind(2) to the address returned.
587(should be IPv6 unspecified addr)
588You can accept either of IPv4 and IPv6 packet via this one socket.
589
590To support only IPv6 traffic on AF_INET6 wildcard binded socket portably,
591always check the peer address when a connection is made toward
592AF_INET6 listening socket. If the address is IPv4 mapped address, you may
593want to reject the connection. You can check the condition by using
594IN6_IS_ADDR_V4MAPPED() macro.
595To resolv this issue more easily, there is system dependent setsockopt()
596option, IPV6_BINDV6ONLY, used like below.
597 int on;
598
599 setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY,
600 (char *)&on, sizeof (on)) < 0));
601When this call succeed, then this socket only receive IPv6 packets.
602
603
604Comments on initiating side:
605
606Advise to application implementers: to implement a portable IPv6 application
607(which works on multiple IPv6 kernels), we believe that the following
608is the key to the success:
609- NEVER hardcode AF_INET nor AF_INET6.
610- Use getaddrinfo() and getnameinfo() throughout the system.
611 Never use gethostby*(), getaddrby*(), inet_*() or getipnodeby*().
612 (To update existing applications to be IPv6 aware easily,
613 sometime getipnodeby*() will be useful. But if possible, try to
614 rewrite the code to use getaddrinfo() and getnameinfo().)
615- If you would like to connect to destination, use getaddrinfo() and try
616 all the destination returned, like telnet does.
617- Some of the IPv6 stack is shipped with buggy getaddrinfo(). Ship a minimal
618 working version with your application and use that as last resort.
619
620If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing
621connection, you will need to use getipnodebyname(). When you would like to
622update your existing appication to be IPv6 aware with minimal effort,
623this approach might be choosed. But please note that it is a temporal
624solution, because getipnodebyname() itself is not recommended as it does
625not handle scoped IPv6 addresses at all. For IPv6 name resolution,
626getaddrinfo() is the preferred API. So you should rewrite your
627application to use getaddrinfo(), when you get the time to do it.
628
629When writing applications that make outgoing connections, story goes much
630simpler if you treat AF_INET and AF_INET6 as totally seaprate address family.
631{set,get}sockopt issue goes simpler, DNS issue will be made simpler. We do
632not recommend you to rely upon IPv4 mapped address.
633
6341.12.1 FreeBSD4x
635
636FreeBSD4x uses shared tcp4/6 code (from sys/netinet/tcp*) and separete
637udp4/6 code. It uses unified inpcb/in6pcb structure.
638
639The platform can be configured to support IPv4 mapped address.
640Kernel configuration is summarized as follows:
641- By default, AF_INET6 socket will grab IPv4 connections in certain condition,
642 and can initiate connection to IPv4 destination embedded in
643 IPv4 mapped IPv6 address.
644- You can disable it on entire system with sysctl like below.
645 sysctl -w net.inet6.ip6.mapped_addr=0
646
6471.12.1.1 FreeBSD4x, listening side
648
649Each socket can be configured to support special AF_INET6 wildcard bind
650(enabled by default).
651You can disable it on each socket basis with setsockopt() like below.
652 int on;
653
654 setsockopt(s, IPPROTO_IPV6, IPV6_BINDV6ONLY,
655 (char *)&on, sizeof (on)) < 0));
656
657Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
658conditions are satisfied:
659- there's no AF_INET socket that matches the IPv4 connection
660- the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
661 getsockopt(IPV6_BINDV6ONLY) returns 0.
662There's no problem with open/close ordering.
663
6641.12.1.2 FreeBSD4x, initiating side
665
666FreeBSD4x supports outgoing connetion to IPv4 mapped address
667(::ffff:10.1.1.1), if the node is configured to support IPv4 mapped address.
668
6691.13 sockaddr_storage
670
671When RFC2553 was about to be finalized, there was discusson on how struct
672sockaddr_storage members are named. One proposal is to prepend "__" to the
673members (like "__ss_len") as they should not be touched. The other proposal
674was that don't prepend it (like "ss_len") as we need to touch those members
675directly. There was no clear consensus on it.
676
677As a result, RFC2553 defines struct sockaddr_storage as follows:
678 struct sockaddr_storage {
679 u_char __ss_len; /* address length */
--- 7 unchanged lines hidden (view full) ---
687 /* and bunch of padding */
688 };
689
690In December 1999, it was agreed that RFC2553bis should pick the latter (XNET)
691definition.
692
693KAME kit prior to December 1999 used RFC2553 definition. KAME kit after
694December 1999 (including December) will conform to XNET definition,
695based on RFC2553bis discusson.
696
697If you look at multiple IPv6 implementations, you will be able to see
698both definitions. As an userland programmer, the most portable way of
699dealing with it is to:
700(1) ensure ss_family and/or ss_len are available on the platform, by using
701 GNU autoconf,
702(2) have -Dss_family=__ss_family to unify all occurences (including header
703 file) into __ss_family, or
704(3) never touch __ss_family. cast to sockaddr * and use sa_family like:
705 struct sockaddr_storage ss;
706 family = ((struct sockaddr *)&ss)->sa_family
707
7082. Network Drivers
709
710KAME requires two items to be added into the standard drivers:
711
712(1) mbuf clustering requirement. In this stable release, we changed
713 MINCLSIZE into MHLEN+1 for all the operating systems in order to make
714 all the drivers behave as we expect.
715
716(2) multicast. If "ifmcstat" yields no multicast group for a
717 interface, that interface has to be patched.
718
719If any of the driver don't support the requirements, then the driver
720can't be used for IPv6 and/or IPsec communication. If you find any
721problem with your card using IPv6/IPsec, then, please report it to
722freebsd-bugs@freebsd.org.
723
724(NOTE: In the past we required all pcmcia drivers to have a call to
725in6_ifattach(). We have no such requirement any more)
726
7273. Translator
728
729We categorize IPv4/IPv6 translator into 4 types.
730
731Translator A --- It is used in the early stage of transition to make
732it possible to establish a connection from an IPv6 host in an IPv6
733island to an IPv4 host in the IPv4 ocean.
734
--- 6 unchanged lines hidden (view full) ---
741to an IPv6 host in the IPv6 ocean.
742
743Translator D --- It is used in the late stage of transition to make it
744possible to establish a connection from an IPv6 host in the IPv6 ocean
745to an IPv4 host in an IPv4 island.
746
747KAME provides an TCP relay translator for category A. This is called
748"FAITH". We also provide IP header translator for category A.
749(The latter is not yet put into FreeBSD4.x yet.)
750
7513.1 FAITH TCP relay translator
752
753FAITH system uses TCP relay daemon called "faithd" helped by the KAME kernel.
754FAITH will reserve an IPv6 address prefix, and relay TCP connection
755toward that prefix to IPv4 destination.
756
757For example, if the reserved IPv6 prefix is 3ffe:0501:0200:ffff::, and
--- 5 unchanged lines hidden (view full) ---
763 | IPv4 tcp toward 163.221.202.12
764 FAITH-relay dual stack node
765 ^
766 | IPv6 TCP toward 3ffe:0501:0200:ffff::163.221.202.12
767 source IPv6 node
768
769faithd must be invoked on FAITH-relay dual stack node.
770
771For more details, consult src/usr.sbin/faithd/README.
772
7733.2 IPv6-to-IPv4 header translator
774
775(to be written)
776
7774. IPsec
778
779IPsec is mainly organized by three components.
780
781(1) Policy Management
782(2) Key Management
783(3) AH and ESP handling
784
7854.1 Policy Management
786
787The kernel implements experimental policy management code. There are two way
788to manage security policy. One is to configure per-socket policy using
789setsockopt(3). In this cases, policy configuration is described in
790ipsec_set_policy(3). The other is to configure kernel packet filter-based
791policy using PF_KEY interface, via setkey(8).
792
793The policy entry is not re-ordered with its
794indexes, so the order of entry when you add is very significant.
795
7964.2 Key Management
797
798The key management code implemented in this kit (sys/netkey) is a
799home-brew PFKEY v2 implementation. This conforms to RFC2367.
800
801The home-brew IKE daemon, "racoon" is included in the kit
802(kame/kame/racoon).
803Basically you'll need to run racoon as daemon, then setup a policy
804to require keys (like ping -P 'out ipsec esp/transport//use').
805The kernel will contact racoon daemon as necessary to exchange keys.
806
8074.3 AH and ESP handling
808
809IPsec module is implemented as "hooks" to the standard IPv4/IPv6
810processing. When sending a packet, ip{,6}_output() checks if ESP/AH
811processing is required by checking if a matching SPD (Security
812Policy Database) is found. If ESP/AH is needed,
813{esp,ah}{4,6}_output() will be called and mbuf will be updated
814accordingly. When a packet is received, {esp,ah}4_input() will be
--- 7 unchanged lines hidden (view full) ---
822extra daisy-chained headers inserted by ESP/AH. Our code takes care of
823the case.
824
825Basic crypto functions can be found in directory "sys/crypto". ESP/AH
826transform are listed in {esp,ah}_core.c with wrapper functions. If you
827wish to add some algorithm, add wrapper function in {esp,ah}_core.c, and
828add your crypto algorithm code into sys/crypto.
829
830Tunnel mode is partially supported in this release, with the following
831restrictions:
832- IPsec tunnel is not combined with GIF generic tunneling interface.
833 It needs a great care because we may create an infinite loop between
834 ip_output() and tunnelifp->if_output(). Opinion varies if it is better
835 to unify them, or not.
836- MTU and Don't Fragment bit (IPv4) considerations need more checking, but
837 basically works fine.
838- Authentication model for AH tunnel must be revisited. We'll need to
839 improve the policy management engine, eventually.
840
8414.4 Conformance to RFCs and IDs
842
843The IPsec code in the kernel conforms (or, tries to conform) to the
844following standards:
845 "old IPsec" specification documented in rfc182[5-9].txt
846 "new IPsec" specification documented in rfc240[1-6].txt, rfc241[01].txt,
847 rfc2451.txt and draft-mcdonald-simple-ipsec-api-01.txt (draft expired,
848 but you can take from ftp://ftp.kame.net/pub/internet-drafts/).
849 (NOTE: IKE specifications, rfc241[7-9].txt are implemented in userland,
850 as "racoon" IKE daemon)
851
852Currently supported algorithms are:
853 old IPsec AH
854 null crypto checksum (no document, just for debugging)
855 keyed MD5 with 128bit crypto checksum (rfc1828.txt)
856 keyed SHA1 with 128bit crypto checksum (no document)
857 HMAC MD5 with 128bit crypto checksum (rfc2085.txt)
858 HMAC SHA1 with 128bit crypto checksum (no document)
--- 13 unchanged lines hidden (view full) ---
872 DES-CBC with explicit IV (rfc2405.txt)
873 3DES-CBC with explicit IV (rfc2451.txt)
874 BLOWFISH CBC (rfc2451.txt)
875 CAST128 CBC (rfc2451.txt)
876 RC5 CBC (rfc2451.txt)
877 each of the above can be combined with:
878 ESP authentication with HMAC-MD5(96bit)
879 ESP authentication with HMAC-SHA1(96bit)
880
881The following algorithms are NOT supported:
882 old IPsec AH
883 HMAC MD5 with 128bit crypto checksum + 64bit replay prevention
884 (rfc2085.txt)
885 keyed SHA1 with 160bit crypto checksum + 32bit padding (rfc1852.txt)
886
887IPsec (in kernel) and IKE (in userland as "racoon") has been tested
888at several interoperability test events, and it is known to interoperate
889with many other implementations well. Also, KAME IPsec has quite wide
890coverage for IPsec crypto algorithms documented in RFC (we cover
891algorithms without intellectual property issues only).
892
8934.5 ECN consideration on IPsec tunnels
894
895KAME IPsec implements ECN-friendly IPsec tunnel, described in
896draft-ipsec-ecn-00.txt.
897Normal IPsec tunnel is described in RFC2401. On encapsulation,
898IPv4 TOS field (or, IPv6 traffic class field) will be copied from inner
899IP header to outer IP header. On decapsulation outer IP header
900will be simply dropped. The decapsulation rule is not compatible
901with ECN, since ECN bit on the outer IP TOS/traffic class field will be
902lost.
903To make IPsec tunnel ECN-friendly, we should modify encapsulation
904and decapsulation procedure. This is described in
905http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt, chapter 3.
906
907KAME IPsec tunnel implementation can give you three behaviors, by setting
908net.inet.ipsec.ecn (or net.inet6.ipsec6.ecn) to some value:
909- RFC2401: no consideration for ECN (sysctl value -1)
910- ECN forbidden (sysctl value 0)
911- ECN allowed (sysctl value 1)
912Note that the behavior is configurable in per-node manner, not per-SA manner
913(draft-ipsec-ecn-00 wants per-SA configuration, but it looks too much for me).
914
915The behavior is summarized as follows (see source code for more detail):
916
917 encapsulate decapsulate
918 --- ---
919RFC2401 copy all TOS bits drop TOS bits on outer
920 from inner to outer. (use inner TOS bits as is)
921
--- 10 unchanged lines hidden (view full) ---
932- if both IPsec tunnel endpoint are capable of ECN-friendly behavior,
933 you'd better configure both end to "ECN allowed" (sysctl value 1).
934- if the other end is very strict about TOS bit, use "RFC2401"
935 (sysctl value -1).
936- in other cases, use "ECN forbidden" (sysctl value 0).
937The default behavior is "ECN forbidden" (sysctl value 0).
938
939For more information, please refer to:
940 http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt
941 RFC2481 (Explicit Congestion Notification)
942 KAME sys/netinet6/{ah,esp}_input.c
943
944(Thanks goes to Kenjiro Cho <kjc@csl.sony.co.jp> for detailed analysis)
945
9464.6 Interoperability
947
948Here are (some of) platforms we have tested IPsec/IKE interoperability
949in the past. Note that both ends (KAME and others) may have modified their
950implementation, so use the following list just for reference purposes.
951 Altiga, Ashley-laurent (vpcom.com), Data Fellows (F-Secure), Ericsson
952 ACC, FreeS/WAN, HITACHI, IBM AIX, IIJ, Intel, Microsoft WinNT, NIST
953 (linux IPsec + plutoplus), Netscreen, OpenBSD, RedCreek, Routerware,
954 SSH, Secure Computing, Soliton, Toshiba, VPNet, Yamaha RT100i
955
9565. IPComp
957(not yet put into FreeBSD4.x, due to inflate related changes in 4.x.)
958
959IPComp stands for IP payload compression protocol. This is aimed for
960payload compression, not the header compression like PPP VJ compression.
961This may be useful when you are using slow serial link (say, cell phone)
962with powerful CPU (well, recent notebook PCs are really powerful...).
963The protocol design of IPComp is very similar to IPsec.
964
965KAME implements the following specifications:
966- RFC2393: IP Payload Compression Protocol (IPComp)
967- RFC2394: IP Payload Compression Using DEFLATE
968
969Here are some points to be noted:
970- IPComp is treated as part of IPsec protocol suite, and SPI and
971 CPI space is unified. Spec says that there's no relationship
972 between two so they are assumed to be separate.
973- IPComp association (IPCA) is kept in SAD.
974- It is possible to use well-known CPI (CPI=2 for DEFLATE for example),
975 for outbound/inbound packet, but for indexing purposes one element from
976 SPI/CPI space will be occupied anyway.
977- pfkey is modified to support IPComp. However, there's no official
978 SA type number assignment yet. Portability with other IPComp
979 stack is questionable (anyway, who else implement IPComp on UN*X?).
980- Spec says that IPComp output processing must be performed before IPsec
981 output processing, to achieve better compression ratio and "stir" data
982 stream before encryption. However, with manual SPD setting, you are able to
983 violate the ordering requirement (KAME code is too generic, maybe).
984- Though MTU can be significantly decreased by using IPComp, no special
985 consideration is made about path MTU (spec talks nothing about MTU
986 consideration). IPComp is designed for serial links, not ethernet-like
987 medium, it seems.
988- You can change compression ratio on outbound packet, by changing
989 deflate_policy in sys/netinet6/ipcomp_core.c. You can also change history
990 buffer size by changing deflate_window in the same source code.
991 (should it be sysctl accessible? or per-SAD configurable?)
992- Tunnel mode IPComp is not working right. KAME box can generate tunnelled
993 IPComp packet, however, cannot accept tunneled IPComp packet.
994
9956. ALTQ
996 (not yet put into FreeBSD4.x)
997
998 <end of IMPLEMENTATION>