PageRenderTime 64ms CodeModel.GetById 19ms RepoModel.GetById 0ms app.codeStats 0ms

/share/doc/IPv6/IMPLEMENTATION

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