1# NOTE: this is from original KAME distribution.
2# Some portion of this document is not applicable to the code merged into
3# FreeBSD-current (for example, section 5).
4
5 Implementation Note
6
7 KAME Project
8 http://www.kame.net/
9 $KAME: IMPLEMENTATION,v 1.216 2001/05/25 07:43:01 jinmei Exp $
10 $FreeBSD: head/share/doc/IPv6/IMPLEMENTATION 121071 2003-10-13 14:57:41Z ume $
11
121. IPv6
13
141.1 Conformance
15
16The KAME kit conforms, or tries to conform, to the latest set of IPv6
17specifications. For future reference we list some of the relevant documents
18below (NOTE: this is not a complete list - this is too hard to maintain...).
19For details please refer to specific chapter in the document, RFCs, manpages
--- 11 unchanged lines hidden (view full) ---
31RFC1933: (see RFC2893)
32RFC1981: Path MTU Discovery for IPv6
33RFC2080: RIPng for IPv6
34 * KAME-supplied route6d, bgpd and hroute6d support this.
35RFC2283: Multiprotocol Extensions for BGP-4
36 * so-called "BGP4+".
37 * KAME-supplied bgpd supports this.
38RFC2292: Advanced Sockets API for IPv6
39 * For supported library functions/kernel APIs, see sys/netinet6/ADVAPI.
40RFC2362: Protocol Independent Multicast-Sparse Mode (PIM-SM)
41 * RFC2362 defines the packet formats and the protcol of PIM-SM.
42RFC2373: IPv6 Addressing Architecture
43 * KAME supports node required addresses, and conforms to the scope
44 requirement.
45RFC2374: An IPv6 Aggregatable Global Unicast Address Format
46 * KAME supports 64-bit length of Interface ID.
47RFC2375: IPv6 Multicast Address Assignments
48 * Userland applications use the well-known addresses assigned in the RFC.
49RFC2428: FTP Extensions for IPv6 and NATs
50 * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428,
51 then RFC1639 if failed.
52RFC2460: IPv6 specification
53RFC2461: Neighbor discovery for IPv6
54 * See 1.2 in this document for details.
55RFC2462: IPv6 Stateless Address Autoconfiguration
56 * See 1.4 in this document for details.
57RFC2463: ICMPv6 for IPv6 specification
58 * See 1.8 in this document for details.
59RFC2464: Transmission of IPv6 Packets over Ethernet Networks
60RFC2465: MIB for IPv6: Textual Conventions and General Group
61 * Necessary statistics are gathered by the kernel. Actual IPv6 MIB
62 support is provided as patchkit for ucd-snmp.
63RFC2466: MIB for IPv6: ICMPv6 group
64 * Necessary statistics are gathered by the kernel. Actual IPv6 MIB
65 support is provided as patchkit for ucd-snmp.
66RFC2467: Transmission of IPv6 Packets over FDDI Networks
67RFC2472: IPv6 over PPP
68RFC2492: IPv6 over ATM Networks
69 * only PVC is supported.
70RFC2497: Transmission of IPv6 packet over ARCnet Networks
71RFC2545: Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing
72RFC2553: Basic Socket Interface Extensions for IPv6
73 * IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind
74 socket (3.8) are,
75 - supported and turned on by default on KAME/FreeBSD[34]x
76 and KAME/BSDI4,
77 - supported but turned off by default on KAME/NetBSD,
78 - not supported on KAME/FreeBSD228, KAME/OpenBSD and KAME/BSDI3.
79 see 1.12 in this document for details.
80RFC2671: Extension Mechanisms for DNS (EDNS0)
81 * see USAGE for how to use it.
82 * not supported on kame/freebsd4 and kame/bsdi4.
83RFC2673: Binary Labels in the Domain Name System
84 * KAME/bsdi4 supports A6, DNAME and binary label to some extent.
85 * KAME apps/bind8 repository has resolver library with partial A6, DNAME
86 and binary label support.
87RFC2675: IPv6 Jumbograms
--- 17 unchanged lines hidden (view full) ---
105 See 1.5 in this document for details.
106RFC2894: Router renumbering for IPv6
107RFC3041: Privacy Extensions for Stateless Address Autoconfiguration in IPv6
108RFC3056: Connection of IPv6 Domains via IPv4 Clouds
109 * So-called "6to4".
110 * "stf" interface implements it. Be sure to read
111 draft-itojun-ipv6-transition-abuse-01.txt
112 below before configuring it, there can be security issues.
113draft-ietf-ipngwg-icmp-name-lookups-07: IPv6 Name Lookups Through ICMP
114draft-ietf-dhc-dhcpv6-15.txt: DHCPv6
115draft-ietf-dhc-dhcpv6exts-12.txt: Extensions for DHCPv6
116 * kame/dhcp6 has test implementation, which will not be compiled in
117 default compilation.
118 * 15/12 drafts are not explicit about padding and string termination.
119 at IETF48, the author confirmed that there's no padding/termination
120 (and extensions can appear unaligned). our code follows the comment.
121draft-itojun-ipv6-tcp-to-anycast-00.txt:
122 Disconnecting TCP connection toward IPv6 anycast address
123draft-ietf-ipngwg-rfc2553bis-03.txt:
124 Basic Socket Interface Extensions for IPv6 (revised)
125draft-ietf-ipngwg-rfc2292bis-02.txt:
126 Advanced Sockets API for IPv6 (revised)
127 * Some of the updates in the draft are not implemented yet. See
128 TODO.2292bis for more details.
129draft-ietf-mobileip-ipv6-13.txt: Mobility Support in IPv6
130 * See section 6.
131draft-ietf-ngtrans-tcpudp-relay-04.txt:
132 An IPv6-to-IPv4 transport relay translator
133 * FAITH tcp relay translator (faithd) implements this. See 3.1 for more
134 details.
135draft-ietf-ipngwg-router-selection-01.txt:
136 Default Router Preferences and More-Specific Routes
137 * router-side only.
138draft-ietf-ipngwg-scoping-arch-02.txt:
139 The architecture, text representation, and usage of IPv6
140 scoped addresses.
141 * some part of the documentation (especially about the routing
142 model) is not supported yet.
143draft-ietf-pim-sm-v2-new-02.txt
144 A revised version of RFC2362, which includes the IPv6 specific
145 packet format and protocol descriptions.
146draft-ietf-dnsext-mdns-00.txt: Multicast DNS
147 * kame/mdnsd has test implementation, which will not be built in
148 default compilation. The draft will experience a major change in the
149 near future, so don't rely upon it.
150draft-itojun-ipv6-transition-abuse-02.txt:
151 Possible abuse against IPv6 transition technologies (expired)
152 * KAME does not implement RFC1933/2893 automatic tunnel.
153 * "stf" interface implements some address filters. Refer to stf(4)
154 for details. Since there's no way to make 6to4 interface 100% secure,
155 we do not include "stf" interface into GENERIC.v6 compilation.
156 * kame/openbsd completely disables IPv4 mapped address support.
157 * kame/netbsd makes IPv4 mapped address support off by default.
158 * See section 1.12.6 and 1.14 for more details.
159draft-itojun-ipv6-tclass-api-02.txt: Socket API for IPv6 traffic class field
160draft-itojun-ipv6-flowlabel-api-01.txt: Socket API for IPv6 flow label field
161 * no consideration is made against the use of routing headers and such.
162
1631.2 Neighbor Discovery
164
165Neighbor Discovery is fairly stable. Currently Address Resolution,
166Duplicated Address Detection, and Neighbor Unreachability Detection
167are supported. In the near future we will be adding Unsolicited Neighbor
--- 154 unchanged lines hidden (view full) ---
322little code change.
323
3241.3.2 Interaction with API
325
326There are several candidates of API to deal with scoped addresses
327without ambiguity.
328
329The IPV6_PKTINFO ancillary data type or socket option defined in the
330advanced API (RFC2292 or draft-ietf-ipngwg-rfc2292bis-xx) can specify
331the outgoing interface of a packet. Similarly, the IPV6_PKTINFO or
332IPV6_RECVPKTINFO socket options tell kernel to pass the incoming
333interface to user applications.
334
335These options are enough to disambiguate scoped addresses of an
336incoming packet, because we can uniquely identify the corresponding
337zone of the scoped address(es) by the incoming interface. However,
338they are too strong for outgoing packets. For example, consider a
339multi-sited node and suppose that more than one interface of the node
340belongs to a same site. When we want to send a packet to the site,
341we can only specify one of the interfaces for the outgoing packet with
342these options; we cannot just say "send the packet to (one of the
343interfaces of) the site."
344
345Another kind of candidates is to use the sin6_scope_id member in the
346sockaddr_in6 structure, defined in RFC2553 and
347draft-ietf-ipngwg-rfc2553bis-xx.txt. The KAME kernel interprets the
348sin6_scope_id field properly in order to disambiguate scoped
349addresses. For example, if an application passes a sockaddr_in6
350structure that has a non-zero sin6_scope_id value to the sendto(2)
351system call, the kernel should send the packet to the appropriate zone
352according to the sin6_scope_id field. Similarly, when the source or
353the destination address of an incoming packet is a scoped one, the
354kernel should detect the correct zone identifier based on the address
355and the receiving interface, fill the identifier in the sin6_scope_id
356field of a sockaddr_in6 structure, and then pass the packet to an
--- 24 unchanged lines hidden (view full) ---
381will need to manipulate the "embedded" zone index. These programs use
382routing sockets and ioctls (like SIOCGIFADDR_IN6) and the kernel API
383will return IPv6 addresses with the 2nd 16bit-word filled in. The
384APIs are for manipulating kernel internal structure. Programs that
385use these APIs have to be prepared about differences in kernels
386anyway.
387
388getaddrinfo(3) and getnameinfo(3) support an extended numeric IPv6
389syntax, as documented in draft-ietf-ipngwg-rfc2553bis-xx.txt. You can
390specify the outgoing link, by using the name of the outgoing interface
391as the link, like "fe80::1%ne0" (again, note that we assume there is
3921-to-1 relationship between links and interfaces.) This way you will
393be able to specify a link-local scoped address without much trouble.
394
395Other APIs like inet_pton(3) and inet_ntop(3) are inherently
396unfriendly with scoped addresses, since they are unable to annotate
397addresses with zone identifier.
--- 9 unchanged lines hidden (view full) ---
407the IPv6 default route by hand, you can type like
408 # route add -inet6 default fe80::9876:5432:1234:abcd%ne0
409(Although we suggest you to run dynamic routing instead of static
410routes, in order to avoid configuration mistakes.)
411
412Some applications have command line options for specifying an
413appropriate zone of a scoped address (like "ping6 -I ne0 ff02::1" to
414specify the outgoing interface). However, you can't always expect such
415options. Thus, we recommend you to use the extended format described
416above.
417
418In any case, when you specify a scoped address to the command line,
419NEVER write the embedded form (such as ff02:1::1 or fe80:2::fedc),
420which should only be used inside the kernel (see Section 1.3.1), and
421is not supposed to work.
422
4231.4 Plug and Play
424
--- 126 unchanged lines hidden (view full) ---
551
552gif can be configured to be ECN-friendly. See 4.5 for ECN-friendliness
553of tunnels, and gif(4) manpage for how to configure.
554
555If you would like to configure an IPv4-in-IPv6 tunnel with gif interface,
556read gif(4) carefully. You may need to remove IPv6 link-local address
557automatically assigned to the gif interface.
558
5591.6 Source Address Selection
560
561KAME's source address selection takes care of the following
562conditions:
563- address scope
564- outgoing interface
565- whether an address is deprecated
566- whether an address is temporary (in terms of RFC 3041)
567- prefix matching against the destination
568
569Roughly speaking, the selection policy is as follows:
570- always use an address that belongs to the same scope zone as the
571 destination.
572- addresses that have equal or larger scope than the scope of the
573 destination are preferred.
574- a deprecated address is not used in new communications if an
575 alternate (non-deprecated) address is available and has sufficient
576 scope.
577- a temporary address (in terms of RFC 3041 privacy extension) are
578 preferred to a public address.
579- if none of above conditions tie-breaks, addresses assigned on the
580 outgoing interface are preferred.
581- if none of above conditions tie-breaks, one which is longest prefix
582 matching against the destination is preferred as the last resort.
583
584For instance, ::1 is selected for ff01::1,
585fe80::200:f8ff:fe01:6317%ne0 for fe80::2a0:24ff:feab:839b%ne0.
586To see how longest-matching works, suppose that
5873ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317
588are given on the outgoing interface. Then the former is chosen as the
589source for the destination 3ffe:501:800::1. Note that even if all
590available addresses have smaller scope than the scope of the
591destination, we choose one anyway. For example, if we have link-local
592and site-local addresses only, we choose a site-local addresses for a
593global destination. If the packet is going to break a site boundary,
594the boundary router will return an ICMPv6 destination unreachable
595error with code 2 - beyond scope of source address.
596
597The precise desripction of the algorithm is quite complicated. To
598describe the algorithm, we introduce the following notation:
599
600For a given destination D,
601 samescope(D): The set of addresses that have the same scope as D.
602 largerscope(D): The set of addresses that have a larger scope than D.
603 smallerscope(D): The set of addresses that have a smaller scope than D.
604
605For a given set of addresses A,
606 DEP(A): the set of deprecated addresses in A.
607 nonDEP(A): A - DEP(A).
608
609For a given set of addresses A,
610 tmp(A): the set of preferred temporary-autoconfigured or
611 manually-configure addresses in A.
612
613Also, the algorithm assumes that the outgoing interface for the
614destination D is determined. We call the interface "I".
615
616The algorithm is as follows. Selection proceeds step by step as
617described; For example, if an address is selected by item 1, item 2 and
618later are not considered at all.
619
620 0. If there is no address in the same scope zone as D, just give up;
621 the packet will not be sent.
622 1. If we do not prefer temporary addresses, go to 3.
623 Otherwise, and if tmp(samescope(D)) is not empty,
624 then choose an address that is on the interface I. If every
625 address is on I, or every address is on a different interface
626 from I, choose an arbitrary one provided that an address longest
627 matching against D is always preferred.
628 2. If tmp(largerscope(D)) is not empty,
629 then choose an address that has the smallest scope. If more than one
630 address has the smallest scope, choose an arbitrary one provided
631 that addresses on I are always preferred.
632 3. If nonDEP(samescope(D)) is not empty,
633 then apply the same logic as of 1.
634 4. If nonDEP(largerscope(D)) is not empty,
635 then apply the same logic as of 2.
636 5. If we do not prefer temporary addresses, go to 7.
637 Otherwise, and if tmp(DEP(samescope(D))) is not empty,
638 then choose an address that is on the interface I. If every
639 address is on I, or every address is on a different interface
640 from I, choose an arbitrary one provided that an address longest
641 matching against D is always preferred.
642 6. If tmp(DEP(largerscope(D))) is not empty,
643 then choose an address that has the smallest scope. If more than
644 one address has the smallest scope, choose an arbitrary one provided
645 that an address on I is always preferred.
646 7. If DEP(samescope(D)) is not empty,
647 then apply the same logic as of 5.
648 8. If DEP(largerscope(D)) is not empty,
649 then apply the same logic as of 6.
650 9. If we do not prefer temporary addresses, go to 11.
651 Otherwise, and if tmp(nonDEP(smallerscope(D))) is not empty,
652 then choose an address that has the largest scope. If more than
653 one address has the largest scope, choose an arbitrary one provided
654 that an address on I is always preferred.
655 10. If tmp(DEP(smallerscope(D))) is not empty,
656 then choose an address that has the largest scope. If more than
657 one address has the largest scope, choose an arbitrary one provided
658 that an address on I is always preferred.
659 11. If nonDEP(smallerscope(D)) is not empty,
660 then apply the same logic as of 9.
661 12. If DEP(smallerscope(D)) is not empty,
662 then apply the same logic as of 10.
663
664There exists a document about source address selection
665(draft-ietf-ipngwg-default-addr-select-xx.txt). KAME's algorithm
666described above takes a similar approach to the document, but there
667are some differences. See the document for more details.
668
669There are some cases where we do not use the above rule. One
670example is connected TCP session, and we use the address kept in TCP
671protocol control block (tcb) as the source.
672Another example is source address for Neighbor Advertisement.
673Under the spec (RFC2461 7.2.2) NA's source should be the target
674address of the corresponding NS's target. In this case we follow
675the spec rather than the above longest-match rule.
676
677If you would like to prohibit the use of deprecated address for some
678reason, configure net.inet6.ip6.use_deprecated to 0. The issue
679related to deprecated address is described in RFC2462 5.5.4 (NOTE:
680there is some debate underway in IETF ipngwg on how to use
681"deprecated" address).
682
6831.7 Jumbo Payload
684
685KAME supports the Jumbo Payload hop-by-hop option used to send IPv6
686packets with payloads longer than 65,535 octets. But since currently
687KAME does not support any physical interface whose MTU is more than
68865,535, such payloads can be seen only on the loopback interface(i.e.
689lo0).
690
--- 171 unchanged lines hidden (view full) ---
862all unicast addresses are removed from the interface, the application
863can't send/receive any multicast packets. Moreover, if a new unicast
864address is assigned to the interface, in_mrejoin() must be called.
865KAME's interfaces, however, have ALWAYS one link-local unicast
866address. These extensions have thus not been implemented in KAME.
867
8681.12 IPv4 mapped address and IPv6 wildcard socket
869
870RFC2553 describes IPv4 mapped address (3.7) and special behavior
871of IPv6 wildcard bind socket (3.8). The spec allows you to:
872- Accept IPv4 connections by AF_INET6 wildcard bind socket.
873- Transmit IPv4 packet over AF_INET6 socket by using special form of
874 the address like ::ffff:10.1.1.1.
875but the spec itself is very complicated and does not specify how the
876socket layer should behave.
877Here we call the former one "listening side" and the latter one "initiating
878side", for reference purposes.
--- 20 unchanged lines hidden (view full) ---
899KAME/BSDI4 enabled supported
900KAME/OpenBSD not supported not supported
901
902The following sections will give you more details, and how you can
903configure the behavior.
904
905Comments on listening side:
906
907It looks that RFC2553 talks too little on wildcard bind issue,
908specifically on (1) port space issue, (2) failure mode, (3) relationship
909between AF_INET/INET6 wildcard bind like ordering constraint, and (4) behavior
910when conflicting socket is opened/closed. There can be several separate
911interpretation for this RFC which conform to it but behaves differently.
912So, to implement portable application you should assume nothing
913about the behavior in the kernel. Using getaddrinfo() is the safest way.
914Port number space and wildcard bind issues were discussed in detail
915on ipv6imp mailing list, in mid March 1999 and it looks that there's
--- 28 unchanged lines hidden (view full) ---
944 Never use gethostby*(), getaddrby*(), inet_*() or getipnodeby*().
945- If you would like to connect to destination, use getaddrinfo() and try
946 all the destination returned, like telnet does.
947- Some of the IPv6 stack is shipped with buggy getaddrinfo(). Ship a minimal
948 working version with your application and use that as last resort.
949
950If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing
951connection, you will need tweaked implementation in DNS support libraries,
952as documented in RFC2553 6.1. KAME libinet6 includes the tweak in
953getipnodebyname(). Note that getipnodebyname() itself is not recommended as
954it does not handle scoped IPv6 addresses at all. For IPv6 name resolution
955getaddrinfo() is the preferred API. getaddrinfo() does not implement the
956tweak.
957
958When writing applications that make outgoing connections, story goes much
959simpler if you treat AF_INET and AF_INET6 as totally separate address family.
960{set,get}sockopt issue goes simpler, DNS issue will be made simpler. We do
961not recommend you to rely upon IPv4 mapped address.
962
9631.12.1 KAME/BSDI3 and KAME/FreeBSD228
964
965The platforms do not support IPv4 mapped address at all (both listening side
966and initiating side). AF_INET6 and AF_INET sockets are totally separated.
967
968Port number space is totally separate between AF_INET and AF_INET6 sockets.
969
970It should be noted that KAME/BSDI3 and KAME/FreeBSD228 are not conformant
971to RFC2553 section 3.7 and 3.8. It is due to code sharing reasons.
972
9731.12.2 KAME/FreeBSD[34]x
974
975KAME/FreeBSD3x and KAME/FreeBSD4x use shared tcp4/6 code (from
976sys/netinet/tcp*) and shared udp4/6 code (from sys/netinet/udp*).
977They use unified inpcb/in6pcb structure.
978
9791.12.2.1 KAME/FreeBSD[34]x, listening side
--- 22 unchanged lines hidden (view full) ---
10021.12.3 KAME/NetBSD
1003
1004KAME/NetBSD uses shared tcp4/6 code (from sys/netinet/tcp*) and shared
1005udp4/6 code (from sys/netinet/udp*). The implementation is made differently
1006from KAME/FreeBSD[34]x. KAME/NetBSD uses separate inpcb/in6pcb structures,
1007while KAME/FreeBSD[34]x uses merged inpcb structure.
1008
1009It should be noted that the default configuration of KAME/NetBSD is not
1010conformant to RFC2553 section 3.8. It is intentionally turned off by default
1011for security reasons.
1012
10131.12.3.1 KAME/NetBSD, listening side
1014
1015The platform can be configured to support IPv4 mapped address/special AF_INET6
1016wildcard bind (disabled by default). Kernel behavior can be summarized as
1017follows:
1018- default: special support code will be compiled in, but is disabled by
1019 default. It can be controlled by sysctl (net.inet6.ip6.v6only),
1020 or setsockopt(IPV6_V6ONLY).
1021- add "INET6_V6ONLY": No special support code for AF_INET6 wildcard socket
1022 will be compiled in. AF_INET6 sockets and AF_INET sockets are totally
1023 separate. The behavior is similar to what described in 1.12.1.
1024
1025sysctl setting will affect per-socket configuration at in6pcb creation time
1026only. In other words, per-socket configuration will be copied from sysctl
1027configuration at in6pcb creation time. To change per-socket behavior, you
1028must perform setsockopt or reopen the socket. Change in sysctl configuration
1029will not change the behavior or sockets that are already opened.
1030
1031Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
1032conditions are satisfied:
1033- there's no AF_INET socket that matches the IPv4 connection
1034- the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
1035 getsockopt(IPV6_V6ONLY) returns 0.
1036
1037You cannot bind(2) with IPv4 mapped address. This is a workaround for port
1038number duplicate and other twists.
1039
10401.12.3.2 KAME/NetBSD, initiating side
1041
1042When you initiate a connection, you can always connect to IPv4 destination
1043over AF_INET6 socket, usin IPv4 mapped address destination (::ffff:10.1.1.1).
1044This is enabled independently from the configuration for listening side, and
1045always enabled.
1046
10471.12.4 KAME/BSDI4
1048
1049KAME/BSDI4 uses NRL-based TCP/UDP stack and inpcb source code,
1050which was derived from NRL IPv6/IPsec stack. We guess it supports IPv4 mapped
1051address and speical AF_INET6 wildcard bind. The implementation is, again,
1052different from other KAME/*BSDs.
1053
10541.12.4.1 KAME/BSDI4, listening side
--- 10 unchanged lines hidden (view full) ---
1065KAME/BSDi4 supports connection initiation to IPv4 mapped address
1066(like ::ffff:10.1.1.1).
1067
10681.12.5 KAME/OpenBSD
1069
1070KAME/OpenBSD uses NRL-based TCP/UDP stack and inpcb source code,
1071which was derived from NRL IPv6/IPsec stack.
1072
1073It should be noted that KAME/OpenBSD is not conformant to RFC2553 section 3.7
1074and 3.8. It is intentionally omitted for security reasons.
1075
10761.12.5.1 KAME/OpenBSD, listening side
1077
1078KAME/OpenBSD disables special behavior on AF_INET6 wildcard bind for
1079security reasons (if IPv4 traffic toward AF_INET6 wildcard bind is allowed,
1080access control will become much harder). KAME/BSDI4 uses NRL-based TCP/UDP
1081stack as well, however, the behavior is different due to OpenBSD's security
1082policy.
--- 36 unchanged lines hidden (view full) ---
1119 else
1120 error;
1121 It is too much to ask for every body to be careful like this.
1122 The problem is, we are not sure if the above code fragment is perfect for
1123 all situations.
1124- By enabling kernel support for IPv4 mapped address (outgoing direction),
1125 servers on the kernel can be hosed by IPv6 native packet that has IPv4
1126 mapped address in IPv6 header source, and can generate unwanted IPv4 packets.
1127 draft-itojun-ipv6-transition-abuse-01.txt talks more about this scenario.
1128
1129Due to the above twists, some of KAME userland programs has restrictions on
1130the use of IPv4 mapped addresses:
1131- rshd/rlogind do not accept connections from IPv4 mapped address.
1132 This is to avoid malicious use of IPv4 mapped address in IPv6 native
1133 packet, to bypass source-address based authentication.
1134- ftp/ftpd assume that you are on dual stack network. IPv4 mapped address
1135 will be decoded in userland, and will be passed to AF_INET sockets
--- 39 unchanged lines hidden (view full) ---
1175 };
1176On the contrary, XNET draft defines as follows:
1177 struct sockaddr_storage {
1178 u_char ss_len; /* address length */
1179 u_char ss_family; /* address family */
1180 /* and bunch of padding */
1181 };
1182
1183In December 1999, it was agreed that RFC2553bis should pick the latter (XNET)
1184definition.
1185
1186KAME kit prior to December 1999 used RFC2553 definition. KAME kit after
1187December 1999 (including December) will conform to XNET definition,
1188based on RFC2553bis discussion.
1189
1190If you look at multiple IPv6 implementations, you will be able to see
1191both definitions. As an userland programmer, the most portable way of
1192dealing with it is to:
1193(1) ensure ss_family and/or ss_len are available on the platform, by using
1194 GNU autoconf,
1195(2) have -Dss_family=__ss_family to unify all occurences (including header
1196 file) into __ss_family, or
--- 49 unchanged lines hidden (view full) ---
1246 (2) offlink packets (so routers should not forward them).
1247 KAME implmements (2) already.
1248
1249KAME code is carefully written to avoid such incidents. More specifically,
1250KAME kernel will reject packets with certain source/dstination address in IPv6
1251base header, or IPv6 routing header. Also, KAME default configuration file
1252is written carefully, to avoid those attacks.
1253
1254draft-itojun-ipv6-transition-abuse-01.txt talks about more about this.
1255
12561.15 Node's required addresses
1257
1258RFC2373 section 2.8 talks about required addresses for an IPv6
1259node. The section talks about how KAME stack manages those required
1260addresses.
1261
12621.15.1 Host case
--- 32 unchanged lines hidden (view full) ---
1295
1296Routing daemons will join appropriate multicast groups, as necessary,
1297like ff02::9 for RIPng.
1298
1299Users can join groups by using appropriate system calls like setsockopt(2).
1300
13011.16 Advanced API
1302
1303Current KAME kernel implements 2292bis API, documented in
1304draft-ietf-ipngwg-rfc2292bis-xx.txt. It also implements RFC2292 API,
1305for backward compatibility purposes with *BSD-integrated codebase.
1306KAME tree ships with 2292bis headers.
1307*BSD-integrated codebase implements either RFC2292, or 2292bis, API.
1308see "COVERAGE" document for detailed implementation status.
1309
1310Here are couple of issues to mention:
1311- *BSD-integrated binaries, compiled for RFC2292, will work on KAME kernel.
1312 For example, OpenBSD 2.7 /sbin/rtsol will work on KAME/openbsd kernel.
1313- KAME binaries, compiled using 2292bis, will not work on *BSD-integrated
1314 kenrel. For example, KAME /usr/local/v6/sbin/rtsol will not work on
1315 OpenBSD 2.7 kernel.
1316- 2292bis API is not compatible with RFC2292 API. 2292bis #define symbols
1317 conflict with RFC2292 symbols. Therefore, if you compile programs that
1318 assume RFC2292 API, the compilation itself goes fine, however, the compiled
1319 binary will not work correctly. The problem is not KAME issue, but API
1320 issue. For example, Solaris 8 implements 2292bis API. If you compile
1321 RFC2292-based code on Solaris 8, the binary can behave strange.
1322
1323There are few (or couple of) incompatible behavior in RFC2292 binary backward
1324compatibility support in KAME tree. To enumerate:
1325- Type 0 routing header lacks support for strict/loose bitmap.
1326 Even if we see packets with "strict" bit set, those bits will not be made
1327 visible to the userland.
1328 Background: RFC2292 document is based on RFC1883 IPv6, and it uses
1329 strict/loose bitmap. 2292bis document is based on RFC2460 IPv6, and it has
1330 no strict/loose bitmap (it was removed from RFC2460). KAME tree obeys
1331 RFC2460 IPv6, and lacks support for strict/loose bitmap.
1332
13332. Network Drivers
1334
1335KAME requires three items to be added into the standard drivers:
1336
1337(1) mbuf clustering requirement. In this stable release, we changed
1338 MINCLSIZE into MHLEN+1 for all the operating systems in order to make
1339 all the drivers behave as we expect.
1340
1341(2) multicast. If "ifmcstat" yields no multicast group for a
1342 interface, that interface has to be patched.
1343
1344To avoid troubles, we suggest you to comment out the device drivers
1345for unsupported/unnecessary cards, from the kernel configuration file.
1346If you accidentally enable unsupported drivers, some of the userland
1347tools may not work correctly (routing daemons are typical example).
--- 217 unchanged lines hidden (view full) ---
1565as OpenBSD team has their home-brew IPsec stack and they have no plan
1566to replace it. IPv6 support for IPsec is, therefore, lacking on KAME/OpenBSD.
1567
1568http://www.netbsd.org/Documentation/network/ipsec/ has more information
1569including usage examples.
1570
15714.1 Policy Management
1572
1573The kernel implements experimental policy management code. There are two way
1574to manage security policy. One is to configure per-socket policy using
1575setsockopt(3). In this cases, policy configuration is described in
1576ipsec_set_policy(3). The other is to configure kernel packet filter-based
1577policy using PF_KEY interface, via setkey(8).
1578
1579The policy entry will be matched in order. The order of entries makes
1580difference in behavior.
1581
--- 9 unchanged lines hidden (view full) ---
1591The kernel will contact racoon daemon as necessary to exchange keys.
1592
1593In IKE spec, there's ambiguity about interpretation of "tunnel" proposal.
1594For example, if we would like to propose the use of following packet:
1595 IP AH ESP IP payload
1596some implementation proposes it as "AH transport and ESP tunnel", since
1597this is more logical from packet construction point of view. Some
1598implementation proposes it as "AH tunnel and ESP tunnel".
1599Racoon follows the former route.
1600This raises real interoperability issue. We hope this to be resolved quickly.
1601
16024.3 AH and ESP handling
1603
1604IPsec module is implemented as "hooks" to the standard IPv4/IPv6
1605processing. When sending a packet, ip{,6}_output() checks if ESP/AH
1606processing is required by checking if a matching SPD (Security
1607Policy Database) is found. If ESP/AH is needed,
1608{esp,ah}{4,6}_output() will be called and mbuf will be updated
1609accordingly. When a packet is received, {esp,ah}4_input() will be
--- 86 unchanged lines hidden (view full) ---
1696 see ipsec wg mailing list discussion in Jan 2000 for details.
1697
16984.5 Conformance to RFCs and IDs
1699
1700The IPsec code in the kernel conforms (or, tries to conform) to the
1701following standards:
1702 "old IPsec" specification documented in rfc182[5-9].txt
1703 "new IPsec" specification documented in:
1704 rfc240[1-6].txt rfc241[01].txt rfc2451.txt
1705 draft-mcdonald-simple-ipsec-api-01.txt
1706 (expired, available in ftp://ftp.kame.net/pub/internet-drafts/)
1707 draft-ietf-ipsec-ciph-aes-cbc-00.txt
1708 IPComp:
1709 RFC2393: IP Payload Compression Protocol (IPComp)
1710IKE specifications (rfc240[7-9].txt) are implemented in userland
1711as "racoon" IKE daemon.
1712
1713Currently supported algorithms are:
1714 old IPsec AH
1715 null crypto checksum (no document, just for debugging)
--- 123 unchanged lines hidden (view full) ---
1839in the past, in no particular order.
1840 IRE, SSH (both IPv4/IPv6), NetLock
1841
1842VPNC (vpnc.org) provides IPsec conformance tests, using KAME and OpenBSD
1843IPsec/IKE implementations. Their test results are available at
1844http://www.vpnc.org/conformance.html, and it may give you more idea
1845about which implementation interoperates with KAME IPsec/IKE implementation.
1846
18475. ALTQ
1848
1849KAME kit includes ALTQ 2.1 code, which supports FreeBSD2, FreeBSD3,
1850NetBSD and OpenBSD. For BSD/OS, ALTQ does not work.
1851ALTQ in KAME supports (or tries to support) IPv6.
1852(actually, ALTQ is developed on KAME repository since ALTQ 2.1 - Jan 2000)
1853
1854ALTQ occupies single character device number. For FreeBSD, it is officially
--- 32 unchanged lines hidden (view full) ---
1887 SFC: http://neo.sfc.wide.ad.jp/~mip6/ (-13 draft)
1888
18897. Coding style
1890
1891The KAME developers basically do not make a bother about coding
1892style. However, there is still some agreement on the style, in order
1893to make the distributed develoment smooth.
1894
1895- the tab character should be 8 columns wide (tabstops are at 8, 16, 24, ...
1896 column). With vi, use ":set ts=8 sw=8".
1897- each line should be within 80 characters.
1898- keep a single open/close bracket in a comment such as in the following
1899 line:
1900 putchar('('); /* ) */
1901 without this, some vi users would have a hard time to match a pair of
1902 brackets. Although this type of bracket seems clumsy and is even
1903 harmful for some other type of vi users and Emacs users, the
1904 agreement in the KAME developers is to allow it.
1905- add the following line to the head of every KAME-derived file:
1906 /* (dollar)KAME(dollar) */
1907 where "(dollar)" is the dollar character ($), and around "$" are tabs.
1908 (this is for C. For other language, you should use its own comment
1909 line.)
1910 Once commited to the CVS repository, this line will contain its
1911 version number (see, for example, at the top of this file). This
1912 would make it easy to report a bug.
1913- when creating a new file with the WIDE copyright, tap "make copyright.c" at
1914 the top-level, and use copyright.c as a template. KAME RCS tag will be
1915 included automatically.
1916- when editting a third-party package, keep its own coding style as
1917 much as possible, even if the style does not follow the items above.
1918
1919When you want to contribute something to the KAME project, and if *you
1920do not mind* the agreement, it would be helpful for the project to
1921keep these rules. Note, however, that we would never intend to force
1922you to adopt our rules. We would rather regard your own style,
1923especially when you have a policy about the style.
1924
1925 <end of IMPLEMENTATION>
2# Some portion of this document is not applicable to the code merged into
3# FreeBSD-current (for example, section 5).
4
5 Implementation Note
6
7 KAME Project
8 http://www.kame.net/
9 $KAME: IMPLEMENTATION,v 1.216 2001/05/25 07:43:01 jinmei Exp $
10 $FreeBSD: head/share/doc/IPv6/IMPLEMENTATION 121071 2003-10-13 14:57:41Z ume $
11
121. IPv6
13
141.1 Conformance
15
16The KAME kit conforms, or tries to conform, to the latest set of IPv6
17specifications. For future reference we list some of the relevant documents
18below (NOTE: this is not a complete list - this is too hard to maintain...).
19For details please refer to specific chapter in the document, RFCs, manpages
--- 11 unchanged lines hidden (view full) ---
31RFC1933: (see RFC2893)
32RFC1981: Path MTU Discovery for IPv6
33RFC2080: RIPng for IPv6
34 * KAME-supplied route6d, bgpd and hroute6d support this.
35RFC2283: Multiprotocol Extensions for BGP-4
36 * so-called "BGP4+".
37 * KAME-supplied bgpd supports this.
38RFC2292: Advanced Sockets API for IPv6
39 * For supported library functions/kernel APIs, see sys/netinet6/ADVAPI.
40RFC2362: Protocol Independent Multicast-Sparse Mode (PIM-SM)
41 * RFC2362 defines the packet formats and the protcol of PIM-SM.
42RFC2373: IPv6 Addressing Architecture
43 * KAME supports node required addresses, and conforms to the scope
44 requirement.
45RFC2374: An IPv6 Aggregatable Global Unicast Address Format
46 * KAME supports 64-bit length of Interface ID.
47RFC2375: IPv6 Multicast Address Assignments
48 * Userland applications use the well-known addresses assigned in the RFC.
49RFC2428: FTP Extensions for IPv6 and NATs
50 * RFC2428 is preferred over RFC1639. ftp clients will first try RFC2428,
51 then RFC1639 if failed.
52RFC2460: IPv6 specification
53RFC2461: Neighbor discovery for IPv6
54 * See 1.2 in this document for details.
55RFC2462: IPv6 Stateless Address Autoconfiguration
56 * See 1.4 in this document for details.
57RFC2463: ICMPv6 for IPv6 specification
58 * See 1.8 in this document for details.
59RFC2464: Transmission of IPv6 Packets over Ethernet Networks
60RFC2465: MIB for IPv6: Textual Conventions and General Group
61 * Necessary statistics are gathered by the kernel. Actual IPv6 MIB
62 support is provided as patchkit for ucd-snmp.
63RFC2466: MIB for IPv6: ICMPv6 group
64 * Necessary statistics are gathered by the kernel. Actual IPv6 MIB
65 support is provided as patchkit for ucd-snmp.
66RFC2467: Transmission of IPv6 Packets over FDDI Networks
67RFC2472: IPv6 over PPP
68RFC2492: IPv6 over ATM Networks
69 * only PVC is supported.
70RFC2497: Transmission of IPv6 packet over ARCnet Networks
71RFC2545: Use of BGP-4 Multiprotocol Extensions for IPv6 Inter-Domain Routing
72RFC2553: Basic Socket Interface Extensions for IPv6
73 * IPv4 mapped address (3.7) and special behavior of IPv6 wildcard bind
74 socket (3.8) are,
75 - supported and turned on by default on KAME/FreeBSD[34]x
76 and KAME/BSDI4,
77 - supported but turned off by default on KAME/NetBSD,
78 - not supported on KAME/FreeBSD228, KAME/OpenBSD and KAME/BSDI3.
79 see 1.12 in this document for details.
80RFC2671: Extension Mechanisms for DNS (EDNS0)
81 * see USAGE for how to use it.
82 * not supported on kame/freebsd4 and kame/bsdi4.
83RFC2673: Binary Labels in the Domain Name System
84 * KAME/bsdi4 supports A6, DNAME and binary label to some extent.
85 * KAME apps/bind8 repository has resolver library with partial A6, DNAME
86 and binary label support.
87RFC2675: IPv6 Jumbograms
--- 17 unchanged lines hidden (view full) ---
105 See 1.5 in this document for details.
106RFC2894: Router renumbering for IPv6
107RFC3041: Privacy Extensions for Stateless Address Autoconfiguration in IPv6
108RFC3056: Connection of IPv6 Domains via IPv4 Clouds
109 * So-called "6to4".
110 * "stf" interface implements it. Be sure to read
111 draft-itojun-ipv6-transition-abuse-01.txt
112 below before configuring it, there can be security issues.
113draft-ietf-ipngwg-icmp-name-lookups-07: IPv6 Name Lookups Through ICMP
114draft-ietf-dhc-dhcpv6-15.txt: DHCPv6
115draft-ietf-dhc-dhcpv6exts-12.txt: Extensions for DHCPv6
116 * kame/dhcp6 has test implementation, which will not be compiled in
117 default compilation.
118 * 15/12 drafts are not explicit about padding and string termination.
119 at IETF48, the author confirmed that there's no padding/termination
120 (and extensions can appear unaligned). our code follows the comment.
121draft-itojun-ipv6-tcp-to-anycast-00.txt:
122 Disconnecting TCP connection toward IPv6 anycast address
123draft-ietf-ipngwg-rfc2553bis-03.txt:
124 Basic Socket Interface Extensions for IPv6 (revised)
125draft-ietf-ipngwg-rfc2292bis-02.txt:
126 Advanced Sockets API for IPv6 (revised)
127 * Some of the updates in the draft are not implemented yet. See
128 TODO.2292bis for more details.
129draft-ietf-mobileip-ipv6-13.txt: Mobility Support in IPv6
130 * See section 6.
131draft-ietf-ngtrans-tcpudp-relay-04.txt:
132 An IPv6-to-IPv4 transport relay translator
133 * FAITH tcp relay translator (faithd) implements this. See 3.1 for more
134 details.
135draft-ietf-ipngwg-router-selection-01.txt:
136 Default Router Preferences and More-Specific Routes
137 * router-side only.
138draft-ietf-ipngwg-scoping-arch-02.txt:
139 The architecture, text representation, and usage of IPv6
140 scoped addresses.
141 * some part of the documentation (especially about the routing
142 model) is not supported yet.
143draft-ietf-pim-sm-v2-new-02.txt
144 A revised version of RFC2362, which includes the IPv6 specific
145 packet format and protocol descriptions.
146draft-ietf-dnsext-mdns-00.txt: Multicast DNS
147 * kame/mdnsd has test implementation, which will not be built in
148 default compilation. The draft will experience a major change in the
149 near future, so don't rely upon it.
150draft-itojun-ipv6-transition-abuse-02.txt:
151 Possible abuse against IPv6 transition technologies (expired)
152 * KAME does not implement RFC1933/2893 automatic tunnel.
153 * "stf" interface implements some address filters. Refer to stf(4)
154 for details. Since there's no way to make 6to4 interface 100% secure,
155 we do not include "stf" interface into GENERIC.v6 compilation.
156 * kame/openbsd completely disables IPv4 mapped address support.
157 * kame/netbsd makes IPv4 mapped address support off by default.
158 * See section 1.12.6 and 1.14 for more details.
159draft-itojun-ipv6-tclass-api-02.txt: Socket API for IPv6 traffic class field
160draft-itojun-ipv6-flowlabel-api-01.txt: Socket API for IPv6 flow label field
161 * no consideration is made against the use of routing headers and such.
162
1631.2 Neighbor Discovery
164
165Neighbor Discovery is fairly stable. Currently Address Resolution,
166Duplicated Address Detection, and Neighbor Unreachability Detection
167are supported. In the near future we will be adding Unsolicited Neighbor
--- 154 unchanged lines hidden (view full) ---
322little code change.
323
3241.3.2 Interaction with API
325
326There are several candidates of API to deal with scoped addresses
327without ambiguity.
328
329The IPV6_PKTINFO ancillary data type or socket option defined in the
330advanced API (RFC2292 or draft-ietf-ipngwg-rfc2292bis-xx) can specify
331the outgoing interface of a packet. Similarly, the IPV6_PKTINFO or
332IPV6_RECVPKTINFO socket options tell kernel to pass the incoming
333interface to user applications.
334
335These options are enough to disambiguate scoped addresses of an
336incoming packet, because we can uniquely identify the corresponding
337zone of the scoped address(es) by the incoming interface. However,
338they are too strong for outgoing packets. For example, consider a
339multi-sited node and suppose that more than one interface of the node
340belongs to a same site. When we want to send a packet to the site,
341we can only specify one of the interfaces for the outgoing packet with
342these options; we cannot just say "send the packet to (one of the
343interfaces of) the site."
344
345Another kind of candidates is to use the sin6_scope_id member in the
346sockaddr_in6 structure, defined in RFC2553 and
347draft-ietf-ipngwg-rfc2553bis-xx.txt. The KAME kernel interprets the
348sin6_scope_id field properly in order to disambiguate scoped
349addresses. For example, if an application passes a sockaddr_in6
350structure that has a non-zero sin6_scope_id value to the sendto(2)
351system call, the kernel should send the packet to the appropriate zone
352according to the sin6_scope_id field. Similarly, when the source or
353the destination address of an incoming packet is a scoped one, the
354kernel should detect the correct zone identifier based on the address
355and the receiving interface, fill the identifier in the sin6_scope_id
356field of a sockaddr_in6 structure, and then pass the packet to an
--- 24 unchanged lines hidden (view full) ---
381will need to manipulate the "embedded" zone index. These programs use
382routing sockets and ioctls (like SIOCGIFADDR_IN6) and the kernel API
383will return IPv6 addresses with the 2nd 16bit-word filled in. The
384APIs are for manipulating kernel internal structure. Programs that
385use these APIs have to be prepared about differences in kernels
386anyway.
387
388getaddrinfo(3) and getnameinfo(3) support an extended numeric IPv6
389syntax, as documented in draft-ietf-ipngwg-rfc2553bis-xx.txt. You can
390specify the outgoing link, by using the name of the outgoing interface
391as the link, like "fe80::1%ne0" (again, note that we assume there is
3921-to-1 relationship between links and interfaces.) This way you will
393be able to specify a link-local scoped address without much trouble.
394
395Other APIs like inet_pton(3) and inet_ntop(3) are inherently
396unfriendly with scoped addresses, since they are unable to annotate
397addresses with zone identifier.
--- 9 unchanged lines hidden (view full) ---
407the IPv6 default route by hand, you can type like
408 # route add -inet6 default fe80::9876:5432:1234:abcd%ne0
409(Although we suggest you to run dynamic routing instead of static
410routes, in order to avoid configuration mistakes.)
411
412Some applications have command line options for specifying an
413appropriate zone of a scoped address (like "ping6 -I ne0 ff02::1" to
414specify the outgoing interface). However, you can't always expect such
415options. Thus, we recommend you to use the extended format described
416above.
417
418In any case, when you specify a scoped address to the command line,
419NEVER write the embedded form (such as ff02:1::1 or fe80:2::fedc),
420which should only be used inside the kernel (see Section 1.3.1), and
421is not supposed to work.
422
4231.4 Plug and Play
424
--- 126 unchanged lines hidden (view full) ---
551
552gif can be configured to be ECN-friendly. See 4.5 for ECN-friendliness
553of tunnels, and gif(4) manpage for how to configure.
554
555If you would like to configure an IPv4-in-IPv6 tunnel with gif interface,
556read gif(4) carefully. You may need to remove IPv6 link-local address
557automatically assigned to the gif interface.
558
5591.6 Source Address Selection
560
561KAME's source address selection takes care of the following
562conditions:
563- address scope
564- outgoing interface
565- whether an address is deprecated
566- whether an address is temporary (in terms of RFC 3041)
567- prefix matching against the destination
568
569Roughly speaking, the selection policy is as follows:
570- always use an address that belongs to the same scope zone as the
571 destination.
572- addresses that have equal or larger scope than the scope of the
573 destination are preferred.
574- a deprecated address is not used in new communications if an
575 alternate (non-deprecated) address is available and has sufficient
576 scope.
577- a temporary address (in terms of RFC 3041 privacy extension) are
578 preferred to a public address.
579- if none of above conditions tie-breaks, addresses assigned on the
580 outgoing interface are preferred.
581- if none of above conditions tie-breaks, one which is longest prefix
582 matching against the destination is preferred as the last resort.
583
584For instance, ::1 is selected for ff01::1,
585fe80::200:f8ff:fe01:6317%ne0 for fe80::2a0:24ff:feab:839b%ne0.
586To see how longest-matching works, suppose that
5873ffe:501:808:1:200:f8ff:fe01:6317 and 3ffe:2001:9:124:200:f8ff:fe01:6317
588are given on the outgoing interface. Then the former is chosen as the
589source for the destination 3ffe:501:800::1. Note that even if all
590available addresses have smaller scope than the scope of the
591destination, we choose one anyway. For example, if we have link-local
592and site-local addresses only, we choose a site-local addresses for a
593global destination. If the packet is going to break a site boundary,
594the boundary router will return an ICMPv6 destination unreachable
595error with code 2 - beyond scope of source address.
596
597The precise desripction of the algorithm is quite complicated. To
598describe the algorithm, we introduce the following notation:
599
600For a given destination D,
601 samescope(D): The set of addresses that have the same scope as D.
602 largerscope(D): The set of addresses that have a larger scope than D.
603 smallerscope(D): The set of addresses that have a smaller scope than D.
604
605For a given set of addresses A,
606 DEP(A): the set of deprecated addresses in A.
607 nonDEP(A): A - DEP(A).
608
609For a given set of addresses A,
610 tmp(A): the set of preferred temporary-autoconfigured or
611 manually-configure addresses in A.
612
613Also, the algorithm assumes that the outgoing interface for the
614destination D is determined. We call the interface "I".
615
616The algorithm is as follows. Selection proceeds step by step as
617described; For example, if an address is selected by item 1, item 2 and
618later are not considered at all.
619
620 0. If there is no address in the same scope zone as D, just give up;
621 the packet will not be sent.
622 1. If we do not prefer temporary addresses, go to 3.
623 Otherwise, and if tmp(samescope(D)) is not empty,
624 then choose an address that is on the interface I. If every
625 address is on I, or every address is on a different interface
626 from I, choose an arbitrary one provided that an address longest
627 matching against D is always preferred.
628 2. If tmp(largerscope(D)) is not empty,
629 then choose an address that has the smallest scope. If more than one
630 address has the smallest scope, choose an arbitrary one provided
631 that addresses on I are always preferred.
632 3. If nonDEP(samescope(D)) is not empty,
633 then apply the same logic as of 1.
634 4. If nonDEP(largerscope(D)) is not empty,
635 then apply the same logic as of 2.
636 5. If we do not prefer temporary addresses, go to 7.
637 Otherwise, and if tmp(DEP(samescope(D))) is not empty,
638 then choose an address that is on the interface I. If every
639 address is on I, or every address is on a different interface
640 from I, choose an arbitrary one provided that an address longest
641 matching against D is always preferred.
642 6. If tmp(DEP(largerscope(D))) is not empty,
643 then choose an address that has the smallest scope. If more than
644 one address has the smallest scope, choose an arbitrary one provided
645 that an address on I is always preferred.
646 7. If DEP(samescope(D)) is not empty,
647 then apply the same logic as of 5.
648 8. If DEP(largerscope(D)) is not empty,
649 then apply the same logic as of 6.
650 9. If we do not prefer temporary addresses, go to 11.
651 Otherwise, and if tmp(nonDEP(smallerscope(D))) is not empty,
652 then choose an address that has the largest scope. If more than
653 one address has the largest scope, choose an arbitrary one provided
654 that an address on I is always preferred.
655 10. If tmp(DEP(smallerscope(D))) is not empty,
656 then choose an address that has the largest scope. If more than
657 one address has the largest scope, choose an arbitrary one provided
658 that an address on I is always preferred.
659 11. If nonDEP(smallerscope(D)) is not empty,
660 then apply the same logic as of 9.
661 12. If DEP(smallerscope(D)) is not empty,
662 then apply the same logic as of 10.
663
664There exists a document about source address selection
665(draft-ietf-ipngwg-default-addr-select-xx.txt). KAME's algorithm
666described above takes a similar approach to the document, but there
667are some differences. See the document for more details.
668
669There are some cases where we do not use the above rule. One
670example is connected TCP session, and we use the address kept in TCP
671protocol control block (tcb) as the source.
672Another example is source address for Neighbor Advertisement.
673Under the spec (RFC2461 7.2.2) NA's source should be the target
674address of the corresponding NS's target. In this case we follow
675the spec rather than the above longest-match rule.
676
677If you would like to prohibit the use of deprecated address for some
678reason, configure net.inet6.ip6.use_deprecated to 0. The issue
679related to deprecated address is described in RFC2462 5.5.4 (NOTE:
680there is some debate underway in IETF ipngwg on how to use
681"deprecated" address).
682
6831.7 Jumbo Payload
684
685KAME supports the Jumbo Payload hop-by-hop option used to send IPv6
686packets with payloads longer than 65,535 octets. But since currently
687KAME does not support any physical interface whose MTU is more than
68865,535, such payloads can be seen only on the loopback interface(i.e.
689lo0).
690
--- 171 unchanged lines hidden (view full) ---
862all unicast addresses are removed from the interface, the application
863can't send/receive any multicast packets. Moreover, if a new unicast
864address is assigned to the interface, in_mrejoin() must be called.
865KAME's interfaces, however, have ALWAYS one link-local unicast
866address. These extensions have thus not been implemented in KAME.
867
8681.12 IPv4 mapped address and IPv6 wildcard socket
869
870RFC2553 describes IPv4 mapped address (3.7) and special behavior
871of IPv6 wildcard bind socket (3.8). The spec allows you to:
872- Accept IPv4 connections by AF_INET6 wildcard bind socket.
873- Transmit IPv4 packet over AF_INET6 socket by using special form of
874 the address like ::ffff:10.1.1.1.
875but the spec itself is very complicated and does not specify how the
876socket layer should behave.
877Here we call the former one "listening side" and the latter one "initiating
878side", for reference purposes.
--- 20 unchanged lines hidden (view full) ---
899KAME/BSDI4 enabled supported
900KAME/OpenBSD not supported not supported
901
902The following sections will give you more details, and how you can
903configure the behavior.
904
905Comments on listening side:
906
907It looks that RFC2553 talks too little on wildcard bind issue,
908specifically on (1) port space issue, (2) failure mode, (3) relationship
909between AF_INET/INET6 wildcard bind like ordering constraint, and (4) behavior
910when conflicting socket is opened/closed. There can be several separate
911interpretation for this RFC which conform to it but behaves differently.
912So, to implement portable application you should assume nothing
913about the behavior in the kernel. Using getaddrinfo() is the safest way.
914Port number space and wildcard bind issues were discussed in detail
915on ipv6imp mailing list, in mid March 1999 and it looks that there's
--- 28 unchanged lines hidden (view full) ---
944 Never use gethostby*(), getaddrby*(), inet_*() or getipnodeby*().
945- If you would like to connect to destination, use getaddrinfo() and try
946 all the destination returned, like telnet does.
947- Some of the IPv6 stack is shipped with buggy getaddrinfo(). Ship a minimal
948 working version with your application and use that as last resort.
949
950If you would like to use AF_INET6 socket for both IPv4 and IPv6 outgoing
951connection, you will need tweaked implementation in DNS support libraries,
952as documented in RFC2553 6.1. KAME libinet6 includes the tweak in
953getipnodebyname(). Note that getipnodebyname() itself is not recommended as
954it does not handle scoped IPv6 addresses at all. For IPv6 name resolution
955getaddrinfo() is the preferred API. getaddrinfo() does not implement the
956tweak.
957
958When writing applications that make outgoing connections, story goes much
959simpler if you treat AF_INET and AF_INET6 as totally separate address family.
960{set,get}sockopt issue goes simpler, DNS issue will be made simpler. We do
961not recommend you to rely upon IPv4 mapped address.
962
9631.12.1 KAME/BSDI3 and KAME/FreeBSD228
964
965The platforms do not support IPv4 mapped address at all (both listening side
966and initiating side). AF_INET6 and AF_INET sockets are totally separated.
967
968Port number space is totally separate between AF_INET and AF_INET6 sockets.
969
970It should be noted that KAME/BSDI3 and KAME/FreeBSD228 are not conformant
971to RFC2553 section 3.7 and 3.8. It is due to code sharing reasons.
972
9731.12.2 KAME/FreeBSD[34]x
974
975KAME/FreeBSD3x and KAME/FreeBSD4x use shared tcp4/6 code (from
976sys/netinet/tcp*) and shared udp4/6 code (from sys/netinet/udp*).
977They use unified inpcb/in6pcb structure.
978
9791.12.2.1 KAME/FreeBSD[34]x, listening side
--- 22 unchanged lines hidden (view full) ---
10021.12.3 KAME/NetBSD
1003
1004KAME/NetBSD uses shared tcp4/6 code (from sys/netinet/tcp*) and shared
1005udp4/6 code (from sys/netinet/udp*). The implementation is made differently
1006from KAME/FreeBSD[34]x. KAME/NetBSD uses separate inpcb/in6pcb structures,
1007while KAME/FreeBSD[34]x uses merged inpcb structure.
1008
1009It should be noted that the default configuration of KAME/NetBSD is not
1010conformant to RFC2553 section 3.8. It is intentionally turned off by default
1011for security reasons.
1012
10131.12.3.1 KAME/NetBSD, listening side
1014
1015The platform can be configured to support IPv4 mapped address/special AF_INET6
1016wildcard bind (disabled by default). Kernel behavior can be summarized as
1017follows:
1018- default: special support code will be compiled in, but is disabled by
1019 default. It can be controlled by sysctl (net.inet6.ip6.v6only),
1020 or setsockopt(IPV6_V6ONLY).
1021- add "INET6_V6ONLY": No special support code for AF_INET6 wildcard socket
1022 will be compiled in. AF_INET6 sockets and AF_INET sockets are totally
1023 separate. The behavior is similar to what described in 1.12.1.
1024
1025sysctl setting will affect per-socket configuration at in6pcb creation time
1026only. In other words, per-socket configuration will be copied from sysctl
1027configuration at in6pcb creation time. To change per-socket behavior, you
1028must perform setsockopt or reopen the socket. Change in sysctl configuration
1029will not change the behavior or sockets that are already opened.
1030
1031Wildcard AF_INET6 socket grabs IPv4 connection if and only if the following
1032conditions are satisfied:
1033- there's no AF_INET socket that matches the IPv4 connection
1034- the AF_INET6 socket is configured to accept IPv4 traffic, i.e.
1035 getsockopt(IPV6_V6ONLY) returns 0.
1036
1037You cannot bind(2) with IPv4 mapped address. This is a workaround for port
1038number duplicate and other twists.
1039
10401.12.3.2 KAME/NetBSD, initiating side
1041
1042When you initiate a connection, you can always connect to IPv4 destination
1043over AF_INET6 socket, usin IPv4 mapped address destination (::ffff:10.1.1.1).
1044This is enabled independently from the configuration for listening side, and
1045always enabled.
1046
10471.12.4 KAME/BSDI4
1048
1049KAME/BSDI4 uses NRL-based TCP/UDP stack and inpcb source code,
1050which was derived from NRL IPv6/IPsec stack. We guess it supports IPv4 mapped
1051address and speical AF_INET6 wildcard bind. The implementation is, again,
1052different from other KAME/*BSDs.
1053
10541.12.4.1 KAME/BSDI4, listening side
--- 10 unchanged lines hidden (view full) ---
1065KAME/BSDi4 supports connection initiation to IPv4 mapped address
1066(like ::ffff:10.1.1.1).
1067
10681.12.5 KAME/OpenBSD
1069
1070KAME/OpenBSD uses NRL-based TCP/UDP stack and inpcb source code,
1071which was derived from NRL IPv6/IPsec stack.
1072
1073It should be noted that KAME/OpenBSD is not conformant to RFC2553 section 3.7
1074and 3.8. It is intentionally omitted for security reasons.
1075
10761.12.5.1 KAME/OpenBSD, listening side
1077
1078KAME/OpenBSD disables special behavior on AF_INET6 wildcard bind for
1079security reasons (if IPv4 traffic toward AF_INET6 wildcard bind is allowed,
1080access control will become much harder). KAME/BSDI4 uses NRL-based TCP/UDP
1081stack as well, however, the behavior is different due to OpenBSD's security
1082policy.
--- 36 unchanged lines hidden (view full) ---
1119 else
1120 error;
1121 It is too much to ask for every body to be careful like this.
1122 The problem is, we are not sure if the above code fragment is perfect for
1123 all situations.
1124- By enabling kernel support for IPv4 mapped address (outgoing direction),
1125 servers on the kernel can be hosed by IPv6 native packet that has IPv4
1126 mapped address in IPv6 header source, and can generate unwanted IPv4 packets.
1127 draft-itojun-ipv6-transition-abuse-01.txt talks more about this scenario.
1128
1129Due to the above twists, some of KAME userland programs has restrictions on
1130the use of IPv4 mapped addresses:
1131- rshd/rlogind do not accept connections from IPv4 mapped address.
1132 This is to avoid malicious use of IPv4 mapped address in IPv6 native
1133 packet, to bypass source-address based authentication.
1134- ftp/ftpd assume that you are on dual stack network. IPv4 mapped address
1135 will be decoded in userland, and will be passed to AF_INET sockets
--- 39 unchanged lines hidden (view full) ---
1175 };
1176On the contrary, XNET draft defines as follows:
1177 struct sockaddr_storage {
1178 u_char ss_len; /* address length */
1179 u_char ss_family; /* address family */
1180 /* and bunch of padding */
1181 };
1182
1183In December 1999, it was agreed that RFC2553bis should pick the latter (XNET)
1184definition.
1185
1186KAME kit prior to December 1999 used RFC2553 definition. KAME kit after
1187December 1999 (including December) will conform to XNET definition,
1188based on RFC2553bis discussion.
1189
1190If you look at multiple IPv6 implementations, you will be able to see
1191both definitions. As an userland programmer, the most portable way of
1192dealing with it is to:
1193(1) ensure ss_family and/or ss_len are available on the platform, by using
1194 GNU autoconf,
1195(2) have -Dss_family=__ss_family to unify all occurences (including header
1196 file) into __ss_family, or
--- 49 unchanged lines hidden (view full) ---
1246 (2) offlink packets (so routers should not forward them).
1247 KAME implmements (2) already.
1248
1249KAME code is carefully written to avoid such incidents. More specifically,
1250KAME kernel will reject packets with certain source/dstination address in IPv6
1251base header, or IPv6 routing header. Also, KAME default configuration file
1252is written carefully, to avoid those attacks.
1253
1254draft-itojun-ipv6-transition-abuse-01.txt talks about more about this.
1255
12561.15 Node's required addresses
1257
1258RFC2373 section 2.8 talks about required addresses for an IPv6
1259node. The section talks about how KAME stack manages those required
1260addresses.
1261
12621.15.1 Host case
--- 32 unchanged lines hidden (view full) ---
1295
1296Routing daemons will join appropriate multicast groups, as necessary,
1297like ff02::9 for RIPng.
1298
1299Users can join groups by using appropriate system calls like setsockopt(2).
1300
13011.16 Advanced API
1302
1303Current KAME kernel implements 2292bis API, documented in
1304draft-ietf-ipngwg-rfc2292bis-xx.txt. It also implements RFC2292 API,
1305for backward compatibility purposes with *BSD-integrated codebase.
1306KAME tree ships with 2292bis headers.
1307*BSD-integrated codebase implements either RFC2292, or 2292bis, API.
1308see "COVERAGE" document for detailed implementation status.
1309
1310Here are couple of issues to mention:
1311- *BSD-integrated binaries, compiled for RFC2292, will work on KAME kernel.
1312 For example, OpenBSD 2.7 /sbin/rtsol will work on KAME/openbsd kernel.
1313- KAME binaries, compiled using 2292bis, will not work on *BSD-integrated
1314 kenrel. For example, KAME /usr/local/v6/sbin/rtsol will not work on
1315 OpenBSD 2.7 kernel.
1316- 2292bis API is not compatible with RFC2292 API. 2292bis #define symbols
1317 conflict with RFC2292 symbols. Therefore, if you compile programs that
1318 assume RFC2292 API, the compilation itself goes fine, however, the compiled
1319 binary will not work correctly. The problem is not KAME issue, but API
1320 issue. For example, Solaris 8 implements 2292bis API. If you compile
1321 RFC2292-based code on Solaris 8, the binary can behave strange.
1322
1323There are few (or couple of) incompatible behavior in RFC2292 binary backward
1324compatibility support in KAME tree. To enumerate:
1325- Type 0 routing header lacks support for strict/loose bitmap.
1326 Even if we see packets with "strict" bit set, those bits will not be made
1327 visible to the userland.
1328 Background: RFC2292 document is based on RFC1883 IPv6, and it uses
1329 strict/loose bitmap. 2292bis document is based on RFC2460 IPv6, and it has
1330 no strict/loose bitmap (it was removed from RFC2460). KAME tree obeys
1331 RFC2460 IPv6, and lacks support for strict/loose bitmap.
1332
13332. Network Drivers
1334
1335KAME requires three items to be added into the standard drivers:
1336
1337(1) mbuf clustering requirement. In this stable release, we changed
1338 MINCLSIZE into MHLEN+1 for all the operating systems in order to make
1339 all the drivers behave as we expect.
1340
1341(2) multicast. If "ifmcstat" yields no multicast group for a
1342 interface, that interface has to be patched.
1343
1344To avoid troubles, we suggest you to comment out the device drivers
1345for unsupported/unnecessary cards, from the kernel configuration file.
1346If you accidentally enable unsupported drivers, some of the userland
1347tools may not work correctly (routing daemons are typical example).
--- 217 unchanged lines hidden (view full) ---
1565as OpenBSD team has their home-brew IPsec stack and they have no plan
1566to replace it. IPv6 support for IPsec is, therefore, lacking on KAME/OpenBSD.
1567
1568http://www.netbsd.org/Documentation/network/ipsec/ has more information
1569including usage examples.
1570
15714.1 Policy Management
1572
1573The kernel implements experimental policy management code. There are two way
1574to manage security policy. One is to configure per-socket policy using
1575setsockopt(3). In this cases, policy configuration is described in
1576ipsec_set_policy(3). The other is to configure kernel packet filter-based
1577policy using PF_KEY interface, via setkey(8).
1578
1579The policy entry will be matched in order. The order of entries makes
1580difference in behavior.
1581
--- 9 unchanged lines hidden (view full) ---
1591The kernel will contact racoon daemon as necessary to exchange keys.
1592
1593In IKE spec, there's ambiguity about interpretation of "tunnel" proposal.
1594For example, if we would like to propose the use of following packet:
1595 IP AH ESP IP payload
1596some implementation proposes it as "AH transport and ESP tunnel", since
1597this is more logical from packet construction point of view. Some
1598implementation proposes it as "AH tunnel and ESP tunnel".
1599Racoon follows the former route.
1600This raises real interoperability issue. We hope this to be resolved quickly.
1601
16024.3 AH and ESP handling
1603
1604IPsec module is implemented as "hooks" to the standard IPv4/IPv6
1605processing. When sending a packet, ip{,6}_output() checks if ESP/AH
1606processing is required by checking if a matching SPD (Security
1607Policy Database) is found. If ESP/AH is needed,
1608{esp,ah}{4,6}_output() will be called and mbuf will be updated
1609accordingly. When a packet is received, {esp,ah}4_input() will be
--- 86 unchanged lines hidden (view full) ---
1696 see ipsec wg mailing list discussion in Jan 2000 for details.
1697
16984.5 Conformance to RFCs and IDs
1699
1700The IPsec code in the kernel conforms (or, tries to conform) to the
1701following standards:
1702 "old IPsec" specification documented in rfc182[5-9].txt
1703 "new IPsec" specification documented in:
1704 rfc240[1-6].txt rfc241[01].txt rfc2451.txt
1705 draft-mcdonald-simple-ipsec-api-01.txt
1706 (expired, available in ftp://ftp.kame.net/pub/internet-drafts/)
1707 draft-ietf-ipsec-ciph-aes-cbc-00.txt
1708 IPComp:
1709 RFC2393: IP Payload Compression Protocol (IPComp)
1710IKE specifications (rfc240[7-9].txt) are implemented in userland
1711as "racoon" IKE daemon.
1712
1713Currently supported algorithms are:
1714 old IPsec AH
1715 null crypto checksum (no document, just for debugging)
--- 123 unchanged lines hidden (view full) ---
1839in the past, in no particular order.
1840 IRE, SSH (both IPv4/IPv6), NetLock
1841
1842VPNC (vpnc.org) provides IPsec conformance tests, using KAME and OpenBSD
1843IPsec/IKE implementations. Their test results are available at
1844http://www.vpnc.org/conformance.html, and it may give you more idea
1845about which implementation interoperates with KAME IPsec/IKE implementation.
1846
18475. ALTQ
1848
1849KAME kit includes ALTQ 2.1 code, which supports FreeBSD2, FreeBSD3,
1850NetBSD and OpenBSD. For BSD/OS, ALTQ does not work.
1851ALTQ in KAME supports (or tries to support) IPv6.
1852(actually, ALTQ is developed on KAME repository since ALTQ 2.1 - Jan 2000)
1853
1854ALTQ occupies single character device number. For FreeBSD, it is officially
--- 32 unchanged lines hidden (view full) ---
1887 SFC: http://neo.sfc.wide.ad.jp/~mip6/ (-13 draft)
1888
18897. Coding style
1890
1891The KAME developers basically do not make a bother about coding
1892style. However, there is still some agreement on the style, in order
1893to make the distributed develoment smooth.
1894
1895- the tab character should be 8 columns wide (tabstops are at 8, 16, 24, ...
1896 column). With vi, use ":set ts=8 sw=8".
1897- each line should be within 80 characters.
1898- keep a single open/close bracket in a comment such as in the following
1899 line:
1900 putchar('('); /* ) */
1901 without this, some vi users would have a hard time to match a pair of
1902 brackets. Although this type of bracket seems clumsy and is even
1903 harmful for some other type of vi users and Emacs users, the
1904 agreement in the KAME developers is to allow it.
1905- add the following line to the head of every KAME-derived file:
1906 /* (dollar)KAME(dollar) */
1907 where "(dollar)" is the dollar character ($), and around "$" are tabs.
1908 (this is for C. For other language, you should use its own comment
1909 line.)
1910 Once commited to the CVS repository, this line will contain its
1911 version number (see, for example, at the top of this file). This
1912 would make it easy to report a bug.
1913- when creating a new file with the WIDE copyright, tap "make copyright.c" at
1914 the top-level, and use copyright.c as a template. KAME RCS tag will be
1915 included automatically.
1916- when editting a third-party package, keep its own coding style as
1917 much as possible, even if the style does not follow the items above.
1918
1919When you want to contribute something to the KAME project, and if *you
1920do not mind* the agreement, it would be helpful for the project to
1921keep these rules. Note, however, that we would never intend to force
1922you to adopt our rules. We would rather regard your own style,
1923especially when you have a policy about the style.
1924
1925 <end of IMPLEMENTATION>